--- name: worker-handover description: Defines context handover format when workers hit turn limit. Posts structured handover to GitHub issue comments enabling replacement workers to continue seamlessly. allowed-tools: - Read - Grep - Glob - Bash - mcp__github__* - mcp__memory__* model: opus --- # Worker Handover ## Overview When workers approach their turn limit (100 turns), they must create a handover that enables a replacement worker to continue without losing context. **Core principle:** A replacement worker should understand the work as well as the original worker did. **Announce at start:** "I'm approaching my turn limit. Creating handover for replacement worker." ## State Management **CRITICAL:** Handover context is stored in GitHub issue comments. NO local handover files. | State | Location | Purpose | |-------|----------|---------| | Handover context | Issue comment | Full context for replacement worker | | Git changes | Branch commits | Work completed so far | | Test status | Issue comment | Current test state | Handover survives crashes because it's in GitHub, not local files. ## When to Handover | Turns Used | Action | |------------|--------| | 85+ | Evaluate if handover needed | | 90+ | Begin handover preparation | | 95+ | Complete handover, prepare to exit | | 100 | Exit (automatic) | ## Handover Format Post to the issue with structured markers: ```markdown # Handover: Issue #[ISSUE] ## Metadata | Field | Value | |-------|-------| | Issue | #[ISSUE] | | Previous Worker | [WORKER_ID] | | Turns Used | [N]/100 | | Timestamp | [ISO_TIMESTAMP] | | Orchestration | [ORCHESTRATION_ID] | | Attempt | [N] | ## Issue Summary [Concise summary of what the issue requires - in your own words, not copied] ## Current State ### Branch Status - **Branch:** `[BRANCH_NAME]` - **Commits:** [N] commits ahead of main - **Last Commit:** `[COMMIT_HASH]` - [COMMIT_MESSAGE] ### Files Modified [List of modified files with brief description of changes] ### Tests Status - **Passing:** [N] - **Failing:** [N] - **Coverage:** [X]% ## Work Completed ### Done - [x] [Completed task 1] - [x] [Completed task 2] ### In Progress - [ ] [Current task - describe state] ### Remaining - [ ] [Remaining task 1] - [ ] [Remaining task 2] ## Context & Decisions ### Key Decisions Made 1. **[Decision]:** [Why this choice was made] 2. **[Decision]:** [Why this choice was made] ### Approaches Tried 1. **[Approach]:** [Result/Why abandoned] ### Important Discoveries - [Discovery that affects implementation] ## Technical Notes ### Architecture Notes [Any architectural decisions or patterns being used] ### Gotchas - [Thing that might trip up the next worker] - [Non-obvious behavior discovered] ## Current Blocker (if any) [Description of what's blocking progress, if anything] ## Recommended Next Steps 1. [Specific next action to take] 2. [Following action] 3. [Following action] ## Files to Review First 1. `[path/to/key/file.ts]` - [Why it's important] 2. `[path/to/key/file.ts]` - [Why it's important] ## Commands to Run ```bash # Verify current state pnpm test # Continue development [specific commands] ``` --- *Handover created by [WORKER_ID] at [TIMESTAMP]* ``` ## Creating a Handover ### Step 1: Assess State ```bash # Check git status git status git log --oneline -10 # Check test status pnpm test 2>&1 | tail -20 # Count modified files git diff --name-only HEAD~[N] ``` ### Step 2: Post Handover to Issue ```bash ISSUE=123 WORKER_ID="worker-1234567890-123" BRANCH=$(git branch --show-current) LAST_COMMIT=$(git log -1 --format='%h - %s') COMMITS_AHEAD=$(git rev-list --count main..HEAD) gh issue comment "$ISSUE" --body " # Handover: Issue #$ISSUE ## Metadata | Field | Value | |-------|-------| | Issue | #$ISSUE | | Previous Worker | $WORKER_ID | | Turns Used | 94/100 | | Timestamp | $(date -u +%Y-%m-%dT%H:%M:%SZ) | | Orchestration | $ORCHESTRATION_ID | ## Current State ### Branch Status - **Branch:** \`$BRANCH\` - **Commits:** $COMMITS_AHEAD commits ahead of main - **Last Commit:** \`$LAST_COMMIT\` [... rest of handover content ...] " ``` ### Step 3: Commit Any Uncommitted Work ```bash git add -A git commit -m "chore: Save progress before handover Worker $WORKER_ID reached turn limit. Handover posted to issue #$ISSUE. Orchestrator: $ORCHESTRATION_ID" ``` ### Step 4: Exit Gracefully Worker exits after posting handover. Orchestrator will spawn replacement. ## Receiving a Handover When a replacement worker starts, it reads handover from issue comments: ### Step 1: Read Handover from GitHub ```bash ISSUE=123 # Get latest handover from issue comments HANDOVER=$(gh api "/repos/$OWNER/$REPO/issues/$ISSUE/comments" \ --jq '[.[] | select(.body | contains(""))] | last | .body') echo "$HANDOVER" ``` ### Step 2: Verify State ```bash # Verify branch git branch --show-current # Check current state matches handover git status git log --oneline -5 # Run tests pnpm test ``` ### Step 3: Acknowledge Receipt Post acknowledgment to issue: ```markdown **Handover Received** **Replacement Worker:** [NEW_WORKER_ID] **Continuing from:** [PREVIOUS_WORKER_ID] **Attempt:** [N] **Handover verified:** - [x] Branch state matches - [x] Tests status matches - [x] Context understood **Continuing with:** [First task from "Recommended Next Steps"] --- *Orchestration: [ORCHESTRATION_ID]* ``` ### Step 4: Continue Work Follow the "Recommended Next Steps" from the handover. ## Handover Quality Checklist Before creating handover: - [ ] All local changes committed - [ ] Handover captures current state accurately - [ ] Key decisions are documented - [ ] Gotchas are noted - [ ] Next steps are specific and actionable - [ ] Files to review are listed in priority order - [ ] Commands to run are tested and correct - [ ] Handover posted to issue comment - [ ] Work committed to branch ## Bad Handover Examples ### Too Vague ```markdown ## Work Completed - Did some stuff - Made progress ## Next Steps - Finish the feature ``` ### Missing Context ```markdown ## Work Completed - [x] Implemented the thing ## Next Steps - Fix the tests ``` (No explanation of WHY tests are failing) ## Good Handover Example See the full format above for a complete, high-quality handover that includes: - Specific commit references - Test failure details - Decisions with rationale - Gotchas discovered - Actionable next steps - File priority list - Verified commands ## Integration This skill is used by: - `worker-protocol` - Triggers handover creation - `worker-dispatch` - Provides handover to replacement workers This skill uses: - GitHub issue comments for handover storage - Git for state verification