Save Progress

This skill must only be invoked from the main session, never from a subagent.

1. Determine the project name (used for file paths in all later steps): a. If a

   ~/.claude/status/*/session-progress.md

   was written earlier this session, reuse that project name. b. Else if inside a git repo with a remote, use the

   origin

   remote. Parse the last path component, stripping any trailing

   .git

   (e.g.,

   my-lib

   from

   git@github.com:user/my-lib.git

   or

   https://github.com/user/my-lib.git

   ). c. Else use the basename of the git root (

   git rev-parse --show-toplevel

   ). d. Else use the basename of the current working directory. e. If still ambiguous, ask the user.

2. Capture test state (do NOT run tests yourself — a Stop hook already runs pytest automatically):

   • If tests ran recently in this session, reference those results (pass/fail counts).
   • If no test results are available, record "No test results available this session."
   • Do NOT invent results.

3. Create the directory

   ~/.claude/status/<project-name>/

   if it does not exist.

4. Write/update

   ~/.claude/status/<project-name>/session-progress.md

   with:

   • Timestamp:

     YYYY-MM-DD HH:MM UTC

   • Current task: what you were working on

   • Completed: detailed progress using typed entries. Each entry is classified and formatted as follows:

     Entry types:

     • Decision: The change involved choosing between alternatives or a non-obvious approach. MUST include a

       Why:

       line.
     • Observation: A factual record of what happened with no meaningful alternatives considered. Plain body, no

       Why:

       required.
     • When in doubt, prefer

       decision

       — better to over-document rationale than lose it.

     Entry format:

     ### [decision] Title describing the choice <!-- id:a1b2c3d4e5f6a7b8 -->
     Why: Rationale for this decision (SACRED — never compress or paraphrase).
     What: Implementation details (optional).
     
     ### [observation] Title describing what happened <!-- id:e5f6a7b8c9d0e1f2 -->
     Plain body text describing the change.
     

     Entry IDs: Generate a unique ID for each new entry — 16 hex characters (e.g.,

     a1b2c3d4e5f6a7b8

     ). Just produce a random-looking 16-char hex string.

     Appending to existing files: When updating an existing

     session-progress.md

     , preserve all existing entries verbatim — only append new ones.

     Auto-captured entries: If a

     ## Auto-captured

     section exists (added by the auto-capture hook), review those entries:
     • Promote useful ones to the main Completed section.
     • Upgrade observations to decisions with a

       Why:

       line where appropriate.
     • Remove the

       ## Auto-captured

       section after processing.

     Entry body content — draw from these details as appropriate:

     • Per-batch/phase breakdown when following a plan — what each batch accomplished
     • Files created, modified, or deleted — explicit paths (e.g.,

       src/foo/bar.py

       — added

       MyClass

       , refactored

       process()

       )
     • Implementation specifics — functions, classes, modules, config options added or changed
     • Issues encountered and workarounds — anything the next session should know about (e.g., "ruff F401 requires atomic edits", "had to retry due to X")
     • Prior session context — when resuming multi-session work, summarize what earlier sessions completed so the file is self-contained

   • Remaining: bullet list of what's left, with enough detail to pick up without re-reading the plan

   • Test state: from step 2

   • Key decisions: any architectural or design choices made

   • Active plan: path to the current plan file in

     ~/.claude/plans/<project-name>/

     , or "None"

   • Context needed to continue: anything a fresh session needs to know (key file paths, uncommitted state, critical checkpoints, next batch to start)

5. Update or create

   ~/.claude/status/<project-name>/project-status.md

   — the cumulative project history across all sessions:

   If the file does not exist, create it with these sections (adapt to the project):

   • Overview: one-line project description
   • Last Updated: timestamp
   • Version History: table of released versions with features (if applicable)
   • Phase Progress: table of completed items with status and key files touched
   • Plans on Disk: paths to active/completed plan files with status
   • Test Results: latest pass/fail/skip counts, coverage, lint status
   • Next Steps: what comes next
   • Deferred Work: backlog items with references to where they're documented
   • Git State: uncommitted changes summary (user handles git)

   If the file already exists, read it first and update the sections that changed this session:

   • Add new rows to phase/version tables for completed work
   • Update test results with latest counts
   • Update plans on disk (add new plans, mark completed ones)
   • Update next steps to reflect current state
   • Update git state if relevant
   • Update last updated timestamp
   • Do NOT delete or rewrite sections that haven't changed
   • If the file uses different section names, match its existing structure — don't force the template above

6. Confirm to the user what was saved and where.