| name | o1-create-handoff-document |
| description | Produce a structured handoff document for downstream migration agents. |
# Skill O1: Create Agent Handoff Document
**When to use:** Any agent that needs to write a structured output file for the next agent in the pipeline to consume.
**Purpose:** Ensure consistent, machine-readable handoff files that downstream agents can reliably parse and validate.
---
## The Handoff Contract
Each handoff document must satisfy three guarantees:
1. **Existence** ā the file is written to `output/` before the producing agent finishes
2. **Structure** ā the file has all required sections so the consuming agent can parse it
3. **Status field** ā the final line of the file declares whether it is COMPLETE or PARTIAL
---
## Steps
### 1. Choose the Correct Output Path
All handoff files go in `output/`:
| Producing Agent | Output File |
|-----------------|-------------|
| Analysis Agent | `output/analysis-report.md` |
| Migration Agent | `output/migration-report.md` |
| Validation Agent | `output/validation-report.md` |
| Orchestrator | `output/orchestration-state.md`, `output/migration-summary.md` |
**Never write handoff files:**
- ā In workspace root
- ā In source directories
- ā Alongside source code
### 2. Write Required Sections First
Before filling in content, create the file with all section headers:
```markdown
# [Report Name]
## Section 1: [Mandatory Section]
(pending)
## Section 2: [Mandatory Section]
(pending)
...
## Status
PENDING
This guarantees the file exists and has the required skeleton even if the agent is interrupted.
3. Fill In Each Section Progressively
Replace (pending) with actual content as you complete each phase of work.
Principle: A partially-complete handoff document is better than no document. Consuming agents can read partial data and decide how to proceed.
4. Required Metadata Header
Every handoff document must start with:
# [Report Name]
**Producing Agent:** [agent name]
**Date:** [current date/time]
**Source Technology:** [if applicable]
**Target Technology:** [if applicable]
5. Required Status Footer
Every handoff document must end with exactly one of these:
## Status
COMPLETE
## Status
PARTIAL ā reason: [brief explanation of what is missing]
## Status
FAILED ā reason: [what went wrong, what consuming agent should do]
6. Finalize and Confirm
After writing the file:
- Re-read the first 10 lines to verify it can be found
- Confirm the
## Status section is at the end
- Report to orchestrator: "ā
[File] written to output/[filename]"
Handoff Document Templates
Analysis Report Template
# Migration Analysis Report
**Producing Agent:** Analysis Agent
**Date:** {date}
**Source Technology:** {SOURCE_TECH}
**Target Technology:** {TARGET_TECH}
**Total Source Files:** {N}
## 1. Workspace Structure
...
## 2. Dependencies
...
## 3. Architecture
...
## 4. File Catalog
...
## 5. Type Mappings
...
## 6. Migration Order
...
## 7. Risk Assessment
...
## 8. Recommended Target Project Name
...
## 9. Setup Commands
...
## Status
COMPLETE
Migration Report Template
# Migration Report
**Producing Agent:** Migration Agent
**Date:** {date}
**Source Technology:** {SOURCE_TECH}
**Target Technology:** {TARGET_TECH}
## Target Project Location
`output/{target-app-name}/`
## Build Command
...
## Dev Server Command
...
## Migrated Files
...
## Dependencies Installed
...
## Unmigrated Files
...
## Notes for Validation Agent
...
## Status
COMPLETE
Validation Report Template
# Validation Report
**Producing Agent:** Validation Agent
**Date:** {date}
**Target Technology:** {TARGET_TECH}
**Target App Location:** `output/{target-app-name}/`
## Build Status
**Result:** ā
PASS / ā FAIL / ā ļø PARTIAL
## Runtime Status
**Result:** ā
STARTS / ā FAILS TO START / āļø SKIPPED
## Fixes Applied
...
## Known Issues
...
## Files Needing Manual Review
...
## Final Assessment
**Overall Status:** ā
SUCCESS / ā ļø PARTIAL / ā FAILED
## Status
COMPLETE
Error Scenarios
If you run out of time before completing a section:
- Write what you have in the section
- Mark incomplete sections with:
ā ļø INCOMPLETE ā time limit reached
- Set status to:
PARTIAL ā reason: time limit, sections {X, Y} incomplete
If a critical error occurs:
- Still write the handoff document
- Document the error clearly
- Set status to:
FAILED ā reason: [what happened]
- The Orchestrator will read this and decide whether to retry
Never leave a handoff file missing. A failed document is better than no document.
Examples
Example: Analysis Agent finishes successfully
# Migration Analysis Report
**Producing Agent:** Analysis Agent
**Date:** 2026-02-26
**Source Technology:** Java Swing
**Target Technology:** React 18
**Total Source Files:** 34
## 1. Workspace Structure
src/
āāā Main.java
āāā ui/
ā āāā MainFrame.java
ā āāā UserPanel.java
āāā services/
āāā UserService.java
**Entry Points:**
- `src/Main.java` ā application entry point
[... rest of sections ...]
## Status
COMPLETE
Example: Migration Agent with some best-effort files
## Status
PARTIAL ā reason: 3 files (UserPanel.java, ComplexDialog.java, ReportGenerator.java)
were migrated as best-effort with TODO comments due to complex GUI logic.
All other 31 files migrated completely.