blackpeanut/awesome-sdd

Use to derive the API contract for a feature — an OpenAPI 3.1 document at docs/features/{slug}/contracts/openapi.yaml plus a drift/sync report (and an events doc when the feature has async flows). Triggers on "api for {slug}", "openapi for {slug}", "API contract for {slug}", "lock the interface for {slug}", "events for {slug}", "/awesome-sdd:api {slug}". The contract is never hand-written: it is a derived function of data-model.md (typed fields + constraints), the sad.md §6 sequence diagrams (error branches, async actors), and spec.md acceptance criteria. Runs an inline drift check (does the contract match the model and the sequences?) and a reconcile mode. Hard-refuse if data-model.md is missing AND the feature changes the schema → run data-model {slug} first; on a legal no-schema-change skip it derives from the existing schema instead.

Use to run an ambiguity sweep over a written spec.md and close every under-specified point before planning or design proceeds — so two engineers can't reasonably build different things from the same spec. Triggers on "clarify {slug}", "find ambiguities in {slug}", "is the spec ready", "sharpen the spec", "/awesome-sdd:clarify {slug}". Re-reads the spec, dispatches a clean-context devil's-advocate subagent to list where the spec forks, then for each ambiguity runs AskUserQuestion to RESOLVE it (tighten §1/§5/§6 in place) or DEFER it (→ §8 Open questions with owner+due). Output: an updated docs/features/{slug}/spec.md with every ambiguity resolved or deferred — none dangling. Hard-refuse if spec.md is missing.

Use to classify a feature into XS/S/M/L/XL and write docs/features/{slug}/.size plus the pipeline route docs/features/{slug}/.route (quick|standard|full) so later skills know how much of each artifact to produce and how handoffs resolve skips. Triggers on "classify size", "feature size", "is this XS or M for {slug}", "size {slug}", "change route", "/awesome-sdd:classify-size {slug}". Asks four AskUserQuestion (PR count / time / new module-API-migration / breaking changes), maps to a size class via the shared size matrix, derives the default route (XS/S→quick, M→standard, L/XL→full), confirms size + route in ONE question, and writes the one-line .size and .route files — the source of truth; the feature_size: frontmatter mirrors in spec.md and sad.md are re-synced to it on every (re)classification.

Use to create and tune the per-project settings file .claude/sdd.local.md — the one place that decides how deeply the pipeline interviews you, which model tier its judgment agents run at, how strict the TDD gates are, and how tasks execute and commit. All conversation and documents are written in English. Triggers on "config", "settings", "configure sdd", "tune the pipeline", "change the judgment model", "set the interview depth", "/awesome-sdd:config". Creates the file with documented defaults FIRST (so you have a working config before answering anything), reads what already differs from the defaults, then asks the applicable decision groups and patches only the keys you confirm — preserving your comments, key order and unknown keys. Never touches the pipeline's artifacts; the settings file is gitignored, only the .gitignore patch is committed.

Use to design the data model AND generate the actual forward + rollback migrations in one pass — shippable SQL, not a plan. Triggers on "data model for {slug}", "schema for {slug}", "generate migrations for {slug}", "DB design + migration", "/awesome-sdd:data-model {slug}". Reads spec.md §5 + sad.md §5 building blocks + the §6 sequence diagrams, then writes docs/features/{slug}/data-model.md plus paired *.up.sql / *.down.sql migrations STAGED under docs/features/{slug}/migrations/ (NOT the live migrations/ tree — implement promotes them when the feature is actually built) and an audit report. Greenfield-first; brownfield delta via --mode brownfield; drift-only via --drift-only. Hard-refuses if spec.md or sad.md is missing. Stack-agnostic: detects and FOLLOWS the repo's DB + migration conventions and domain layer — it imposes no DB philosophy and writes no rules file.

