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

Each skill carries its own triggers in the description frontmatter — Claude Code activates them automatically based on natural-language phrasing. You can also invoke explicitly (e.g. "let's spec this out", "diagnose this bug", "verify the spec").

Hooks

Hooks live in each skill's frontmatter and activate only when the skill is active. They turn the skill's textual rules into hard guarantees.

Hooks fire mechanically — they're shell scripts on the harness side, not LLM judgments — so a skill's rules cannot be ignored even if the model decides to skip a step.

Installation

This repo ships as a single plugin, sdd-pipeline, packaged for both Claude Code marketplaces (.claude-plugin/) and Codex CLI plugins (.codex-plugin/). The skills/ tree and hook scripts are shared — only the per-tool manifest dotdirs differ. See Install above for the commands.

Updating

Claude Code:

/plugin marketplace update my-awesome-skills

Codex CLI: re-run /plugins and update from the marketplace entry.

Each commit to this repo is treated as a new version (the version field is omitted in marketplace.json, so the git SHA distinguishes releases).

Useful subsets

All six skills install together. You don't have to use all of them — Claude Code only activates a skill when its trigger phrasing matches. Common cores:

• Features only: interview-to-spec + tdd + verify.
• Bugs only: diagnose + tdd + verify.
• Both with orchestrator: add feature and spec-approach on top.

First-run setup in a project

The first time you invoke tdd in a new project, it will create .agents/tdd/test-command.txt with the project's test command (one line, e.g. npm test or uv run pytest). The Stop hook reads this file. Edit it directly to change the command.

verify writes .agents/verify/last-verdict.txt after each run. Both directories live inside the target project, not in ~/.claude/ or ~/.codex/. The .agents/ prefix is tool-neutral so the same state file works regardless of which harness you ran the skill in.

Skipping the pipeline

The skills include explicit "skip" sections — for typos, doc tweaks, spikes, generated files, and so on. The pipeline pays off when the work has real surface area. Don't drag a one-line PR through interview-to-spec → spec-approach → tdd → verify just because it exists.