handoff — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited handoff (Agent Skill) and scored it 96/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 1 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 1 flagged
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Guards:
Typical use: ~75% context. You have a lot of conversation to mine — extract maximum value before closing. On 1M context that's ~750K tokens of history.
The user should not need to provide anything — /handoff alone is sufficient.
Arguments: $ARGUMENTS
Parallelize independent research. Launch in one message.
| What | Mode | Why |
|---|---|---|
| Step 1A (git/beads/ls) | Parallel Bash, never agents | Cheap commands; agent bootup wastes 15K+ each |
| Step 1B context agents (OV, stale-refs, bible) | Parallel Bash inline; agents only if parent handoff >500 lines | Independent research |
| Step 1C (conversation mining) | Main agent only | Only you have the history |
| Steps 5+6 (beads/memory writes) | Parallel Bash | Independent writes |
Run in one message as inline Bash calls:
| Commands | Returns | |
|---|---|---|
git log --oneline -20, git diff --stat, `git status -s \ | head -30, git branch --show-current` | Branch, recent commits, uncommitted changes |
bd list --status=in_progress, bd list --status=open --priority=0,1, bd stats (skip if bd unavailable) | Active/open beads | |
ls plans/handoffs/, ls .claude/handoffs/, ls plans/*.md | Existing handoff files |
Resolve the chain tag (use first that applies):
myproject-xxxx, myproject-yyyy)python -c "import secrets; print(secrets.token_hex(4))" → standalone-{hex}Find prior handoff in this chain (two tiers, stop at first match):
Read HANDOFF_foo_date.md (seq 2, chain-x) and continue...? If yes, that file is the parent. Read its header. Continuation — seq = parent's + 1. grep -l "Chain:.*{chain_tag}" plans/handoffs/HANDOFF_*.md 2>/dev/null \
| xargs grep -L "^\*\*Auto:\*\* true" 2>/dev/nullA shared bead is a CANDIDATE, not proof of continuation. Before claiming the match as parent:
## Where We're Going section.## Related Handoffs section listing the sibling file as reference only, NOT parent. A bead can host many independent work streams (brainstorm → impl → testing) — don't conflate them.{file} on same bead. Is this session a continuation? (default: new chain)"Neither tier matches: seq 1, parent: none.
Once chain tag resolved, launch in parallel:
| Task | Returns |
|---|---|
OV Recall (if available): /memory-recall with 2-3 keyword searches | Prior decisions, failed approaches |
| Parent Context (if parent exists): READ FULL PARENT — extract Goal, Where We Are, Key Decisions, What We Tried, Where We're Going, Open Questions, code identifiers | Parent summary for "Since Last Handoff" + identifier list |
Reference Docs: ls plans/*BIBLE* plans/*bible* *BIBLE* CLAUDE.md .claude/CLAUDE.md and read if found | Project context |
| Stale Refs (if parent): Grep each parent identifier against current codebase | List of identifiers NOT found |
Parent reading is MANDATORY when a parent exists. "Since Last Handoff" requires comparing what was planned vs what happened. Skip agents that don't apply.
If arguments were provided ($ARGUMENTS), use as a soft hint for framing. Conversation is ground truth.
Choose mining pass and announce it (this is not optional):
| Pass | When | Strategy |
|---|---|---|
| Quick | <100K context tokens | Single pass with extraction checklist below |
| Deep | 100K-500K context tokens, OR 1M context + 20+ tool calls | Two passes — read `references/mining-deep-chunked.md` |
| Chunked | 500K+ context tokens, OR 1M context + 50+ tool calls or >1hr work | Map-reduce — read `references/mining-deep-chunked.md` |
Write: "Mining with {Quick/Deep/Chunked} pass ({reason})." before starting. Don't use numeric names — they collide with chain seq numbers.
For Deep or Chunked, read references/mining-deep-chunked.md NOW for the multi-pass protocol. Don't do map-reduce from memory.
Extraction checklist (apply per pass):
If you're skimming, STOP. Re-read. Details are the value.
First directory that exists (or create plans/handoffs/):
plans/handoffs/.claude/handoffs/HANDOFF_{chain_tag}_{slug}_{YYYY-MM-DD}.md (e.g., HANDOFF_myproject-xxxx_auth-rewrite_2026-03-19.md). For multi-bead, use primary bead only.HANDOFF_{slug}_{YYYY-MM-DD}.md_2, _3, etc.Read `references/output-template.md` for the full file structure. It defines every section (Goal, Where We Are, What We Tried, Evidence & Data, etc.) with composition rules.
Check your system prompt for context window size.
| Standard (200K) | Extended (1M) | |
|---|---|---|
| Target (aim for ceiling) | 300-400 lines | 500-800 lines |
| Hard minimum | 150 lines | 250 lines |
| Light session min | 80 lines | 120 lines |
| Split threshold | 400 lines | 800 lines |
Target the CEILING. An 800-line handoff on 1M context is ~0.7% of the window — negligible cost, huge savings. Too-long is cheap; too-short costs hours of re-investigation.
Phase 1 MUST hit the pass minimum on its own — Quick: 150+ standard / 250+ extended, Deep: 300+, Chunked: 500+. Phase 1 is not a rough draft; it's the baseline. If you find yourself planning to "flesh it out in Phase 2," stop and expand the current sections before writing.
Phase 2 is for gaps, not for baseline. If Phase 2 needs to add 50+ lines to reach the minimum, Phase 1 was under-mined.
Phase 2 is MANDATORY for Deep and Chunked passes. Optional for Quick — but run it if your first pass is below the ceiling by >20%.
Splitting: only if final file exceeds threshold. Under threshold = one file.
Read `references/validation.md` and run every check. If any fails, expand thin sections before proceeding.
# Beads (if in_progress work exists)
bd update {id} --notes "Handoff written. See {file_path}"
# Memory (if bd remember available)
bd remember "Handoff: {path}. Chain: {chain_tag} seq {N}. Status: {status}. Next: {next action}"Tell the user concisely:
Ask:
Handoff complete. Ready to close this session?
>
- Yes — I'll commit, mark "session closed", give you a paste prompt for the next session. - No — We keep working. Say "close session" when done.
>
(Defaults to commit — say "close without commit" to skip.)
Based on the answer, read `references/close-session.md` and follow the flow for Yes / No / "close without commit".
When bead/epic is closed and all work is done:
# Find all handoffs for a bead or epic
grep -l 'Chain:.*{bead_id_or_epic}' plans/handoffs/HANDOFF_*.md plans/handoffs/PLAN_*.md 2>/dev/null
# Archive (don't delete — old decisions are useful)
mkdir -p plans/handoffs/archive/
mv {files} plans/handoffs/archive/~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.