Skip to content
Back to search

sdd

MarketplaceWorks with Claude CodeGitHub

Spec-Driven Development for Claude Code: 12 atomic Socratic skills + a TDD implement engine (agent-team & dynamic-workflow modes)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/genkovich--sdd/badge.svg)](/listings/genkovich--sdd)

HTML

<a href="/listings/genkovich--sdd"><img src="/api/listings/genkovich--sdd/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Claude Code** — native plugin:

/plugin marketplace add genkovich/sdd
/plugin install sdd@sdd

After updating to a new release: re-run `/plugin install sdd@sdd`, then `/reload-plugins`.

**Codex CLI** — `cd` into your project first (installs into `.agents/skills/` + `.codex/agents/` of the current directory; `--global` for `~`, `--prefix DIR` for an arbitrary directory):

cd your-project
curl -fsSL https://raw.githubusercontent.com/genkovich/sdd/main/install.sh | bash -s -- codex

Restart codex and type `$sdd-specify`. Alternative: `codex plugin marketplace add genkovich/sdd`, then **inside codex** `/plugins` → the `sdd` tab → **Install plugin** — registers the **unprefixed** names (`$specify`) instead of the script's `$sdd-specify`. **Pick one path, not both** — running both shows every skill twice. Undo: `install.sh codex --uninstall` (script) or `/plugins` → uninstall (marketplace). Windows: run the installer from Git Bash or WSL — the dot-directories it writes are hidden by default in Explorer.

**Cursor** (2.4+) — the same script (`.cursor/skills/` + `.cursor/agents/`); restart Cursor (or **Developer: Reload Window**), then type `/` and pick `sdd-specify`:

cd your-project
curl -fsSL https://raw.githubusercontent.com/genkovich/sdd/main/install.sh | bash -s -- cursor

How every Claude-specific mechanism — `AskUserQuestion`, subagents, `/clear`, the implement engine modes — maps to Codex / Cursor is one table: [`skills/_shared/tool-adapters.md`](./skills/_shared/tool-adapters.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 26 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "sdd",
  3. "owner": {
  4. "name": "Kyrylo Genkov",
  5. "email": "genkovi4@gmail.com",
  6. "url": "https://github.com/genkovich"
  7. },
  8. "plugins": [
  9. {
  10. "name": "sdd",
  11. "source": "./",
  12. "version": "2.4.1",
  13. "description": "Spec-Driven Development pipeline: 23 atomic Socratic skills (survey/scaffold → spec → ux-flows → design → data-model → api → screens → tasks → tests → implement → review → ship) + a living decomposition roadmap (steps + dependency graph + parallel-safe execution waves) above the per-feature flow + 10 subagents, plus a TDD implementation engine with agent-team and dynamic-workflow modes. The Q&A skills are depth-tunable (easy/medium/hard); the ideation analyses (researcher/strategist/analyst/devil's-advocate) run as named subagents gated by that dial; diagrams are confirmed in prose; and every acceptance criterion is covered end-to-end. Surface-aware: declare target surfaces at design (backend/web/mobile/desktop/CLI/worker/library, as C4 containers); downstream gates the `ui` task layer, UI-driven flows, and frontend test tiers. UI features get a design pipeline (auto-skipped for backend-only work): design-system (the committed canon — Figma MCP / Pencil MCP / code-markdown; on pencil it also bootstraps and seeds the .pen library), ux-flows (user flows + SCR inventory) and screens (the per-state manifest tasks/implement/review build against, reuse-first). Every stage prints a copy-ready handoff (what changed + files to review + `/clear` + the next command).",
  14. "category": "workflow",
  15. "tags": [
  16. "sdd",
  17. "spec-driven-development",
  18. "prd",
  19. "adr",
  20. "architecture",
  21. "openapi",
  22. "tdd"
  23. ]
  24. }
  25. ]
  26. }
