Ctrl K

Quick Ref / Command

Engineer Kit

/ak:handoff

Agent Continuation Contract

Create one redacted Markdown handoff that lets a fresh coding agent resume safely, with mission, guardrails, workspace state, decisions, verification, blockers, exact next actions, and source pointers.

Identify reader

Resolve destination

Probe read-only state

Separate evidence

Rule 01

Write a continuation contract, not a transcript dump.

Rule 02

Prefer observed workspace facts and explicit uncertainty over invented continuity.

Rule 03

Redaction and collision safety are part of the artifact, not optional polish.

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

Start

Input, scope, route

1 Identify reader Use handoff when the next reader is another coding agent continuing this exact task; use watzup for human project status.
2 Resolve destination Write plans/handoffs/<slug>-<YYYYMMDD-HHmm>.md under an existing plans root, or a workspace-local --output path. Ask before writing if no plans root exists. Also scan legacy plans/reports/handoff-*.md.

Work

Agent / skill execution

3 Probe read-only state Collect git root, branch, HEAD, status, and optional bounded diff/status evidence without mutating the repo.
4 Separate evidence Distinguish observed facts from session assertions, and use “Not captured in this session” for unknown sections.

Verify

Gate, review, validation

5 Fill report schema Include the verified handoff content: title, time, focus, goal, current state, decisions and rejected approaches, verification, files and pointers, open work, and a fresh-agent prompt.
6 Redact secrets Pass the artifact and optional diff/status through the redaction catalog for tokens, cookies, keys, credentials, private URLs, and personal data.

Report, handoff, artifact

7 Guard collisions Refuse an existing target unless --force is explicitly present; never rename or delete silently.
8 Write matching outputs Return one fenced Markdown block in the response and save the same content as the timestamped report.

Syntax, arguments, subcommands

How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.

Syntax

/ak:handoff [task focus] [--output PATH] [--include-diff] [--include-status] [--force] [--dispatch --agent <id> [--handoff PATH] [--cwd PATH] [--model NAME] [--yes]]

Arguments

[task focus]

Next-session focus

Optional one-line focus for the successor agent. It is used in the Mission section and filename slug after credential-looking values are refused.

/ak:handoff "Continue the authentication migration after the failing integration test is diagnosed"

Shared options

--output PATH

Exact output path

Write the handoff to this workspace-local path instead of the auto timestamped plans/reports path. It does not imply overwrite permission.

/ak:handoff --output plans/handoffs/oauth-callback.md

--include-diff

Include diff evidence

Append redacted git diff --stat and the first 200 diff lines, with truncation marked when the diff is longer.

/ak:handoff --include-diff --include-status

--include-status

Include status snapshot

Append a redacted git status --short snapshot without turning the handoff into a full repository status report.

/ak:handoff --include-status

--force

Allow overwrite

Explicitly allow overwriting an existing handoff target. Without it, an existing file is refused with guidance.

/ak:handoff --force --output plans/handoffs/oauth-callback.md

--dispatch

Dispatch after capture

After a valid capture, hand that one artifact to ak:orchestrate. Requires --agent. Stops after capture when ak:orchestrate is not installed.

/ak:handoff --dispatch --agent claude-code "continue the OAuth callback fix"

--agent <id>

Selected runtime

Required with --dispatch. Must match a catalog runtime id. No default and no silent substitution.

/ak:handoff --dispatch --agent codex

--handoff PATH

Reuse artifact

Dispatch an existing handoff file instead of capturing a new one. The file must exist and pass section and redaction checks.

/ak:handoff --dispatch --agent cursor --handoff plans/handoffs/oauth-callback.md

--cwd PATH

Dispatch workspace

Workspace root passed to the orchestrate job. Defaults to the current workspace. --cwd . on a clean tree keeps isolation off worktree.

/ak:handoff --dispatch --agent codex --cwd .

--model NAME

CLI model override

Overrides the model for a CLI runtime job. Rejected when --agent is internal.

/ak:handoff --dispatch --agent opencode --model anthropic/claude-sonnet-5 --yes

--yes

Inherit write approval

Sets the dispatched job approval from require to inherit. Destructive scope classifications stay require.

/ak:handoff --dispatch --agent opencode --yes

Don't skip the required step

Each item contrasts a tempting shortcut with the required approach.

Tempting shortcut

The transcript has everything; paste it.

Do this instead

Never dump raw transcripts or hidden reasoning; capture only actionable continuation facts.

Tempting shortcut

The path exists; overwrite it.

Do this instead

Existing targets require explicit --force.

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

Bare capture Recommended

/ak:handoff

Use when:: You are about to switch sessions and need a successor-ready contract.
Expected:: Creates a workspace-local plans/reports Markdown artifact with the verified handoff schema, fills unknowns as “Not captured in this session,” and returns the same content as a fenced Markdown block.

Focused handoff

/ak:handoff "continue the OAuth callback fix"

Use when:: The successor should focus on one known thread of work.
Expected:: Screens the focus for credential-looking values, then uses the safe text in the Mission section and filename slug so the successor agent knows the exact thread to resume.

Explicit artifact

/ak:handoff --output plans/handoffs/oauth-callback.md

Use when:: You need a stable handoff path instead of an auto timestamped slug.
Expected:: Writes to the exact workspace-local path and creates the parent directory if needed; if that target already exists, it refuses with mtime guidance unless --force is explicitly added.

Dispatch one runtime

/ak:handoff --dispatch --agent claude-code "continue the OAuth callback fix"

Use when:: The captured contract should be handed to one selected coding runtime, not left as a file.
Expected:: Captures and validates the handoff, builds one orchestrate job, dispatches that runtime, and prints the artifact path, run directory, resolved runtime, and job result.

Dirty-worktree evidence

/ak:handoff --include-diff --include-status

Use when:: The successor needs bounded, redacted workspace evidence about modified or untracked files.
Expected:: Adds redacted git status --short plus git diff --stat and the first 200 diff lines with truncation marked, while keeping the main handoff schema and return value unchanged.

Handled Scope

Session continuation capture
Redacted state summaries
Exact next action handoffs
Workspace-local Markdown artifacts

Artifacts Produced

Handoff report output

Pattern

One fenced Markdown block in the response, matching the content saved to the timestamped report.

The response block and saved report must match, and redacted values must not be reconstructable.