agent-handoff

Agent Handoff Documentation Generator

Overview

Autonomously generate comprehensive handoff documentation optimized for AI agent takeover. Analyzes your project and produces a complete Context Stack in docs/handoff/.

Core principle: Zero configuration. Fully autonomous. Machine-readable first.

Output: 8-document Context Stack in docs/handoff/ with master manifest.

The Process

Execute these 4 phases sequentially:

Phase 1: Discovery

Gather project information automatically:

1.1 Find Design Documents

Use Glob to discover existing documentation:

docs/**/*.md
README.md
ARCHITECTURE.md
*/README.md

Look for keywords: design, architecture, ADR, requirements, specification, RFC

1.2 Analyze Git History

git log --since="30 days ago" --pretty=format:"%h %s" --no-merges

Extract:

• Feature additions (feat:, add:, implement:)
• Major changes (refactor:, breaking:)
• Bug fixes (fix:, bug:)
• Architecture decisions from commit messages

1.3 Detect Project Type

File markers to check:

# Libraries/Packages
ls setup.py pyproject.toml Cargo.toml package.json

# Web Services
ls Dockerfile docker-compose.yml
find . -name "routes*" -o -name "api*" -o -name "handlers*"

# CLI Tools
grep -r "cobra" "click" "commander" --include="*.go" --include="*.py" --include="*.ts"

# Monorepos
find . -name "go.mod" -o -name "package.json" | wc -l
ls services/ packages/ apps/

Structure patterns:

• Go: cmd/, internal/, pkg/
• Library: src/, lib/, tests/
• Service: api/, handlers/, routes/

Classification logic:

IF (has Dockerfile + routes/) → web-service
ELSE IF (has setup.py + no HTTP) → library
ELSE IF (has main with arg parsing + no HTTP) → cli-tool
ELSE IF (multiple go.mod/package.json) → monorepo
ELSE → generic

Detection output format:

project_type: "web-service" # library | cli-tool | monorepo | generic
language: "go" # go | python | typescript | rust | etc
framework: "gin" # if detected (optional)
confidence: "high" # high | medium | low

1.4 Scan Codebase Structure

