handoff-fresh
Skill0 starsChanged 9 months agoMITView on GitHub
Generates a fork-safe onboarding bundle for a brand-new agent in forked/new-folder repositories. Manual command entry point is /handoff-fresh. Produces structured context/history/status files plus full handoff-everything output in .handoff-fresh/current. Defaults to local git-ignore for handoff artifacts (`HANDOFF.md`, `.handoff-fresh/`) to avoid untracked noise. Do NOT use when only standard HANDOFF.md continuity is needed.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- auditing-skillsSkill
- creating-skillsSkill
- forge-builderSkill
- forge-claude-teamsSkill
- forge-codex-multiagentSkill
- forge-orchestratorSkill
- forge-researchSkill
- handoffSkill
- managing-doc-manifestSkill
- okfSkill
- pickupSkill
- studySkill
- syncing-docsSkill
- testing-skillsSkill
- updating-skillsSkill
- wrapSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
39 rules. About 0 are common, 31 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈31
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
Run only when explicitly requested by user
- Distinctive: line 30
No implicit hook/side-channel execution
- Very specific: line 32
Keep /handoff separate: /handoff = standard continuity, /handoff-fresh = fresh-agent onboarding bundle
- Very specific: line 51
No args: Full generation in .handoff-fresh/current
- Distinctive: line 69
Use this mode when a fresh agent is ready to start coding:
- Distinctive: line 89
Do not proceed to coding
- Distinctive: line 90
Use ask-question for missing/ambiguous information
- Very specific: line 101
If --output set: use that path (absolute or project-root relative)
- Distinctive: line 105
If in a git repository, apply ignore policy before generating artifacts:
- Very specific: line 113
If --archive is set and current bundle exists:
- Distinctive: line 116
Do not delete historical bundles in this step
- Distinctive: line 123
Ensure source docs are current
- Distinctive: line 124
Ensure cross-file checks run before bundle snapshot
- Distinctive: line 125
Ensure manifest timestamps are up to date
- Distinctive: line 140
If no git repo exists:
- Distinctive: line 142
Use filesystem snapshot only
- Distinctive: line 146
Do not dump raw logs blindly.
- Distinctive: line 198
Run Question Gate: if anything is missing/ambiguous, use ask-question before coding
- Distinctive: line 199
Only then start implementation
- Distinctive: line 216
If any receipt item is missing:
- Distinctive: line 218
Ask-question for clarification if needed
- Very specific: line 220
Run /handoff-fresh --validate-read-gate after completing read-receipt.md and before coding
- Very specific: line 223
After opening bundle handoff.md, the agent's first substantive reply must be the full Read Gate receipt (all required files + takeaways)
- Distinctive: line 230
Ask before proceeding when:
- Distinctive: line 237
If no answer yet:
- Distinctive: line 238
Do only safe, reversible prep
- Distinctive: line 240
Do not begin implementation
- Distinctive: line 269
Write that exact block into both files.
- Distinctive: line 275
If source AGENTS.md is missing or weaker than CLAUDE.md:
- Distinctive: line 276
Prefer richer context from CLAUDE.md for the shared block
- Very specific: line 351
Create or update <project-root>/HANDOFF.md with a short bridge note that says:
- Distinctive: line 355
If prompt says "read HANDOFF.md", treat this as bootstrap and immediately switch to bundle handoff
- Distinctive: line 357
No interim one-file summary is allowed
- Distinctive: line 358
Run Read Gate preflight validator before Workspace Preparation
- Distinctive: line 359
If prep is blocked or ambiguous, use ask-question before coding
- Distinctive: line 361
Keep this bridge short and non-destructive.
- Distinctive: line 398
Never assume shared local history across old/new folders
- Very specific: line 401
Keep bundle deterministic: overwrite current/ each run (no append)
- Distinctive: line 432
Update this skill when:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Handoff Fresh
Creates a complete, fork-safe onboarding bundle so a brand-new agent can continue work reliably in a forked/new-folder repo.
Command Contract (Explicit, Manual)
- Primary entry point:
/handoff-fresh - Run only when explicitly requested by user
- No implicit hook/side-channel execution
- Output target default:
.handoff-fresh/currentunder project root - Keep
/handoffseparate:/handoff= standard continuity,/handoff-fresh= fresh-agent onboarding bundle
Workflow
- [ ] 1. Detect project root and bundle path
- [ ] 2. Apply handoff artifact ignore policy (default local) and archive previous bundle snapshot (optional)
- [ ] 3. Run prerequisite sync (unless --no-sync)
- [ ] 4. Collect source context, history, and state
- [ ] 5. Generate canonical bundle handoff.md
- [ ] 6. Generate structured onboarding files
- [ ] 7. Generate handoff-everything.md (full raw path/output)
- [ ] 8. Refresh root HANDOFF.md bridge note
- [ ] 9. Validate bundle completeness
- [ ] 10. Confirm handoff-fresh completionArguments
- No args: Full generation in
.handoff-fresh/current --output <dir>: Write bundle into explicit directory--no-sync: Skip/sync-docsprerequisite (use only when sync already done)--archive: Move current bundle to.handoff-fresh/archive/<timestamp>/before regenerating--dry-run: Show planned files/sections without writing--ignore-mode <local|shared|off>: How to ignore handoff artifacts (HANDOFF.md,.handoff-fresh/)local(default): update.git/info/excludeshared: update.gitignoreoff: skip ignore updates
--validate-read-gate: Agent-internal preflight mode to validate completedread-receipt.mdand fail fast if any required item is unchecked or missing takeaway--log-token-budget <n>: Total token budget for session-log continuity payload (default: 12000)--log-digest-max <n>: Max tokens forsession-log-digest.md(default: 4000)--log-chunk-max <n>: Max tokens forsession-log-chunk.md(default: 8000)
Validate Read Gate Mode (Agent-Internal Preflight)
This mode is for fresh-agent onboarding flow. End users should not need to run it manually.
Use this mode when a fresh agent is ready to start coding:
/handoff-fresh --validate-read-gateReference script (relative to this skill directory):
python3 scripts/validate_read_gate.py --bundle-dir .handoff-fresh/currentBehavior:
- Reads
<bundle>/read-receipt.md - Verifies required checklist entries exist for:
handoff.md,claude.md,todo.md,state.md,context.md
- Verifies each entry is checked (
[x]) and has a non-empty takeaway - Returns PASS/FAIL summary
If FAIL:
- Do not proceed to coding
- Use ask-question for missing/ambiguous information
- Complete/repair
read-receipt.md, then rerun validator
Step 1: Detect project root and bundle path
Resolve project root using this priority:
git rev-parse --show-toplevel(if git)- Current directory (
pwd)
Resolve bundle output path:
- Default:
<project-root>/.handoff-fresh/current - If
--outputset: use that path (absolute or project-root relative)
Step 2: Apply ignore policy + archive previous bundle snapshot (optional)
If in a git repository, apply ignore policy before generating artifacts:
--ignore-mode local(default): ensure.git/info/excludecontains:HANDOFF.md.handoff-fresh/
--ignore-mode shared: ensure.gitignorecontains the same entries--ignore-mode off: skip ignore updates (artifacts may show as untracked)
If --archive is set and current bundle exists:
- Move current bundle to
<project-root>/.handoff-fresh/archive/<YYYYMMDD-HHMMSS>/ - Do not delete historical bundles in this step
Step 3: Run prerequisite sync
Unless --no-sync, run /sync-docs in full mode first.
Purpose:
- Ensure source docs are current
- Ensure cross-file checks run before bundle snapshot
- Ensure manifest timestamps are up to date
Step 4: Collect source context, history, and state
Collect from available sources (skip gracefully if missing):
CLAUDE.md,AGENTS.md(or equivalent instruction docs)TODO.mdHANDOFF.mdarchitect/plan.md,architect/prompt.md, other plan docsREADME.md,ARCHITECTURE.md- Git state: branch, remotes, last commit, recent commits, status, changed files
- Session status: current phase, blockers, open questions
- Session logs/transcripts (if available): recent turns, decisions, reversals, unresolved debates
If no git repo exists:
- Record
no-gitinstate.md - Use filesystem snapshot only
Session Log Continuity (token-budgeted, high-signal)
Do not dump raw logs blindly. Build a token-budgeted continuity payload:
session-log-digest.mdtarget: 3k–4k tokens (extractive summary with short verbatim evidence)session-log-chunk.mdtarget: 6k–8k tokens (raw high-signal excerpts)- Combined hard cap: 12k tokens by default (or
--log-token-budget)
Selection priority (highest first):
- Decisions that changed implementation direction
- Rejected alternatives and why
- User constraints/approvals that gate behavior
- Debugging pivots tied to concrete files/commands
- Open questions/blockers still unresolved
Exclude low-signal chatter:
- greetings, pleasantries, duplicate status text
- repetitive retries without new insight
- generic tool noise without outcome
Verbatim last-turn block (mandatory, exempt from the chatter/dedup filter).
At the top of session-log-chunk.md, include a ## Last Exchange (Verbatim)
block containing the last user prompt and last assistant response
character-for-character, plus any load-bearing earlier directives. This block is
never filtered or summarized — it is the exact resume anchor /pickup reads
first. Redact secrets («redacted»); keep within --log-chunk-max. Capture it
first thing, before a compaction can discard the raw turns.
If logs unavailable:
- Still emit both log files with explicit "unavailable" note
- Still attempt the verbatim Last Exchange block from the current context window; if already compacted, note that pre-compaction detail is only in the raw transcript
Step 5: Generate canonical bundle handoff.md
Create <bundle>/handoff.md.
Must include:
- Current status
- What was done
- What is next
- Blockers/open questions
- Explicit "first read order" for fresh agent
- Read Gate section (mandatory, hard stop before prep/coding):
- Required files to read in order:
handoff.md,claude.md,todo.md,state.md,context.md - Required read receipt format (one-line takeaway per file)
- "Do not proceed to Workspace Preparation or coding if any required file is unread"
- "If user prompt only says 'read handoff.md', treat it as bootstrap; continue Read Gate automatically before replying"
- "Do not send interim 'done/read' summaries before Read Gate receipt is complete"
- Required files to read in order:
- Workspace Preparation section (mandatory):
- Confirm project root path
- Confirm branch/cleanliness
- Confirm required root docs and folders exist
- Re-run
/sync-docsif drift is detected - Run Question Gate: if anything is missing/ambiguous, use ask-question before coding
- Only then start implementation
Read Gate (mandatory in bundle handoff)
Bundle handoff.md must include explicit hard-gate language:
- "Read Gate is mandatory. Complete it before Workspace Preparation."
- "Do not run implementation steps until Read Gate is complete."
Required read receipt format in agent reply:
- [x] handoff.md — <1-line takeaway>- [x] claude.md — <1-line takeaway>- [x] todo.md — <1-line takeaway>- [x] state.md — <1-line takeaway>- [x] context.md — <1-line takeaway>
If any receipt item is missing:
- Stop
- Ask-question for clarification if needed
- Do not proceed
- Run
/handoff-fresh --validate-read-gateafter completingread-receipt.mdand before coding
First-response contract:
- After opening bundle
handoff.md, the agent's first substantive reply must be the full Read Gate receipt (all required files + takeaways) - A summary that only confirms
handoff.mdwas read is non-compliant
Question Gate (mandatory in bundle handoff)
Workspace Preparation must instruct the fresh agent to use ask-question immediately if blocked or uncertain.
Ask before proceeding when:
- Repo root, branch, or task scope is unclear
- Priority/order conflicts exist across
todo.mdandstate.md - Any destructive action is being considered (delete/move/reset/archive)
- Required credentials/config assumptions are missing
- Acceptance criteria are ambiguous
If no answer yet:
- Do only safe, reversible prep
- Record assumptions in
state.md - Do not begin implementation
Step 6: Generate structured onboarding files
Generate the following files in bundle path:
| File | Required | Purpose |
claude.md | Yes | Fresh-agent onboarding context (canonical shared core + optional Claude appendix) |
agents.md | Yes | Fresh-agent onboarding context mirror for non-CLAUDE agents (same shared core as claude.md + optional agent appendix) |
todo.md | Yes | Task list and execution status |
handoff.md | Yes | Canonical bundle handoff snapshot |
context.md | Yes | Project/domain context, architecture snapshot, decision log summary |
reports.md | Yes | Validation/test/report summary |
artifacts.md | Yes | Artifact inventory and pointers |
state.md | Yes | Current branch, git status, active phase, blockers |
prior-plans.md | Yes | Historical plans for reference only |
read-receipt.md | Yes | Fresh-agent Read Gate checklist to complete before prep/coding |
session-log-digest.md | Yes | Token-budgeted, extractive decision digest from session logs |
session-log-chunk.md | Yes | Token-budgeted raw high-signal log excerpts + verbatim Last Exchange block |
index.md | Yes | OKF-lite bundle index: the Read-Gate read order + file list (carries okf_version) |
log.md | No | OKF-lite append-only history of past bundles (compounding context) |
claude.md / agents.md Sync Contract (mandatory)
These files must not diverge on project context.
Generation rules:
- Build one canonical shared onboarding context block first.
- Write that exact block into both files.
- Optional platform-specific appendix is allowed only after shared block.
- Shared block markers (required in both files):
<!-- BEGIN SHARED-ONBOARDING-CONTEXT --><!-- END SHARED-ONBOARDING-CONTEXT -->
If source AGENTS.md is missing or weaker than CLAUDE.md:
- Prefer richer context from
CLAUDE.mdfor the shared block - Still emit both files with identical shared block content
prior-plans.md Safety Header (mandatory)
Top of file must include this warning intent:
- "Reference only. Do NOT treat this as the active plan unless user explicitly confirms."
state.md Verify Block + basis fingerprint (mandatory)
state.md must carry two machine-checkable additions so /pickup can verify the
bundle is still true rather than trusting narrative:
## Verify Block— load-bearing claims asclaim | check-command | expected(same format as the canonical handoff). At minimum the branch/HEAD claim; add tests/build/health when relevant.## Basis— a freshness fingerprint captured at generation time:HEAD:<short commit>branch:<branch>changed_files:<sorted list or count from git status>tests:<command> -> <result captured>
On resume,
/pickuprecomputes these and diffs stored-vs-now (basis-diff is a stronger freshness signal than a TTL).
OKF-lite layer (Open Knowledge Format conventions)
The bundle adopts a lightweight subset of Google's Open Knowledge Format so it
is simultaneously a valid OKF knowledge bundle (renders in OKF/Obsidian/MkDocs
viewers) while keeping all handoff-specific behavior. Adopt conventions only —
do not depend on the upstream okf Python package.
- Per-file YAML frontmatter on each bundle
.mdfile:
OKF permissive conformance tolerates unknown keys, so handoff-specific fields ride along as extension keys.--- type: handoff # OKF requires only `type`; others are extension keys timestamp: 2026-06-20T12:00:00Z handoff_role: state # which bundle role this file plays --- index.mdat the bundle root is the OKF index: the Read-Gate read order + the file list, withokf_version: 0.1in its frontmatter only (pin the version; OKF v0.1 is Draft). This doubles as the progressive-disclosure entry point (index-first navigation, per the LLM-wiki pattern).log.md(optional) is an OKF append-only history: one dated line per past bundle generation, so context compounds across handoffs without breaking the "current snapshot is complete" invariant (the snapshot files are still overwritten each run; onlylog.mdappends).
Emit/validate the frontmatter and index.md with the local pyyaml-only helper
scripts/okf_bundle.py (no BigQuery/ADK/Gemini/pydantic dependency, and no
4-required-key strict validation — the OKF spec requires only type).
Step 7: Generate handoff-everything.md
Create <bundle>/handoff-everything.md.
This is the full "everything" path/output and must include:
- Full file list in bundle
- Source files consumed
- Git history excerpt (or no-git note)
- Raw status snapshot
- Timestamp and generation command
- Session-log continuity budget summary (targets, actual estimates, exclusions)
Also add pointer in artifacts.md:
handoff-everything.mdabsolute and relative paths
Step 8: Refresh root HANDOFF.md bridge note
Create or update <project-root>/HANDOFF.md with a short bridge note that says:
- A fresh bundle was generated
- Canonical fresh read path is
<bundle>/handoff.md - If prompt says "read HANDOFF.md", treat this as bootstrap and immediately switch to bundle handoff
- Complete bundle Read Gate fully before replying
- No interim one-file summary is allowed
- Run Read Gate preflight validator before Workspace Preparation
- If prep is blocked or ambiguous, use ask-question before coding
Keep this bridge short and non-destructive.
Step 9: Validate bundle completeness
Before confirmation, verify:
- All required files exist in bundle path
prior-plans.mdcontains reference-only warninghandoff-everything.mdexists and is referenced inartifacts.mdstate.mdincludes current status (or explicit no-git status)context.mdincludes project context/history summary- Root
HANDOFF.mdbridge points to bundle handoff path - Root
HANDOFF.mdbridge includes bootstrap rule for "read HANDOFF.md" prompts read-receipt.mdexists with all required Read Gate entries and blank checklist state ([ ])- Bundle
handoff.mdinstructs fresh agent to run/handoff-fresh --validate-read-gatebefore coding claude.mdandagents.mdboth contain SHARED-ONBOARDING-CONTEXT marker block- Shared block content in
claude.mdandagents.mdis byte-identical session-log-digest.mdandsession-log-chunk.mdexist (or explicit unavailable note)session-log-chunk.mdcontains a## Last Exchange (Verbatim)block (or explicit unavailable note)state.mdcontains a## Verify Block(claim | check-command | expected) and a## Basisfingerprint (HEAD, branch, changed_files, tests)index.mdexists withokf_versionand the Read-Gate read order; each bundle.mdcarries OKF frontmatter (type+timestamp)- Combined session-log payload is within configured token budget
- If in git repo and
--ignore-modeis notoff, selected ignore file containsHANDOFF.mdand.handoff-fresh/
Step 10: Confirm completion
Output:
- Bundle output path used
- Files generated
- Root bridge status (
HANDOFF.mdupdated or created) - Ignore policy result (
local/shared/off, and target file updated if applicable) - Recommended next prompt for fresh agent:
- "Read .handoff-fresh/current/handoff.md, complete Read Gate fully before replying (no interim summary), run Read Gate preflight validator, then run Workspace Preparation. Use session-log-digest.md first if extra historical context is needed."
Fork / New-Folder Reliability Rules
- Never assume shared local history across old/new folders
- Include absolute source path provenance inside
handoff-everything.md - Preserve both relative and absolute file references when possible
- Keep bundle deterministic: overwrite
current/each run (no append)
Example
Input:
/handoff-freshOutput files (.handoff-fresh/current/):
- claude.md
- agents.md
- todo.md
- handoff.md
- context.md
- reports.md
- artifacts.md
- state.md
- prior-plans.md
- read-receipt.md
- session-log-digest.md
- session-log-chunk.md
- handoff-everything.md
- index.md (OKF bundle index, carries okf_version)
- log.md (optional OKF append-only history)
Plus bridge file:
HANDOFF.md(root pointer to bundle handoff, line-1 schema markerproducer=handoff-fresh-bridge)
Self-Evolution
Update this skill when:
- Required onboarding files change
- Fork/new-folder failure mode is discovered
handoff-everything.mdis missing context needed by fresh agents- Users report ambiguity between
/handoffand/handoff-fresh
Applied Learnings:
- v1.10.0: Added a verbatim
## Last Exchangeblock insession-log-chunk.md(exempt from the chatter filter), a## Verify Block+## Basisfingerprint instate.md(consumed by/pickupfor verify-still-true), and an OKF-lite layer (per-filetype+timestampfrontmatter, rootindex.mdwithokf_version: 0.1, optional append-onlylog.md) via the local pyyaml-onlyscripts/okf_bundle.py— no dependency on the upstream OKF package. The read-gate validator is now generalized (--required-list,--required-from-firststeps) and shared with/pickup. - v1.9.0: Added explicit handoff-artifact ignore policy (
--ignore-mode local|shared|off, default local) so fresh-bundle outputs and bridgeHANDOFF.mddo not pollute git status by default. - v1.8.0: Strengthened root HANDOFF bridge wording so "read HANDOFF.md" is treated as bootstrap and forces immediate switch to bundle Read Gate before reply.
- v1.7.0: Added token-budgeted session-log continuity artifacts (
session-log-digest.md+session-log-chunk.md) with high-signal selection rules to improve continuity without flooding context windows. - v1.6.0: Added mandatory
claude.md/agents.mdshared-context parity contract using SHARED-ONBOARDING-CONTEXT marker blocks and byte-identical validation. - v1.5.0: Added bootstrap/autostart Read Gate rule for single-file
handoff.mdprompts and a first-response contract that forbids interim one-file summaries. - v1.4.2: Clarified that
--validate-read-gateis agent-internal preflight enforcement, not a required manual user step. - v1.4.1: Added executable validator script (
scripts/validate_read_gate.py) for deterministic pass/fail Read Gate preflight enforcement. - v1.4.0: Added explicit
/handoff-fresh --validate-read-gatepreflight mode that enforces checked read receipts with non-empty takeaways before coding. - v1.3.0: Added mandatory Read Gate hard-stop rules, required read receipt checklist with per-file takeaways, and required
read-receipt.mdartifact to prevent agents from skipping required context files. - v1.2.0: Added mandatory Question Gate guidance in bundle handoff so fresh agents ask clarifying questions during workspace prep before coding.
- v1.1.0: Switched default output to
.handoff-fresh/current/, added optional archive flow, added mandatory Workspace Preparation section, and added rootHANDOFF.mdbridge pointer to fresh bundle handoff. - v1.0.0: Initial fork-safe fresh-agent bundle workflow with explicit manual command contract and hybrid output model.
Current version: 1.10.0. See CHANGELOG.md for history.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

