Handoff

Handoff

Generate the lightweight handoff summary (what was built, what's missing, acceptance criteria) and, when needed, save a formal handoff artifact to .tasks/handoffs/. The receiver verifies the summary before starting work.

Steps

1. Parse arguments

Extract from $ARGUMENTS:

| Positional | Required | Description | | :--- | :--- | :--- | | ` | yes | Sending agent name (e.g. backend-developer) | | | yes | Receiving agent name (e.g. qa-engineer) | | | yes | Primary file or path being handed off | | [task_id]` | no | Task ID to link checkpoint — auto-detected from active checkpoint if omitted |

| Flag | Default | Description | | :--- | :--- | :--- | | --risk | Medium | Risk tier: Low, Medium, High | | --status | complete | Artifact status: complete, partial, draft | | --criteria | prompt | Acceptance criteria strings (can be multi-value) | | --formal | off | Force writing a durable handoff file even when risk is not High |

If from-agent, to-agent, or artifact are missing, print usage and stop:

Usage: /handoff    [task_id] \
                [--risk Low|Medium|High] \
                [--status complete|partial|draft] \
                [--criteria "criterion 1" "criterion 2"] \
                [--formal]

Example:
  /handoff backend-developer qa-engineer src/api/auth.ts 042 \
           --risk Medium --criteria "POST /auth returns 201" "Invalid creds → 401"

Schema reference: .claude/docs/handoff-schema.md

2. Validate agents

Check that .md and .md exist in .claude/agents/. If either is missing, warn but continue:

⚠️  Agent "" not found in .claude/agents/ — check spelling.

3. Resolve taskid and contextsnapshot

• If task_id was provided, check if .tasks/checkpoints/.md exists.

If yes, set context_snapshot to that path.

• If task_id was NOT provided, scan .tasks/checkpoints/ for the most recently

modified .md file (excluding .gitkeep) and use it as a suggestion.

• If no checkpoint exists, set context_snapshot to null.

4. Collect acceptance criteria

If --criteria flags were provided, use them directly.

If no criteria were provided, prompt:

📋 Enter acceptance criteria for this handoff (one per line, blank line to finish):
>

Require at least 1 criterion. Reject vague criteria and ask for a rewrite:

• Contains "works correctly", "looks good", "should be fine", "seems OK" → reject
• Must describe a concrete, testable outcome

5. Get session info

Run git branch --show-current to get the current branch for the session field. Get current ISO timestamp for ts.

6. Generate handoff summary

Build the 3-field summary per .claude/docs/handoff-schema.md:

## Handoff Summary
- What was built:  is available with its current behavior/status
- What's missing: remaining gaps, partial work, or "Nothing blocking in current scope"
- Acceptance criteria:
  - 
  - 

Also prepare the formal JSON payload only when:

• risk_tier is High and the handoff crosses domains, or
• the caller passes --formal

When the formal artifact is needed, use this JSON:

{
  "from": "",
  "to": "",
  "task_id": "",
  "artifact": "",
  "artifact_status": "",
  "acceptance_criteria": ["", ""],
  "context_snapshot": "",
  "risk_tier": "",
  "ts": "",
  "session": ""
}

7. Save formal contract when required

If formal persistence is required, write to .tasks/handoffs/-to--.json. If task_id is null, use timestamp: .tasks/handoffs/-to--.json.

If formal persistence is not required, do not create a file. The markdown handoff summary is the default artifact.

8. Ledger entry (Medium / High risk only)

If risk_tier is Medium or High, append to production/traces/decision_ledger.jsonl:

{"ts":"","session":"","agent_id":"","task_id":"","request":"Handoff to ","reasoning":"Artifact  is  — transferring ownership","choice":"Handoff summary prepared","outcome":"pass","risk_tier":"","duration_s":0}

9. Display and confirm

Print the summary first, then note whether a durable file was written:

🤝 Handoff Summary Generated
━━━━━━━━━━━━━━━━━━━━━━━━━━

  From  : @
  To    : @
  Task  : 
  File  :  []
  Risk  : 

  What was built:
    

  What's missing:
    

  Acceptance Criteria:
    - 
    - 

  Context Snapshot: 
  [if formal]: Saved to .tasks/handoffs/.json
  [if Medium/High]: Ledger entry written.

📨 Ready to hand off. @ should verify the summary above
   before starting work on .

---

Receiver Protocol

When an agent receives a handoff, it must:

1. Read the 3-field summary (and the formal file if one exists)
2. Verify each acceptance_criterion against the artifact
3. If all criteria pass → begin work
4. If any criterion fails → do NOT start work; reply to sender with:

❌ Handoff rejected — criterion failed:
   ""
   Artifact: 
   Action needed: 

---

Quick Examples

# Basic handoff — backend to QA
/handoff backend-developer qa-engineer src/api/auth.ts 042

# With explicit criteria and risk
/handoff frontend-developer lead-programmer src/components/LoginForm.tsx 055 \
  --risk Low --status partial \
  --criteria "Form renders without errors" "Submit disabled when fields empty"

# Draft handoff for review before final delivery
/handoff data-engineer backend-developer src/db/migrations/004_add_users.sql 031 \
  --status draft --risk High --formal \
  --criteria "Migration runs without error on empty DB" "Down migration restores schema"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tranhieutt
• Source: tranhieutt/softwaredevelopment_department
• License: MIT

Install and usage instructions live in the source repository linked above.