Run first on any unfamiliar or dormant project · reports, then fixes only what you approve
+
report firstone approval per fixsafe on any project
✓
Context files: CLAUDE.md (under 200 lines? points to the steering docs?), AGENTS.md, the three steering docs, .claude/rules/
✓
STATE.md drift: how many commits since its hash. Commits that only touch STATE.md, the CHANGELOG or steering docs don't count.
✓
Specs: features in specs/ that STATE.md doesn't mention, and unticked tasks
✓
Task format: does every task have Files: and Check: lines?
✓
Metadata: CHANGELOG, README and version, measured in commits since each last changed
✓
Agents: are sdd-implementer and sdd-reviewer installed? Is .claude/worktrees/ ignored?
Invoke
/sdd-checkup
── SDD HEALTH ───────────────────────CONTEXT ✓ CLAUDE.md 48 lines ⚠ CLAUDE.md @imports 3 steering docs ✗ steering/tech.md missingSTATE ⚠ STATE.md 4 commits behindSPECS ✓ specs/auth/ done ⚠ specs/queue/ not in STATE.md ⚠ specs/queue/ tasks lack Check linesAGENTS ✗ sdd-reviewer not installed── FIXES ────────────────────────────Critical: write tech.md · install agentsImportant: update STATE.md · drop importsOptional: add Check lines to queue
Found an AGENTS.md? Nothing is broken: Claude Code reads AGENTS.md when there's no CLAUDE.md. Checkup offers a CLAUDE.md that starts with @AGENTS.md and adds the SDD sections, so teammates using other AI tools keep working from the same file.
E·02
/sdd-bootstrap
Writes the context files from what the code shows · parallel Explore agents · never invents decisions
+
once per projectno application code changed3 Explore agents in parallel
01
Map the code. Three Explore agents run at once, covering the stack, the structure and the conventions. Each sends back a short summary with file paths, so your conversation never fills up with raw files.
02
Answer the gaps. Claude asks only about what the code can't tell it, such as two competing test frameworks, a half-finished migration, or the product's purpose.
03
Review the files. tech.md marks each decision as inferred from code or confirmed by you. STATE.md starts at the current commit.
04
Commit: chore: add SDD context files
Invoke
/sdd-bootstrap
Output files
.claude/steering/product.md
.claude/steering/tech.md
.claude/steering/structure.md
CLAUDE.md · stack · commands · NEVER · pointers
STATE.md · anchored at HEAD
Watch for: rationale or folder maps written into CLAUDE.md. Those belong in the steering docs. If you see them in CLAUDE.md, ask Claude to move them.
E·03
STATE.md and the commit hash
Kept current by the skills, never edited by hand · the hash makes staleness checkable
+
01
/sdd-implement marks a feature as implemented, awaiting validation
02
/sdd-validate moves it to Done and sets the hash to HEAD
03
/sdd-checkup runs git log <hash>..HEAD to count the commits STATE.md hasn't seen, and offers to catch up
Why this works alongside teammates who don't use SDD: if someone pushes without updating STATE.md, the hash makes it obvious. "Are there commits after this hash?" is a yes/no question git can answer.
# State_Generated: 2026-10-19_Last commit: `a3f9c12`## Done- auth — see specs/auth/## In progress- csv-export — implemented, awaiting validation- queue — T1–T3 done, T4 next## Blockers- none## Next steps- /sdd-validate csv-export
E·04
Upgrading a project set up with the earlier skills
Reinstall, then let checkup bring the project files up to date
+
01
Re-run the install command from Setup. It updates the six skills and adds the two agents.
02
Run /sdd-checkup in the project. It flags the three differences below and offers to fix each one.
03
@ imports of the steering docs in CLAUDE.md are replaced by a short "Project context" list of pointers.
04
Unticked tasks get Files: and Check: lines. /sdd-implement needs them to dispatch and verify each task.
05
Agent labels such as backend-builder in old tasks.md files can stay. They're ignored, because every task now goes to sdd-implementer.