Generates standardized agent handoff documents for phase transitions. Ensures critical information is preserved and passed between agents during workflow orchestration. Automates handoff creation to prevent implementation failures from missing context.
Generates standardized handoff documents for agent phase transitions. Automatically triggered when completing work to preserve critical context and prevent implementation failures from missing information.
/plugin marketplace add DarkMonkDev/WitchCityRope/plugin install darkmonkdev-witchcityrope-agents@DarkMonkDev/WitchCityRopeThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Purpose: Automate creation of standardized handoff documents between agents and phases.
When to Use: At every phase transition to ensure context preservation.
Critical Finding: 90%+ of implementation failures traced to missing handoff documents.
Problem: Agents starting work without context make wrong assumptions.
Solution: Mandatory handoff documents at every transition.
Location: /docs/functional-areas/[feature]/new-work/[date]/handoffs/[source]-to-[target]-handoff.md
# Agent Handoff: [Source] → [Target]
**Date**: YYYY-MM-DD HH:MM
**Source Agent**: [agent-name]
**Target Agent**: [agent-name]
**Phase Transition**: [Phase X] → [Phase Y]
**Feature**: [Feature Name]
**Work Type**: Feature|Bug|Hotfix|Docs|Refactor
---
## Executive Summary
[2-3 sentences: What was completed, what's next, critical decisions]
## Completed Work
### Primary Deliverables
- [ ] [Deliverable 1] - Location: /path/to/file
- [ ] [Deliverable 2] - Location: /path/to/file
### Quality Gate Score
- Score: XX/YY (ZZ%)
- Required: AA%
- Status: PASS|FAIL
## Critical Decisions Made
1. **[Decision Topic]**
- Decision: [What was decided]
- Rationale: [Why this was chosen]
- Impact: [Implications for next phase]
- Alternatives Considered: [What was rejected and why]
## Context for Next Agent
### Must Read
- [ ] File: /path/to/requirements.md
- [ ] File: /path/to/design.md
- [ ] Lessons: /docs/lessons-learned/[agent]-lessons-learned.md
### Key Insights
- [Critical insight 1]
- [Critical insight 2]
### Assumptions Made
- [Assumption 1 - target agent must validate]
- [Assumption 2 - may need adjustment]
## Technical Specifications
### Architecture Decisions
- [ADR or architectural pattern chosen]
- [Technology stack decisions]
### Data Models
[Key schemas, types, or data structures]
### API Contracts
| Endpoint | Method | Purpose | Status |
|----------|--------|---------|--------|
| /api/... | GET | ... | Designed |
## Dependencies & Blockers
### Dependencies Required
- [ ] [Dependency 1] - Status: Ready|Pending
- [ ] [Dependency 2] - Status: Ready|Pending
### Known Blockers
- [Blocker if any - NONE is valid]
## Security & Privacy
- [Security requirements]
- [Data privacy considerations]
- [Auth/authz requirements]
## Testing Requirements
### Test Cases Needed
- [ ] [Test case 1]
- [ ] [Test case 2]
### Acceptance Criteria
- [ ] [Criteria 1]
- [ ] [Criteria 2]
## Questions for Target Agent
- [ ] [Question needing clarification]
- [ ] [Decision target agent should make]
## Files Created/Modified
| File | Action | Purpose |
|------|--------|---------|
| /path/to/file.md | CREATED | [purpose] |
## Next Steps
1. [Step 1 for target agent]
2. [Step 2 for target agent]
3. [Step 3 for target agent]
## Validation Checklist
- [ ] All deliverables complete
- [ ] Quality gate passed
- [ ] Decisions documented
- [ ] Context provided
- [ ] Dependencies identified
- [ ] Files logged in registry
- [ ] Next steps clear
---
**Target Agent**: Read this entire handoff before starting work. Validate all assumptions.
# Generate handoff from business requirements to functional spec
bash .claude/skills/handoff-document-generator/execute.sh \
business-requirements \
functional-spec \
user-management \
Feature
# Generate handoff from functional spec to react developer
bash .claude/skills/handoff-document-generator/execute.sh \
functional-spec \
react-developer \
user-management \
Feature
# Generate handoff for bug fix
bash .claude/skills/handoff-document-generator/execute.sh \
backend-developer \
test-executor \
api-fixes \
Bug
# Show help and usage information
bash .claude/skills/handoff-document-generator/execute.sh --help
Use the handoff-document-generator skill to create handoff from [source-agent] to [target-agent] for [feature-name]
At phase transition (orchestrator-automated):
bash .claude/skills/handoff-document-generator/execute.sh \
business-requirements \
functional-spec \
user-management \
Feature
From agent (self-service):
# Before completing my work, generate handoff for next agent
bash .claude/skills/handoff-document-generator/execute.sh \
my-role \
next-agent-role \
feature-name \
Feature
Use the handoff-document-generator skill to create handoff from business-requirements to functional-spec
# Create handoff document
bash .claude/skills/handoff-document-generator.md \
business-requirements \
functional-spec \
user-management \
Feature
Before completing my work, I'll use the handoff-document-generator skill to create a handoff document for the next agent.
Source: business-requirements Target: functional-spec, database-designer, ui-designer Critical Context: User stories, business rules, success metrics Decisions: Feature scope, user roles affected, priority
Source: functional-spec, database-designer, ui-designer Target: react-developer, backend-developer Critical Context: Architecture, data models, API contracts Decisions: Tech stack, component structure, database schema
Source: react-developer, backend-developer Target: test-executor Critical Context: What was implemented, where, how to test Decisions: Test approach, fixtures needed, edge cases
Source: test-executor Target: librarian, git-manager Critical Context: Test results, coverage, blockers Decisions: Deployment readiness, rollback plan
REQUIRED at these transitions:
Before transitioning from Phase X to Phase Y:
1. Check if handoff exists
2. Verify handoff is complete (no TODO sections)
3. Require target agent to acknowledge reading handoff
4. Block transition if handoff missing
{
"handoff": {
"source": "business-requirements",
"target": "functional-spec",
"feature": "user-management",
"workType": "Feature",
"phaseTransition": "Phase 1 → Phase 2",
"file": "/docs/functional-areas/.../handoffs/business-requirements-to-functional-spec-handoff.md",
"status": "created",
"todoSectionsRemaining": 8,
"complete": false
},
"nextSteps": [
"business-requirements agent: Complete all TODO sections",
"Run phase-1-validator to get quality gate score",
"functional-spec agent: Read handoff before starting"
]
}
Symptom: Agent completes work but creates no handoff Impact: Next agent starts with zero context Solution: Orchestrator must REQUIRE handoff creation
Symptom: TODO sections not filled in Impact: Next agent has template but no real information Solution: Phase validators check for complete handoffs
Symptom: Target agent asks questions already answered in handoff Impact: Wasted time, repeated mistakes Solution: Require agents to acknowledge reading handoff
Handoffs are NOT lessons learned:
When to promote handoff content to lessons:
Initial Context: Show handoff location and whether it exists On Request: Generate template with TODOs On Completion: Show next agent what to read On Failure: Show which sections are incomplete
Remember: Handoff documents are the memory system for multi-agent workflows. Without them, agents work in isolation and fail. With them, agents build on each other's work successfully.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.