Repo reentry

Repo Reentry

Save durable project knowledge and active task state into repo-local files, then verify both against the repository. The next agent should be able to continue by reading the project instead of asking the user to retell the story. Keep the continuity contract agent-neutral; product-specific files are adapters, not the source of truth.

Default Contract

• Write handoffs under docs/ai-handoffs/.
• Keep long-lived context in docs/ai-handoffs/PROJECT_MEMORY.md.
• Keep docs/ai-handoffs/LATEST.md as the stable entry point.
• Keep the last atomic checkpoint in docs/ai-handoffs/STATE.json for machine validation.
• Add or update a small managed continuity block in the universal AGENTS.md.
• Auto-update only the tool-specific entrypoints already used by the repository.
• Preserve existing instructions outside the managed block.
• Use repository-relative paths in handoffs.
• Record evidence, uncertainty, failures, and user constraints; never invent completion.
• Never include secret values, credentials, private keys, .env contents, or copied chat transcripts.

Read references/memory-contract.md before changing durable project memory. Read references/handoff-contract.md before composing or updating active task state. Read references/redaction-policy.md when the repository contains credentials, customer data, private infrastructure, or other sensitive material.

Choose the launcher

Use the bundled launcher so agents do not have to guess the Python path.

On Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File <skill-root>/scripts/repo-reentry.ps1 <command> <arguments>

On macOS or Linux:

sh <skill-root>/scripts/repo-reentry <command> <arguments>

The Windows launcher rejects the Microsoft Store placeholder and locates Python 3.10+ through installed Python, py, uv, common local installs, or the bundled Codex runtime. In the commands below, replace <repo-reentry> with the platform launcher. Direct python <skill-root>/scripts/repo_reentry.py remains supported when a real Python 3.10+ executable is already known.

Workflow

1. Inspect repository facts

Run the bundled inspector from the repository root:

<repo-reentry> inspect --root .

The inspector is read-only. It gathers Git state, recent commits, changed paths, stack signals, project instructions, likely verification commands, and environment-variable names from example env files only.

Also read the relevant project instructions and current work:

• AGENTS.md, CLAUDE.md, and equivalent repo rules
• existing docs/ai-handoffs/LATEST.md
• task/spec/roadmap files relevant to the active work
• changed files and test output from the current session

Treat the inspector as factual evidence, not a substitute for the conversation context available to the current agent.

2. Scaffold the handoff

Choose a short topic slug, then run:

<repo-reentry> scaffold \
  --root . \
  --topic <topic-slug> \
  --source-agent "<current agent>" \
  --target-agent "<next agent>"

This creates docs/ai-handoffs/YYYY-MM-DD-<topic-slug>.md and, on first use, scaffolds docs/ai-handoffs/PROJECT_MEMORY.md. It does not publish the handoff as latest.

If a current handoff already covers the same objective, update that file instead of creating competing handoffs. Do not overwrite a handoff unless it is clearly the same continuity thread.

3. Complete durable memory and active state

Fill every placeholder in PROJECT_MEMORY.md with long-lived facts only:

• project identity and product intent
• architecture, invariants, and protected boundaries
• working and verification conventions
• durable user preferences and scope constraints
• settled decisions and their reasons
• safe setup facts and environment-variable names
• project-specific vocabulary

Do not copy temporary task progress into project memory. Put the current objective, stopping point, dirty work, failures, and next actions in the dated handoff.

Replace every handoff placeholder with evidence:

Complete all required sections:

• current objective and concrete stopping point
• completed work, separated from partial work
• decisions and their reasons
• files changed or investigated
• commands/tests run with exact outcomes
• known failures, warnings, and stale assumptions
• constraints, user preferences, and do-not-touch areas
• open decisions that require judgment
• next 3-7 concrete steps
• a copy-paste reactivation prompt

Use git diff --stat, git status --short, relevant diffs, test logs, and task artifacts to verify claims. If a fact comes only from conversation, label it Conversation context. If a fact is inferred, label it Inference.

Do not paste large diffs or full logs. Summarize them and name the command or file that proves the claim.

4. Verify the handoff

Refresh the evidence metadata after completing the handoff body:

<repo-reentry> refresh \
  --root . \
  --handoff docs/ai-handoffs/YYYY-MM-DD-<topic-slug>.md

Then run:

<repo-reentry> verify \
  --root . \
  --handoff docs/ai-handoffs/YYYY-MM-DD-<topic-slug>.md

Fix every error. Review warnings about stale Git state, absolute local paths, missing evidence, or possible secrets. Use --strict before publishing a public repository or when the handoff is part of a release process.

5. Checkpoint the agent switch

After verification succeeds, use the one-shot switch command:

<repo-reentry> switch \
  --root . \
  --handoff docs/ai-handoffs/YYYY-MM-DD-<topic-slug>.md \
  --source-agent "<current agent>" \
  --target-agent "<next agent>"

This atomically refreshes Git metadata, verifies memory and handoff content, publishes LATEST.md, writes STATE.json, and updates detected entrypoints. If verification or a write fails, it restores the prior checkpoint.

When the memory must survive a fresh clone, commit the generated continuity files after switch, then push only when the user has authorized it. A commit containing only Repo Reentry continuity paths is recognized as the same READY checkpoint and does not create false staleness. Never mix unrelated code into that continuity-only commit.

Use link only when the handoff metadata is already current and only stable pointers need republishing:

<repo-reentry> link \
  --root . \
  --handoff docs/ai-handoffs/YYYY-MM-DD-<topic-slug>.md

This:

• writes docs/ai-handoffs/LATEST.md
• writes docs/ai-handoffs/STATE.json with handoff, memory, Git, and adapter digests
• adds or updates a bounded Repo Reentry block in AGENTS.md
• auto-detects and updates existing Claude Code, Copilot, Cursor, Windsurf, Cline, OpenCode, and generic agent-rule entrypoints; Hermes Agent uses the agent-neutral AGENTS.md entrypoint
• leaves all unrelated project instructions intact

Use --entrypoints all only when the user wants every supported adapter scaffolded. Use an explicit comma-separated list such as agents,cursor,claude when the repository has a defined agent set.

Run git diff --check and inspect the final diff. Do not commit or push unless the user asked for that.

6. Resume in the next agent

The user should only need a short instruction such as:

Continue this repository. Read AGENTS.md, then run Repo Reentry resume.

The receiving agent must run:

<repo-reentry> resume --root .

Interpret READY as a digest-consistent checkpoint, STALE as valid saved memory that must be reconciled with newer repository state, and INVALID as missing, changed, or unsafe continuity artifacts. READY proves internal consistency, not that every recorded claim is universally true.

Raw git status may still show uncommitted files under docs/ai-handoffs/ or managed agent entrypoints after switch. Read the continuity object from resume or doctor: when the overall status is READY, continuity-only dirty paths are expected checkpoint output and do not make project state stale. Do not rerun switch or link merely to clean Git status. Commit those paths only when the user authorizes a durable checkpoint.

Receiving a Handoff

When starting work from Repo Reentry:

1. Read the repository's agent instructions, starting with AGENTS.md.
2. Run resume and stop on INVALID.
3. Read PROJECT_MEMORY.md, then LATEST.md and its linked handoff.
4. Compare branch, HEAD, dirty paths, and verification commands with the saved checkpoint. Distinguish current.working_tree (project evidence) from continuity.working_tree (Repo Reentry artifacts).
5. Mark and reconcile stale statements explicitly.
6. Continue from the listed next steps only after confirming they still apply.

When status is READY, do not perform an unbounded repository scan. Treat PROJECT_MEMORY.md and the active handoff as the context index, then open only the files named there or required by the next concrete step. Expand inspection only when a recorded fact is missing, stale, contradictory, or insufficient for the requested change.

Run doctor --root . when adapters, digests, or stable pointers may have been edited manually. Use --strict to fail on every stale warning.

Never assume a handoff is current merely because it is named LATEST.md.

Update Rules

• Update the same handoff while the objective remains the same.
• Create a new dated handoff when the objective, branch, release, or ownership changes materially.
• Preserve prior dated handoffs as history.
• Update PROJECT_MEMORY.md only for facts expected to remain useful across multiple tasks.
• Keep LATEST.md small; it should point to one dated handoff, not duplicate the full document.
• If both Claude Code and Codex are working concurrently, record branch/worktree ownership and do not claim uncommitted changes made by another agent.

Quality Bar

A handoff is ready only when:

• another agent can identify the exact current objective
• completed, partial, and unstarted work are distinguishable
• important files and commands are named
• tests have exact pass/fail outcomes
• known failures and open decisions are visible
• the next steps are executable
• user constraints and protected areas are preserved
• the document contains no placeholders or secret values
• project memory contains no placeholders or secret values
• STATE.json digests match the published handoff and project memory
• the Git metadata is recent enough to trust, or staleness is clearly disclosed

Anti-Patterns

Avoid:

• generic summaries such as "continue implementation"
• claiming tests passed without the command and result
• copying the entire chat into the repository
• recording secret values because they appeared in terminal output
• replacing existing agent instruction files
• silently changing architecture or scope during handoff
• listing dozens of speculative next steps
• treating uncommitted work as durable without naming its dirty files
• publishing LATEST.md before verification succeeds