# Map directories (exclude hidden, node_modules, vendor)
find . -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/vendor/*'

# Identify entry points
find . -name "main.go" -o -name "main.py" -o -name "index.ts" -o -name "app.py"

# Count file types
find . -name "*.go" -o -name "*.py" -o -name "*.ts" -o -name "*.rs" | sort | uniq -c

Phase 2: Analysis

Extract structured information from discovered sources:

2.1 Extract Architecture Decisions

Sources:

• Existing ADR files in docs/adr/ or docs/architecture/
• Code comments containing: "IMPORTANT", "DO NOT", "WHY", "HACK"
• Git blame for major refactorings
• README sections about architecture

What to extract:

• Why this technology choice?
• Why this structure/pattern?
• What must NOT be changed and why?
• Known trade-offs and their rationale

2.2 Build Domain Dictionary

Extract terminology from:

1. Type Definitions

   # Go
   grep -r "type.*struct" --include="*.go"
   
   # Python
   grep -r "class " --include="*.py"
   
   # TypeScript
   grep -r "interface " --include="*.ts"
   

2. Database Schema

   # Find migrations
   find . -path "*/migrations/*" -o -path "*/schema/*"
   
   # Look for SQL files
   find . -name "*.sql"
   

3. API Schemas

   # OpenAPI/Swagger
   find . -name "openapi.yaml" -o -name "swagger.json"
   
   # GraphQL
   find . -name "schema.graphql" -o -name "*.gql"
   

Build mapping:

{
  "Term": {
    "code_synonyms": ["list", "of", "variations"],
    "database_column": "db_column_name",
    "type": "data_type",
    "api_field": "apiFieldName"
  }
}

2.3 Map System Boundaries

Only for distributed systems (web-service, monorepo):

1. Parse Docker Compose

   # Find docker-compose files
   find . -name "docker-compose*.yml"
   
   # Extract services, ports, dependencies
   

2. Find External API Calls

   # HTTP client usage
   grep -r "http.Client" "requests.get" "axios" "fetch"
   
   # Extract hostnames from code
   grep -r "https://" --include="*.go" --include="*.py" --include="*.ts"
   

3. Identify Databases

   # Database drivers
   grep -r "postgres" "mysql" "mongodb" "redis"
   
   # Connection strings (sanitized)
   grep -r "DATABASE_URL" "DB_HOST"
   

4. Generate Mermaid Graph

   graph TD
       A[Service Name :port] -->|protocol| B[Dependency]
       A -->|SQL| C[(Database)]
   

2.4 Discover Build Commands

Check these sources in order:

1. Makefile

   cat Makefile | grep "^[a-z].*:"
   

2. package.json scripts

   cat package.json | jq '.scripts'
   

3. CI/CD configs

   cat .github/workflows/*.yml
   cat .gitlab-ci.yml
   

4. Language defaults

   Go:       go build ./...
   Python:   pip install -e .
   Rust:     cargo build
   Node:     npm install
   

Extract:

• Build/compile command
• Lint command
• Test command
• Integration test command
• Deploy/run command

Phase 3: Generation

Generate all 8 documents using extracted data:

3.1 Generate Handoff_Manifest.yaml

Always generated first as master index.

project_name: "<extracted from git remote or dir name>"
generated_at: "<ISO 8601 timestamp>"
generator_version: "1.0.0"
project_type: "<from detection>"
language: "<from detection>"
framework: "<from detection or null>"
confidence: "<from detection>"

critical_context:
  - "./strategic-context/PRD_Machine_Readable.md"
  - "./strategic-context/Architecture_Decision_Records.md"
  - "./strategic-context/Domain_Dictionary.json"

execution_context:
  - "./operational-context/Agent_Runbook.md"
  <% if has_system_map %>
  - "./operational-context/System_Context_Map.mermaid"
  <% end %>
  - "./operational-context/Codebase_Walkthrough_Annotated.md"

guardrails:
  - "./guardrails/Test_Strategy_Matrix.md"

constraints:
  <% list extracted constraints from ADRs, comments %>

quality_gates:
  build_command: "<from discovery>"
  lint_command: "<from discovery or 'not configured'>"
  test_command: "<from discovery>"
  coverage_threshold: <from config or 80>

3.2 Generate PRD_Machine_Readable.md

Sources:

• Existing design docs
• README.md features section
• Git commits (features added)
• Code analysis (exported APIs, endpoints, commands)

Format:

# Product Requirements Document (Machine-Readable)

**Project:** <name>
**Type:** <project_type>
**Version:** <from package file or git tag>

## Purpose

<extract from README or design docs>

## Core User Flows

<Generate Gherkin-style scenarios from:>
- README examples
- Test descriptions
- Code comments
- API endpoint handlers

### Flow: <extracted flow name>

**Given:** <precondition>
**When:** <action>
**Then:** <expected result>

## Invariants

<Extract from:>
- Code comments with "MUST", "ALWAYS", "NEVER"
- Validation logic
- Test assertions
- Security checks

Examples:

- User passwords are never stored in plaintext
- All API endpoints require authentication except /health
- Database transactions use isolation level READ COMMITTED

## Negative Constraints

<Extract from:>
- Comments with "DO NOT"
- ADRs with "rejected alternatives"
- Code marked with "HACK" or "WORKAROUND"

Examples:

- Do not introduce new npm dependencies without approval
- Do not refactor the legacy auth system (external dependencies)
- Do not change database schema without migration

## Success Criteria

<Extract from:>
- Test coverage requirements
- Performance benchmarks
- README goals section

Examples:

- All endpoints respond in <200ms p95
- Test coverage >80%
- Zero critical security vulnerabilities

3.3 Generate Architecture_Decision_Records.md

Format:

# Architecture Decision Records

<For each discovered ADR or major decision:>

## ADR-<number>: <Title>

**Status:** <accepted | rejected | superseded>
**Date:** <from git or "unknown">

### Context

<Why was this decision needed?>

### Decision

<What was decided?>

### Consequences

**Positive:**

- <benefit 1>
- <benefit 2>

**Negative:**

- <trade-off 1>
- <trade-off 2>

### Do Not Refactor

<Extract code blocks that should NOT be changed:>

**File:** `path/to/file.go:line`
**Reason:** <why this ugly code exists>

Example:

- `internal/auth/session.go:45-67` - UUID v4 required for legacy Java service compatibility

3.4 Generate Domain_Dictionary.json

Format:

{
  "<Term>": {
    "code_synonyms": ["<variant1>", "<variant2>"],
    "database_column": "<column_name>",
    "type": "<data_type>",
    "api_field": "<apiFieldName>",
    "description": "<optional brief description>"
  }
}

Example:

{
  "User": {
    "code_synonyms": ["subscriber", "account_holder", "member"],
    "database_column": "usr_id",
    "type": "uuid",
    "api_field": "userId",
    "description": "Registered user account"
  },
  "Session": {
    "code_synonyms": ["auth_session", "login_session"],
    "database_column": "session_token",
    "type": "string",
    "api_field": "sessionId",
    "description": "Active authentication session"
  }
}

3.5 Generate System_Context_Map.mermaid

Only for: web-service, monorepo Skip for: library, cli-tool, generic

graph TD
    <% for each service %>
    <ID>[<Name> :<port>]
    <% end %>

    <% for each dependency %>
    <FROM> -->|<protocol>| <TO>
    <% end %>

    <% for each database %>
    <ID>[(<Database Type> :<port>)]
    <% end %>

    <% for each external API %>
    <ID>[<External API>]
    <% end %>

    style <main_service> fill:#4CAF50
    style <databases> fill:#FF9800
    style <external> fill:#2196F3

Example:

graph TD
    A[Web API :8080] -->|REST| B[Auth Service :50051]
    A -->|gRPC| C[Payment Service :500

---

*Content truncated.*