|
| 1 | +# Damascus |
| 2 | + |
| 3 | +**Structured Prompt-Driven Development for Claude Code.** A raw idea enters; folded, hardened, tested steel leaves. Damascus packages the SPDD pipeline — four gated stages plus an orchestrator — as skills you symlink into any repo. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +## The Pipeline |
| 8 | + |
| 9 | +| Stage | Skill | Alias | Input | Output | |
| 10 | +|-------|-------|-------|-------|--------| |
| 11 | +| 1 | `forge` | `prd-authoring` | raw idea | `.prd/NNN_<slug>.md` (REASONS Canvas PRD) | |
| 12 | +| 2 | `anvil` | `speckit-decomposition` | PRD | `specs/NNN-<slug>/{spec,plan,tasks}.md` | |
| 13 | +| 3 | `temper` | `adversarial-review-loop` | spec triplet | `review.md` with A++ rating | |
| 14 | +| 4 | `quench` | `bdd-tdd-execution` | A++ triplet | passing BDD + TDD tests + implementation | |
| 15 | +| ⊕ | `smithy` | `spdd-pipeline` | (any state) | drives all 4 stages, halting at every gate | |
| 16 | + |
| 17 | +```mermaid |
| 18 | +flowchart LR |
| 19 | + idea([raw idea]) --> forge |
| 20 | + forge -->|PRD| anvil |
| 21 | + anvil -->|spec / plan / tasks| temper |
| 22 | + temper -->|A++ triplet| quench |
| 23 | + quench -->|tested code| done([merged PR]) |
| 24 | + smithy -.orchestrates, halts at gates.-> forge & anvil & temper & quench |
| 25 | +``` |
| 26 | + |
| 27 | +**Golden Rule (Fowler):** when reality diverges from the prompt, fix the prompt before the code. |
| 28 | + |
| 29 | +Every stage halts at its gate for user signoff. State lives in the disk artifacts, so `smithy` can resume any feature from any point. For one-line typos and hotfixes: skip the pipeline and just fix it — SPDD is for non-trivial work. |
| 30 | + |
| 31 | +### Temper: the adversarial review loop |
| 32 | + |
| 33 | +Temper needs **no external API**. Each round, three critic subagents with distinct lenses (completeness, feasibility, testability) try to *refute* the spec triplet; a judge dedupes findings and assigns a rating. Blocking findings are applied, the round is logged, and the loop repeats. **A++ requires two consecutive rounds with zero blocking findings** (max 5 rounds, then escalate). The full trail lives in `specs/NNN-<slug>/review.md`, append-only. |
| 34 | + |
| 35 | +## Install |
| 36 | + |
| 37 | +From your repo root: |
| 38 | + |
| 39 | +```bash |
| 40 | +git submodule add <this-repo-url> vendor/damascus |
| 41 | +git submodule update --init --recursive |
| 42 | +./vendor/damascus/install.sh |
| 43 | +``` |
| 44 | + |
| 45 | +This symlinks into your `.claude/`: |
| 46 | + |
| 47 | +- the 5 stage skills + 5 aliases → `.claude/skills/` |
| 48 | +- 5 quench agents (`bdd-scenario-writer`, `tdd-test-generator`, `playwright-e2e-tester`, `fastapi-implementer`, `labcoat`) → `.claude/agents/` |
| 49 | +- the KEEP-class [obra/superpowers](https://github.com/obra/superpowers) skills (see policy below) → `.claude/skills/` |
| 50 | + |
| 51 | +Re-run any time to refresh; `./vendor/damascus/install.sh --uninstall` removes everything it owns and nothing else. |
| 52 | + |
| 53 | +## Vendored Submodules |
| 54 | + |
| 55 | +| Submodule | Pin | Role | |
| 56 | +|-----------|-----|------| |
| 57 | +| [obra/superpowers](https://github.com/obra/superpowers) | v4.3.1 | process-discipline skills; KEEP-class linked at install | |
| 58 | +| [github/spec-kit](https://github.com/github/spec-kit) | v0.10.1 | `anvil`'s fallback templates (`templates/{spec,plan,tasks}-template.md`) when `/speckit.*` slash commands aren't registered | |
| 59 | + |
| 60 | +## Superpowers Policy (DENY / KEEP / CONDITIONAL) |
| 61 | + |
| 62 | +The pipeline stages are the canonical entrypoints. Three upstream skills overlap them and are **DENY** — not linked at install, and each stage skill carries redirect language: |
| 63 | + |
| 64 | +| Upstream skill | Policy | Use instead | |
| 65 | +|----------------|--------|-------------| |
| 66 | +| `brainstorming` | DENY | `forge` — structured elicitation with a durable PRD artifact | |
| 67 | +| `writing-plans` | DENY | `anvil` — 3-file spec-kit-shaped artifact set | |
| 68 | +| `executing-plans` | DENY | `quench` (or `smithy` cross-stage) — BDD-first, red-amber-green | |
| 69 | +| `test-driven-development` | CONDITIONAL | linked; quench **overrides** its red-green cycle with red-amber-green | |
| 70 | +| remaining 10 skills | KEEP | linked as-is (`systematic-debugging`, `verification-before-completion`, `finishing-a-development-branch`, …) | |
| 71 | + |
| 72 | +**Red-amber-green:** standard TDD goes red → green. Quench inserts **amber** — the test must fail *for the right reason* (the assertion you care about, not an import error) before any implementation is written. Amber is the moment you trust the test. |
| 73 | + |
| 74 | +## Layout |
| 75 | + |
| 76 | +``` |
| 77 | +skills/{forge,anvil,temper,quench,smithy}/SKILL.md the five stages |
| 78 | +skills/<alias> -> <stage> invocation aliases |
| 79 | +agents/*.md quench's dispatch agents |
| 80 | +vendor/superpowers pinned submodule |
| 81 | +vendor/spec-kit pinned submodule |
| 82 | +install.sh consumer-side symlinker |
| 83 | +``` |
| 84 | + |
| 85 | +## Optional host-repo integrations |
| 86 | + |
| 87 | +The skills degrade gracefully — each of these is used when present and skipped silently when not: |
| 88 | + |
| 89 | +- **Board projection** — if your repo has a kanban/state sync script, each stage gate runs it once |
| 90 | +- **Phase signalling** — if your repo has a status-bar helper (e.g. tmux), quench calls it at red/amber/green transitions |
| 91 | +- **Drift detection** — if a pre-commit hook flags code changes without spec changes, smithy halts on it |
| 92 | + |
| 93 | +## Credits |
| 94 | + |
| 95 | +- Martin Fowler — [*Structured Prompt-Driven Development*](https://martinfowler.com/articles/structured-prompt-driven/) (REASONS Canvas, Golden Rule) |
| 96 | +- [obra/superpowers](https://github.com/obra/superpowers) — process-discipline skills |
| 97 | +- [github/spec-kit](https://github.com/github/spec-kit) — spec-driven development toolkit |
0 commit comments