quantumbitcz/forge-handoff
skills/forge-handoff/SKILL.md
[writes] Create, list, show, resume, or search forge session handoffs. Use when context is getting heavy and you want to transfer a forge run or conversation into a fresh Claude Code session, or to resume from a prior handoff artefact. Subcommands - no args (write), list, show, resume, search.
development
Updated Apr 23, 2026
$ install --global
skillsauthnpx skillsauth add quantumbitcz/dev-pipeline forge-handoffInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 23, 2026, 10:48 AM269.3s1 file scanned
SKILL.md
- name:
- forge-handoff
- description:
- [writes] Create, list, show, resume, or search forge session handoffs. Use when context is getting heavy and you want to transfer a forge run or conversation into a fresh Claude Code session, or to resume from a prior handoff artefact. Subcommands - no args (write), list, show, resume, search.
- allowed-tools:
- ['Read', 'Bash', 'AskUserQuestion']
- ui:
- { ask: true }
/forge-handoff
Manage forge session handoffs — structured artefacts that preserve run state for continuation in a fresh Claude Code session.
Flags
- --help: print usage and exit 0
- --run <id>: (list only) scope to a specific run_id
Exit codes
See shared/skill-contract.md for the standard exit-code table.
Subcommand dispatch
| Invocation | Behaviour |
|-------------------------------------------------|---------------------------------------------------------------------------|
| /forge-handoff | Write a full-variant manual handoff for the current run |
| /forge-handoff list [--run <id>] | List handoff chain for the current or specified run |
| /forge-handoff show <path\|latest> | Print a handoff's contents (latest = most recent for current run) |
| /forge-handoff resume [<path>] | Structured resume — parses, checks staleness, seeds state, delegates |
| /forge-handoff search <query> | FTS5 full-text search across all handoffs in run-history.db |
Subcommand: write (no args)
Writes a full-variant handoff for the current run (if any). In interactive mode, uses AskUserQuestion to confirm slug and variant. In autonomous mode, silently writes.
Calls: python3 -m hooks._py.handoff.cli write --level manual
Subcommand: list
Lists handoff chain for the current run or the specified run.
Calls: python3 -m hooks._py.handoff.cli list [--run <id>]
Subcommand: show
Prints a handoff's contents to stdout. latest picks the most recent handoff for the current run.
Calls: python3 -m hooks._py.handoff.cli show <path|latest>
Subcommand: resume
Structured resume. Parses handoff, checks staleness, seeds state.json, delegates to /forge-recover resume <run_id>. With no args, picks the most recent un-SHIPPED handoff.
Calls: python3 -m hooks._py.handoff.cli resume [<path>]
Subcommand: search
FTS5 full-text search over all handoffs in run-history.db.
Calls: python3 -m hooks._py.handoff.cli search "<query>"
Instructions
Route the user invocation to the matching subcommand via python3 -m hooks._py.handoff.cli. Surface the CLI's stdout to the user. When resume returns a run_id, delegate to /forge-recover resume <run_id> so the orchestrator picks up from the seeded checkpoint.
Behaviour
- Path:
.forge/runs/<run_id>/handoffs/YYYY-MM-DD-HHMMSS-<level>-<slug>.md - Levels:
soft,hard,milestone,terminal,manual - File survives
/forge-recover reset - Config: see
shared/preflight-constraints.md#handofffor defaults - Spec: see ADR
docs/adr/0012-session-handoff-as-state-projection.md
Error Handling
| Condition | Action | |-----------------------------------------------|---------------------------------------------------------------------| | No active forge run | Report "No active run. Nothing to hand off." STOP | | Handoff file missing (show/resume) | CLI exits non-zero; surface "Handoff not found: <path>" and STOP | | Stale handoff (git_head drift, checkpoint gap)| Resumer returns STALE verdict; ask user to confirm or abort | | Rate limit hit (manual writes) | CLI emits "Rate limited — 15min window"; STOP unless terminal level | | Redaction pattern match | Handoff is written with secret redacted inline; no user prompt | | FTS5 index corrupt | Search returns empty result set with stderr warning; STOP |
See Also
/forge-recover— structured continuation from a checkpoint (useresumesubcommand)/forge-status— current run state
Design references (not skills): see preflight-constraints.md section handoff for config defaults, and ADR 0012-session-handoff-as-state-projection.md for design rationale.
Examples
# Write a handoff now
/forge-handoff
# List all handoffs for current run
/forge-handoff list
# Resume from a specific handoff
/forge-handoff resume .forge/runs/20260421-a3f2/handoffs/2026-04-21-143022-soft-add-health.md
# Resume from latest (auto-pick)
/forge-handoff resume
# Find past discussions
/forge-handoff search "cache layer decision"
Related Skills
quantumbitcz/forge
development
VerifiedTrustedCommunity
[writes] Build, fix, deploy, review, or modify code in this project. Universal entry for the forge pipeline. Auto-bootstraps on first run; brainstorms before planning when given a feature description. Use when you want to take any productive action: implementing features, fixing bugs, reviewing branches, deploying, committing, running migrations.
SKILL.mdUpdated Apr 30, 2026
quantumbitcz/forge-admin
tools
VerifiedTrustedCommunity
[writes] Manage forge state and configuration: recovery, abort, config edits, session handoff, automations, playbooks, output compression, knowledge graph maintenance. Use when you need to recover from broken pipeline state, edit settings, or manage long-lived state.
SKILL.mdUpdated Apr 30, 2026
quantumbitcz/forge-graph
development
VerifiedTrustedCommunity
[writes] Manage the Neo4j knowledge graph. Subcommands: init, rebuild (writes); status, query <cypher>, debug (read-only). Requires Docker. No default — an explicit subcommand is required. Use when setting up the graph for the first time, rebuilding after major refactors, checking graph health, or running ad-hoc Cypher diagnostics.
SKILL.mdUpdated Apr 21, 2026
quantumbitcz/forge-recover
testing
VerifiedTrustedCommunity
[writes] Diagnose or fix pipeline state — read-only diagnose (default), repair counters/locks, reset clearing state while preserving caches, resume from checkpoint, rollback worktree commits, rewind to any prior checkpoint (time-travel), or list the checkpoint DAG. Use when pipeline stuck, failed with state errors, or you need to explore alternate execution paths. Trigger: /forge-recover, diagnose state, repair pipeline, reset state, resume from checkpoint, rollback commits, rewind checkpoint, time travel, list checkpoints
SKILL.mdUpdated Apr 20, 2026