Use to record a post-hoc or asynchronous architecture decision as a MADR ADR when it was NOT captured during the synchronous design pass — a choice made in code, in a chat, on a whiteboard, or one a tasks/review gate flagged as missing. Triggers on "ADR for {decision}", "adr for {slug}", "document the decision on {topic}", "lock in the decision about {X}", "MADR for {topic}", "/awesome-sdd:decide-adr {slug} {title}". Confirms the decision is ADR-worthy via the blast-radius gate, picks the next 4-digit number, copies design's MADR template, and fills context / drivers / considered options / outcome / honest consequences. Supports a Proposed → Accepted review flow. Output: docs/features/{slug}/adr/NNNN-{title}.md. For decisions made live with the user, use design — it spawns ADRs inline (Accepted).

Use to produce a Software Architecture Document for a feature — Arc42 12 sections + C4 L1/L2 inline + ADRs spawned on a blast-radius gate — once spec.md exists. Triggers on "design {slug}", "architecture for {slug}", "SAD for {slug}", "arc42 for {slug}", "C4 context+container for {slug}", "/awesome-sdd:design {slug}". Drafts §1–§12, discusses unresolved choices one at a time in plain language, spawns an ADR only when a decision crosses the blast-radius threshold (irreversible / multi-module / has legitimate alternatives), writes each resolved section + its ADRs to disk immediately, then runs a clean-context critic and commits sad.md + each ADR separately. Brownfield: dispatches an Explore subagent to map the repo first. Hard-refuse if spec.md is missing; CONTEXT.md is optional (when present its Glossary is canonical).

Use to establish the project's design canon — docs/design-system.md: the design-tool choice (Figma MCP / Pencil MCP / code-only markdown), the platform posture (mobile-first / desktop-first / responsive), the token source, and the reusable component inventory. Once per repo, like survey. Triggers on "set up the design system", "design canon", "which design tool", "establish the UI foundation", "/awesome-sdd:design-system". Read by ux-flows (posture) and screens (tool + inventory); implement registers NEW components back into it. On tool: pencil it also bootstraps the .pen library itself — creates the file, walks the user through opening it, and seeds tokens + a foundations frame via the pen-keeper agent. Utility — not a backbone stage; run it before the first UI feature (ux-flows recommends it when absent).

Use to fix a reported bug spec-first: reproduce it, trace the symptom to the owning feature's acceptance criteria, pin it with a failing (RED) test, apply the minimal GREEN fix through the same per-task gate implement uses, then patch the spec so the bug class can't silently return. Triggers on "fix {bug}", "fix the bug in {slug}", "bug in {feature}", "/awesome-sdd:fix {slug}", "regression in {slug}". Triage is three-way: AC exists and is violated (regression) / AC is ambiguous (spec-bug — patch the wording) / no AC covers it (gap — add one, marked added-by-fix). Works on a repo with no specs at all (soft mode — code-first, recommends survey after). Writes a fix record under docs/features/{slug}/_fixes/ and commits the fix (SDD-Fix trailer), the record and any spec patch as separate commits.

Use to capture or update domain terms in CONTEXT.md before their meaning drifts — whenever a fuzzy word shows up in an interview, spec, or review and you want one canonical definition plus a NOT-reference so a homonym can't bite you in six months. Triggers on "add term {X}", "what is {X} in our domain", "add to CONTEXT", "fix the glossary", "define {X}", "/awesome-sdd:glossary {term}". Two-level contract: repo-root CONTEXT.md holds project-wide terms, docs/features/{slug}/CONTEXT.md holds feature-scoped ones; readers read both and the per-feature entry wins. Lazy-bootstraps the target from a template, checks BOTH levels for a conflicting existing entry, asks for a one-sentence definition + the concept it's confused with, and appends one line to ## Glossary. Skip generic tech words (HTTP, queue, cache) — those are not domain terms. Output: created/edited CONTEXT.md. Runs anytime, no input gate; specify, clarify, design and api read its ## Glossary as the canonical source of role and domain-term names.

Use to implement a feature from its tasks.json with test-driven development — writes a failing test first, makes it pass, refactors, gates, and commits per task. Triggers on "implement {slug}", "build {slug}", "TDD {slug}", "code up the tasks for {slug}", "/awesome-sdd:implement {slug}". Reads docs/features/{slug}/tasks.json + the upstream artifacts, detects the repo's test/lint/vet commands stack-agnostically, builds a dependency DAG, and runs one of three modes — sequential sequential TDD, an agent team (TeamCreate), or a dynamic Workflow — chosen from settings + DAG shape with graceful fallback. Hard-refuses if tasks.json is missing.

