@luizsantiago/spec-guardrails 3.1.2 → 3.1.3

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 (4) hide show
  1. package/README.md +61 -24
  2. package/package.json +2 -2
  3. package/skills/agent-architecture.md +0 -4
  4. package/skills/references/tasks.md +1 -1
package/README.md CHANGED
@@ -3,9 +3,13 @@
3
3
  [![npm version](https://img.shields.io/npm/v/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
4
4
  [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
5
 
6
- **Guardrails for AI coding agents** — agree on the goal in writing, break work into provable steps, run automatic checks before calling anything “done”, and verify with a fresh context that did not write the code.
6
+ **Keep AI coding agents honest — specify the work, prove each step, verify independently.**
7
7
 
8
- **Token-efficient by design:** the agent loads **one phase guide per turn** (~9k est. tokens on Specify) instead of dumping the full skill library (~31k). Measured savings: **~72%** on planning, **~86%** on Execute vs a naive full reload ([details below](#token-cost)).
8
+ | | |
9
+ | --- | --- |
10
+ | **Problem** | Agents ship “looks good” with thin specs, missing evidence, and the same context that wrote the code declaring victory. |
11
+ | **Solution** | A repo-local process kit: Specify → Tasks → Execute waves → Verify with fresh context. **Process mode** (Node) always; **Brakes mode** (+ Python) adds structural stop-gates; you approve specs/tasks. |
12
+ | **Result** | Traceable `.specs/` memory, fewer fake finishes, cheaper turns (~70% less skill text on planning), and an explicit stop when evidence is missing. |
9
13
 
10
14
  npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.1.x**
11
15
 
@@ -22,7 +26,7 @@ npx @luizsantiago/spec-guardrails install
22
26
  | Requirement | Role |
23
27
  | --- | --- |
24
28
  | **Node.js 18+** | Required — runs the CLI and `install` |
25
- | **Python 3.10+** | Recommended — runs automatic **gates** (`validate-spec`, `validate-tasks`, …). Without Python the agent still follows the same checklists manually |
29
+ | **Python 3.10+** | Activates **Brakes mode** — structural gates (`validate-spec`, `validate-tasks`, …). Without Python you stay in **Process mode**: same phases and checklists, no exit-code enforcement. Run [`doctor`](#install) to see the banner when Python is missing |
26
30
 
27
31
  ### What install does
28
32
 
@@ -44,6 +48,55 @@ Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.
44
48
 
45
49
  ---
46
50
 
51
+ ## How it works in one screen
52
+
53
+ Four ideas stack — full explanation: **[Concepts](docs/guide/concepts.md)**
54
+
55
+ | Idea | What it is | What it does |
56
+ | --- | --- | --- |
57
+ | **Spec-driven** | Written plan before code | `spec.md` + `tasks.md`; evidence before “done” |
58
+ | **Brakes / Gates** | Structural stop-gates | Python scripts exit non-zero when paperwork or evidence is missing |
59
+ | **Loop** | Execute in waves | `loop-plan` picks the next jobs; sub-agents when files don’t overlap |
60
+ | **Graph** | Parallel task map | `task-graph.md` — safe parallelism without file collisions |
61
+ | **Memory** | Repo-local state | `.specs/` — specs, decisions, and handoff survive across chats |
62
+
63
+ **You** approve specs and tasks. **The agent** runs gates and implements. **Gates** exit non-zero when paperwork or evidence is missing.
64
+
65
+ Plain-language tour: [Home](docs/guide/Home.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
66
+
67
+ ---
68
+
69
+ ## Operating modes
70
+
71
+ | Mode | Runtime | What you get |
72
+ | --- | --- | --- |
73
+ | **Process** | Node.js 18+ | Workflow, `.specs/` memory, progressive loading, independent `/verify` |
74
+ | **Brakes** | Node + Python 3.10+ | Process **plus** exit-code enforcement on structural gates |
75
+
76
+ Python activates Brakes — not a bug. Without it you keep the same phases and checklists (flexible mode). Run `doctor` to see when enforcement is manual-only.
77
+
78
+ ---
79
+
80
+ ## Guarantees matrix
81
+
82
+ **Guarantees are the product.** Commands are implementation.
83
+
84
+ | Guarantee | Mechanism | Mode | Enforcement |
85
+ | --- | --- | --- | --- |
86
+ | Intent exists before code | `validate-spec` | Brakes | Hard gate |
87
+ | Tasks derive from requirements | `analyze-artifacts` | Brakes | Hard gate |
88
+ | Requirements stay traceable | `validate-traceability` | Brakes | Hard gate |
89
+ | Dependencies respected in Execute | `loop-plan` | Brakes | Hard gate |
90
+ | Parallel work is file-safe | `task-graph.md` + `validate-tasks` | Process + Brakes | Artifact + gate |
91
+ | Completion cites evidence | `validate-state` | Brakes | Hard gate |
92
+ | Commits follow policy | `check-commit` | Brakes | Hard gate |
93
+ | Verification is independent | `/verify` + `validate.md` | Process | Phase skill |
94
+ | Knowledge survives chats | `.specs/` + `archive-feature` | Process | Install + CLI |
95
+
96
+ Full matrix, limits, and phase diagram → **[Guarantees matrix](docs/guide/Guarantees-matrix.md)** · [Architecture](docs/guide/Architecture.md) (Core + adapters)
97
+
98
+ ---
99
+
47
100
  ## Token cost
48
101
 
49
102
  Progressive loading is the main cost win: **one working set per turn**, not the entire playbook.
@@ -62,24 +115,6 @@ More: [Token efficiency](docs/guide/Token-efficiency.md)
62
115
 
63
116
  ---
64
117
 
65
- ## How the pieces fit together
66
-
67
- Four ideas stack — full explanation: **[Concepts](docs/guide/concepts.md)**
68
-
69
- | Idea | What it is | What it does |
70
- | --- | --- | --- |
71
- | **Spec-driven** | Written plan before code | `spec.md` + `tasks.md`; evidence before “done” |
72
- | **Guardrails** | This package | Skills + Python gates that stop incomplete work |
73
- | **Loop** | Execute in waves | `loop-plan` picks the next jobs; sub-agents when files don’t overlap |
74
- | **Graph** | Parallel task map | `task-graph.md` — safe parallelism without file collisions |
75
- | **Memory** | Repo-local state | `.specs/` — specs, decisions, and handoff survive across chats |
76
-
77
- **You** approve specs and tasks. **The agent** runs gates and implements. **Gates** exit non-zero when paperwork or evidence is missing.
78
-
79
- Plain-language tour: [Home](docs/guide/Home.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
80
-
81
- ---
82
-
83
118
  ## Complexity tiers (how work flows)
84
119
 
85
120
  The hub **Complexity Router** picks how much ceremony a feature needs — Quick, Simple, Medium, Complex, or Parallel. It is **not** a separate product feature; it is how the agent decides which phases to run.
@@ -115,7 +150,7 @@ Full map: **[Skills and hub](docs/guide/skills-and-hub.md)**
115
150
 
116
151
  ## Gates (summary)
117
152
 
118
- Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
153
+ Commands implement the guarantees above. Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
119
154
 
120
155
  | When | Gate | What it blocks |
121
156
  | --- | --- | --- |
@@ -130,7 +165,7 @@ Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
130
165
  | After Verify FAIL | `lessons` | Ungrounded “lessons learned” |
131
166
  | After Verify PASS | `archive-feature` | (CLI) folds feature into domain memory |
132
167
 
133
- Full reference: **[Gates](docs/guide/gates.md)** · [Gates and guarantees](docs/guide/Gates-and-guarantees.md)
168
+ Full reference: **[Gates](docs/guide/gates.md)** · [Guarantees matrix](docs/guide/Guarantees-matrix.md) · [Gates and guarantees](docs/guide/Gates-and-guarantees.md)
134
169
 
135
170
  ---
136
171
 
@@ -138,12 +173,14 @@ Full reference: **[Gates](docs/guide/gates.md)** · [Gates and guarantees](docs/
138
173
 
139
174
  | Doc | For |
140
175
  | --- | --- |
176
+ | [Guarantees matrix](docs/guide/Guarantees-matrix.md) | Product promises → mechanisms |
177
+ | [Architecture](docs/guide/Architecture.md) | Core vs platform adapters |
141
178
  | [Agent commands](docs/guide/agent-commands.md) | Every `/specify`, `/loop`, `/verify`, … — purpose, when, examples |
142
179
  | [Quick start](docs/guide/Quick-start.md) | First ten minutes |
143
180
  | [Concepts](docs/guide/concepts.md) | Spec-driven + guardrails + loop + graph |
144
181
  | [Skills and hub](docs/guide/skills-and-hub.md) | What each skill file does |
145
182
  | [Gates](docs/guide/gates.md) | How each gate works |
146
- | [Platform parity](docs/guide/Platform-parity.md) | Cursor vs Claude Code |
183
+ | [Platform parity](docs/guide/Platform-parity.md) | Cursor vs Claude Code adapters today |
147
184
  | [FAQ](docs/guide/FAQ.md) | Common questions |
148
185
  | [Changelog](docs/CHANGELOG.md) | Full version history |
149
186
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@luizsantiago/spec-guardrails",
3
- "version": "3.1.2",
4
- "description": "Guardrails for AI coding agents — spec-driven phases, automatic gates, progressive skill loading (~70% fewer tokens per turn). Works in Cursor and Claude.",
3
+ "version": "3.1.3",
4
+ "description": "Spec-driven process kit for repo-local AI agents (Cursor and Claude Code adapters today): written goals, structural stop-gates, independent verify, progressive skill loading.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "spec-guardrails": "./index.js"
package/skills/agent-architecture.md CHANGED
@@ -190,10 +190,6 @@ Never skip to step 5 while steps 1–4 are available. Fabrication cascades throu
190
190
 
191
191
  Project rules: `.cursor/rules/engineering-baseline.mdc` (always applied in Cursor).
192
192
 
193
- ## Optional companion: Full Stack Floor Map
194
-
195
- When [`@luizsantiago/fullstack-floor-map`](https://www.npmjs.com/package/@luizsantiago/fullstack-floor-map) is installed, **Execute** may load one **Lane** layer manual and at most one catalog specialist per turn; **`/verify` stays Guardrails-only** (no Lane manuals, no catalog). Floor Map **0.5.0 (planned)** adds **Desk** memory under `.specs/desks/` for specialist continuity and handoff — companion-owned, not Guardrails gates. Pairing contract: [Companion: Full Stack Floor Map](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/Companion-fullstack-floor-map.md).
196
-
197
193
  ## Commands
198
194
 
199
195
  | Command | Reference | Action |
package/skills/references/tasks.md CHANGED
@@ -27,7 +27,7 @@ Break the work into atomic tasks with real dependencies and binary done criteria
27
27
  ## Procedure
28
28
 
29
29
  1. **Write one task per deliverable.** A task is something you would hand to a single agent and check in one commit.
30
- 2. **Prefer vertical slices.** One thin verifiable path per **feature** (e.g. register), not “all schema then all APIs then all UI” as *phases*. If `.cursor/rules/fullstack-layer.mdc` is present (`@luizsantiago/fullstack-floor-map`), keep each task `Files` list on **one Lane** (path layer; 0.4.x docs may still say “Floor”). Split UI vs API into T1/T2 with `Depends on`. Vertical still means a thin *feature*, not one task mixing `apps/web` + `apps/api`. See [Companion: Full Stack Floor Map](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/Companion-fullstack-floor-map.md).
30
+ 2. **Prefer vertical slices.** One thin verifiable path per **feature** (e.g. register), not “all schema then all APIs then all UI” as *phases*. Split UI vs API into separate tasks with `Depends on` when they must stay sequential. Vertical still means a thin *feature*, not one task that mixes unrelated areas without a dependency edge.
31
31
  3. **Give every task the full field set.** Authoring and the gate require all six:
32
32
  - `Requirement` — the spec ID it serves (gated)
33
33
  - `Files` — where the change lands (gated; required; `none` / `—` rejected; overlap across independent tasks blocks)