/aide:handoff — Session Handoff

Record current pipeline state to .aide/session.aide. This skill owns the orchestration; the aide-spec-writer agent owns the actual file write (it transcribes orchestrator-supplied state into the canonical format). Nothing deletes session.aide; it is long-lived and rewritten as features close. See session.aide spec for the file format.

Hard constraints

• You do NOT write .aide/session.aide yourself. The actual file write belongs to aide-spec-writer. This skill describes the orchestration that surrounds the delegation.
• You do NOT invent content. The invoking agent (orchestrator or other) holds the conversation context — current stage, settled decisions, where work paused, anti-regression invariants. That context is the content source. Write what it supplies; leave the rest empty — never fabricate state, and never hold the write back for content you don't have.
• You do NOT delete .aide/session.aide. Nothing does. This skill is exclusively for create/update.

Checklist

• Make sure the file exists. It always should — aide_init and the /aide boot create the empty placeholder with aide_scaffold type=session. If .aide/session.aide is missing anyway, call aide_scaffold({ directory: ".", type: "session" }) first — the placeholder's single source; it never overwrites. Then continue.

• Gather content from conversation context. Every handoff is an UPDATE. Supply whatever you have, section by section:

  • the change description (what happened)
  • section-targeted edits, e.g. "fill the intent with: ...", "append decision #4: ...", "rewrite ## Where this cycle stopped to: ..."
  • numbered references to preserve (decision #N stays stable across edits)
  • when a task was created, moved, finished, or newly tied to the work, the matching ## Kanban edit

  The first handoff after the placeholder fills in whatever is known: the one-line intent, the state summary, where the cycle stopped and the next steps, what is done, decisions, invariants, open questions. A missing piece is not a reason to wait. Write what you have now; empty sections stay empty until there is something true to put in them.

• Keep it the full session record. session.aide holds what was done, every decision, what is validated and what comes next, in full. A fresh agent reading only this file must know where everything stands. Stashing into the task through the kanban skill still happens alongside, but never in place of the detail here.
• Link tasks when there are tasks. Every task tied to the work goes into ## Kanban by slug, column and what it covers. The slug is the stable link — the kanban skill finds the task by slug in whatever column it sits. Work with no task is still recorded: never hold a handoff back until a task exists. If it is trackable work, ask the user whether to create a task for it, and link it once it exists.
• Delegate to aide-spec-writer via the Agent tool (subagent_type: aide-spec-writer). The delegation prompt MUST:
  • Name the operation type explicitly — session.aide UPDATE. The spec-writer's default operation is .aide frontmatter; naming the operation is mandatory for correct dispatch.
  • Quote all supplied content verbatim — the spec-writer transcribes; it never invents.
• Receive the verdict — UPDATED. A REFUSED only means the prompt was ambiguous about which section an edit belongs to; clarify and re-delegate.
• Confirm completion and continue with whatever pipeline work was in flight before the handoff was invoked.

What this skill does NOT do

• It does not interview the user. The invoking agent holds the conversation context; this skill only formats it into a delegation prompt for aide-spec-writer.
• It does not apply the Brevity Contract. session.aide is operational state, not durable intent — no caps on description, no word counts, no forbidden-content rules from the .aide body. The Brevity Contract is .aide-only.
• It does not delete session.aide. Nothing does — at feature close, UPDATE it for the next task.
• It does not bypass aide-spec-writer. The skill is the orchestration layer; the agent owns the file write. Calling Write/Edit on .aide/session.aide directly from this skill violates the delegation pattern.