README.md · README · 354 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # SDD — Spec-Driven Development for Claude Code
  2. A self-contained Claude Code plugin that carries a feature from a one-line idea to
  3. **reviewed, verified, shipped** code through **23 atomic, stack-agnostic skills** and a
  4. **TDD implementation engine** — with a living decomposition roadmap above the per-feature flow and a
  5. **design pipeline** (design-system · ux-flows · screens) for UI features.
  6. Every skill is Socratic (it walks decisions with you, it doesn't dump a wall of output),
  7. gated (a stage hard-refuses when its prerequisite artifact is missing), and stack-agnostic
  8. (no language, tracker, or test tool is hard-coded — the skills detect what your repo uses).
  9. The Q&A skills are **depth-tunable** (easy / medium / hard) and run on **any Claude plan or
  10. model tier** — no skill requires a specific one; judgment agents default to `opus` and degrade
  11. gracefully when it's unavailable (see [Levers](#levers)).
  12. ## The flow
  13. There are three kinds of skill. Most of your time is the **backbone** — a straight line you
  14. walk in order. A few are **utilities** you call whenever you need them. Two **close the loop**
  15. after the code is written.
  16. ```mermaid
  17. flowchart LR
  18. IV[interview<br/>optional] -->|docs/idea-brief.md| SV[survey<br/>once per repo]
  19. SV -->|docs/architecture-map.md| RM[roadmap<br/>decomposition]
  20. RM -->|greenfield: step 1| SC[scaffold] --> S
  21. SV -.->|greenfield, no brief| SC
  22. RM -.->|per step| S
  23. IV -.-> S
  24. SV -.->|brownfield| S
  25. DS[design-system<br/>once per repo, UI] -.-> UX
  26. subgraph backbone["BACKBONE — run in order"]
  27. S[specify] --> CL[clarify] --> UX[ux-flows<br/>UI features] --> D[design] --> SQ[sequences] --> DM[data-model] --> API[api] --> SCR[screens<br/>UI features] --> T[tasks] --> PT[plan-tests] --> IM[implement]
  28. CL -.->|no UI| D
  29. API -.->|no UI| T
  30. end
  31. IM --> RV[review] --> SH[ship]
  32. subgraph util["UTILITIES — call anytime"]
  33. CFG[config]
  34. CS[classify-size]
  35. GL[glossary]
  36. ADR[decide-adr]
  37. FX[fix]
  38. end
  39. CL -.-> GL -.-> D
  40. SH --> done([shipped: PR + changelog])
  41. ```
  42. ## Install
  43. **Claude Code** — native plugin:
  44. ```text
  45. /plugin marketplace add genkovich/sdd
  46. /plugin install sdd@sdd
  47. ```
  48. After updating to a new release: re-run `/plugin install sdd@sdd`, then `/reload-plugins`.
  49. **Codex CLI** — `cd` into your project first (installs into `.agents/skills/` + `.codex/agents/`
  50. of the current directory; `--global` for `~`, `--prefix DIR` for an arbitrary directory):
  51. ```sh
  52. cd your-project
  53. curl -fsSL https://raw.githubusercontent.com/genkovich/sdd/main/install.sh | bash -s -- codex
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 64 on GitHub
  54. ```
  55. Restart codex and type `$sdd-specify`. Alternative: `codex plugin marketplace add genkovich/sdd`,
  56. then **inside codex** `/plugins` → the `sdd` tab → **Install plugin** — registers the
  57. **unprefixed** names (`$specify`) instead of the script's `$sdd-specify`. **Pick one path, not
  58. both** — running both shows every skill twice. Undo: `install.sh codex --uninstall` (script) or
  59. `/plugins` → uninstall (marketplace). Windows: run the installer from Git Bash or WSL — the
  60. dot-directories it writes are hidden by default in Explorer.
  61. **Cursor** (2.4+) — the same script (`.cursor/skills/` + `.cursor/agents/`); restart Cursor (or
  62. **Developer: Reload Window**), then type `/` and pick `sdd-specify`:
  63. ```sh
  64. cd your-project
  65. curl -fsSL https://raw.githubusercontent.com/genkovich/sdd/main/install.sh | bash -s -- cursor
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 79 on GitHub
  66. ```
  67. How every Claude-specific mechanism — `AskUserQuestion`, subagents, `/clear`, the implement
  68. engine modes — maps to Codex / Cursor is one table:
  69. [`skills/_shared/tool-adapters.md`](./skills/_shared/tool-adapters.md).
  70. ## First run
  71. The flow is a straight line: **each stage writes a file the next one reads**, and refuses to run
  72. if its input is missing — so you can't skip ahead by accident. The argument every stage takes is
  73. a kebab-case **feature slug** you make up once (here `checkout-discounts`); it becomes
  74. `docs/features/checkout-discounts/`, so use the same slug at every stage.
  75. ```text
  76. /sdd:interview # optional: pressure-test a raw idea → docs/idea-brief.md
  77. /sdd:survey # once per repo: map the current architecture
  78. /sdd:roadmap # optional: decompose into steps + waves
  79. /sdd:specify checkout-discounts # interview → spec (reads the architecture map)
  80. /sdd:clarify checkout-discounts
  81. /sdd:ux-flows checkout-discounts # UI features only — user flows + screen inventory
  82. /sdd:design checkout-discounts
  83. /sdd:sequences checkout-discounts
  84. /sdd:data-model checkout-discounts
  85. /sdd:api checkout-discounts
  86. /sdd:screens checkout-discounts # UI features only — the per-state screen manifest
  87. /sdd:tasks checkout-discounts
  88. /sdd:plan-tests checkout-discounts
  89. /sdd:implement checkout-discounts
  90. /sdd:review checkout-discounts # independent review of the whole change
  91. /sdd:ship checkout-discounts # verify it runs, changelog, PR
  92. ```
  93. **Every stage ends with a copy-ready handoff block** ([`skills/_shared/handoff.md`](./skills/_shared/handoff.md)) —
  94. *What I did* + *Review before continuing* + *Run next*: **`/clear`**, then the next `/sdd:…`
  95. command, ready to copy. `/clear` matters because each stage **re-reads its inputs from disk**, so
  96. clearing keeps context small instead of letting one stage's chatter drift into the next
  97. (loop-backs like `review` → `implement` are the exception; utilities make it optional):
  98. ```md
  99. ## ✅ specify — checkout-discounts
  100. **What I did** — wrote docs/features/checkout-discounts/spec.md, size M; commit `spec: checkout-discounts`
  101. **Review** — spec.md: goals, user stories, the §5 acceptance criteria
  102. **Run next** — /clear, then: /sdd:clarify checkout-discounts
  103. ```
  104. Three notes: **`classify-size` is optional up front** — `specify` writes `.size` itself when it's
  105. absent; run it only to size *before* specifying, or to re-classify. **Skip the depth question**
  106. with `/sdd:specify checkout-discounts --depth=easy` (also `clarify`/`design`; see [Levers](#levers)).
  107. And **`ux-flows`/`screens` auto-skip** for backend-only work, no confirmation needed.
  108. ### Step 0 — survey (once per repo, before the backbone)
  109. | # | Skill | What it does | Reads → Produces |
  110. |---|---|---|---|
  111. | 0 | **survey** | Existing repo → scans once, persists the current architecture. Empty repo → level-adaptive foundation session → fixes the foundation + emits a scaffold `tasks.json` for `scaffold`. | the repo (+ `docs/idea-brief.md` if present) → `docs/architecture-map.md` (+ scaffold `tasks.json` on greenfield) |
  112. | 0b | **scaffold** | *Greenfield only:* materializes the skeleton the foundation planned — sequentially inline, anchored on the **skeleton smoke test** (builds + boots + empty test suite + migration tool) | `architecture-map.md` + `_scaffold/tasks.json` → the committed skeleton |
  113. | 0c | **design-system** | *Once per repo, before the first UI feature:* fixes the committed design canon — the drawing tool (Figma / Pencil / code), platform posture, tokens, component inventory | the repo (+ design MCPs) → `docs/design-system.md` |
  114. ### Backbone — the straight line (run in order)
  115. | # | Skill | What it does | Reads → Produces |
  116. |---|---|---|---|
  117. | 1 | **specify** | Interviews you to capture the idea, writes the product spec + acceptance criteria (reads the architecture map for constraints) | *your idea*, `architecture-map.md` → `spec.md` |
  118. | 2 | **clarify** | Sweeps the spec for ambiguities (a devil's-advocate pass), closes or defers each | `spec.md` → tightened `spec.md` |
  119. | 3 | **ux-flows** | *UI features only (auto-skipped otherwise):* derives one user flow per UI-touching user story (happy + AC-driven error branches) + the `SCR-NN` screen inventory — always markdown+mermaid, whatever the design tool | `spec.md`, `design-system.md` → `ux-flows.md` |
  120. | 4 | **design** | **Matches the feature to your existing architecture** + **declares the target surfaces** (reading `ux-flows.md` as evidence), writes the Arc42 SAD + C4 + ADRs | `spec.md` (+ `ux-flows.md`, `CONTEXT.md` if present) → `sad.md`, `adr/*` |
  121. | 5 | **sequences** | Draws the runtime flows as Mermaid sequence diagrams (UI-driven flows agree with `ux-flows.md`) | `sad.md` → `sad.md §6` |
  122. | 6 | **data-model** | Designs the schema and writes the actual forward+rollback migrations — **staged** under the feature folder, not the live tree (`implement` promotes them) | `spec.md`, `sad.md`, sequences → `data-model.md`, staged `migrations/*.up/down.sql` |
  123. | 7 | **api** | Derives the OpenAPI contract from the data model (or the existing schema on the fast lane) + sequences + spec | `data-model.md`, sequences, `spec.md` → `contracts/openapi.yaml` |
  124. | 8 | **screens** | *UI features only (auto-skipped otherwise):* the canonical screen manifest — every screen in every state (default / loading / empty / error / …), reuse-first components; drawn per the canon's tool | `ux-flows.md`, `sad.md`, contracts, `design-system.md` → `screens.md` |
  125. | 9 | **tasks** | Breaks the work into atomic ≤1-day tasks + a `tasks.json` dependency DAG (each `ui` task cites `screens.md` SCR ids + states) | all of the above → `tasks/*`, **`tasks.json`** |
  126. | 10 | **plan-tests** | Maps every acceptance criterion to ≥1 test (inline in the spec for XS/S; e2e-through-UI paths from `ux-flows.md`, component states from `screens.md`) | `spec.md`, `data-model.md` → `test-plan.md` (M+) or an inline `## Test plan` in `spec.md` (XS/S) |
  127. | 11 | **implement** | The TDD engine: writes a failing test, makes it pass, gates, commits — per task; **promotes** each staged migration into the live `migrations/` as it builds; a `ui` task builds to the `screens.md` states, reusing the inventory | `tasks.json` + all artifacts → code + tests + promoted migrations, committed |
  128. ### Close the loop (after the code is written)
  129. | # | Skill | What it does | Reads → Produces |
  130. |---|---|---|---|
  131. | 12 | **review** | An **independent, clean-context** code review of the *whole* change against spec/AC + quality (incl. built-screen ↔ `screens.md` match) | the diff + `spec.md` → review record, `PASS` / `CHANGES REQUESTED` |
  132. | 13 | **ship** | **Verifies the feature actually runs** (not just green tests), writes the changelog, opens the PR | the reviewed change → changelog + PR (never auto-merges) |
  133. `review` can bounce back to `implement` if it finds an unmet acceptance criterion. `ship` is the
  134. end: a reviewed, verified change with a changelog and an open PR — merging to main stays your call.
  135. Tests-pass happens continuously inside `implement` (a per-task gate); `review` is the cross-cutting
  136. whole-change check a human reviewer would do; `ship` runs the feature for real.
  137. ### Utilities — call whenever you need them (not part of the line)
  138. - **interview** *(before roadmap / specify)* — gets the idea out of your head and onto disk: an
  139. adaptive engineering interview with bounded fact-checking and risk-based critique. Writes the
  140. 8-section `docs/idea-brief.md` with decisions, evidence and readiness. Outside a repo or in Plan
  141. Mode it stays talk-only; headless it stops before writes/helpers. `specify` reuses its answers.
  142. - **config** — the per-project settings file `.claude/sdd.local.md`: creates it with documented
  143. defaults, then walks six grouped questions and patches only the keys you confirm (your comments,
  144. key order and unknown keys survive untouched). The **only** skill that changes a setting — the six
  145. creating skills create and read, they never offer to tune.
  146. - **classify-size** — size the feature XS/S/M/L/XL (writes `.size`); later skills read it. Run it
  147. at the start, or any time scope changes.
  148. - **glossary** — capture a domain term in `CONTEXT.md`. Run it whenever a new term shows up;
  149. `design` and the spec read it.
  150. - **decide-adr** — write a standalone ADR after the fact, when `tasks` (or a review) flags a
  151. decision that needs recording but wasn't captured during `design`.
  152. - **fix** — the bugfix entry point: reproduce, trace the symptom to the spec's acceptance
  153. criteria, pin it with a failing test, apply the minimal fix through the same gate `implement`
  154. runs, then patch the spec. Works on a repo with no specs at all.
  155. ## Above a single feature
  156. The backbone builds one feature at a time. Three utilities carry what's above it.
  157. **The idea, out of your head.** `interview` (optional) writes the 8-section `docs/idea-brief.md`
  158. (raw idea, problem, users, why now, out of scope, risks, recommendation, open questions).
  159. `specify` reuses its accepted answers/evidence and asks only specification gaps; without a brief,
  160. it retains standalone discovery. `roadmap` refuses to decompose without a source. The interview
  161. can also end `needs-evidence`, `reframe`, or `stop` rather than force an unready idea downstream.
  162. Its saved/explicit depth is a ceiling (easy ≤4, medium ≤10, hard ≤15 questions), with no opening
  163. selector or minimum count. Research follows a decision-changing gap; critique follows risk.
  164. **The codebase, studied once.** `survey` persists `docs/architecture-map.md` — module layout,
  165. datastores, conventions, a C4 of what exists — so no later stage re-opens "what's the current
  166. architecture?" `specify`/`design`/`data-model`/`implement` all read it. An empty repo gets a short
  167. foundation session instead (`mode: greenfield-bootstrap` + a scaffold `tasks.json` that
  168. `/sdd:scaffold` materializes — after `roadmap` when there is a brief, since the skeleton is the
  169. roadmap's step 1). Refresh once the repo drifts past its recorded `reflects_commit`.
  170. **The idea, decomposed.** `roadmap` breaks it into `docs/roadmap.md`: source-anchored steps sized
  171. XS–XL or `fog` (unformulated work waits in `Not yet specified` until a recon pass sharpens it), a
  172. dependency graph, and conflict-safe execution waves for parallel worktree lanes. No RICE, no dates
  173. — order is the prioritization, and delivery keeps it current (`specify` marks spec'd, `ship`
  174. marks shipped).
  175. ## Levers
  176. Four dials tune how much a skill decides for you vs. asks — each is a floor-not-pin default,
  177. never a change to *what* gets covered:
  178. | Lever | What it decides | Set via | Canonical |
  179. |---|---|---|---|
  180. | **Interview depth** (easy / medium / hard) | how many questions `specify` / `clarify` / `design` ask | `/sdd:config`, or `--depth=` inline for one run | [`interview-depth.md`](./skills/_shared/interview-depth.md) |
  181. | **Target surface** (backend-service / web-frontend / mobile-app / desktop-app / cli / worker / library-sdk) | which C4 container the feature targets; gates the `ui` task layer, UI-driven sequences, and the frontend test tiers | declared by `design` §4, from the spec's "for whom" | [`surfaces.md`](./skills/_shared/surfaces.md) |
  182. | **Judgment model & effort** | which model tier the judgment agents (reviewer/critic/devils-advocate/strategist/analyst) run at; L/XL escalates critical verifications to `effort: xhigh` | `/sdd:config` (writes `judgment_model`, `model_<role>`, `effort_<role>`) | [`agent-roster.md`](./skills/_shared/agent-roster.md) |
  183. | **Route** (quick / standard / full) | how aggressively optional stages (clarify/sequences/data-model/api/plan-tests) auto-skip when their N/A condition holds | `.route`, defaulted by size (XS/S → quick, M → standard, L/XL → full) and confirmed at `classify-size` | [`size-matrix.md`](./skills/_shared/size-matrix.md) |
  184. No dial weakens diagram presentation (always confirmed **in prose**, written to file, never
  185. dumped raw — [`diagram-presentation.md`](./skills/_shared/diagram-presentation.md)) or acceptance-criteria
  186. coverage (every spec §4 story + §5 AC traced end-to-end, `easy`/XS just asks fewer questions).
  187. ### The settings file
  188. Six skills — `interview`, `survey`, `roadmap`, `scaffold`, `specify`, `implement` — **create**
  189. `.claude/sdd.local.md` after their entry gate (`interview` defers creation until its final
  190. writable brief step), so the file exists before downstream stages need it
  191. instead of surfacing three stages later. It's per-project, gitignored (the `.gitignore` patch is
  192. the only committed part), and self-documenting: every key carries its default and allowed values
  193. inline. **`/sdd:config` is the only thing that changes a value** — it creates the file first, so
  194. you have a working config before answering anything, then asks six grouped questions and patches
  195. only the keys you confirm.
  196. This is exactly what lands on disk, defaults and all:
  197. ```yaml
  198. interview_depth: medium # easy | medium | hard — plugin-wide default for specify/clarify/design
  199. artifact_language: en # en | uk (any language tag) — language pipeline DOCUMENTS are written in
  200. tdd: true # enforce red→green→refactor
  201. team_mode: false # true → agent team via TeamCreate
  202. workflow_mode: auto # auto → dynamic Workflow; off → never
  203. max_parallel_agents: 3 # integer ≥1 — fan-out cap for team/workflow modes (1 = sequential)
  204. isolation: worktree # worktree | inplace (parallel>1 ⇒ forces worktree)
  205. stop_on_red: true # halt on a red that survives escalation, vs drop-and-continue
  206. max_red_retries: 3 # integer ≥1 — RED→GREEN attempts before escalation
  207. gate_lint: true # true | false — include lint in the per-task gate
  208. gate_vet: true # true | false — include vet / static-analysis in the per-task gate
  209. require_integration: auto # auto | always | never (Docker-probed)
  210. auto_commit: per_task # per_task | per_phase | off — off also stops document-stage commits
  211. branch_strategy: feature # feature | current
  212. cmd_test_unit: "" # empty = autodetect (escape hatch)
  213. cmd_test_integration: ""
  214. cmd_lint: ""
  215. cmd_vet: ""
  216. model_test_author: sonnet # per-role model; inherit = session model
  217. model_implementer: sonnet
  218. model_reviewer: opus
  219. judgment_model: opus # tier alias (haiku|sonnet|opus|fable), inherit, or a full model id
  220. effort_test_author: medium # per-role effort; raised to high on escalation
  221. effort_implementer: medium
  222. effort_reviewer: high
  223. ```
  224. Grouped the way `/sdd:config` asks about them — one answer per group, several keys per answer:
  225. | Group | Keys | Default | What it decides |
  226. |---|---|---|---|
  227. | **Interview depth** | `interview_depth` | `medium` | how many questions `specify` / `clarify` / `design` ask before deciding for you; never changes *what* is covered |
  228. | **Document language** | `artifact_language` | `en` | the prose language of every pipeline document; headings, frontmatter and machine tokens stay English |
  229. | **Model tier** | `judgment_model`, `model_test_author`, `model_implementer`, `model_reviewer`, `effort_test_author`, `effort_implementer`, `effort_reviewer` | judgment `opus`, execution `sonnet` | which tier the judgment agents and the execution agents run at. `judgment_model` is one switch for all five judges; `opus` is a floor, not a pin |
  230. | **Strictness & gates** | `tdd`, `stop_on_red`, `max_red_retries`, `gate_lint`, `gate_vet`, `require_integration` | `true` / `true` / `3` / `true` / `true` / `auto` | whether the failing test comes first, what a surviving red does to the run, and which tiers the per-task gate runs |
  231. | **Execution & commits** | `team_mode`, `workflow_mode`, `max_parallel_agents`, `isolation`, `auto_commit`, `branch_strategy` | `false` / `auto` / `3` / `worktree` / `per_task` / `feature` | sequential vs. agent team vs. dynamic workflow, how wide it fans out, and how finely the work commits (every document stage also commits its own documents, one commit per document; `auto_commit: off` turns that off too). `team_mode` / `workflow_mode` need Claude Code — on Codex CLI and Cursor they clamp to sequential |
  232. | **Commands** *(never asked)* | `cmd_test_unit`, `cmd_test_integration`, `cmd_lint`, `cmd_vet` | `""` | empty means autodetect, which beats a pinned command that goes stale. Fill one only for a repo the cascade can't read |
  233. Command detection (for `implement`'s gate) is a stack-agnostic cascade: settings override →
  234. Makefile → `package.json` scripts → language manifests → Docker probe for integration.
  235. ## The design pipeline (UI features)
  236. Three skills carry a UI feature from user flows to a per-state screen manifest, auto-skipped
  237. end-to-end for backend-only work ([`size-matrix.md`](./skills/_shared/size-matrix.md)):
  238. - **`design-system`** *(once per repo)* — the committed canon `docs/design-system.md`: which tool
  239. screens are drawn with (Figma MCP / Pencil MCP / inline markdown), platform posture, tokens,
  240. component inventory.
  241. - **`ux-flows`** *(after `clarify`)* — one mermaid flow per UI-touching user story + the `SCR-NN`
  242. screen inventory; `design` reads it as evidence for the target-surface declaration.
  243. - **`screens`** *(between `api` and `tasks`)* — every screen in every state, derived from the ACs +
  244. sequence branches + contract errors; reuse-first — a `NEW` component only with a
  245. why-no-primitive-fits justification, registered back into the canon.
  246. Downstream, the manifest is the contract: `tasks` cites SCR ids + states, `implement` builds to
  247. the declared states with the named components, `review` checks the built screen against it.
  248. ## The implementation engine
  249. `implement` reads `tasks.json`, builds a dependency DAG, and runs a **TDD cycle per task** —
  250. `SELECT → RED → GREEN → REFACTOR → GATE → COMMIT`: a failing test first, proof the failure is for
  251. the right reason, the minimal code to pass, refactors that stay green, the gate, then a commit
  252. with `SDD-Task` / `SDD-AC` trailers.
  253. Three execution modes, chosen automatically from settings + DAG shape (graceful fallback):
  254. - **Sequential single-agent TDD** — the default and the floor everything degrades to.
  255. - **Agent team** (`team_mode: true`) — `test-author` → `implementer` → `reviewer` over the DAG,
  256. coordinated through a shared task list, one git worktree per agent.
  257. - **Dynamic workflow** (`workflow_mode: auto`) — a generated `Workflow` pipeline that fans out
  258. independent tasks up to a parallelism cap.
  259. ### When a stage refuses
  260. Stages are gated: each one **hard-refuses when the artifact it consumes is missing** and names the
  261. stage to run first. A refusal is not an error — it's the pipeline telling you which step was
  262. skipped.
  263. | Refusal | What it means | What to do |
  264. |---|---|---|
  265. | `design`: «run `specify` first» | there's no `spec.md` for this slug yet (or the slug is spelled differently) | run `/sdd:specify <slug>`; check the slug matches the folder under `docs/features/` |
  266. | `api`: «run `data-model` first» | the feature **changes the schema** but has no `data-model.md`. (No schema change → `api` doesn't refuse: it derives from the existing schema) | run `/sdd:data-model <slug>` |
  267. | `tasks`: «no Accepted ADR» | `design` spawned no ADR (rare — usually a sign the SAD walk was cut short) | run `/sdd:decide-adr <slug>` for the key decision, or re-run `/sdd:design <slug>` |
  268. ## Repository layout
  269. ```
  270. .claude-plugin/ plugin.json + marketplace.json (self-marketplace)
  271. .codex-plugin/ Codex CLI plugin manifest (+ .agents/plugins/marketplace.json — its self-marketplace)
  272. .cursor-plugin/ Cursor plugin manifest (skills/ + agents/ auto-discovered from the root)
  273. install.sh Codex CLI / Cursor installer — copies the subtree, prefixes skill names, generates functional agents
  274. agents/ explorer, test-author, implementer, reviewer, critic, devils-advocate, researcher, strategist, analyst, pen-keeper
  275. scripts/ validate_plugin.py (CI gate: manifests + skill/agent frontmatter + the consistency invariants — links resolve, /sdd: form, handoff block, single-source taxonomy, no _shared orphans)
  276. skills/_shared/ canonical agent-roster / artifact-language / ask-style / critic / diagram-presentation / handoff / interview-depth / mermaid-check / self-check / settings-file / size-matrix / socratic-loop / surfaces / tool-adapters (referenced, not duplicated)
  277. skills/<name>/ SKILL.md spine + references/ (heavy detail) + templates/ (output scaffolds)
  278. ```
  279. ## What's next
  280. Directions under consideration — not promises, no dates:
  281. - **`sync`** — spec↔code drift detection: re-derive what the code actually does and diff it
  282. against the spec/SAD, so long-lived features don't quietly outgrow their documents.
  283. - **Traceability matrix + adherence score** — `review`/`ship` emit a single AC × (flow / contract
  284. / task / test / commit) matrix with a coverage score, instead of prose-only tracing.
  285. - **Tracker integration** — `tasks.json` ⇄ Jira / Linear / GitHub Issues two-way sync (today the
  286. export is one-shot and copy-paste).
  287. - **Constitution file** — a repo-level set of inviolable rules (security, compliance, style) every
  288. stage reads and the validator enforces, complementing the per-feature artifacts.
  289. ## License
  290. MIT © Kyrylo Genkov. See [LICENSE](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.