Document Handoff

document-handoff

Produce a self-contained handoff package: a curated workfolder copy of project files plus a dark-mode HTML memo covering 16 structured sections. Enables any agent to cold-start on the project without re-reading sessions.

Announce at start: "I'm using the document-handoff skill to create a project handoff package."

Prerequisites

Resolve the CLI path once at session start:

$cli = (Get-ChildItem "$env:USERPROFILE\.claude\plugins\cache" -Recurse -Filter "cli.mjs" -ErrorAction SilentlyContinue |
  Where-Object { $_.FullName -match [regex]::Escape("document-handoff\scripts") } |
  Select-Object -First 1).FullName

if (-not $cli) {
  $cli = (Get-ChildItem "$env:USERPROFILE\.claude\skills" -Recurse -Filter "cli.mjs" -ErrorAction SilentlyContinue |
    Where-Object { $_.FullName -match [regex]::Escape("document-handoff\scripts") } |
    Select-Object -First 1).FullName
}
if (-not $cli) {
  # Codex skill install: respects CODEX_HOME env var
  $codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$env:USERPROFILE\.codex" }
  $cli = (Get-ChildItem "$codexHome\skills" -Recurse -Filter "cli.mjs" -ErrorAction SilentlyContinue |
    Where-Object { $_.FullName -match [regex]::Escape("document-handoff\scripts") } |
    Select-Object -First 1).FullName
}
if (-not $cli) {
  # Legacy: Codex plugin cache
  $cli = (Get-ChildItem "$env:USERPROFILE\.codex\plugins" -Recurse -Filter "cli.mjs" -ErrorAction SilentlyContinue |
    Where-Object { $_.FullName -match [regex]::Escape("document-handoff\scripts") } |
    Select-Object -First 1).FullName
}
if (-not $cli) { Write-Error "document-handoff cli.mjs not found. Install via: claude skills install / codex skills install"; return }

Collect Inputs

Ask the user (or infer from context):

1. Project slug — short name used in output file names (e.g. my-project)
2. Source root — absolute path to the project directory to archive
3. Output directory — where to write the workfolder and memo. Honor the active harness/session output policy when one exists; otherwise default to <source_root>\.handoff-output.
4. Fresh or resume? — --fresh overwrites existing state; --resume continues from last completed phase

Provider detection note: The default session adapters discover Claude Code and Codex. A session-capture JSON file can also enable Kimi Code, Hermes SQLite, or declared JSONL/supporting sources from another harness. See references/session-capture.md.

$slug = "<project-slug>"
$sourceRoot = "<absolute-path-to-project>"
$outputDir = "$sourceRoot\.handoff-output"
$statePath = "$outputDir\.handoff\state.json"

Phase 0 — Initialize

node --no-warnings $cli init --project $slug --source-root $sourceRoot --output-dir $outputDir --fresh

For multi-harness or explicit-source capture, add --session-config <absolute-path-to-config.json>.

Phase 1 — Discover

node --no-warnings $cli discover --state $statePath

GATE: Review $outputDir\.handoff\catalog.html in a browser. For each high-risk file listed as excluded:

• If you need it: open $outputDir\.handoff\catalog.json, set "action": "copy" on that entry, save.
• If excluded files are correct: proceed.

Type PROCEED to continue.

Phase 2 — Populate

node --no-warnings $cli populate --state $statePath

Phase 3 — Extract Sessions

node --no-warnings $cli extract-sessions --state $statePath

Unless capture_raw:false is configured, this phase also creates content-addressed raw evidence under .handoff/session-evidence/. Active JSONL logs are captured as verified complete-record prefixes; Hermes sessions are exported from a read transaction. This phase does not add an ACL or privacy-classification gate.

GATE: Review the sessions listed above. Confirm these are the right sessions for this project.

If sessions are missing: they may not have a matching cwd in their metadata. You can manually add session entries to $statePath under sessions_found.

Type PROCEED and set sessions_validated: true in state, or edit state manually.

Phase 4 — Synthesize

node --no-warnings $cli synthesize --state $statePath

Phase 5 — Sections (GATE — no script)

Review $outputDir\.handoff\synthesis.md. The skill will write these 16 sections:

bootstrap, executive-summary, deliverables, current-state, technical-decisions, challenges-blockers, next-steps, context-sources, open-questions, dependencies, environment, testing, architecture, data-flow, changelog

Plus privacy-security if any risk-flagged files were found.

GATE: Confirm the section list or remove any sections you don't need.

Type PROCEED to render.

Phase 6 — Render Memo

node --no-warnings $cli render-memo --state $statePath

Open $outputDir\$slug-memo.html in a browser to preview.

Phase 7 — Verify

node --no-warnings $cli verify --state $statePath

Review $outputDir\.handoff\verification.json. If overall: false, fix the reported issues and re-run this phase.

Outputs