Clarify and stress-test an engineering idea before roadmap or specification. Use for a product, feature, or technical change whose problem, outcome, scope, or key assumptions are unsettled: "interview {slug}", "idea brief", "stress test this idea", "/awesome-sdd:interview {slug}". Reuses existing context, adapts questions to uncertainty, checks decision-changing facts, and requests independent critique when risk warrants it. Returns a short brief with decisions, evidence, unknowns, and a justified next step. Does not implement code, design the architecture, or write specify's detailed requirements.

Use to turn a feature's acceptance criteria into a test plan before any test is written — a table that maps every spec.md §5 acceptance criterion to at least one test, names the test levels (unit / integration / e2e / contract / load) without binding to a language or framework, and fixes the integration and data strategy. Triggers on "plan tests for {slug}", "test plan for {slug}", "how do we test {slug}", "test strategy for {slug}", "/awesome-sdd:plan-tests {slug}". Output: docs/features/{slug}/test-plan.md (separate file for M+), or inline in spec.md for XS/S per the size matrix. Hard-refuse if spec.md is missing → run specify {slug} first.

Use to run an independent, clean-context code review of an implemented feature against its spec and acceptance criteria before shipping. Triggers on "review {slug}", "code review the changes for {slug}", "review the diff for {slug}", "is {slug} ready to ship", "/awesome-sdd:review {slug}". Dispatches the reviewer subagent over the whole feature diff (stage 1 spec/AC compliance, stage 2 quality), collects cited findings, and resolves each with you. Hard-refuses if the feature isn't implemented yet.

