Save progress

Save Progress

Create a trustworthy project checkpoint for a completely fresh Codex or Claude Code session.

The output is CONTINUE.md in the repository root. Treat it as a current-state snapshot, not a chat transcript and not a permanent project specification.

Invocation

• Codex: $save-progress
• Claude Code standalone skill: /save-progress
• Claude Code plugin: /save-progress:save-progress

Arguments may add emphasis, for example: record migration risks, preserve a particular decision, or call out verification that has not been run. Arguments must not weaken the safety and evidence requirements below.

Core rules

• Inspect the actual workspace. Do not summarize only from chat memory.
• Distinguish verified facts, reasonable inferences, and unknowns.
• Never claim that code, tests, commits, pushes, deployments, or fixes succeeded unless evidence confirms it.
• Do not commit, push, stash, reset, clean, checkout, delete, install dependencies, or rewrite unrelated files.
• Persistently modify only CONTINUE.md, unless the user explicitly asks for other changes. A temporary candidate file may be used and must be removed after rendering.
• Do not expose secrets. Record environment variable names only, never values.
• Preserve the existing manual-notes block exactly when refreshing an existing CONTINUE.md.
• Refuse to overwrite a symlinked or out-of-root CONTINUE.md.
• If preserved manual notes contain a suspected secret, stop without changing the file and ask the user to remove or redact it manually. Never silently alter manual notes.
• Use the language of the user's latest instruction. If unclear, use the primary language of the repository documentation; otherwise use English.
• Prefer concrete file paths, symbols, commands, error messages, and acceptance criteria over vague prose.

1. Resolve the project boundary

