agentleFS
gradigitgradigit/claude-skills/.claude/skills/handoff-fresh/SKILL.md

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.

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
  1. Distinctive:

    Run only when explicitly requested by user

    line 29
  2. Distinctive:

    No implicit hook/side-channel execution

    line 30
  3. Very specific:

    Keep /handoff separate: /handoff = standard continuity, /handoff-fresh = fresh-agent onboarding bundle

    line 32
  4. Very specific:

    No args: Full generation in .handoff-fresh/current

    line 51
  5. Distinctive:

    Use this mode when a fresh agent is ready to start coding:

    line 69
  6. Distinctive:

    Do not proceed to coding

    line 89
  7. Distinctive:

    Use ask-question for missing/ambiguous information

    line 90
  8. Very specific:

    If --output set: use that path (absolute or project-root relative)

    line 101
  9. Distinctive:

    If in a git repository, apply ignore policy before generating artifacts:

    line 105
  10. Very specific:

    If --archive is set and current bundle exists:

    line 113
  11. Distinctive:

    Do not delete historical bundles in this step

    line 116
  12. Distinctive:

    Ensure source docs are current

    line 123
  13. Distinctive:

    Ensure cross-file checks run before bundle snapshot

    line 124
  14. Distinctive:

    Ensure manifest timestamps are up to date

    line 125
  15. Distinctive:

    If no git repo exists:

    line 140
  16. Distinctive:

    Use filesystem snapshot only

    line 142
  17. Distinctive:

    Do not dump raw logs blindly.

    line 146
  18. Distinctive:

    Run Question Gate: if anything is missing/ambiguous, use ask-question before coding

    line 198
  19. Distinctive:

    Only then start implementation

    line 199
  20. Distinctive:

    If any receipt item is missing:

    line 216
  21. Distinctive:

    Ask-question for clarification if needed

    line 218
  22. Very specific:

    Run /handoff-fresh --validate-read-gate after completing read-receipt.md and before coding

    line 220
  23. Very specific:

    After opening bundle handoff.md, the agent's first substantive reply must be the full Read Gate receipt (all required files + takeaways)

    line 223
  24. Distinctive:

    Ask before proceeding when:

    line 230
  25. Distinctive:

    If no answer yet:

    line 237
  26. Distinctive:

    Do only safe, reversible prep

    line 238
  27. Distinctive:

    Do not begin implementation

    line 240
  28. Distinctive:

    Write that exact block into both files.

    line 269
  29. Distinctive:

    If source AGENTS.md is missing or weaker than CLAUDE.md:

    line 275
  30. Distinctive:

    Prefer richer context from CLAUDE.md for the shared block

    line 276
  31. Very specific:

    Create or update <project-root>/HANDOFF.md with a short bridge note that says:

    line 351
  32. Distinctive:

    If prompt says "read HANDOFF.md", treat this as bootstrap and immediately switch to bundle handoff

    line 355
  33. Distinctive:

    No interim one-file summary is allowed

    line 357
  34. Distinctive:

    Run Read Gate preflight validator before Workspace Preparation

    line 358
  35. Distinctive:

    If prep is blocked or ambiguous, use ask-question before coding

    line 359
  36. Distinctive:

    Keep this bridge short and non-destructive.

    line 361
  37. Distinctive:

    Never assume shared local history across old/new folders

    line 398
  38. Very specific:

    Keep bundle deterministic: overwrite current/ each run (no append)

    line 401
  39. Distinctive:

    Update this skill when:

    line 432

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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/current under project root
  • Keep /handoff separate: /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 completion

Arguments

  • No args: Full generation in .handoff-fresh/current
  • --output <dir>: Write bundle into explicit directory
  • --no-sync: Skip /sync-docs prerequisite (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/exclude
    • shared: update .gitignore
    • off: skip ignore updates
  • --validate-read-gate: Agent-internal preflight mode to validate completed read-receipt.md and 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 for session-log-digest.md (default: 4000)
  • --log-chunk-max <n>: Max tokens for session-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-gate

Reference script (relative to this skill directory):

python3 scripts/validate_read_gate.py --bundle-dir .handoff-fresh/current

Behavior:

  • 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:

  1. git rev-parse --show-toplevel (if git)
  2. Current directory (pwd)

Resolve bundle output path:

  • Default: <project-root>/.handoff-fresh/current
  • If --output set: 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/exclude contains:
    • HANDOFF.md
    • .handoff-fresh/
  • --ignore-mode shared: ensure .gitignore contains 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.md
  • HANDOFF.md
  • architect/plan.md, architect/prompt.md, other plan docs
  • README.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-git in state.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.md target: 3k–4k tokens (extractive summary with short verbatim evidence)
  • session-log-chunk.md target: 6k–8k tokens (raw high-signal excerpts)
  • Combined hard cap: 12k tokens by default (or --log-token-budget)

Selection priority (highest first):

  1. Decisions that changed implementation direction
  2. Rejected alternatives and why
  3. User constraints/approvals that gate behavior
  4. Debugging pivots tied to concrete files/commands
  5. 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):
    1. Required files to read in order: handoff.md, claude.md, todo.md, state.md, context.md
    2. Required read receipt format (one-line takeaway per file)
    3. "Do not proceed to Workspace Preparation or coding if any required file is unread"
    4. "If user prompt only says 'read handoff.md', treat it as bootstrap; continue Read Gate automatically before replying"
    5. "Do not send interim 'done/read' summaries before Read Gate receipt is complete"
  • Workspace Preparation section (mandatory):
    1. Confirm project root path
    2. Confirm branch/cleanliness
    3. Confirm required root docs and folders exist
    4. Re-run /sync-docs if drift is detected
    5. Run Question Gate: if anything is missing/ambiguous, use ask-question before coding
    6. 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-gate after completing read-receipt.md and 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.md was 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.md and state.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:

FileRequiredPurpose
claude.mdYesFresh-agent onboarding context (canonical shared core + optional Claude appendix)
agents.mdYesFresh-agent onboarding context mirror for non-CLAUDE agents (same shared core as claude.md + optional agent appendix)
todo.mdYesTask list and execution status
handoff.mdYesCanonical bundle handoff snapshot
context.mdYesProject/domain context, architecture snapshot, decision log summary
reports.mdYesValidation/test/report summary
artifacts.mdYesArtifact inventory and pointers
state.mdYesCurrent branch, git status, active phase, blockers
prior-plans.mdYesHistorical plans for reference only
read-receipt.mdYesFresh-agent Read Gate checklist to complete before prep/coding
session-log-digest.mdYesToken-budgeted, extractive decision digest from session logs
session-log-chunk.mdYesToken-budgeted raw high-signal log excerpts + verbatim Last Exchange block
index.mdYesOKF-lite bundle index: the Read-Gate read order + file list (carries okf_version)
log.mdNoOKF-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.md for 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 as claim | 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, /pickup recomputes 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.

  1. Per-file YAML frontmatter on each bundle .md file:
    ---
    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
    ---
    OKF permissive conformance tolerates unknown keys, so handoff-specific fields ride along as extension keys.
  2. index.md at the bundle root is the OKF index: the Read-Gate read order + the file list, with okf_version: 0.1 in 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).
  3. 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; only log.md appends).

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.md absolute 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.md contains reference-only warning
  • handoff-everything.md exists and is referenced in artifacts.md
  • state.md includes current status (or explicit no-git status)
  • context.md includes project context/history summary
  • Root HANDOFF.md bridge points to bundle handoff path
  • Root HANDOFF.md bridge includes bootstrap rule for "read HANDOFF.md" prompts
  • read-receipt.md exists with all required Read Gate entries and blank checklist state ([ ])
  • Bundle handoff.md instructs fresh agent to run /handoff-fresh --validate-read-gate before coding
  • claude.md and agents.md both contain SHARED-ONBOARDING-CONTEXT marker block
  • Shared block content in claude.md and agents.md is byte-identical
  • session-log-digest.md and session-log-chunk.md exist (or explicit unavailable note)
  • session-log-chunk.md contains a ## Last Exchange (Verbatim) block (or explicit unavailable note)
  • state.md contains a ## Verify Block (claim | check-command | expected) and a ## Basis fingerprint (HEAD, branch, changed_files, tests)
  • index.md exists with okf_version and the Read-Gate read order; each bundle .md carries OKF frontmatter (type + timestamp)
  • Combined session-log payload is within configured token budget
  • If in git repo and --ignore-mode is not off, selected ignore file contains HANDOFF.md and .handoff-fresh/

Step 10: Confirm completion

Output:

  • Bundle output path used
  • Files generated
  • Root bridge status (HANDOFF.md updated 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-fresh

Output 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 marker producer=handoff-fresh-bridge)

Self-Evolution

Update this skill when:

  1. Required onboarding files change
  2. Fork/new-folder failure mode is discovered
  3. handoff-everything.md is missing context needed by fresh agents
  4. Users report ambiguity between /handoff and /handoff-fresh

Applied Learnings:

  • v1.10.0: Added a verbatim ## Last Exchange block in session-log-chunk.md (exempt from the chatter filter), a ## Verify Block + ## Basis fingerprint in state.md (consumed by /pickup for verify-still-true), and an OKF-lite layer (per-file type+timestamp frontmatter, root index.md with okf_version: 0.1, optional append-only log.md) via the local pyyaml-only scripts/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 bridge HANDOFF.md do 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.md shared-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.md prompts and a first-response contract that forbids interim one-file summaries.
  • v1.4.2: Clarified that --validate-read-gate is 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-gate preflight 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.md artifact 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 root HANDOFF.md bridge 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.