@luizsantiago/spec-guardrails 4.7.0 → 4.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/README.md +222 -139
  2. package/index.js +57 -1
  3. package/lib/constants.js +2 -0
  4. package/lib/feature-pr-body.js +65 -0
  5. package/lib/gates.js +2 -0
  6. package/lib/install-hooks.js +57 -0
  7. package/package.json +6 -4
  8. package/scripts/_project_config.py +32 -0
  9. package/scripts/req_analysis_diff.py +128 -0
  10. package/scripts/validate_design.py +153 -0
  11. package/scripts/validate_spec.py +111 -2
  12. package/scripts/validate_state.py +39 -0
  13. package/skills/agent-architecture.md +3 -2
  14. package/skills/references/design.md +18 -1
  15. package/skills/references/validate.md +1 -0
  16. package/templates/ci/guardrails-pr.yml +78 -0
  17. package/templates/config.yaml.example +6 -0
  18. package/templates/hooks/pre-commit +49 -0
  19. package/templates/presets/python-platform.yaml +1 -1
package/README.md CHANGED
@@ -8,242 +8,325 @@
8
8
 
9
9
  **Governed spec-driven development for AI coding agents.**
10
10
 
11
- Spec Guardrails installs a working method into your repository: the agent writes down what it is going to build, gets your approval, implements in small waves, and proves the result before calling it done. Nothing about your stack changes — you get written requirements, a task plan, and verification evidence stored as files in the project.
11
+ Agents are fast — and optimistic. They ship code, summarize what they *think* they did, and move on. Spec Guardrails installs a **repeatable contract** into your repo: agree on the goal in writing, break work into provable steps, implement in waves, and verify with evidence that lives in **git**, not in a chat scrollback.
12
12
 
13
- npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.7.x**
13
+ You keep control: the agent proposes; you approve specs and tasks; push, merge, and deploy stay on your terms.
14
14
 
