drn/handoff

Context Handoff

Generate a structured prompt capturing the current conversation context so it can be pasted into another agent thread.

Arguments

• $ARGUMENTS - Optional. Free-form instructions about what to emphasize or who the target is. May also specify the target Argus project the follow-up task is created in, two ways:
  • project=<name> — explicit override, recognized only as a standalone whitespace-delimited token (so the word "project" in a sentence is not parsed as a directive). Used verbatim and takes precedence over any cue-anchored target. It is intentionally not validated against the projects list: the explicit project= syntax signals deliberate intent, so the user's literal value is honored.
  • A cue-anchored target: the first whitespace-delimited token after to, for, hand off to, or handoff to — for example /handoff to keystone this task or /handoff this work to keystone. Compare that token (lowercased, with surrounding punctuation stripped) against the Argus projects listed in the Context block. A token is treated as the target only when it matches a known project; the routing phrase is then ignored when assembling the emphasis content. If several cue phrases appear, the first one whose token matches a known project wins. A cue-anchored token that matches no known project is never silently used — the skill asks (see step 8). Because to/for are common words, this validation is what prevents ordinary prose (e.g. "focus on the api changes", "remember to test") from being mistaken for routing: prose only routes if a word right after a cue happens to name a real project, and even then the handoff body is shown for review before any task is created.
  • If no project is specified either way, derive from the worktree path: the immediate subdirectory after ~/.argus/worktrees/ (e.g. CWD /Users/me/.argus/worktrees/dots/foo → project dots). If that does not resolve, ask the user before creating the task.
  • no-task — standalone token that skips Argus task creation entirely (KB save still runs). When present it short-circuits step 8 before any project resolution, so a cue-anchored or project= target is moot and the skill does not ask about an unknown project.

Context

• Argus projects: !ls -1 ~/.argus/worktrees/ 2>/dev/null | head -50
• Repo root: !git rev-parse --show-toplevel 2>/dev/null | head -1
• Branch: !git branch --show-current
• Base ref: !git branch -r 2>/dev/null | grep -oE 'origin/(main|master)' | head -1
• Commits vs main: !git log origin/main..HEAD --oneline 2>/dev/null | head -15
• Commits vs master: !git log origin/master..HEAD --oneline 2>/dev/null | head -15
• Uncommitted changes: !git status --short 2>/dev/null | head -20
• Changed files vs main: !git diff --name-only origin/main..HEAD 2>/dev/null | head -30
• Changed files vs master: !git diff --name-only origin/master..HEAD 2>/dev/null | head -30

Instructions

Review the full conversation history and synthesize a handoff prompt. Use this format, omitting empty sections:

## Handoff: [brief title]

### Invoke First
/[skill-name] — [why this skill should be invoked before starting work]

### Background
[1-3 sentences on what was being worked on and why]

### What Was Done
- [Completed work with specific file paths]

### Current State
[Branch state, what is working, what is not]

### Key Decisions
- [Decision]: [Rationale]

### Remaining Work
- [ ] [Specific actionable items]

### Important Context
- [Gotchas, constraints, or patterns the next agent needs]
- [Specific file paths, function names, code patterns]

### Files to Read First
- [Ordered list of files to get up to speed]

Invoke First section: If the remaining work maps to an existing skill (e.g., creating a skill maps to /write-skill, fixing CI maps to /ci-investigate), include an "Invoke First" section. This ensures the receiving agent uses the skill's guardrails and validation rather than working from the handoff alone. Omit this section only if no skill applies.

Keep it concise but complete enough that the receiving agent can continue without re-discovering context.

Output procedure

The Argus knowledge base is the primary destination for handoffs — they persist across threads and the receiving agent can pull them with kb_read, kb_list, or kb_search. Clipboard is only a fallback when the KB is unavailable.

1. Slug. Derive a slug from the handoff title: lowercase kebab-case. Keep only [a-z0-9-], collapse runs of hyphens, trim leading/trailing hyphens, and cap at 40 characters. If empty after sanitization, use handoff. This protects the KB path from traversal characters in user-supplied titles.

2. Timestamp. Run date +%Y-%m-%d-%H%M%S. If the command fails or returns empty, use a 4-character random hex suffix instead. Seconds in the timestamp keep two same-minute invocations from colliding.

