@luizsantiago/spec-guardrails 4.1.0 → 4.1.1
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.
- package/README.md +179 -97
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -5,172 +5,254 @@
|
|
|
5
5
|
|
|
6
6
|
**Governed spec-driven development for AI coding agents.**
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.1.x**
|
|
8
|
+
npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.1.x** · Works with Cursor, Claude Code, GitHub Copilot, and Codex.
|
|
11
9
|
|
|
12
10
|
---
|
|
13
11
|
|
|
14
|
-
## What
|
|
15
|
-
|
|
16
|
-
Spec Guardrails is **not** an application framework, a vector database, or a replacement for your stack. It is an **operating model** for AI-assisted engineering:
|
|
17
|
-
|
|
18
|
-
| Layer | Role |
|
|
19
|
-
| --- | --- |
|
|
20
|
-
| **Phase guides** | Instructions the agent loads one step at a time |
|
|
21
|
-
| **Project memory** | `.specs/` — specs, tasks, validation, and state that survive chat sessions |
|
|
22
|
-
| **Structural checks** | Optional Python gates that enforce document shape and evidence hooks |
|
|
12
|
+
## What this solves
|
|
23
13
|
|
|
24
|
-
|
|
14
|
+
AI agents are fast but forgetful. Ask for a feature and you usually get code with no written requirement, no record of the decisions, no proof it works, and nothing left behind when the chat window closes. The next session starts from zero.
|
|
25
15
|
|
|
26
|
-
|
|
16
|
+
Spec Guardrails installs a **repeatable process** into your repository so the agent always works the same way:
|
|
27
17
|
|
|
28
|
-
|
|
18
|
+
1. **Write down what is being built** — before any code exists, and you approve it.
|
|
19
|
+
2. **Break it into jobs** — a checklist you can read and approve.
|
|
20
|
+
3. **Implement in small waves** — one job at a time, each committed.
|
|
21
|
+
4. **Prove it works** — a separate verification pass that did not write the code.
|
|
22
|
+
5. **Keep the record** — spec, decisions, and proof stay in your repo, in git.
|
|
29
23
|
|
|
30
|
-
|
|
24
|
+
You stay the decision-maker. The agent stops and asks instead of guessing. When the session ends, the reasoning is still there — for you, for your team, and for the next agent run.
|
|
31
25
|
|
|
32
|
-
|
|
33
|
-
| --- | --- |
|
|
34
|
-
| **Traceability** | Requirements, jobs, and verification live in version-controlled artifacts |
|
|
35
|
-
| **Controlled autonomy** | Agents propose and execute; humans approve scope, design forks, and git tiers |
|
|
36
|
-
| **Progressive depth** | Quick fixes skip ceremony; complex work gets discuss, design, and task graphs |
|
|
37
|
-
| **Platform-agnostic** | Cursor, Claude Code, GitHub Copilot, Codex, and other agents via root `AGENTS.md` |
|
|
38
|
-
| **Token efficiency** | One phase guide per turn instead of dumping the entire playbook |
|
|
39
|
-
| **Optional enforcement** | Process mode (Node only) or Brakes mode (Node + Python gates) |
|
|
26
|
+
It is **not** an application framework, a runtime, or a dependency in your build. It is a set of markdown instructions plus optional check scripts. Remove the folders and your project is untouched.
|
|
40
27
|
|
|
41
|
-
|
|
28
|
+
Deeper: [Overview](docs/guide/Overview.md) · [How it works](docs/guide/How-it-works.md) · [Concepts](docs/guide/concepts.md)
|
|
42
29
|
|
|
43
30
|
---
|
|
44
31
|
|
|
45
32
|
## Install
|
|
46
33
|
|
|
47
|
-
|
|
34
|
+
Run once in your project root:
|
|
48
35
|
|
|
49
36
|
```bash
|
|
50
37
|
npx @luizsantiago/spec-guardrails install
|
|
38
|
+
npx @luizsantiago/spec-guardrails doctor
|
|
51
39
|
```
|
|
52
40
|
|
|
53
|
-
Re-run after upgrading
|
|
41
|
+
`install` writes the agent instructions and a `.specs/` folder. Re-run it after upgrading — your existing notes are preserved. `doctor` confirms everything is wired up.
|
|
54
42
|
|
|
55
43
|
| Requirement | Role |
|
|
56
44
|
| --- | --- |
|
|
57
|
-
| **Node.js 18+** | Required —
|
|
58
|
-
| **Python 3.10+** | Optional —
|
|
45
|
+
| **Node.js 18+** | Required — installer and CLI |
|
|
46
|
+
| **Python 3.10+** | Optional — turns on the automatic checks ("Brakes mode") |
|
|
47
|
+
|
|
48
|
+
Without Python you still get the full process; the agent performs the same checks by reading the guides instead of running scripts.
|
|
59
49
|
|
|
60
|
-
|
|
50
|
+
Setup per platform: [Platform parity](docs/guide/Platform-parity.md) · First session: [Quick start](docs/guide/Quick-start.md)
|
|
61
51
|
|
|
62
52
|
---
|
|
63
53
|
|
|
64
|
-
## How
|
|
54
|
+
## How a feature flows
|
|
55
|
+
|
|
56
|
+
You work in **agent chat** — normal conversation, in your own language. You do not memorize commands or run the CLI yourself; the agent knows the process and drives it, pausing at the two points where your approval is required.
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
YOU describe the work
|
|
60
|
+
│
|
|
61
|
+
▼
|
|
62
|
+
┌──────────────────────┐
|
|
63
|
+
│ 1. UNDERSTAND │ Vague request? The agent asks questions
|
|
64
|
+
│ │ first and writes a requirements brief.
|
|
65
|
+
└──────────┬───────────┘
|
|
66
|
+
▼
|
|
67
|
+
┌──────────────────────┐
|
|
68
|
+
│ 2. SPECIFY │ What gets built, what "done" means,
|
|
69
|
+
│ │ what is out of scope.
|
|
70
|
+
└──────────┬───────────┘
|
|
71
|
+
│
|
|
72
|
+
◆ YOU APPROVE ◆ Nothing is coded before this.
|
|
73
|
+
│
|
|
74
|
+
▼
|
|
75
|
+
┌──────────────────────┐
|
|
76
|
+
│ 3. PLAN │ The work becomes an ordered job list.
|
|
77
|
+
│ │ Big changes also get a design step.
|
|
78
|
+
└──────────┬───────────┘
|
|
79
|
+
│
|
|
80
|
+
◆ YOU APPROVE ◆ Scope is locked here.
|
|
81
|
+
│
|
|
82
|
+
▼
|
|
83
|
+
┌──────────────────────┐
|
|
84
|
+
│ 4. BUILD │ One job at a time, tests first,
|
|
85
|
+
│ ↺ loop │ one commit each. Repeats until done.
|
|
86
|
+
└──────────┬───────────┘
|
|
87
|
+
▼
|
|
88
|
+
┌──────────────────────┐
|
|
89
|
+
│ 5. VERIFY │ A fresh pass that did not write the
|
|
90
|
+
│ │ code checks it against the spec.
|
|
91
|
+
└──────────┬───────────┘
|
|
92
|
+
▼
|
|
93
|
+
┌──────────────────────┐
|
|
94
|
+
│ 6. ARCHIVE │ Outcome and lessons folded into
|
|
95
|
+
│ │ project memory for future runs.
|
|
96
|
+
└──────────────────────┘
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Between steps the agent runs structural checks. **A failed check stops the process** rather than letting a half-written spec reach implementation.
|
|
100
|
+
|
|
101
|
+
Details: [How it works](docs/guide/How-it-works.md) · Phase-by-phase reference: [Agent commands](docs/guide/agent-commands.md)
|
|
102
|
+
|
|
103
|
+
---
|
|
65
104
|
|
|
66
|
-
|
|
105
|
+
## It sizes the work before starting
|
|
67
106
|
|
|
68
|
-
|
|
107
|
+
The full flow would be absurd for a typo. Spec Guardrails first judges **how big the change actually is**, then loads only the steps and instructions that change needs. A one-line fix skips straight to implementation; a new integration gets the design conversation.
|
|
69
108
|
|
|
70
|
-
|
|
|
109
|
+
| If the change is… | The agent runs |
|
|
71
110
|
| --- | --- |
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
78
|
-
|
|
111
|
+
| A tiny fix — up to 3 files, no decisions | Describe → build → verify → commit |
|
|
112
|
+
| Localized — a few files, no new patterns | Specify → build → verify |
|
|
113
|
+
| A normal feature — under 10 jobs | Specify → plan → build → verify |
|
|
114
|
+
| New architecture, an API, or infrastructure | Specify → discuss options → design → plan → build → verify |
|
|
115
|
+
| Splittable across parallel agents | The above, plus a job dependency map |
|
|
116
|
+
|
|
117
|
+
Two things follow from this, and both matter in practice:
|
|
79
118
|
|
|
80
|
-
**
|
|
119
|
+
- **Speed** — small work stays small. No ceremony is added to a change that does not need it.
|
|
120
|
+
- **Cost and accuracy** — the agent reads one short guide per step instead of the whole playbook. Less context per turn means lower token spend and fewer instructions competing for attention.
|
|
81
121
|
|
|
82
|
-
|
|
122
|
+
The agent proposes the depth and explains why; you can always ask for more or less.
|
|
83
123
|
|
|
84
|
-
|
|
124
|
+
Deeper: [Overview → Three ways to start](docs/guide/Overview.md#three-ways-to-start-pick-one) · [Loop patterns](docs/guide/loop-patterns.md)
|
|
85
125
|
|
|
86
|
-
|
|
126
|
+
---
|
|
87
127
|
|
|
88
|
-
|
|
128
|
+
## What you get, layer by layer
|
|
89
129
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
130
|
+
Each layer is useful on its own. You do not have to understand all of them to benefit from the first one.
|
|
131
|
+
|
|
132
|
+
### Artifacts — the paper trail
|
|
133
|
+
|
|
134
|
+
Every feature gets a folder of plain markdown in your repo: what was requested, what was decided, the job list, and the verification report. Because it is markdown in git, it reviews like code, diffs like code, and travels with the branch. Months later you can answer "why is this built this way?" without asking anyone.
|
|
135
|
+
|
|
136
|
+
→ [Artifacts and `.specs/`](docs/guide/Architecture.md)
|
|
137
|
+
|
|
138
|
+
### Skills — the agent's instruction manual
|
|
139
|
+
|
|
140
|
+
The process itself is written as short guides the agent reads on demand — one per step. This is why the agent behaves consistently across sessions and across tools: the instructions live in your repo, not in a prompt someone typed once. It also keeps each turn focused, since only the relevant guide is loaded.
|
|
141
|
+
|
|
142
|
+
→ [Skills and hub](docs/guide/skills-and-hub.md)
|
|
143
|
+
|
|
144
|
+
### Gates — the checks that stop bad work early
|
|
145
|
+
|
|
146
|
+
Small scripts verify structure at each handoff: does the spec state acceptance criteria, are the jobs atomic, does the commit reference a real task, is there evidence for the claim of "done". They check **shape, not opinion** — so they are predictable, and they run before you spend time reviewing. A failing gate blocks progress.
|
|
147
|
+
|
|
148
|
+
→ [Gates](docs/guide/gates.md) · [Gates and guarantees](docs/guide/Gates-and-guarantees.md)
|
|
149
|
+
|
|
150
|
+
### Requirements analysis — for when the request is still fuzzy
|
|
151
|
+
|
|
152
|
+
"Make the dashboard better" is not buildable. This layer runs a short structured interview, records the answers and the open questions, and asks you to sign off before anything is specified. It is optional and never forced — but it is where most rework is prevented, because misunderstandings surface while they are still cheap.
|
|
100
153
|
|
|
101
|
-
|
|
154
|
+
→ [Requirements analysis](docs/guide/agent-commands.md)
|
|
155
|
+
|
|
156
|
+
### Loops — how implementation actually happens
|
|
157
|
+
|
|
158
|
+
Work advances in waves rather than one giant edit: pick the next job, write the test, make it pass, commit, repeat. Each wave is small enough to review and to roll back. If a wave reveals the plan was wrong, the process stops and returns to planning instead of improvising forward.
|
|
159
|
+
|
|
160
|
+
→ [Loop patterns](docs/guide/loop-patterns.md)
|
|
161
|
+
|
|
162
|
+
### Memory — what survives the chat window
|
|
163
|
+
|
|
164
|
+
State, decisions, and lessons are written to disk as work happens. A new session — or a different agent, or a teammate — reads the current state and continues instead of restarting. Archived features become long-lived project knowledge, and repeated mistakes get recorded as lessons so they stop repeating.
|
|
165
|
+
|
|
166
|
+
→ [Memory](docs/guide/Memory.md) · [Brownfield context](docs/guide/brownfield-context.md)
|
|
102
167
|
|
|
103
168
|
---
|
|
104
169
|
|
|
105
170
|
## What lands in your repository
|
|
106
171
|
|
|
107
|
-
| Path |
|
|
172
|
+
| Path | What it is |
|
|
108
173
|
| --- | --- |
|
|
109
|
-
| `.cursor/skills/` (+ Claude, Copilot, Codex trees) |
|
|
110
|
-
| `.specs/STATE.md` |
|
|
111
|
-
| `.specs/features/NNN-slug/` | Spec,
|
|
112
|
-
| `.specs/guardrails/scripts/` |
|
|
113
|
-
| `.specs/config.yaml` | Optional project rules and
|
|
174
|
+
| `.cursor/skills/` (+ Claude, Copilot, Codex trees) | The step-by-step guides the agent reads |
|
|
175
|
+
| `.specs/STATE.md` | Current feature and next step |
|
|
176
|
+
| `.specs/features/NNN-slug/` | Spec, job list, and verification per feature |
|
|
177
|
+
| `.specs/guardrails/scripts/` | The check scripts (Brakes mode) |
|
|
178
|
+
| `.specs/config.yaml` | Optional project rules and limits |
|
|
114
179
|
|
|
115
|
-
|
|
180
|
+
All plain text, all in git. Nothing is added to your dependencies or your build output.
|
|
116
181
|
|
|
117
182
|
---
|
|
118
183
|
|
|
119
|
-
##
|
|
184
|
+
## Optional extras
|
|
120
185
|
|
|
121
|
-
Start with the
|
|
186
|
+
Start with the core flow. Turn these on when the work calls for them.
|
|
122
187
|
|
|
123
|
-
|
|
|
124
|
-
| --- | --- |
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
| Questions | [FAQ](docs/guide/FAQ.md) | [Stability policy](docs/guide/Stability-policy.md) |
|
|
188
|
+
| Capability | What it adds |
|
|
189
|
+
| --- | --- |
|
|
190
|
+
| Memory search | Find past specs, decisions, and verifications by keyword |
|
|
191
|
+
| Code index | A lightweight map of an existing codebase for brownfield work |
|
|
192
|
+
| Solution exploration | Compare implementation options side by side before committing |
|
|
193
|
+
| Execution policy | Limits on which paths the agent may touch, and budgets |
|
|
194
|
+
| Episodic memory | Session notes distilled into lessons for later runs |
|
|
195
|
+
| Semantic retrieval | Search memory by meaning instead of keyword — off by default |
|
|
132
196
|
|
|
133
|
-
|
|
197
|
+
### Cursor hooks — optional, and off by default in this repo
|
|
134
198
|
|
|
135
|
-
|
|
199
|
+
On **Cursor**, `install` can register IDE hooks that check scope before a file edit and screen shell commands before they run. They are a safety net, not part of the core flow — everything above works without them.
|
|
136
200
|
|
|
137
|
-
|
|
201
|
+
Be aware they spawn a short-lived **Node** process per action, which can make the IDE feel heavy on busy sessions, especially on Windows. To reduce or remove that cost, delete the `beforeShellExecution` entry from `.cursor/hooks.json` first, then `preToolUse` if needed.
|
|
138
202
|
|
|
139
|
-
|
|
203
|
+
→ [Cursor hooks and sandbox](docs/guide/Cursor-hooks-and-sandbox.md) — what they do, symptoms, tuning, full disable
|
|
140
204
|
|
|
141
|
-
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Documentation
|
|
142
208
|
|
|
143
|
-
|
|
209
|
+
| If you want to… | Read |
|
|
210
|
+
| --- | --- |
|
|
211
|
+
| Understand the idea | [Overview](docs/guide/Overview.md) · [Concepts](docs/guide/concepts.md) |
|
|
212
|
+
| Run your first feature | [Quick start](docs/guide/Quick-start.md) |
|
|
213
|
+
| See each step in detail | [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/guide/agent-commands.md) |
|
|
214
|
+
| Know what is enforced | [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md) |
|
|
215
|
+
| Work in an existing codebase | [Brownfield context](docs/guide/brownfield-context.md) · [Memory](docs/guide/Memory.md) |
|
|
216
|
+
| Tune Cursor IDE behavior | [Cursor hooks and sandbox](docs/guide/Cursor-hooks-and-sandbox.md) |
|
|
217
|
+
| Upgrade or check stability | [CHANGELOG](docs/CHANGELOG.md) · [Stability policy](docs/guide/Stability-policy.md) |
|
|
218
|
+
| Ask something specific | [FAQ](docs/guide/FAQ.md) |
|
|
144
219
|
|
|
145
|
-
|
|
220
|
+
Full index: [docs/guide/README.md](docs/guide/README.md)
|
|
146
221
|
|
|
147
|
-
|
|
148
|
-
npx @luizsantiago/spec-guardrails@latest install
|
|
149
|
-
npx @luizsantiago/spec-guardrails doctor
|
|
150
|
-
```
|
|
222
|
+
---
|
|
151
223
|
|
|
152
|
-
|
|
224
|
+
## Contributing
|
|
153
225
|
|
|
154
|
-
|
|
226
|
+
Focused improvements to skills, gates, CLI, docs, and tests are welcome.
|
|
155
227
|
|
|
156
228
|
```bash
|
|
157
229
|
git clone https://github.com/luizssantiago92/spec-guardrails.git
|
|
158
230
|
cd spec-guardrails
|
|
159
231
|
npm install
|
|
160
232
|
npm run guardrails -- install
|
|
161
|
-
npm
|
|
233
|
+
npm test
|
|
162
234
|
```
|
|
163
235
|
|
|
164
|
-
|
|
236
|
+
Source lives in `skills/` (agent guides), `scripts/` (check scripts), `lib/` (CLI), and `test/`. Re-run `npm run guardrails -- install` after changing shipped assets, and run `npm test` before opening a PR.
|
|
165
237
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
238
|
+
We build Spec Guardrails using Spec Guardrails — the recommended contribution workflow, gate stability rules, and the adversarial test policy are in [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## Credits
|
|
243
|
+
|
|
244
|
+
Spec Guardrails adapts patterns from these projects. Listed here are the ones whose ideas are **actually shipped** in the package:
|
|
245
|
+
|
|
246
|
+
| Project | License | What we adapted |
|
|
247
|
+
| --- | --- | --- |
|
|
248
|
+
| [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills) | CC-BY-4.0 | The specify → plan → build → verify phase model, the `.specs/` layout, and the "gates as brakes" philosophy |
|
|
249
|
+
| [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Discuss-phase patterns (option A/B/C decision records) and definition-of-done framing |
|
|
250
|
+
| [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Job dependency rules — one file owner per wave, stop rule, fake-edge detection |
|
|
251
|
+
| [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | The implementation wave model behind the build loop |
|
|
252
|
+
|
|
253
|
+
Everything else — the Node CLI, the Python gates, the platform adapters, and the requirements analysis phase — is original work in this repository.
|
|
172
254
|
|
|
173
|
-
|
|
255
|
+
Full lineage, including work we cite but do not bundle: [docs/guide/credits.md](docs/guide/credits.md)
|
|
174
256
|
|
|
175
257
|
---
|
|
176
258
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@luizsantiago/spec-guardrails",
|
|
3
|
-
"version": "4.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "4.1.1",
|
|
4
|
+
"description": "Governed spec-driven process kit for AI agents: phase guides, .specs/ memory, optional Python gates. Loop: specify, tasks, execute, verify. Cursor hooks (scope + shell policy) are optional; disable on lighter machines. Node 18+; Python 3.10+ for Brakes. Cursor, Claude, Copilot, Codex.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"spec-guardrails": "./index.js"
|