1. Identify the current working directory.
2. If this is a Git repository, resolve the top-level repository root and write CONTINUE.md there.
3. If this is not a Git repository, use the current project directory and explicitly state that Git metadata is unavailable.
4. Detect nested repositories and worktrees. Do not accidentally summarize a parent or sibling repository.
5. Read the instruction files that apply to the current project before writing the snapshot, including when present:
   • AGENTS.md and AGENTS.override.md for Codex;
   • CLAUDE.md, CLAUDE.local.md, and applicable .claude/rules/*.md files for Claude Code;
   • repository README, contribution guidance, task plans, and architecture notes.
6. Read an existing CONTINUE.md before replacing it. If it is a symbolic link, stop and report the unsafe target.

2. Inspect real state

Use read-only commands appropriate to the repository. For Git projects, normally inspect:

git rev-parse --show-toplevel
git branch --show-current
git rev-parse --short HEAD
git status --short --branch
git worktree list --porcelain
git log -5 --oneline --decorate
git diff --stat
git diff --name-status
git diff --cached --stat
git diff --cached --name-status

Also inspect, when relevant:

• README and project instructions.
• Package manifests, lockfiles, task files, plans, issue references, and design documents.
• Files changed during the current task.
• Relevant diffs, not just filenames.
• Test, lint, build, migration, benchmark, or deployment commands already run in this session.
• Running services or scripts that the next session must know about.
• Untracked files, generated files, local-only configuration, and ignored-but-important artifacts.
• Detached HEAD, merge/rebase/cherry-pick state, unpushed commits, and multiple worktrees.

Do not run a full test suite merely to produce the checkpoint. Run a targeted, non-destructive verification only when it is quick, directly relevant, and needed to resolve uncertainty. Otherwise record that verification was not run.

3. Protect sensitive information

Before writing:

• Replace secret values with <redacted>.
• Record only environment variable names, such as DATABASE_URL, never their values.
• Do not copy credentials from .env, shell history, command output, URLs, config files, logs, or chat messages.
• Avoid including private customer data, access tokens, cookies, bearer headers, passwords, signing keys, or internal URLs containing credentials.
• When a command contains a secret-bearing argument, record a sanitized command shape instead of the literal command.

4. Preserve manual notes

If CONTINUE.md already exists, preserve all bytes between these markers exactly:

<!-- continue:manual-notes:start -->
<!-- continue:manual-notes:end -->

If the markers do not exist, create an empty manual-notes block using the bundled template. Use the bundled renderer in step 6 to perform the preservation deterministically; do not copy the block by hand.

5. Draft the checkpoint

Use the bundled assets/CONTINUE.template.md as the structural template. Keep every <!-- continue:... --> marker because the validator uses them. Draft the new checkpoint in an operating-system temporary file outside the repository; the renderer will merge it into CONTINUE.md atomically.

Fill every section with current evidence. Use None, Unknown, or Not run when that is the truthful state; do not invent filler.

Required content quality

Snapshot metadata

Include:

• Generation timestamp with timezone.
• Repository or project path.
• Current working directory.
• Branch or detached-HEAD state.
• Current commit, if available.
• Worktree information, if applicable.
• Agent used to create the snapshot, when known (Codex, Claude Code, or another compatible agent).

Current mission

Explain the active task, intended outcome, and success condition in terms a new session can understand without reading the old conversation.

State classification

Separate work into:

• Implemented and verified.
• Implemented but not verified.
• Partially completed.
• Not started or intentionally deferred.

Completed work

For each meaningful item, include relevant files, symbols, commands, and evidence.

Work in progress and blockers

For each incomplete item, explain:

• Current behavior or symptom.
• What has already been tried.
• Result or error.
• Current best hypothesis.
• What remains unknown.

Next actions

Order actions by execution sequence. The first action must be something a fresh session can perform immediately. Each action should include:

• File or module to inspect or change.
• Command to run, when useful.
• Expected result.
• Acceptance criterion.

Decisions

Record decisions that would otherwise be reconsidered, with rationale and tradeoffs. Do not promote temporary guesses into permanent architecture decisions.

Pitfalls

Record approaches that failed or caused regressions. Explain why they failed and what evidence disproved them. Make the warning actionable.

Workspace and Git state

Record:

• Modified, staged, and untracked files.
• Unpushed commits, if determinable.
• Merge, rebase, or cherry-pick state.
• Stashes only if visible from read-only inspection.
• Generated or local-only files that should not be committed.
• Whether the workspace is clean.

Verification

List exact sanitized commands and outcomes. Explicitly list important checks not run.

Important files and environment

List the smallest set of files the next session should open first. Record required environment variable names and setup assumptions without values.

Resume instruction

End with a copy-ready prompt that tells the next coding-agent session to:

1. Read CONTINUE.md and the applicable agent instruction files.
2. Re-check Git and workspace state.
3. Treat repository evidence as authoritative when the snapshot is stale.
4. Avoid documented failed approaches.
5. Start with the first next action.
6. Update CONTINUE.md when material state changes.

6. Render and validate the checkpoint

Resolve the directory containing this SKILL.md as SKILL_ROOT. For a Codex plugin, use ${PLUGIN_ROOT}/skills/save-progress; for a Claude Code plugin, use ${CLAUDE_PLUGIN_ROOT}/skills/save-progress. For a standalone installation, use the selected skill directory.

Render the temporary candidate into the repository root. The renderer rejects symlinks and out-of-root targets, preserves existing manual notes exactly, validates content without echoing secrets, and writes atomically:

python3 "$SKILL_ROOT/scripts/render_continue.py" \
  /absolute/path/to/temporary-candidate.md \
  /absolute/path/to/project-root/CONTINUE.md \
  --project-root /absolute/path/to/project-root

Delete the temporary candidate, then validate the written file independently and read it again against the workspace:

python3 "$SKILL_ROOT/scripts/validate_continue.py" \
  /absolute/path/to/project-root/CONTINUE.md \
  --project-root /absolute/path/to/project-root

Fix validation errors before finishing. Secret findings are errors and never include the matched value. If the error comes from preserved manual notes, stop without changing them and request manual redaction.

7. Report completion

Return a concise final report containing:

• The path written.
• The current branch and workspace-clean/dirty state, when available.
• The most important next action.
• Any unverified work, unresolved blocker, or secret warning.

Do not paste the entire checkpoint into the response unless the user asks.