15
- ### Who it's for
16
-
17
- - **Any stack** — default SDD with gates and `.specs/` memory
18
- - **Python platform teams** — backend + DevOps + AI in one repo: use preset `python-platform`, Ship/AI Surface, and [Tutorial 04](docs/guide/tutorials/04-python-platform-ship-surface.md). Not a live observability platform — see [limitations](docs/guide/python-platform.md#limitations-honest).
19
-
20
- ---
21
-
22
- ## What changes in practice
23
-
24
- | Without it | With Spec Guardrails |
15
+ | Without Spec Guardrails | With Spec Guardrails |
25
16
  | --- | --- |
26
- | The agent jumps straight to code and says "done" | Requirements are written and approved first, and "done" needs evidence |
27
- | Each new chat starts from zero | Specs, decisions, and state live in `.specs/` and survive the session |
28
- | Small fixes and risky features get the same treatment | The agent measures complexity and applies only the depth the change needs |
29
- | The whole playbook is pasted into every message | One phase guide is loaded per turn, which keeps cost and focus under control |
17
+ | Jumps to code and says “done” | Written goal first; “done” needs evidence |
18
+ | Each chat starts from zero | `.specs/` survives sessions and handoffs |
19
+ | Same ceremony for a typo and a payment flow | Complexity router matches depth to risk |
20
+ | Whole playbook pasted every turn | One skill per turn — lower cost, sharper focus |
30
21
 
31
- You stay in charge of scope: the agent proposes, you approve specs, task plans, and anything that touches git beyond local commits.
22
+ **Platform adapters.** The same kit installs into the skill tree your agent already reads — **Cursor** (`.cursor/skills/`), **Claude Code** (`.claude/skills/`), **GitHub Copilot** (`.github/skills/`), **OpenAI Codex** (`.codex/skills/`), plus root `AGENTS.md` for other tools. By default `install` detects one platform and writes **one** tree; use `--all-platforms` when the repo serves multiple agents. Existing trees are preserved when you switch IDEs.
32
23
 
33
- Read more: [Overview](docs/guide/Overview.md) · [How it works](docs/guide/How-it-works.md) · [Concepts](docs/guide/concepts.md)
24
+ npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.8.x**
25
+
26
+ **Docs:** [Overview](docs/guide/Overview.md) · [Quick start](docs/guide/Quick-start.md) · [Full guide index](docs/guide/README.md)
34
27
 
35
28
  ---
36
29
 
37
30
  ## Install
38
31
 
39
- Run once in your project root:
32
+ Two commands — run both once in your project root:
40
33
 
41
34
  ```bash
42
35
  npx @luizsantiago/spec-guardrails install
43
36
  npx @luizsantiago/spec-guardrails doctor
44
37
  ```
45
38
 
46
- `install` writes the phase guides for your agent and creates the `.specs/` folder. By default it detects your platform (Cursor, Claude Code, Copilot, or Codex) and installs **one** skill tree plus that platform's adapter entry file. Existing trees are preserved when you switch IDEs. Use `install --all-platforms` for every tree, or `install --platform <id>` to force one.
39
+ | Command | What it does |
40
+ | --- | --- |
41
+ | **`install`** | Copies phase guides and sister skills into your agent tree, creates `.specs/`, installs Python gate scripts |
42
+ | **`doctor`** | Audits readiness — **Process** score (Node workflow) and **Brakes** score (Python gates available). Run after install and after every upgrade |
43
+
44
+ | Requirement | What you get |
45
+ | --- | --- |
46
+ | **Node.js 18+** | **Required** — CLI, skills, `.specs/` scaffold, full SDD workflow |
47
+ | **Python 3.10+** | **Optional** — enables **Brakes mode** (automatic gates below) |
47
48
 
48
- Re-run `install` after upgrading the package — your existing `.specs/` notes are preserved. After that, you work in **agent chat**, not in the terminal; the agent calls the CLI and checks when needed.
49
+ Re-run `install` after package upgrades — your `.specs/` notes are preserved. Day to day you work in **agent chat**; the agent calls the CLI when a phase needs it.
49
50
 
50
- | Requirement | Role |
51
+ ### Optional presets
52
+
53
+ Seed team rules and stack hints in `.specs/config.yaml`:
54
+
55
+ ```bash
56
+ npx @luizsantiago/spec-guardrails init-config --preset <name>
57
+ npx @luizsantiago/spec-guardrails preset list
58
+ ```
59
+
60
+ | Preset | Typical use |
51
61
  | --- | --- |
52
- | **Node.js 18+** | Required — the CLI and the install step |
53
- | **Python 3.10+** | Optional — turns on automatic proof at each step |
62
+ | `default` | General SDD |
63
+ | `node-ts` | Node / TypeScript projects |
64
+ | `python` | Python apps (`pytest`, `ruff`) |
65
+ | `python-platform` | Python + optional deploy/infra and/or AI paths per feature — [guide](docs/guide/python-platform.md) |
54
66
 
55
- ### Do you need Python?
67
+ **Go deeper:** [Quick start](docs/guide/Quick-start.md) · [Platform parity](docs/guide/Platform-parity.md) · [Migration](docs/guide/Migration.md)
56
68
 
57
- **Node alone is enough to use everything** — every phase, every document, every approval point. The full process runs the same way.
69
+ ### Node alone vs Node + Python (gates)
58
70
 
59
- The difference is who decides whether a step is really finished:
71
+ **Node is enough for the full process** — every phase, every artifact, every approval. The agent follows the same hub and phase guides.
60
72
 
61
- - **Without Python** — the agent checks its own work by reading the phase checklist. It works, but you are trusting the agent to be honest when it is eager to move on.
62
- - **With Python** — the same checks run automatically, and the agent **cannot advance** with half-done work: saying "done" without test evidence, writing a task that matches no requirement, or closing a step with an open question all stop the process until fixed.
73
+ The difference is who decides whether a step is really finished:
63
74
 
64
- In short: Python turns "trust the agent" into "the agent has to prove it."
75
+ | | **Process** (Node only) | **Brakes** (Node + Python) |
76
+ | --- | --- | --- |
77
+ | **Workflow** | Same SDD phases | Same SDD phases |
78
+ | **Who checks** | Agent reads the checklist in skills | Python scripts with **exit codes** |
79
+ | **When something is incomplete** | Agent *should* stop — relies on honesty | Agent **cannot** advance — non-zero = STOP |
80
+ | **Best for** | Learning the method, light teams | Teams that want proof between your approvals |
65
81
 
66
- Which checks exist and what each one requires: [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
82
+ Add Python when you want those checklists enforced by **exit codes** instead of agent honesty — [what gates check at each boundary](#2-gates-brakes--done-has-to-be-provable). `doctor` reports Process vs Brakes readiness after install and upgrades.
67
83
 
68
- | Go deeper | [Quick start](docs/guide/Quick-start.md) · [CHANGELOG](docs/CHANGELOG.md) · [Product history](docs/guide/Product-history.md) · [Tutorials](docs/guide/tutorials/README.md) · [Platform parity](docs/guide/Platform-parity.md) |
84
+ **Go deeper:** [Gates reference](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md) · [Process vs Brakes (FAQ)](docs/guide/FAQ.md#process-vs-brakes)
69
85
 
70
86
  ---
71
87
 
72
- ## How you use it day to day
88
+ ## Why teams adopt it — three pillars
73
89
 
74
- You describe your project or the feature you want — in chat, or by pointing the agent at a file such as `prd.md` or `docs/brief.md`. With Spec Guardrails already installed, the agent reads that material plus what is already in the repo and picks up from there if work is in progress (`STATE.md` tells it where you left off).
90
+ Most agent failures are not “bad code in one file.” They are **wrong goal**, **lost context**, or **fake done**. Spec Guardrails attacks those three problems directly.
75
91
 
76
- ![Spec Guardrails phase flow — classify, optional elicitation, three human approvals, build loop, verify, archive](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/flow.svg)
92
+ | Problem | Pillar | One-line win |
93
+ | --- | --- | --- |
94
+ | Built the wrong feature | **Requirements analysis** | Agree on intent before `spec.md` |
95
+ | Skipped steps and called it done | **Gates (Brakes)** | Proof at boundaries, not trust |
96
+ | Every chat starts from zero | **Memory** | `.specs/` in git beats chat history |
77
97
 
78
- The agent never skips your approvals on the full path. Requirements analysis is **suggested**, not forced — if the request is already clear, it goes straight to Specify.
98
+ ### 1. Requirements analysis — stop building the wrong thing
79
99
 
80
- Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/guide/agent-commands.md) · [Glossary](docs/guide/Glossary.md)
100
+ **Without it:** “Add login” becomes three different products in three chats — OAuth vs magic link vs username/password — and you discover the mismatch halfway through a PR.
81
101
 
82
- ---
102
+ **With `/elicit`:** The agent asks a **small number of sharp questions** (at most five per round, one topic at a time, always with suggested options). It reads what you already wrote (`prd.md`, `docs/brief.md`, kickoff notes) and **does not re-ask** what those files already answer. You approve a **requirements brief** before `spec.md` exists — so vague chat does not harden into vague acceptance criteria.
83
103
 
84
- ## How it sizes the work
104
+ | Without analysis | With analysis |
105
+ | --- | --- |
106
+ | Assumptions stay implicit in chat | Assumptions surface early with owners |
107
+ | Spec rewrites mid-build | Spec starts from an approved brief |
108
+ | “I thought you meant…” after code exists | Disagreement costs minutes, not days |
85
109
 
86
- Before starting, the agent classifies the change and loads only what that change needs. A typo does not get a task graph; a payments integration does not skip review.
110
+ It is **suggested**, not mandatory — clear requests can go straight to `/specify`. The win is catching ambiguity **before** the agent treats a half-sentence as a contract.
87
111
 
88
- ![Complexity tiers — Quick, Simple, Medium, Complex, Parallel](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/tiers.svg)
112
+ **4.8+:** optional `elicitation` policy (`require_brief` on Complex), NFR section checks, and `req-analysis diff` for brief↔spec drift — [workshop](docs/guide/tutorials/05-requirements-analysis-workshop.md).
89
113
 
90
- | Complexity | Typical scope | What gets created | Your approvals |
91
- | --- | --- | --- | --- |
92
- | **Quick** | ≤3 files, no new dependency, no auth/payments | Code + quick evidence | None (express lane) |
93
- | **Simple** | Small localized change, 2–5 files | `spec.md` → code → `validation.md` | Spec |
94
- | **Medium** | Real feature, under ~10 jobs | `spec.md`, `tasks.md` → code → `validation.md` → archive | Spec + tasks |
95
- | **Complex** | New APIs, architecture, infrastructure | Above + `design.md`, option discussion | Spec + tasks (+ design when used) |
96
- | **Parallel** | Work safely splittable across agents | Above + `task-graph.md` | Spec + tasks |
114
+ **Go deeper:** [Requirements analysis](docs/guide/requirements-analysis.md) · [/elicit in agent commands](docs/guide/agent-commands.md)
97
115
 
98
- This is also why sessions stay affordable: the agent loads one short guide per step instead of the entire playbook.
116
+ ---
99
117
 
100
- Read more: [Complexity tiers](docs/guide/concepts.md#complexity-tiers--how-the-agent-chooses-depth) · [Token efficiency](docs/guide/Token-efficiency.md)
118
+ ### 2. Gates (Brakes) — “done” has to be provable
101
119
 
102
- ---
120
+ **Process vs Brakes** — who enforces the checklist — is in [Install](#node-alone-vs-node--python-gates). Here is *when* Brakes run: scripts return non-zero = **STOP**; fix the artifact, re-run.
103
121
 
104
- ## What is inside the kit
122
+ | Moment | What gates protect |
123
+ | --- | --- |
124
+ | **Before spec approval** | Criteria are testable (`SHALL`/`MUST`), assumptions documented |
125
+ | **Before task approval** | Every REQ maps to a task; tasks have shape and file ownership |
126
+ | **Each commit** | Conventional message, no empty staged diff, no linter/test bypass in the diff |
127
+ | **Before “feature done”** | Traceability REQ → task → `file:line` evidence; PASS verdict and `Verifier-Mode` in `validation.md` |
128
+ | **After verify FAIL** | Lessons are recorded — failures become rules, not forgotten |
105
129
 
106
- Each block names what ships in the package, how many pieces there are, and what you get from it. Technical detail lives in the linked guides.
130
+ Fifteen+ gates cover planning through close — including `validate-design` (Complex), optional [Python Platform](#python-platform-optional--47) checks, CI template (`templates/ci/guardrails-pr.yml`), and opt-in `install-hooks` for pre-commit. Command list and pipeline order: [gates reference](docs/guide/gates.md).
107
131
 
108
- ### Artifacts (12)
132
+ ---
109
133
 
110
- Plain markdown in `.specs/` — the paper trail that survives the chat and reviews like code in git.
134
+ ### 3. Memory — the repo remembers so you do not have to
111
135
 
112
- | File | What it holds |
136
+ **Without memory:** Every new session starts cold. You re-paste context, re-explain decisions, and hope the model does not contradict last week’s architecture chat.
137
+
138
+ **With `.specs/`:** `STATE.md` says where you left off. Each feature folder holds spec, tasks, design, and validation. Archive folds shipped work into **domain specs** and `ROADMAP.md`. Failed verifies become **lessons** that constrain the next run.
139
+
140
+ | Without `.specs/` | With `.specs/` |
113
141
  | --- | --- |
114
- | `STATE.md` | Active feature, current phase, next step |
115
- | `requirements-brief.md` | Answers from requirements analysis, signed off by you |
116
- | `spec.md` | Requirements, acceptance criteria, out of scope |
117
- | `exploration.md` | Compared solution options (when used) |
118
- | `design.md` | Technical approach and decisions (when used) |
119
- | `tasks.md` | Checkable jobs with file ownership |
120
- | `task-graph.md` | Which jobs can run in parallel (when used) |
121
- | `validation.md` | Independent verify verdict and proof |
122
- | `project/PROJECT.md` | Long-lived repo map |
123
- | `project/ROADMAP.md` | Planned and delivered features |
124
- | `domains/<slug>/spec.md` | Consolidated domain knowledge after archive |
125
- | `lessons.json` | Rules learned from past failures |
142
+ | Chat is the source of truth | Git is the source of truth |
143
+ | Handoff = long message | Handoff = read `STATE.md` + feature folder |
144
+ | Same mistake twice | Lessons promote to confirmed rules |
145
+ | “What did we decide about timeouts?” | `memory-retrieve "session timeout"` (optional index) |
126
146
 
127
- → [Architecture](docs/guide/Architecture.md)
147
+ The **markdown artifacts alone** already beat chat-only workflows for any team that ships more than one feature. Optional search (keyword, graph, semantic embed) — see [Optional capabilities](#optional-capabilities-off-by-default).
128
148
 
129
- ### Skills (1 hub + 19 phase guides + 8 specialists)
149
+ **Go deeper:** [Memory guide](docs/guide/Memory.md) · [Brownfield context](docs/guide/brownfield-context.md)
130
150
 
131
- Instructions the agent loads **one at a time** — hub `agent-architecture.md` (router + contract), phase guides such as `specify.md`, `tasks.md`, `implement.md`, `validate.md`, and specialists such as `appsec.md`, `qa-strategy.md`, `security-review.md` when the work needs them.
151
+ ---
132
152
 
133
- → [Skills and hub](docs/guide/skills-and-hub.md)
153
+ ## Spec-driven development (SDD)
134
154
 
135
- ### Gates (11)
155
+ Under the three pillars sits the **spec-driven method** the agent follows: written phases instead of improvisation. Before work starts, **`classify-change`** picks a complexity tier (Quick → Parallel) so a typo does not get a task graph and a payment flow does not skip review.
136
156
 
137
- Automatic checks at step boundaries — each one blocks a specific kind of shortcut:
157
+ Lineage: [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven), [loop-engineering](https://github.com/cobusgreyling/loop-engineering), [graph-engineering](https://github.com/codejunkie99/graph-engineering), [loopgate_harness](https://github.com/rxdt/loopgate_harness). **Repo-native harness** — not another desktop runtime.
138
158
 
139
- | Gate | Stops the agent when… |
140
- | --- | --- |
141
- | `validate-req-analysis` | Requirements brief has open questions or no owner approval |
142
- | `validate-spec` | Spec has no testable acceptance criteria |
143
- | `analyze-artifacts` | A requirement has no matching task |
144
- | `validate-tasks` | Tasks are vague or file ownership conflicts |
145
- | `validate-traceability` | REQ → task → proof chain is broken |
146
- | `validate-state` | Feature is declared done without evidence |
147
- | `validate-quick` | Quick-mode fix broke its size or shape rules |
148
- | `check-commit` | Commit message is not conventional, staged diff is empty, or exceeds `commit.max_staged_lines` |
149
- | `check-suppressions` | Staged diff adds `# noqa`, `eslint-disable`, `@ts-ignore`, skipped tests, or `--no-verify` |
150
- | `quality-checks` | Configured project commands (`npm test`, …) fail during `/verify` |
151
- | `lessons` | A failed verify tries to skip the lesson step |
159
+ ![Spec Guardrails phase flow — classify, optional elicitation, approvals, build loop, verify, archive](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/flow.svg)
152
160
 
153
- → [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
161
+ ### Phase map — what runs when
154
162
 
155
- ### Requirements analysis
163
+ | Phase | Required? | What happens | You approve? |
164
+ | --- | --- | --- | --- |
165
+ | **Explore** | Optional | Research before a feature folder exists | — |
166
+ | **Elicit** | Optional | Structured Q&A → requirements brief ([pillar §1](#1-requirements-analysis--stop-building-the-wrong-thing)) | Brief |
167
+ | **Constitution** | Once per project | Project principles (`/constitution`) | Once |
168
+ | **Specify** | Yes (full path) | Written requirements | **Spec** |
169
+ | **Discuss** | When product is gray | Options A/B/C, decision records | As needed |
170
+ | **Design** | When architecture matters | Technical approach in `design.md`; `validate-design` on Complex | As needed |
171
+ | **Solution explore** | When architectures fork (optional — [off by default](#optional-capabilities-off-by-default)) | Compare candidates; record decision | Decision |
172
+ | **Tasks** | When work needs a job list | Atomic tasks, file ownership, REQ coverage | **Tasks** |
173
+ | **Execute** | Yes | `/loop` waves — implement, gate, commit; parallel when files are disjoint | — |
174
+ | **Verify** | Yes | **Independent proof** — fresh context writes `validation.md`; author ≠ verifier | Verdict |
175
+ | **Archive** | After Verify PASS | Fold into domain memory and roadmap | — |
176
+ | **Quick** | Alternative path | ≤3 files, express lane — skips full spec/tasks ceremony | — |
177
+ | **Converge** | On drift | Realign spec ↔ tasks before more Execute | — |
178
+
179
+ **Brownfield:** `project-init` maps an existing repo into `.specs/` (`PROJECT.md`, domains, suggested preset) so the agent is not guessing stack every session.
156
180
 
157
- When the request is still fuzzy, the agent asks a **few targeted questions** — at most five per round, one topic at a time, always with suggested options — and never re-asks what your document already answered. You approve the brief before Specify starts.
181
+ **Traceability:** REQ → task → evidence at verify ([pillar §2](#2-gates-brakes--done-has-to-be-provable)); semantic test quality is still your judgment.
158
182
 
159
- → [Requirements analysis](docs/guide/requirements-analysis.md)
183
+ **Parallel work:** `loop-plan` picks the next wave; `task-graph.md` and git worktrees (`workspace-prepare`) keep parallel agents off the same files.
160
184
 
161
- ### Loops
185
+ **Git tiers:** approving spec/tasks authorizes **local work only** (Tier 0). Push, PR, merge, and deploy need your explicit go-ahead — see [git-handoff](docs/guide/agent-commands.md).
162
186
 
163
- Implementation happens in **small waves**: pick the next runnable jobs, test, implement, check, commit, repeat. Parallel work only when two jobs touch different files; if tests fail, the agent retries a bounded number of times before escalating to you.
187
+ ![Complexity tiers — Quick, Simple, Medium, Complex, Parallel](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/tiers.svg)
164
188
 
165
- → [Loop patterns](docs/guide/loop-patterns.md)
189
+ **Go deeper:** [How it works](docs/guide/How-it-works.md) · [Loop patterns](docs/guide/loop-patterns.md) · [Agent commands](docs/guide/agent-commands.md) · [Concepts](docs/guide/concepts.md)
166
190
 
167
- ### Memory (6 commands)
191
+ ### Hub and skills — how the agent navigates
168
192
 
169
- `memory-index`, `memory-search`, `memory-query`, `memory-retrieve`, `episodes`, and `code-index` — so a new session or teammate can ask "what did we decide about session timeout?" without you re-explaining. Lessons from verify failures feed back into future runs.
193
+ The **hub** (`agent-architecture.md`) is the map loaded every turn: contract, **complexity router**, gate schedule, phase order, and git tiers. It tells the agent *which* procedure to open next — not the whole playbook at once.
170
194
 
171
- → [Memory](docs/guide/Memory.md) · [Brownfield context](docs/guide/brownfield-context.md)
195
+ **Phase guides** (`references/`) load **one per turn** (`specify.md`, `tasks.md`, `implement.md`, `validate.md`, …) — roughly **70% fewer skill tokens** than dumping the full kit each message.
172
196
 
173
- ### Optional — off by default
197
+ **Sister skills** load only when the work needs extra depth (security, task graphs, platform infra/AI, …). The hub loads **at most one** conditional sister at a time for Verify extras (AppSec, then QA).
174
198
 
175
- | Capability | What it adds |
176
- | --- | --- |
177
- | **Semantic memory search** | Find past specs and decisions by meaning, not just keywords |
199
+ For **what each skill does and when to load it**, see the full catalog — hub, nineteen phase guides, ten sister skills:
178
200
 
179
- → [Memory](docs/guide/Memory.md)
201
+ **Go deeper:** [Skills and hub](docs/guide/skills-and-hub.md) · [Token efficiency](docs/guide/Token-efficiency.md)
180
202
 
181
203
  ---
182
204
 
183
- ## What lands in your repository
205
+ ## Python Platform (optional — 4.7+)
184
206
 
185
- | Path | Role |
207
+ **What it is:** an optional **preset and gate pack** for **Python repos** where **some features** also touch **deploy/infra** and/or **AI/LLM** code paths. You do **not** need backend + DevOps + AI on every change — surfaces activate **per feature** when task files match:
208
+
209
+ | Your feature touches… | What gets documented in `design.md` |
186
210
  | --- | --- |
187
- | `.cursor/skills/` (or detected platform tree) | Phase instructions for your agent |
188
- | `.specs/STATE.md` | Active feature and next step |
189
- | `.specs/features/NNN-slug/` | Spec, tasks, and validation per feature |
190
- | `.specs/guardrails/scripts/` | Python checks (when Brakes mode is on) |
191
- | `.specs/config.yaml` | Optional project rules and execution policy |
211
+ | Docker, Compose, Terraform, Helm, CI workflows | **Ship Surface** (deploy unit, CI, rollback) |
212
+ | `prompts/`, `evals/`, MCP, RAG, embeddings | **AI Surface** (eval harness, fallback, scope) |
213
+ | Application Python only | Standard SDD — extra surfaces only when paths match |
192
214
 
193
- ---
215
+ `project-init` may suggest this preset when it detects compose, Terraform, CI, or eval directories — you still opt in.
216
+
217
+ ```bash
218
+ npx @luizsantiago/spec-guardrails init-config --preset python-platform
219
+ ```
194
220
 
195
- ## Honest limits
221
+ **Without the preset:** deploy steps live in someone’s head, eval harnesses are “later,” rollback is learned during an incident.
196
222
 
197
- Gates enforce **structure and evidence in `.specs/`** — not product taste, not whether your tests are clever, and not a full AST review of implementation code. A green gate means the artifact shape and cited proof look complete; you still approve specs and tasks.
223
+ **With the preset:** gate `validate-ship-surface` blocks verify when matching paths lack documented surfaces; sisters `python-devops` and `ai-engineering` guide authoring; `feature-overview` adds operational + AI traceability tables.
198
224
 
199
- | Gates check | Gates do **not** check |
225
+ ### What Python Platform is **not** (honest)
226
+
227
+ | It is **not** | What we do instead |
200
228
  | --- | --- |
201
- | Spec sections and `SHALL`/`MUST` criteria | Semantic alignment between tests and requirements |
202
- | REQ → task → validation traceability | Stub or broken source outside cited paths |
203
- | Commit message shape and suppression patterns | Whether coverage % equals test quality |
204
- | Commands you list under `quality.checks` | Commands you never configured |
229
+ | LangSmith, Coze Loop, live production traces | Version **contracts** in git + `/verify` evidence |
230
+ | MLOps / eval runtime | Require a **documented** harness — quality is yours |
231
+ | `terraform plan` security or cost review | Structural checks when you configure them |
232
+ | Separate FastAPI/Django presets | Framework patterns in **tutorial appendices** |
233
+
234
+ Repos without `python-platform` are unchanged.
205
235
 
206
- See [Guarantees matrix](docs/guide/Guarantees-matrix.md) for the full product view.
236
+ **Go deeper:** [Python platform guide](docs/guide/python-platform.md) · [Tutorial 04](docs/guide/tutorials/04-python-platform-ship-surface.md)
207
237
 
208
238
  ---
209
239
 
210
- ## Documentation
240
+ ## Optional capabilities (off by default)
241
+
242
+ These ship in the package but stay **disabled or unused until you configure them** — extra guardrails and power tools, not part of the default SDD path.
211
243
 
212
- | Topic | Start here | Go deeper |
244
+ | Capability | What it adds | Turn on when |
213
245
  | --- | --- | --- |
214
- | Orientation | [Overview](docs/guide/Overview.md) | [Concepts](docs/guide/concepts.md) |
215
- | First session | [Quick start](docs/guide/Quick-start.md) | [Agent commands](docs/guide/agent-commands.md) |
216
- | Process model | [How it works](docs/guide/How-it-works.md) | [Loop patterns](docs/guide/loop-patterns.md) |
217
- | Enforcement | [Gates](docs/guide/gates.md) | [Gates and guarantees](docs/guide/Gates-and-guarantees.md) |
218
- | Requirements | [Requirements analysis](docs/guide/requirements-analysis.md) | [Agent commands → /elicit](docs/guide/agent-commands.md) |
219
- | Long-running projects | [Memory](docs/guide/Memory.md) | [Brownfield context](docs/guide/brownfield-context.md) |
220
- | Questions | [FAQ](docs/guide/FAQ.md) | [Glossary](docs/guide/Glossary.md) · [Product history](docs/guide/Product-history.md) · [Stability policy](docs/guide/Stability-policy.md) |
246
+ | **Semantic memory** | Meaning-based search across archived specs (`memory-index embed`) | Many archived features; keyword search is not enough |
247
+ | **`execution-policy`** | Path allow/deny, retry and run budgets in `.specs/config.yaml` | Agent has broad shell or file access |
248
+ | **`context-guard`** | Block edits outside approved task `Files` | You want scope enforcement before edits |
249
+ | **`sandbox check-command`** | Warn or block destructive shell (`rm -rf`, force-push, …) | Agent runs terminal commands unsupervised |
250
+ | **`episodes`** | Short-lived session notes (`episodes record`) | Very long sessions; prune when done |
251
+ | **`solution-explore`** | Formal architecture fork with `exploration.md` | Two+ defensible designs for the same spec |
221
252
 
222
- Full index: [docs/guide/README.md](docs/guide/README.md)
253
+ **Go deeper:** [Agent commands](docs/guide/agent-commands.md) · [Architecture](docs/guide/Architecture.md)
223
254
 
224
255
  ---
225
256
 
226
- ## Contributing
257
+ ## More in the kit
258
+
259
+ | Capability | Role |
260
+ | --- | --- |
261
+ | **`feature-status` / `feature-overview`** | Human-readable checklist and REQ → task → evidence dashboard |
262
+ | **`phase-context`** | Inject team rules from `config.yaml` at a given phase |
263
+ | **Tutorials** | Hands-on paths: quick fix → medium feature → parallel → python platform — [index](docs/guide/tutorials/README.md) |
264
+
265
+ **Go deeper:** [Tutorials](docs/guide/tutorials/README.md) · [Ecosystem map](docs/guide/ecosystem.md)
266
+
267
+ ---
268
+
269
+ ## Limitations
227
270
 
228
- Focused improvements are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for layout, gate stability rules, and local checks.
271
+ Gates enforce **structure and evidence in `.specs/`** — not product taste, not semantic test quality, not a full AST review of implementation code.
229
272
 
230
- Edit sources under `skills/`, `lib/`, `scripts/`, and `rules/`; re-run `npm run guardrails -- install` after changing shipped assets, and run `npm test` before every PR.
273
+ | Enforced | Not enforced |
274
+ | --- | --- |
275
+ | Spec shape, REQ → task → proof traceability | Semantic test ↔ REQ alignment |
276
+ | Evidence citations and PASS verdict | Stub code outside cited paths |
277
+ | Ship/AI fields when paths match (platform) | Rollback tested in prod, eval quality |
278
+ | Commit policy and suppression patterns | Coverage % as quality proxy |
279
+ | Commands under `quality.checks` | Commands you never configured |
280
+
281
+ A green gate means the paperwork looks complete — **you** still approve specs and tasks.
282
+
283
+ **Go deeper:** [Gates and guarantees](docs/guide/Gates-and-guarantees.md) · [FAQ](docs/guide/FAQ.md)
284
+
285
+ ---
286
+
287
+ ## Contributing
288
+
289
+ Focused improvements are welcome — [CONTRIBUTING.md](CONTRIBUTING.md). Sources: `skills/`, `lib/`, `scripts/`, `rules/`. Run `npm test` before every PR.
231
290
 
232
291
  ---
233
292
 
234
293
  ## Credits
235
294
 
236
- Spec Guardrails adapts patterns from open-source work. These are the projects whose ideas are actually shipped in the package:
295
+ Patterns adapted from open source. **Shipped influences** (skills, gates, or layout consumers install):
237
296
 
238
- | Project | License | Used for |
297
+ | Source | License | What we extracted |
239
298
  | --- | --- | --- |
240
- | [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) | CC-BY-4.0 | Spec → tasks → execute → verify model, `.specs/` layout, gate philosophy |
241
- | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Design-discussion patterns and definition-of-done framing |
242
- | [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Task-graph rules behind safe parallel waves |
243
- | [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | Wave-based execution model |
244
- | [loopgate_harness](https://github.com/rxdt/loopgate_harness) | MIT | Suppression-bypass blocking, project-configured quality commands as verify evidence, honest-limits framing, and README diagram layout (proxy-safe SVG; SMIL animation on GitHub) |
299
+ | [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) | CC-BY-4.0 | Spec → tasks → execute → verify phases; `.specs/features/`, `STATE.md`; gate “brakes” philosophy |
300
+ | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Discuss-phase options A/B/C; definition-of-done in verify/archive |
301
+ | [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Task-graph rules; `validate-tasks` graph hygiene |
302
+ | [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | Execute wave model; [loop-patterns.md](docs/guide/loop-patterns.md) |
303
+ | [Addy Osmani — Loop engineering](https://addyosmani.com/blog/loop-engineering/) | Essay | Loop taxonomy in loop-patterns guide |
304
+ | [awesome-harness-engineering](https://github.com/ai-boost/awesome-harness-engineering) | CC0 | Harness vs app vocabulary in [ecosystem.md](docs/guide/ecosystem.md) |
305
+ | [loopgate_harness](https://github.com/rxdt/loopgate_harness) | MIT | `check-suppressions`; `quality.checks` as verify evidence; `check-commit --staged`; honest-limits framing; README diagram approach |
306
+ | [obra/superpowers](https://github.com/obra/superpowers) | MIT | Two-stage subagent review in `sub-agents.md` |
307
+
308
+ **Original work here:** Node CLI, Python gates, platform adapters, elicitation (`/elicit`), Python Platform pack (4.7+), SDLC integration helpers (4.8+), memory-index, execution policy, req-analysis tooling.
245
309
 
246
- Everything else — the CLI, the Python checks, the platform adapters, and the requirements-analysis phase — is original work in this repository. Full lineage, including references we cite but do not bundle: [Credits and lineage](docs/guide/credits.md).
310
+ **Cited, not vendored:** [DeepCode](https://github.com/HKUDS/DeepCode), [RepoGraph](https://github.com/ozyyshr/RepoGraph), [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector) — see [credits.md](docs/guide/credits.md).
311
+
312
+ ---
313
+
314
+ ## Documentation
315
+
316
+ | Topic | Link |
317
+ | --- | --- |
318
+ | Start here | [Overview](docs/guide/Overview.md) · [Quick start](docs/guide/Quick-start.md) · [Tutorials](docs/guide/tutorials/README.md) |
319
+ | Chat & CLI | [Agent commands](docs/guide/agent-commands.md) |
320
+ | Process | [How it works](docs/guide/How-it-works.md) · [Concepts](docs/guide/concepts.md) |
321
+ | Skills (each role) | [Skills and hub](docs/guide/skills-and-hub.md) |
322
+ | Gates | [gates.md](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md) |
323
+ | Requirements | [requirements-analysis.md](docs/guide/requirements-analysis.md) |
324
+ | Memory | [Memory.md](docs/guide/Memory.md) |
325
+ | Python platform | [python-platform.md](docs/guide/python-platform.md) |
326
+ | Versions | [CHANGELOG](docs/CHANGELOG.md) · [Product history](docs/guide/Product-history.md) |
327
+ | Help | [FAQ](docs/guide/FAQ.md) · [Glossary](docs/guide/Glossary.md) |
328
+
329
+ Full index: [docs/guide/README.md](docs/guide/README.md)
247
330
 
248
331
  ---
249
332
 
package/index.js CHANGED
@@ -29,9 +29,11 @@ import {
29
29
  featureOverview,
30
30
  formatFeatureOverview,
31
31
  } from "./lib/feature-overview.js";
32
+ import { featurePrBody } from "./lib/feature-pr-body.js";
32
33
  import { featureStatus, formatFeatureStatus } from "./lib/feature-status.js";
33
34
  import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
34
35
  import { install } from "./lib/install.js";
36
+ import { installHooks } from "./lib/install-hooks.js";
35
37
  import { parsePlatformArg } from "./lib/platform-detect.js";
36
38
  import {
37
39
  cleanupWorkspaces,
@@ -95,6 +97,7 @@ Commands:
95
97
  req-analysis promote Print next steps after brief approval
96
98
  [--scope project|feature] Match the brief scope
97
99
  req-analysis validate [brief.md] Gate: approved requirements brief before /specify
100
+ req-analysis diff [feature] Compare brief capabilities vs spec REQ coverage
98
101
  req-analysis context Assemble kickoff + brief context for Specify
99
102
  [--scope project|feature] Scope (default: project)
100
103
  [--slug <feature-slug>] Feature slug when scope=feature
@@ -112,6 +115,10 @@ Commands:
112
115
  feature-overview [feature] REQ → task → evidence dashboard (markdown)
113
116
  [--write] Save .specs/features/<feature>/overview.md
114
117
  [--json] Machine-readable output (no markdown body)
118
+ feature-pr-body [feature] Generate GitHub PR description from overview
119
+ [--json] Machine-readable output
120
+ install-hooks Install optional git pre-commit (check-commit, suppressions)
121
+ [--remove] Remove Spec Guardrails-managed pre-commit hook
115
122
  phase-context <phase> Print .specs/config.yaml context + rules for a phase
116
123
  doctor [path] Audit guardrails readiness (score + next actions)
117
124
  [--json] Machine-readable output
@@ -186,6 +193,8 @@ Commands:
186
193
  validate-ship-surface [feature] Ship Surface + AI Surface when infra/AI paths in tasks
187
194
  validate-quick [quick-folder] Quick-mode TASK.md / SUMMARY.md structural gate
188
195
  validate-req-analysis [brief.md] Requirements brief gate before /specify (/elicit)
196
+ validate-design [feature] design.md structure gate (Complex / Medium+)
197
+ req-analysis-diff [feature] Brief capabilities vs spec REQ drift (heuristic)
189
198
  validate-state [feature] Completion gate before declaring a feature done
190
199
  check-commit --message "<msg>" Conventional Commits gate
191
200
  [--staged] Also reject empty commits and oversized staged diffs
@@ -251,6 +260,28 @@ if (command === "--version" || command === "-v" || command === "version") {
251
260
  console.error(`❌ ${err.message}`);
252
261
  process.exit(1);
253
262
  }
263
+ } else if (command === "install-hooks") {
264
+ try {
265
+ let remove = false;
266
+ for (const arg of args) {
267
+ if (arg === "--remove") {
268
+ remove = true;
269
+ } else {
270
+ throw new Error("Usage: install-hooks [--remove]");
271
+ }
272
+ }
273
+ const result = await installHooks(process.cwd(), { remove });
274
+ if (result.action === "installed") {
275
+ console.log(`✅ Installed pre-commit hook at ${result.path}`);
276
+ } else if (result.action === "removed") {
277
+ console.log(`✅ Removed Spec Guardrails pre-commit hook`);
278
+ } else {
279
+ console.log(`ℹ️ No Spec Guardrails hook to remove`);
280
+ }
281
+ } catch (err) {
282
+ console.error(`❌ ${err.message}`);
283
+ process.exit(1);
284
+ }
254
285
  } else if (command === "init-config") {
255
286
  try {
256
287
  let preset = "default";
@@ -999,6 +1030,10 @@ if (command === "--version" || command === "-v" || command === "version") {
999
1030
  const briefPath = rest.find((arg) => !arg.startsWith("--"));
1000
1031
  const code = await runGate("validate-req-analysis", briefPath ? [briefPath] : []);
1001
1032
  process.exit(code);
1033
+ } else if (sub === "diff") {
1034
+ const featureArg = rest.find((arg) => !arg.startsWith("--"));
1035
+ const code = await runGate("req-analysis-diff", featureArg ? [featureArg] : []);
1036
+ process.exit(code);
1002
1037
  } else if (sub === "context") {
1003
1038
  let scope = "project";
1004
1039
  let slug = "";
@@ -1029,7 +1064,7 @@ if (command === "--version" || command === "-v" || command === "version") {
1029
1064
  const code = await runGuardrailsScript("req-context", scriptArgs);
1030
1065
  process.exit(code);
1031
1066
  } else {
1032
- throw new Error("Usage: req-analysis init | discover | promote | validate | context");
1067
+ throw new Error("Usage: req-analysis init | discover | promote | validate | diff | context");
1033
1068
  }
1034
1069
  } catch (err) {
1035
1070
  console.error(`❌ ${err.message}`);
@@ -1114,6 +1149,27 @@ if (command === "--version" || command === "-v" || command === "version") {
1114
1149
  console.error(`❌ ${err.message}`);
1115
1150
  process.exit(1);
1116
1151
  }
1152
+ } else if (command === "feature-pr-body") {
1153
+ try {
1154
+ let json = false;
1155
+ const positional = [];
1156
+ for (const arg of args) {
1157
+ if (arg === "--json") {
1158
+ json = true;
1159
+ } else {
1160
+ positional.push(arg);
1161
+ }
1162
+ }
1163
+ const result = await featurePrBody(positional[0]);
1164
+ if (json) {
1165
+ console.log(JSON.stringify(result, null, 2));
1166
+ } else {
1167
+ process.stdout.write(result.body);
1168
+ }
1169
+ } catch (err) {
1170
+ console.error(`❌ ${err.message}`);
1171
+ process.exit(1);
1172
+ }
1117
1173
  } else if (AUX_COMMANDS.includes(command)) {
1118
1174
  try {
1119
1175
  const code = await runGuardrailsScript(command, args);
package/lib/constants.js CHANGED
@@ -128,6 +128,8 @@ export const SCRIPT_ASSETS = [
128
128
  { file: "episodes.py", remotePath: "scripts/episodes.py" },
129
129
  { file: "code_index.py", remotePath: "scripts/code_index.py" },
130
130
  { file: "validate_req_analysis.py", remotePath: "scripts/validate_req_analysis.py" },
131
+ { file: "validate_design.py", remotePath: "scripts/validate_design.py" },
132
+ { file: "req_analysis_diff.py", remotePath: "scripts/req_analysis_diff.py" },
131
133
  { file: "req_context.py", remotePath: "scripts/req_context.py" },
132
134
  { file: "check_suppressions.py", remotePath: "scripts/check_suppressions.py" },
133
135
  { file: "run_quality_checks.py", remotePath: "scripts/run_quality_checks.py" },