oh-my-sdd
A set of global Claude Code skills that rigorously enforce Spec-Driven Development (SDD): before implementing any task, Claude analyzes the project, generates constitution.md → spec.md → plan.md → tasks.md, with mandatory human validation before implementation is allowed to start.
📖 Documentation: English · Português
Installation
npx oh-my-sdd install
This installs the 6 skills globally in ~/.claude/skills/, available in any project opened in Claude Code — installation does not depend on the directory the command is run from.
Architecture
An orchestrator skill (oh-my-sdd) activates, in sequence, 5 specialized skills — one per SDD phase:
| Skill | Responsibility |
|---|
oh-my-sdd | Orchestrates the flow, identifies the input (free text or Jira) and activates the others in order |
oh-my-sdd-constitution | Founds the constitution on what the project already documents and practices: scans CLAUDE.md, AGENTS.md, .cursor/rules/, CONTRIBUTING.md, lint configs and CI workflows first (every rule traced to its source, conflicts asked — never silently resolved), then falls back to code analysis, asking the user only what remains |
oh-my-sdd-specify | Generates spec.md in EARS/GEARS — human checkpoint #1 |
oh-my-sdd-plan | Translates the validated spec into technical decisions (plan.md) |
oh-my-sdd-tasks | Breaks the plan into atomic tasks (tasks.md) — human checkpoint #2 |
oh-my-sdd-implement | Implements task by task, only after both checkpoints are confirmed |
Each installed skill is self-contained: it gets its own copy of knowledge/, the SDD knowledge base (maturity levels, EARS/GEARS syntax, artifact hierarchy, practical examples) that underpins how each phase generates its document.
Usage
Once installed, the flow is automatically discovered by Claude Code whenever a task should be specified before being implemented. It can also be invoked directly:
/oh-my-sdd "add a logout endpoint that invalidates the refresh token"
/oh-my-sdd PROJ-123
/oh-my-sdd https://company.atlassian.net/browse/PROJ-123
Other commands
npx oh-my-sdd status # shows which of the 6 skills are installed and whether any file was manually modified
npx oh-my-sdd uninstall # removes the 6 skills from ~/.claude/skills/
Adaptive scale
Not every task deserves the full pipeline. Before running any sub-skill, the orchestrator classifies the task and routes it:
- QUICK — inline mini-spec + single confirmation, straight to implementation (typos, isolated bug fixes)
- SMALL — condensed spec + tasks with embedded decisions, both human checkpoints kept
- MEDIUM / LARGE — full pipeline, unchanged
Classification + reason print in one line and are recorded in .oh-my-sdd/runtime/scale.json (gitignored). The model may only reclassify upward; only you can force the scale down. See Quick Start for the full criteria table.
Change hygiene
SDD disciplines what comes before and after implementation; change hygiene disciplines the edit itself. Four behavioral guardrails are embedded in the artifacts you already review:
| Guardrail | Where it acts | What it enforces |
|---|
| Surface assumptions | specify → implement | Assumptions and competing interpretations are written down; ambiguity stops the run instead of being silently resolved |
| Minimum that solves | plan → implement | No unrequested features, single-use abstractions, or speculative configuration; every abstraction justifies today's problem and current consumers |
| Surgical diff | tasks → implement | Every changed line traces to a task; adjacent untouched code is never reformatted or refactored; only self-created orphans are removed |
| Verifiable per task | tasks → implement | Each task declares its verification up front and cannot be checked off until that verification runs |
Full rules live in knowledge/7-change-hygiene.md. QUICK tasks apply only the minimal subset (assumptions, minimum, surgical diff); MEDIUM/LARGE apply all four. No new skill, phase, or human checkpoint is added.
Execution discipline
Change hygiene disciplines the edit; execution discipline disciplines the proof. Four rules are embedded in the pipeline where they act:
| Rule | Where it acts | What it enforces |
|---|
| Evidence before claims | implement → report | Run the command, read output and exit code, then state the result. No claim without a fresh run |
| Test first | tasks → implement | Behavior changes start with a test that failed; minimum code to pass; whole suite before finishing |
| Root cause first | implement on failure | Reproduce and isolate before fixing; after three failed fixes, stop and question the architecture |
| Record, don't improvise | implement | Plan-internal decisions become Ruling: decision — reason — cost if wrong; scope, security and irreversible actions stop and ask |
Full rules live in knowledge/8-verification-discipline.md, 9-test-first-execution.md, 10-systematic-debugging.md and 11-execution-records.md. Scale still governs rigor: QUICK gets evidence and root cause, SMALL adds TDD, MEDIUM/LARGE get the full set plus an optional fresh-context review.
Multi-tool export
oh-my-sdd is Claude Code-first, but the SDD flow itself is tool-agnostic. Export the distilled rules so other AI tools follow the same pipeline in the same repo:
npx oh-my-sdd export cursor|codex|gemini|windsurf|zed
This is the beginning of the README. Read the rest at the original. Read the full README ↗
