ampa-handoff-management

AMPA Handoff Management Skill

Overview

Context transfer between AMPA sessions via structured handoff documents (Markdown + YAML frontmatter). Enables seamless work state transfer across agent transitions, session boundaries, bug discoveries, and work interruptions.

Prerequisites

• AI Maestro running for inter-agent messaging notifications (uses $AIMAESTRO_API environment variable).
• Handoff directory exists at $CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/ (create with mkdir -p if needed).
• Valid session name registered with AI Maestro (format: <project>-programmer-<number>).
• $CLAUDE_PROJECT_DIR set to the project root (set automatically by Claude Code).

Instructions

Copy this checklist and track your progress:

1. Determine the handoff operation needed. Match your situation to Read, Create, Bug Report, or Document Work State.
2. Read the corresponding reference file from references/ before proceeding.
3. Verify the handoff directory exists. Run mkdir -p "$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/ampa-<task-name>/".
4. Execute the operation. All handoff documents require YAML frontmatter with fields: type, from, to, task, created, priority, status. Bug reports (type: bug-report) have modified fields: type, from, task, bug-id, severity, created.
5. Validate the handoff document. Re-read to confirm all required fields are present and content is accurate.
6. Send notification. Use the globally installed agent-messaging skill to notify the receiving agent, including the handoff file path.
7. Archive previous versions. If updating an existing handoff, move current.md to archive/ with a timestamp suffix before writing the new version.

Output

• Handoff documents stored at $CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/ampa-<task-name>/current.md.
• Notification sent to receiving agent via agent-messaging skill.

Error Handling

Error	Resolution
Handoff directory missing	Run mkdir -p "$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/ampa-<task-name>/"
AI Maestro notification fails	Verify running with amp-status (frozen CLI, not the server /api/ — R23), check agent-messaging skill for connectivity troubleshooting
YAML frontmatter parse error	Ensure --- delimiters on own lines, quote special characters in values
Receiving agent not found	Use the agent-messaging skill to list registered agents
Handoff document is stale	Archive existing current.md to archive/ with timestamp, then create new

Examples

• Input: Task complete, need to transfer context to another agent
• Output: current.md with YAML frontmatter, modified files, test status, next steps. Notification sent.

Resources

Document	Description
op-read-handoff-document.md	When to Use, Prerequisites, Procedure, Examples, Error Handling
op-create-handoff-document.md	When to Use, Prerequisites, Procedure, Checklist, Examples, Error Handling
op-write-bug-report.md	When to Use, Prerequisites, Procedure, Checklist, Examples, Error Handling
op-document-work-state.md	When to Use, Prerequisites, Procedure, Checklist, Examples, Error Handling

agent-messaging skill (global) — Send notifications, list agents.

Governance

This skill operates under the AI Maestro approval tiers — the escalation ladder Tier 0 (self-authority for in-scope work + DERIVED NPT/EHT tasks) → CHIEF-OF-STAFF → MANAGER → USER. See the ampa-prrd-trdd-kanban skill and ~/.claude/rules/trdd-approval-tiers.md for which transitions need approval. A MEMBER never self-approves its own releases — entering the release pipeline (publish/deploy) is USER/MANAGER-authorized, and the INTEGRATOR (not the MEMBER) owns the → complete flip.

Related

• ampa-task-execution — Core implementation workflow producing handoff-worthy work state.
• ampa-orchestrator-communication — Messaging patterns for AMOA coordination.