@luizsantiago/spec-guardrails 3.1.2 → 3.1.4

package/README.md

@@ -3,9 +3,13 @@
 [![npm version](https://img.shields.io/npm/v/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**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.
+**Keep AI coding agents honest — specify the work, prove each step, verify independently.**
 
-**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)).
+| | |
+| --- | --- |
+| **Problem** | Agents ship “looks good” with thin specs, missing evidence, and the same context that wrote the code declaring victory. |
+| **Solution** | One kit, two deliberate modes: **Process** (Node only) for a flexible spec-driven workflow; **Brakes** (Node + Python) for the **full product** — structural gates that exit non-zero when paperwork or evidence is missing. You approve specs/tasks in both. |
+| **Result** | Traceable `.specs/` memory, fewer fake finishes, cheaper turns (~70% less skill text on planning). Choose Process for light ceremony; add Python when you want the [Guarantees matrix](#guarantees-matrix) enforced automatically. |
 
 npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.1.x**
 
@@ -22,17 +26,19 @@ npx @luizsantiago/spec-guardrails install
 | Requirement | Role |
 | --- | --- |
 | **Node.js 18+** | Required — runs the CLI and `install` |
-| **Python 3.10+** | Recommended — runs automatic **gates** (`validate-spec`, `validate-tasks`, …). Without Python the agent still follows the same checklists manually |
+| **Python 3.10+** | Activates **Brakes mode** — the **full** kit with Python structural gates (`validate-spec`, `validate-tasks`, …). Gates stay Python by design. Without Python you stay in **Process mode**: same phases and checklists, no exit-code enforcement. Run [`doctor`](#install) to see which mode you are in |
 
 ### What install does
 
 | Lands in your project | Purpose |
 | --- | --- |
-| `.cursor/skills/` + `.claude/skills/` | Hub, phase references, sister skills |
-| `.specs/guardrails/scripts/` | Python gate scripts |
-| `.specs/STATE.md`, `.specs/features/`, … | Project memory |
+| `.cursor/skills/` + `.claude/skills/` | Hub, phase references, sister skills (first shipped **adapters** — not the only supported agents) |
+| `.specs/guardrails/scripts/` | Python gate scripts (Brakes mode) |
+| `.specs/STATE.md`, `.specs/features/`, … | Project memory (any agent) |
 | `.cursor/rules/engineering-baseline.mdc` | Always-on Cursor rule |
 
+**Agent environments:** the **core** (`.specs/`, CLI, hub, Python gates) works with any AI agent that reads repo instructions and runs shell commands. Install ships Cursor + Claude Code adapters today; Codex, GitHub Copilot, and others are documented in [Architecture](docs/guide/Architecture.md).
+
 Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.md` are kept.
 
 | Need | Command |
@@ -44,6 +50,59 @@ Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.
 
 ---
 
+## How it works in one screen
+
+Four ideas stack — full explanation: **[Concepts](docs/guide/concepts.md)**
+
+| Idea | What it is | What it does |
+| --- | --- | --- |
+| **Spec-driven** | Written plan before code | `spec.md` + `tasks.md`; evidence before “done” |
+| **Brakes / Gates** | Structural stop-gates | Python scripts exit non-zero when paperwork or evidence is missing |
+| **Loop** | Execute in waves | `loop-plan` picks the next jobs; sub-agents when files don’t overlap |
+| **Graph** | Parallel task map | `task-graph.md` — safe parallelism without file collisions |
+| **Memory** | Repo-local state | `.specs/` — specs, decisions, and handoff survive across chats |
+
+**You** approve specs and tasks. **The agent** runs gates and implements. **Gates** exit non-zero when paperwork or evidence is missing.
+
+Plain-language tour: [Home](docs/guide/Home.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
+
+---
+
+## Operating modes
+
+Two modes, one package — pick how much rigor you want:
+
+| Mode | Runtime | What you get | Best for |
+| --- | --- | --- | --- |
+| **Process** | Node.js 18+ | Spec-driven workflow, `.specs/` memory, progressive loading, independent `/verify` | Flexible ceremony, exploration, teams that enforce by review |
+| **Brakes** | Node + **Python 3.10+** | Everything in Process **plus** Python gates from the [Guarantees matrix](#guarantees-matrix) — exit ≠ 0 → stop and fix | The **full Spec Guardrails** — traceability, evidence, and structural guarantees enforced automatically |
+
+**Gates stay Python.** That is the product: Brakes mode is the complete version with automated enforcement. Process mode is the same loop without exit-code brakes — intentional, not incomplete.
+
+Install Python when you want gates to fire; run `doctor` to confirm Brakes are available.
+
+---
+
+## Guarantees matrix
+
+**Guarantees are the product.** Commands are implementation.
+
+| Guarantee | Mechanism | Mode | Enforcement |
+| --- | --- | --- | --- |
+| Intent exists before code | `validate-spec` | Brakes | Hard gate |
+| Tasks derive from requirements | `analyze-artifacts` | Brakes | Hard gate |
+| Requirements stay traceable | `validate-traceability` | Brakes | Hard gate |
+| Dependencies respected in Execute | `loop-plan` | Brakes | Hard gate |
+| Parallel work is file-safe | `task-graph.md` + `validate-tasks` | Process + Brakes | Artifact + gate |
+| Completion cites evidence | `validate-state` | Brakes | Hard gate |
+| Commits follow policy | `check-commit` | Brakes | Hard gate |
+| Verification is independent | `/verify` + `validate.md` | Process | Phase skill |
+| Knowledge survives chats | `.specs/` + `archive-feature` | Process | Install + CLI |
+
+Full matrix, limits, and phase diagram → **[Guarantees matrix](docs/guide/Guarantees-matrix.md)** · [Architecture](docs/guide/Architecture.md) (Core + adapters)
+
+---
+
 ## Token cost
 
 Progressive loading is the main cost win: **one working set per turn**, not the entire playbook.
@@ -62,24 +121,6 @@ More: [Token efficiency](docs/guide/Token-efficiency.md)
 
 ---
 
-## How the pieces fit together
-
-Four ideas stack — full explanation: **[Concepts](docs/guide/concepts.md)**
-
-| Idea | What it is | What it does |
-| --- | --- | --- |
-| **Spec-driven** | Written plan before code | `spec.md` + `tasks.md`; evidence before “done” |
-| **Guardrails** | This package | Skills + Python gates that stop incomplete work |
-| **Loop** | Execute in waves | `loop-plan` picks the next jobs; sub-agents when files don’t overlap |
-| **Graph** | Parallel task map | `task-graph.md` — safe parallelism without file collisions |
-| **Memory** | Repo-local state | `.specs/` — specs, decisions, and handoff survive across chats |
-
-**You** approve specs and tasks. **The agent** runs gates and implements. **Gates** exit non-zero when paperwork or evidence is missing.
-
-Plain-language tour: [Home](docs/guide/Home.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
-
----
-
 ## Complexity tiers (how work flows)
 
 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 +156,7 @@ Full map: **[Skills and hub](docs/guide/skills-and-hub.md)**
 
 ## Gates (summary)
 
-Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
+Commands implement the guarantees above. Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
 
 | When | Gate | What it blocks |
 | --- | --- | --- |
@@ -130,7 +171,7 @@ Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
 | After Verify FAIL | `lessons` | Ungrounded “lessons learned” |
 | After Verify PASS | `archive-feature` | (CLI) folds feature into domain memory |
 
-Full reference: **[Gates](docs/guide/gates.md)** · [Gates and guarantees](docs/guide/Gates-and-guarantees.md)
+Full reference: **[Gates](docs/guide/gates.md)** · [Guarantees matrix](docs/guide/Guarantees-matrix.md) · [Gates and guarantees](docs/guide/Gates-and-guarantees.md)
 
 ---
 
@@ -138,12 +179,14 @@ Full reference: **[Gates](docs/guide/gates.md)** · [Gates and guarantees](docs/
 
 | Doc | For |
 | --- | --- |
+| [Guarantees matrix](docs/guide/Guarantees-matrix.md) | Product promises → mechanisms |
+| [Architecture](docs/guide/Architecture.md) | Core vs platform adapters |
 | [Agent commands](docs/guide/agent-commands.md) | Every `/specify`, `/loop`, `/verify`, … — purpose, when, examples |
 | [Quick start](docs/guide/Quick-start.md) | First ten minutes |
 | [Concepts](docs/guide/concepts.md) | Spec-driven + guardrails + loop + graph |
 | [Skills and hub](docs/guide/skills-and-hub.md) | What each skill file does |
 | [Gates](docs/guide/gates.md) | How each gate works |
-| [Platform parity](docs/guide/Platform-parity.md) | Cursor vs Claude Code |
+| [Platform parity](docs/guide/Platform-parity.md) | Shipped adapters (Cursor, Claude Code) — core works with any agent |
 | [FAQ](docs/guide/FAQ.md) | Common questions |
 | [Changelog](docs/CHANGELOG.md) | Full version history |
 

package/lib/gates.js

@@ -112,8 +112,8 @@ export async function runGuardrailsScript(command, args, options = {}) {
 
   if (!python) {
     throw new Error(
-      "Python 3 not found. Install Python 3.10+ to run guardrails scripts, " +
-        "or perform the equivalent checks manually (degraded mode).",
+      "Python 3 not found. Install Python 3.10+ for Brakes mode (automatic gates), " +
+        "or perform the equivalent checks manually in Process mode.",
     );
   }
 

package/lib/install.js

@@ -129,8 +129,8 @@ export async function install(options = {}) {
   const pythonAvailable = await hasPython();
   if (!pythonAvailable) {
     log(
-      "⚠️  Python 3 not found. Skills still work in degraded mode " +
-        "(manual checks). Install Python 3.10+ to enable the gates.",
+      "⚠️  Python 3 not found — Process mode only (flexible workflow, manual checkpoints). " +
+        "Install Python 3.10+ for Brakes mode (full kit with automatic gates).",
     );
   }
 

package/lib/next-steps.js

@@ -12,9 +12,10 @@ export function formatInstallNextSteps(options = {}) {
     "✨ Setup complete.",
     "",
     "Next:",
-    "  1. Open Cursor or Claude Code in this project.",
+    "  1. Open your AI coding agent in this project (Cursor and Claude Code adapters install automatically).",
     "  2. Run **Specify** (`/specify` or “Specify a feature: …”).",
     "",
+    "  Other agents: core + CLI work anywhere — see docs/guide/Architecture.md",
     "  Guide: docs/guide/Quick-start.md (repo) · .specs/GETTING_STARTED.md (this project)",
   ];
 
@@ -24,7 +25,8 @@ export function formatInstallNextSteps(options = {}) {
 
   if (options.pythonAvailable === false) {
     lines.push(
-      "  Note: install Python 3.10+ for automatic gates, or the agent checks by hand.",
+      "  Note: install Python 3.10+ for Brakes mode (full kit with automatic gates), " +
+        "or stay in Process mode (same phases, manual checkpoints).",
     );
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.1.2",
-  "description": "Guardrails for AI coding agents — spec-driven phases, automatic gates, progressive skill loading (~70% fewer tokens per turn). Works in Cursor and Claude.",
+  "version": "3.1.4",
+  "description": "Spec-driven process kit for any repo-local AI agent: Process mode (Node) or full Brakes mode (Node + Python gates). Progressive loading, independent verify, Guarantees matrix.",
   "type": "module",
   "bin": {
     "spec-guardrails": "./index.js"

package/skills/agent-architecture.md

@@ -190,10 +190,6 @@ Never skip to step 5 while steps 1–4 are available. Fabrication cascades throu
 
 Project rules: `.cursor/rules/engineering-baseline.mdc` (always applied in Cursor).
 
-## Optional companion: Full Stack Floor Map
-
-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).
-
 ## Commands
 
 | Command | Reference | Action |

package/skills/references/tasks.md

@@ -27,7 +27,7 @@ Break the work into atomic tasks with real dependencies and binary done criteria
 ## Procedure
 
 1. **Write one task per deliverable.** A task is something you would hand to a single agent and check in one commit.
-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).
+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.
 3. **Give every task the full field set.** Authoring and the gate require all six:
    - `Requirement` — the spec ID it serves (gated)
    - `Files` — where the change lands (gated; required; `none` / `—` rejected; overlap across independent tasks blocks)

package/templates/GETTING_STARTED.md

@@ -4,7 +4,7 @@ You installed the **Spec Guardrails**. You do **not** need to memorize CLI comma
 
 ## What to do now
 
-1. Open **Cursor** or **Claude Code** in this project.
+1. Open your **AI coding agent** in this project (Cursor or Claude Code if you use those adapters).
 2. Start with **Specify** (an **agent command** — chat, not terminal):
 
    ```
@@ -20,7 +20,7 @@ You installed the **Spec Guardrails**. You do **not** need to memorize CLI comma
 
 ## Agent commands (chat — not terminal)
 
-Type these in **Cursor or Claude Code**. They load phase procedures from `.cursor/skills/references/`. The agent runs gates for you.
+Type these in **chat** in your agent environment. They load phase procedures from the installed skills tree (e.g. `.cursor/skills/references/`). In **Brakes mode**, the agent runs Python gates for you.
 
 | Command | When |
 | --- | --- |