olliecrow/handoff

Handoff

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous requirements, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes. Example loops (adapt as needed, not rigid): collect context -> write handoff -> verify references -> consolidate -> report.
• Keep looping until actual completion criteria are met: the handoff exists, is accurate, avoids needless duplication, and names the next useful skills.
• Run organise-docs frequently during execution when durable project knowledge should be promoted instead of left only in the handoff.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Before finishing any non-trivial task or pass, run at least one explicit consolidation pass across the touched code, docs, notes, tests, and configs.
• Use that pass to merge toward one clear source of truth, remove stale or duplicate material, and resolve contradictions before you declare the work complete.
• Do this by default as part of normal completion, even when the user did not explicitly ask for cleanup, consolidation, or contradiction resolution.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time. Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.
• Compound knowledge continuously: keep durable docs accurate, and keep the handoff focused on what another agent needs next.

Long-task checkpoint cadence

• For any non-trivial task, check whether durable facts belong in canonical docs before writing a handoff.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked, record the blocker in the handoff with the last evidence checked and the exact next step.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: a handoff file has been written at a mktemp -t handoff-XXXXXX.md path, or the task is marked blocked with concrete blocker evidence.
• Workflow completion: context review, duplicate check, handoff writing, skill suggestion, and verification are each resolved as done, blocked, or not-applicable.
• Step-level terminal completion: each workflow step has brief evidence, such as the temp path, referenced artifacts, or the reason a source was skipped.
• Verification completion: the file is read back after writing and checked against the current conversation plus any referenced artifacts.
• Reporting completion: the final user message gives the handoff path, suggested next-session skills, and any verification gap.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Terminal state examples (adapt to skill)

• done: the handoff file exists, has been read back, references existing artifacts instead of copying them, and lists next useful skills.
• blocked: the agent cannot create or read the temp file after bounded retries; the report states the failing command and the needed unblock action.
• not-applicable: no next-session skill is useful; the handoff says no skill suggestion is needed and why.

Workflow

1. Read the active conversation, current repo state when relevant, and any artifacts the conversation already created.
2. If the user passed arguments, treat them as the next session's focus and tailor the handoff to that focus.
3. Create the output path with mktemp -t handoff-XXXXXX.md.
4. Read that file before writing to it. It should normally be empty; if it is not empty, preserve or move any content before writing.
5. Write the handoff as a compact Markdown document.
6. Read the written file back and fix any mismatch, stale claim, or duplicate content.
7. Tell the user the path and the next suggested skills.

Handoff content

Include only what a fresh agent needs:

• Goal and next-session focus.
• Current state and what has already been done.
• Key files, branches, URLs, tickets, commands, jobs, or artifacts to inspect next.
• Open risks, blockers, and exact next steps.
• Verification already run and verification still missing.
• Suggested skills for the next session, with a short reason for each.

Do not duplicate content already captured in other artifacts such as PRDs, plans, ADRs, issues, commits, diffs, reports, or notebooks. Reference those by path or URL instead.

Output shape

Use this compact shape unless the task clearly needs another one:

# Handoff

## Next focus

## Current state

## Existing artifacts

## Open items

## Suggested skills

## Verification

Keep the document short, direct, and specific. Prefer links and paths over copied detail.

Skill composition

When this skill is triggered, compose other skills as needed:

• Use organise-docs first when the conversation contains durable project knowledge that belongs in long-lived docs, not only in a temp handoff.
• Use summarize when the conversation is long or messy and needs a brief first pass before writing the final handoff.
• Use verify when the handoff depends on current code, tests, job state, or external artifacts that may have changed.
• Use git-summary when the next session is mainly about a branch or PR and the branch delta is the best source of truth.

If there is a conflict, durable canonical artifacts win. The handoff should point to them and only add the live state needed for the next agent.