sdd-pipeline

my-awesome-skills

A spec-driven development pipeline for Claude Code and Codex CLI. Refine the spec before you code, let TDD enforce it, verify nothing slipped, then review.

Install

Installation differs by harness. If you use both, install separately for each.

Claude Code:

/plugin marketplace add eduwxyz/my-awesome-skills
/plugin install sdd-pipeline@my-awesome-skills

Restart Claude Code so the hooks load.

Codex CLI:

/plugins

Search for sdd-pipeline (or add the repo manually). Hooks are opt-in in Codex — add this to ~/.codex/config.toml so the TDD/verify gates fire:

[features]
plugin_hooks = true

See Installation below for updates and useful subsets.

Why this approach

LLMs produce code well but produce the right code only when constrained. Every gap left in a prompt becomes a place for the model to fill in plausible-but-wrong assumptions. These skills implement an SDD pipeline that adds constraints — amarras — at every stage, so by the time human review starts, "is this what we wanted?" is already answered mechanically.

The pipeline compounds:

1. interview-to-spec captures the WHAT — Goal, Behaviors, Acceptance criteria, edge cases. Every AC is an amarra: the implementation must satisfy it.
2. spec-approach adds the HOW — strategy, modules touched, key decisions, schema changes, risks. Now the spec describes both intent and the implementation path.
3. tdd turns each behavior into a failing test, then writes the minimum code to pass. Each test is an executable amarra — the code is constrained not just by the spec text, but by the suite that proves it.
4. verify maps every spec AC to a green test. If a single AC has no test, the verdict is Not ready and the workflow auto-loops back to TDD until clean. Mechanical guarantee that nothing slipped.
5. review (built-in) focuses purely on code quality. The "is this what we wanted?" question is already answered.

By review time, the work has been pinned down by the spec contract + the tests + the verify gate. Reviewers (you, or the built-in review skill) only have to think about quality and style.

For bugs, diagnose produces a bug-shaped spec (Symptom, Reproduction, Root cause, Fix, AC) and the rest of the pipeline is identical. One contract, two entrypoints.

The two workflows

FEATURE                                    BUG
───────                                    ───
interview-to-spec                          diagnose
       ↓                                       ↓
[spec-approach]   (if non-trivial)             ↓
       ↓                                       ↓
       └────────────────┐         ┌────────────┘
                        ↓         ↓
                       spec/<slug>.md      ← single contract
                            ↓
                          tdd
                            ↓
                        verify             ← gate
                            ↓
                       review (built-in) → PR

Both branches converge on the same spec/<slug>.md. tdd and verify don't know — or care — which branch produced it.

Skills