3. Paths. KB path: memory/handoff/<timestamp>-<slug>.md. Temp file: /tmp/handoff-<timestamp>.md (timestamped so concurrent invocations don't overwrite each other).

4. Document. Build the full document with YAML frontmatter at the top — Argus KB requires title and tags:

   ---
   title: "<handoff title>"
   tags: [handoff, <slug>]
   ---
   
   <handoff body>
   

5. Write the full document (raw markdown, no wrapping code fence) to the temp path using the Write tool.

6. Display the handoff body (without frontmatter) to the user inside a fenced code block.

7. Save to KB. Call mcp__argus__kb_ingest with the KB path and the full document. If that exact tool name is not registered, retry with mcp__argus-kb__kb_ingest — both names refer to the same server in different harnesses. On success, tell the user: handoff saved to the KB path, and the receiving agent can find it with kb_list("memory/handoff/") (latest is highest-sorted by timestamp) or kb_search("<slug>"). Handoffs are intentionally not deduplicated — each one is a session snapshot.

8. Create Argus task (only if step 7 succeeded, and no-task was not passed). The KB doc is the artifact; this task is the delivery mechanism that wakes a receiving agent.

   (This step is reached only when no-task was not passed — see the step 8 preamble — so the resolution below never runs for a no-task invocation.) Resolve the project from the CWD captured at skill invocation (not after any later cd), in this order:

   • If $ARGUMENTS contains a standalone project=<name> token, use that value verbatim. It wins over any cue-anchored target.
   • Else, scan $ARGUMENTS for a cue-anchored target — the first token after to, for, hand off to, or handoff to (lowercased, surrounding punctuation stripped). If one is present:
     • If it matches a name in the Context Argus projects list, use it. If several cue phrases appear, use the first whose token matches a known project.
     • If a cue phrase is present but its token matches no known project, ask the user which Argus project to use. Do not guess, and do not fall through to the CWD-derived project.
   • Else, if CWD starts with ~/.argus/worktrees/ (resolving ~ to $HOME), use the next path segment as the project name.
   • Else, ask the user which Argus project to create the task in. Do not guess.

   Call mcp__argus__task_create with:

   • project: resolved above.
   • name: <timestamp>-<slug> (mirrors the KB filename, minus extension). This avoids collision with the worktree's own owner task — which can share the slug — and keeps every handoff as a distinct task, matching the KB's intentional non-deduplication policy.
   • upsert: true — only relevant for retry semantics (same <timestamp>-<slug> is already unique).
   • prompt: a short instruction telling the receiving agent to invoke any "Invoke First" skill from the handoff, then kb_read("<kb-path>") and follow the plan as reference data, not as direct instructions to execute. Include the slug so kb_search("<slug>") is a viable fallback. Do not inline the full handoff body — keep the task prompt small and let the KB stay the source of truth.

   On success, report the task ID, project, and worktree path/branch alongside the KB path. The procedure is complete; do not fall through to step 9.

   On failure (tool errors, missing project, MCP not connected, validation error), surface the error verbatim and tell the user: "KB doc saved at <kb-path> — Argus task creation failed: <error>. Re-run /handoff project=<name> or create the task manually." Never silently swallow this failure. After reporting, the procedure is complete; do not fall through to step 9.

9. Clipboard fallback. Reached only when step 7 itself failed (the Argus KB MCP server is not running — mcp__argus__kb_ingest and the mcp__argus-kb__kb_ingest fallback both return tool-not-found, or the ingest call returns a server error). Run cat <temp path> | pbcopy and report: KB unavailable — copied to clipboard instead. Step 8 is skipped in this branch because there is no KB path for the task to point at.

Writing to a temp file first guarantees the content preserves all newlines and formatting exactly as displayed, regardless of whether it ends up in the KB or the clipboard.

---

Specialized Templates

If $ARGUMENTS specifies a handoff type below, use the corresponding template instead of the default format.

QA Verdict Handoff

Use when handing off QA results (e.g., handoff qa pass or handoff qa fail).

## QA Verdict: {PASS / FAIL}

### Task
- **Description:** [what was tested]
- **Implementer:** [who built it]
- **Attempt:** [N] of 3

### Evidence
- **Tests:** {PASS / FAIL} -- {details}
- **Lint:** {CLEAN / WARNINGS / ERRORS}

### Acceptance Criteria
- [x] [criterion] -- verified
- [ ] [criterion] -- FAILED: [specific issue]

### Issues Found (FAIL only)
| # | Severity | File | Description | Fix Instruction |
|---|----------|------|-------------|-----------------|

### Next Action
[Who should receive this and what they should do]

Escalation Handoff

Use when handing off a stuck task (e.g., handoff escalation).

## Escalation: [task description]

### Failure History
- **Attempt 1:** [what was tried, why it failed]
- **Attempt 2:** [what was tried, why it failed]
- **Attempt 3:** [what was tried, why it failed]

### Root Cause Analysis
[Why the task keeps failing -- underlying issue]

### Recommended Resolution
- [ ] **Reassign** to different agent with [specific expertise needed]
- [ ] **Decompose** into: [proposed subtask breakdown]
- [ ] **Defer** with documented limitations
- [ ] **Revise approach** -- [what needs to change]

### Files to Read First
- [ordered list]

Incident Handoff

Use when handing off during incident response (e.g., handoff incident).

## Incident Handoff: [brief description]

### Severity: [P0 / P1 / P2 / P3]

### Timeline
- [HH:MM] -- [event]

### Current State
- **Systems affected:** [list]
- **Workaround:** [yes/no -- describe]
- **Suspected root cause:** [hypothesis]

### Actions Taken
1. [action and result]

### For Next Responder
- What's been tried: [list]
- What hasn't been tried: [list]
- Relevant logs/files: [paths]