done

Run without pausing

Invoking this skill is the user's request to run every step below — reading files, running shell commands (git, PowerShell, Bash), and writing/editing CLAUDE.md. Execute every step without stopping to ask for confirmation. Claude Code's own permission settings still apply: if a tool call needs approval under those settings, the harness will prompt for it.

What this skill does

You're closing out a working session. The goal is to leave the project in a clean, well-documented state: capture what happened, update the docs that describe the project so a future session picks up with full context, confirm tests still pass, and report a crisp summary.

Step 1 — Detect what changed this session

First, figure out what actually happened. Check in order:

1. Git repo — run git status and git diff HEAD (or git diff if nothing is staged). Also run git log --oneline -10 to see recent commits.
2. No git — look at files with recent modification times: Bash: find . -type f -newer /dev/null -not -path '*/node_modules/*' -not -path '*/.git/*' -printf '%T+ %p\n' 2>/dev/null | sort -r | head -40 (If printf fails, fall back to: ls -lt --time-style=full-iso *.html *.js *.py *.md 2>/dev/null | head -20)
3. Conversation context — use what you know from this session if neither of the above is conclusive.

From this, produce a short internal change list (you'll use it in Steps 2–5):

• Which files were created or modified
• What the overall purpose of the session was (feature, bugfix, config, docs)
• Any architectural or behavioral changes worth documenting

Step 2 — Update CLAUDE.md

Open the project-level CLAUDE.md (in the current working directory) and the global ~/.claude/CLAUDE.md. For each, ask: do the changes from Step 1 affect any documented section?

The bar for writing a line into CLAUDE.md is "would a future session get this wrong if the line weren't there?" Per Anthropic's context-engineering rules for Claude 5 models, CLAUDE.md should stay lightweight and spend most of its tokens on gotchas. Claude 5 recovers structure from the filesystem reliably, so anything derivable by listing a directory, reading package.json, or grepping the source is context cost with no return — and the built-in /doctor checkup will strip it out later anyway.

Update only if one of these is true:

• A pitfall or gotcha was discovered that would bite a future session — especially one that already cost time this session
• A rationale was established: why the code is this way, and what breaks if someone "fixes" it
• A convention that differs from the tool's default was adopted
• A build / test / run command changed
• A security, auth, or data-handling rule changed
• An integration's contract changed (how another system must be called, not which package was installed)

Do not update CLAUDE.md for:

• Anything derivable from the codebase — file inventories, directory layouts, dependency lists, route inventories, "architecture overview" narration
• Routine feature additions that are self-evident from the code
• Bug fixes with no architectural impact
• Things already documented

A concrete version of the distinction: "added ws to dependencies" is derivable — skip it. "The WebSocket server shares the same http.Server as Express, so changing the port in one place moves both" is a gotcha — write it. When a change produced both, write only the gotcha.

If you make any changes, note exactly which file and which section was updated. If no changes are needed, say so explicitly — don't skip it silently.

Step 2a — Decide where the content goes: cut, keep, or load on demand

Content that passed Step 2 is real knowledge. Now decide where it lives. The test is not file length — it's whether a future session needs this on a typical task, or only when working on that one narrow feature.

• Ask: would a session working on an unrelated part of this project ever need this fact to avoid a mistake, or is it only relevant to someone specifically touching the feature/section this change belongs to?
• Keep in CLAUDE.md — pitfalls, rationale, and conventions that differ from tool defaults; security/auth gates; data rules; cross-cutting gotchas (anything that could bite unrelated work); build/test/run commands; and anything genuinely referenced from multiple places in the codebase. Note the shift from the older phrasing: architecture rationale ("the terminal and API share one http.Server, so…") stays, but an architecture overview that just narrates the file layout is derivable and should have been dropped back in Step 2.
• Relocate so it loads on demand — deep implementation detail scoped to one narrow feature, tile, routine, or endpoint that only gets touched on its own dedicated task (e.g. "how the PDF export button formats page breaks," "the full history of one specific data-check's edge cases," "Dockerfile/deploy-zip build gotchas"). If it's the kind of detail you'd only look up when someone says "fix X" for that specific X, relocate it.
• If genuinely unsure whether something is narrow or cross-cutting, default to keeping it in CLAUDE.md — moving a cross-cutting gotcha out is the costlier mistake (it gets missed on unrelated tasks), not the safer default. This tie-break applies to where a real gotcha lives, not to whether derivable content survives — for that, Step 2 already says drop it.
• Don't force existing, already-appropriate CLAUDE.md content into a reference doc just because the file is long. Only relocate content this session actually added or is directly touching. A full rightsizing pass is a separate, explicit task — e.g. the built-in /doctor checkup — not something /done does on every run.

Where to relocate — prefer the highest rung that fits. The point is for the harness to load the content automatically when it becomes relevant, rather than relying on a session noticing a pointer:

1. A skill (~/.claude/skills/<name>/SKILL.md) — the content is a multi-step procedure, not a fact. Split a long one across several files in the skill folder instead of one wall of text.
2. A path-scoped rule (<project>/.claude/rules/<topic>.md with paths: frontmatter globs) — the content is a convention or constraint tied to specific files or directories. It loads only when Claude reads a matching file.
3. A nested CLAUDE.md in the subdirectory the content is about — loads on demand when Claude reads files in that subtree. Caveat: nested files are not re-injected after /compact, so don't use this for anything that must survive a long session.
4. docs/X.md + a pointer — a common convention, and the right fallback for narrative reference material that's neither a procedure nor path-scoped (e.g. docs/DEPLOYMENT.md, docs/INTEGRATIONS.md). Reuse an existing one if the topic fits; otherwise name a new one after the feature.

When moving content out: write the full detail to the target, and leave a short paragraph or bullet list in CLAUDE.md — enough for a session to know the feature exists and get the one-sentence gist — ending with a pointer like "See docs/X.md for full detail." Never use an @path import for this: imports are expanded at launch, so they organize content without saving any context.

If you create or edit a .claude/rules/*.md, resolve every paths: glob before you finish. A glob matching zero files (a typo, or a path that has since been renamed) means the rule never loads and the content you just relocated is silently gone — worse than having left it in CLAUDE.md, because nothing ever surfaces the failure. Check each pattern against the filesystem and confirm it matches at least one real file. Same applies to a rule you didn't write but whose files this session renamed or moved: renaming a file out from under a glob is an easy way to kill a rule without touching it. Don't leave a known-dead glob behind for a later audit to find.

Step 3 — Run tests

Detect the test framework and run it. Check in this order:

Capture the output. Report:

• Pass / fail count if the framework shows it
• Any failing test names and their error summary (first line of the error)
• If the test command itself errors (e.g., missing dependency, config error), report the error output verbatim — do not swallow it as "No test suite detected"
• If tests were skipped due to no suite being found

Do not fix failing tests here — just report them so the user knows what to address next session.

Step 3a — Close the resumed handoff

If this same conversation loaded a handoff with /resume-handoff (the session-handoff plugin), set that file's **Handoff-Status:** line (directly under the H1) to **Handoff-Status:** complete <date time> with the real time — date "+%Y-%m-%d %H:%M" (macOS / Linux / Git Bash) or Get-Date -Format "yyyy-MM-dd HH:mm" (Windows PowerShell), or the user's preferred date format if CLAUDE.md sets one. Insert the line under the H1 if it is missing. Change nothing else in the file. If the file has moved (an archiving script may have moved it), skip it and say so in the report.

Close only the path(s) this conversation itself resumed — you know them from your own context. There is no fallback: a session that did not resume a handoff marks none complete, not even the newest one, so one session's /done can never close another session's handoff. A script can then move complete handoffs into archive/handoffs/.

Step 4 — Git commit and push

Commit only the files this session changed — never git add -A or git add . Several sessions often share one working tree, so a blanket add sweeps another session's unsaved work into this commit. Use the Step 1 change list cross-checked against what this conversation actually edited; a modified file you didn't touch stays unstaged and is named in the report.

Do this for every repository this session edited files in, not only the current directory's — a session in one project can still have changed ~/.claude or another project. For each:

1. No .git folder — if it is a new project folder, create the repository with Step 4a, then continue with item 2. Otherwise skip it and note "No git repository".
2. .git exists — run git status --porcelain to check for uncommitted changes.
   • None of this session's files are modified — note "Git: nothing to commit". Still run git push in case earlier commits were never pushed.
   • This session's files are modified — do all three in order:
     1. git add -- <each file this session changed>, then git diff --cached --stat to confirm nothing else is staged
     2. git commit -m "<message>" — derive the message from the session summary in Step 1. Use the format: "<verb> <what> — session wrap-up" (e.g. "Add weekly compliance chart — session wrap-up"). Keep it under 72 characters.
     3. git push

Report the outcome:

• Git: ✓ committed "<message>" and pushed — on success
• Git: ✓ nothing to commit — pushed — if only a push was needed
• Git: ✗ push failed — <error> — if push errors (show the error)
• Git: skipped — no repository — if no .git folder
• Left unstaged: <files> — other changes in the tree this session didn't make

Step 4a — Create a repository for a new project

A new project folder with no git yet gets a repository, a deny-by-default .gitignore, and a first commit that has passed a secret check.

Create one only when all of these hold — otherwise skip and note why:

• The folder is a single project's root folder: the session's working directory, or another project folder this session edited. Never the home folder, the Desktop, a folder that holds several projects, or a synced or network drive.
• git -C <folder> rev-parse --is-inside-work-tree fails (not already inside a repo).
• No subfolder has its own .git — a folder that contains repos must never become one.
• There is no .nogit file in the folder. That file is the user's opt-out for scratch folders; respect it silently.
• This session changed files in it.

Steps, in order — never skip the safety check:

1. .gitignore — if none exists, copy assets/gitignore-baseline (in this skill's folder) to <folder>/.gitignore. If one exists, append only the baseline lines it is missing; never remove a line.
2. Init — git init (uses the user's configured default branch).
3. Stage — git add -A is correct here only: the repo is brand new, so every file is the project's first version.
4. Safety check before the first commit — run bash <this skill's folder>/scripts/first-commit-check.sh "<folder>" (on Windows, from Git Bash). It prints one <reason>\t<path> line per staged file that must stay out: spreadsheets, CSVs, databases, key and credential files; non-code files whose name says key/secret/token/credential/password/ snapshot/employee/salary/payroll; anything over 5 MB; and any file whose content looks like a key or password. For each line: git rm --cached -- "<path>" and add the path to .gitignore. Then git add .gitignore and re-run the script until it prints nothing and exits 0. A non-zero exit means the check itself failed: do not commit — report the error and leave the repo uncommitted. Report removed files by name only — never open or print their contents.
5. Commit — "Initial commit — <project> — session wrap-up".
6. Remote — only if the user's CLAUDE.md defines where new projects get their remote (for example a local bare repo per project as a backup): follow that convention, then git push -u origin <branch>. If the target already exists, don't push — it may belong to another project or an old copy; report the name clash and leave the repo local. With no convention defined, leave the repo local and say so.

Report: Git: ✓ new repository — <N> files committed[, pushed to <remote>| — local only], plus Kept out of git: <files> for anything the safety check removed.

Step 5 — Final status report

Print a compact, scannable summary using this template:

Session wrap-up
───────────────────────────────────────
Changed: <N> files
  • <file1> — <one-line description of what changed>
  • <file2> — <one-line description>
  ...

CLAUDE.md: <"Updated — <which file>, <which section>" | "Updated — <section> (+ <topic> detail → <docs/X.md | skill | .claude/rules/X.md>)" | "No changes needed" | "No changes needed — <what changed> is derivable from the code">


Tests: <"✓ N passed" | "✗ N failed — <test names>" | "No test suite detected">
───────────────────────────────────────
<One sentence summarizing the overall session goal and outcome.>

Keep each bullet tight — one line. The user can read the diff for details; this report is for orientation, not documentation.