Use to break a product idea into incremental steps and keep that decomposition living — one docs/roadmap.md with a destination sentence, the steps table (source-anchored, sized XS–XL or marked fog), the fog vocabulary (what's in scope but not yet formulated, what never graduates, which decisions are still open and who owns them), the dependency graph that owns every edge, and the execution path: dependency-respecting waves that show what can run in parallel (e.g. in worktrees) and what must wait. Triggers on "roadmap", "break this down", "decompose the idea", "what depends on what", "execution plan", "/awesome-sdd:roadmap". Takes any scope — a whole product, an epic, or a single feature. Reads docs/idea-brief.md or a PRD (+ design canon and architecture map when they exist; neither is required). It decomposes and orders — it is NOT a prioritization scorecard and NOT a dated Gantt; specify/ship keep step statuses in sync as features move.

Use to materialize the greenfield skeleton that survey's foundation session planned. Reads docs/architecture-map.md (mode: greenfield-bootstrap) plus docs/features/_scaffold/tasks.json and builds the real project structure: folders + entry point, test harness + smoke test, migration tooling, CI, the conventions doc. Triggers on "scaffold the skeleton", "materialize the skeleton", "bootstrap the project skeleton", "/awesome-sdd:scaffold". Runs the S-tasks sequentially inline (no team/workflow orchestration), anchored on the skeleton smoke test — builds + boots + empty test suite runs + migration tool runs — commits, and hands off to /awesome-sdd:specify. Hard-refuses without the greenfield foundation: run survey first.

Use to produce the canonical screen manifest for a UI feature — every screen in every state (default / loading / empty / error / success / validation), with reuse-first component picks — written to docs/features/{slug}/screens.md between api and tasks. Draws per the design-system tool: Figma MCP into the canon file, Pencil MCP into screens.pen, or inline markdown wireframes (code mode — also the degradation when an MCP is unavailable). Triggers on "screens for {slug}", "screen states for {slug}", "draw the screens", "mockups for {slug}", "/awesome-sdd:screens {slug}". States derive from §5 ACs + sad.md §6 branches + contract error responses; tasks/implement/review read ONLY the manifest. Hard-refuse if sad.md is missing; skipped when target_surfaces declares no UI surface.

Use to add Mermaid sequenceDiagram blocks to the SAD's runtime view (sad.md §6) — one per critical flow, showing how a request moves between participants with happy + error paths. Triggers on "sequences for {slug}", "sequence diagram for {slug}", "draw the runtime flow", "add a sequence to the SAD", "/awesome-sdd:sequences {slug}". Reads sad.md §5 for participants, drafts each flow from templates/sequence.md with generic participants, walks them Socratically one flow at a time, and writes confirmed blocks into sad.md §6 — they inform data-model indexes downstream. Hard-refuse if sad.md is missing → run design {slug} first.

Use to close the loop after review — verify the feature actually works, write the changelog / knowledge-base note, and open the pull request. Triggers on "ship {slug}", "open a PR for {slug}", "changelog for {slug}", "prepare {slug} for merge", "/awesome-sdd:ship {slug}". Re-runs the gate, runs the app/feature to confirm the spec's outcomes for real (not just green tests), drafts a changelog + PR body that link spec/ AC/ADRs, and proposes the PR command for whatever forge the repo uses. Never auto-merges to main.

Use to turn a raw feature idea into a reviewed spec.md — a lightweight Socratic interview front (capture the idea, deep-dive the problem) merged with a full product spec (context, goals, user stories, acceptance criteria, NFRs, KPIs). Triggers on "specify {slug}", "spec for {slug}", "write the spec", "capture this idea", "draft requirements for {slug}", "/awesome-sdd:specify {slug}". Opens by setting the interview-depth dial (easy/medium/hard), drafts from templates/spec.md, validates each acceptance criterion Socratically, runs a clean-context critic, then writes docs/features/{slug}/spec.md. The ideation analyses (competitive research, strategic approaches, multi-perspective review, devil's-advocate) run as named subagents gated by the depth dial — easy skips them, hard runs the full suite.

Give a read-only SDD progress recap when asked "where are we?", "what is left?", "status {slug}", or "help me pick this up again". Read saved decisions, tasks, Git and verification evidence; report what is finished, blocked and next. Does not start work, repair settings or change task status. Explicit implementation requests use implement.

Use to establish the repo's architecture map the rest of the pipeline reads. Two modes: on an EXISTING codebase it scans once and persists what's there; on an EMPTY/greenfield repo it runs a short, level-adaptive foundation session — picks the stack / folder structure / data approach / conventions WITH you (defaults-heavy), fixes them as the foundation + foundational ADRs, and emits a scaffold tasks.json that the scaffold skill materializes into a real skeleton. Triggers on "survey the codebase", "map the architecture", "set up a new project", "bootstrap the foundation", "/awesome-sdd:survey". Output: docs/architecture-map.md (+ adr/ + scaffold tasks.json on greenfield). Records reflects_commit for staleness; reads, never overwrites, an authored architecture doc.

Use to break a designed feature into atomic, ≤1-day tasks with a dependency graph, a per-task Definition of Done, and a machine-readable tasks.json that the implement engine consumes. Triggers on "task breakdown for {slug}", "break down tasks for {slug}", "tasks for {slug}", "plan the work for {slug}", "/awesome-sdd:tasks {slug}". Reads spec.md + sad.md + Accepted ADRs (+ data-model + openapi if present), writes docs/features/{slug}/tasks/{_epic,tracker,<task>}.md AND docs/features/{slug}/tasks.json. Tracker export to any issue tracker is optional and tool-neutral. Hard-refuses if spec.md or sad.md or an Accepted ADR is missing.

Use to derive the user flows of a UI-touching feature after the spec is clarified — one mermaid flowchart per UI-touching §4 user story (happy + alt/error branches from §5 ACs), a screen inventory (SCR-NN ids), and an AC→flow map, written to docs/features/{slug}/ux-flows.md. Triggers on "ux flows for {slug}", "user flows for {slug}", "screen flow for {slug}", "/awesome-sdd:ux-flows {slug}". Always markdown + mermaid regardless of the design tool; the Socratic pass confirms each flow in prose, never raw mermaid. Feeds design (target-surface evidence), sequences (SCR alignment), screens (the inventory) and plan-tests (e2e-through-UI paths). Hard-refuse if spec.md is missing; skipped for features with no human-facing UI.