From 87b199a77267ef6eb171164fedc912403fcb9144 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 13 Jun 2026 12:19:34 +0200
Subject: [PATCH] docs(sdd): add at-a-glance workflow graph, prerequisites, and
 gates

Consolidates the full SDD workflow into one view at the top of the guide: a
Mermaid flowchart (skills, the three gates, the TDD loop), a one-time
prerequisites checklist, and a gates table.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 SPEC_DRIVEN_DEVELOPMENT.md | 65 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/SPEC_DRIVEN_DEVELOPMENT.md b/SPEC_DRIVEN_DEVELOPMENT.md
index ac942538..a97af88d 100644
--- a/SPEC_DRIVEN_DEVELOPMENT.md
+++ b/SPEC_DRIVEN_DEVELOPMENT.md
@@ -12,6 +12,71 @@ multi-persona review → red/green TDD). It does not replace any of that — see
 
 ---
 
+## 0. The whole workflow at a glance
+
+```mermaid
+flowchart TD
+    idea([Feature idea]):::start --> draft
+
+    subgraph author["✍️  Author"]
+        draft[/"/draft-spec<br/>(Requirements Engineer)"/]:::skill --> issue[("Gitea issue = the SPEC<br/>EARS REQ-NNN + acceptance criteria")]:::spec
+    end
+
+    issue --> ri[/"/review-issue"/]:::skill
+    ri --> g1{"GATE 1 · spec review<br/>6 personas APPROVE?<br/>Open Questions empty?"}:::gate
+    g1 -- "FAIL / question" --> amend["Amend the issue body"]:::work --> ri
+    g1 -- "APPROVE" --> rtm["Seed RTM rows<br/>REQ-ID → issue #"]:::work
+
+    rtm --> wt["Create git worktree<br/>(pull main first)"]:::work --> impl[/"/implement"/]:::skill
+
+    subgraph build["🔁  Build · TDD per REQ-NNN"]
+        impl --> red["Red: failing test"]:::work --> green["Green: minimal code"]:::work --> sync["Refactor + sync<br/>generate:api · flip RTM → Done"]:::work --> commit["Commit · Refs #n"]:::work
+        commit -- "next REQ" --> red
+    end
+
+    build --> pr[["Open PR · Closes #n"]]:::work --> g2{"GATE 2 · CI green?<br/>ci.yml + sdd-gate.yml"}:::gate
+    g2 -- "red" --> fixci["Fix on branch"]:::work --> g2
+    g2 -- "green" --> rp[/"/review-pr"/]:::skill
+
+    rp --> g3{"GATE 3 · PR review<br/>all personas APPROVE?<br/>every REQ implemented + tested?<br/>no Do-Not-Touch violation?"}:::gate
+    g3 -- "changes requested" --> fixpr["Fix on branch"]:::work --> rp
+    g3 -- "APPROVE" --> merge([Merge → main<br/>closed issue = archived spec]):::start
+
+    rules["📐 constitution.md + AGENTS.md<br/>(bind every step)"]:::rules -.-> draft
+    rules -.-> impl
+    rules -.-> rp
+
+    classDef start fill:#1d3b53,color:#fff,stroke:#1d3b53;
+    classDef skill fill:#e8f5f0,stroke:#3aa884,color:#13352b;
+    classDef gate fill:#fff3cd,stroke:#d39e00,color:#5a4500;
+    classDef spec fill:#eef2ff,stroke:#5b6ee1,color:#1e2a5a;
+    classDef work fill:#f6f6f6,stroke:#bbb,color:#222;
+    classDef rules fill:#fdecea,stroke:#d9534f,color:#611a15;
+```
+
+> `/deliver-issue` runs **GATE 1 → discuss → build → GATE 3 (loop)** end-to-end in one go.
+
+### Prerequisites (one-time setup)
+
+Before the workflow runs cleanly, confirm these exist (most ship with this repo):
+
+- [ ] **Gitea labels** `spec-required` and `needs-review` exist (the feature template + `/draft-spec` attach them; the `labels` create-param is ignored, so they must pre-exist).
+- [ ] **Gitea MCP** server configured (`gitea`) — the skills read/write issues and PRs through it.
+- [ ] **`.spectral.yaml`** at the repo root (extends `spectral:oas`) — the CI contract check needs it.
+- [ ] **Personas present**: identities in [`.claude/personas/`](./.claude/personas/) + checklists in [`.specify/personas/`](./.specify/personas/).
+- [ ] **`.specify/constitution.md` + `AGENTS.md`** committed on `main` (so every branch inherits them).
+- [ ] **Worktrees + hooks**: new feature work goes in a `git worktree` (plus-free name); run `npm install` in `frontend/` once per worktree so the pre-commit lint hook works.
+
+### The three gates
+
+| Gate | When | Mechanism | Blocks on |
+|---|---|---|---|
+| **1 · Spec review** | after `/draft-spec`, before any code | `/review-issue` (6 persona checklists) | any persona `CHANGES REQUESTED`, or an unresolved `## Open Question` |
+| **2 · CI** | on every PR | `ci.yml` (tests · lint · semgrep) + `sdd-gate.yml` (rtm-check · contract-validate · constitution-diff) | `ci.yml` failure (hard); `sdd-gate` jobs are non-blocking during adoption — see the workflow TODO |
+| **3 · PR review** | before merge | `/review-pr` (7 personas + traceability) | any persona `Changes requested`, an unimplemented/untested `REQ-NNN`, or a constitution Do-Not-Touch violation |
+
+---
+
 ## 1. The workflow in 8 steps
 
 | # | Step | Who | Artifacts created / touched |