claudeframework: Skill for Claude Code

Implement the feature described in a spec file. $ARGUMENTS should be the spec filename (without path or extension), e.g. export-zip. If no argument is given, use the most recently modified file in .claude/specs/.

Steps:

1. Read the spec from .claude/specs/<name>.md

2. Read CLAUDE.md — note the project's test command, lint command, build command, and typecheck command if listed

3. Read all files in .claude/context/ if the directory exists — long-lived project references (schemas, API docs, glossaries)

4. Read all files listed under "Affected files", "New files", and "Patterns to mirror" in the spec — the "Patterns to mirror" files are the primary convention references; follow their structure, naming, and style 4b. Context budget check: count the total files from steps 3 and 4. If the total exceeds 15, read "Patterns to mirror" files in full and only read the relevant sections of remaining files. Note which files were fully read vs. partially read.

5. Decomposition gate: count the total files listed under "Affected files" + "New files". If the total exceeds complexity_gate_max_files from CLAUDE.md (default: 10), or if the spec has a ⚠ Complexity flag, pause and ask the user whether to proceed as a single session or break the spec into smaller sub-specs first. Continue only after confirmation.

6. Create a safety checkpoint: if the project uses git and checkpoint/<spec-name> does not already exist (e.g., already created by /ship), run git checkout -b checkpoint/<spec-name> from the current branch, then immediately switch back with git checkout -. This creates a named rollback point that survives crashes and avoids stash collisions. Skip if the checkpoint branch already exists or the working tree is already clean (no staged or unstaged changes).

7. Enter plan mode: propose a step-by-step implementation plan and wait for approval before writing any code

8. Phase management — check whether this is a phased implementation: a. If .claude/specs/<name>-phases.md already exists (resuming a later phase): read it, find the next pending phase, set its status to in-progress, and implement only that phase's scope. If all phases are done, report completion and stop. b. If no phase manifest exists but the approved plan proposes splitting into multiple phases: write .claude/specs/<name>-phases.md using the format below. Mark Phase 1 as in-progress, others as pending. Implement only Phase 1. c. If no phases are needed, skip the phase manifest and proceed normally.

   Phase manifest format (.claude/specs/<name>-phases.md):

   # Phases for <name>
   
   ## Phase 1 — <title>
   Status: in-progress
   Scope:
   - <spec requirement covered in this phase>
   Contract items:
   - <ids from the spec's ## Contract that this phase must satisfy, e.g. C1, C2>
   
   ## Phase 2 — <title>
   Status: pending
   Scope:
   - <spec requirement covered in this phase>
   Contract items:
   - <ids from the spec's ## Contract that this phase must satisfy, e.g. C1, C2>
   
   ## Artifact coverage
   Every file from the spec's "Affected files" + "New files" must appear in exactly one phase above.
   Unassigned:
   - (none)
   

   Phase reconciliation (mandatory when creating or resuming a phase manifest): Before proceeding, cross-reference the spec's "Affected files" + "New files" lists against all phases in the manifest. Every spec artifact must be assigned to exactly one phase. If any artifact is missing from all phases, add it to the appropriate phase or create an additional phase for it. The "Unassigned" block in the manifest must be empty — if it is not, stop and resolve before continuing. This prevents silent scope loss where entire subsystems (e.g. frontend) are dropped during decomposition.

   Apply the same reconciliation to the contract: every id in the spec's ## Contract must be assigned to exactly one phase. An unassigned contract id is the same class of silent scope loss as an unassigned file — the criterion would never be gated by any phase.