Spec Seatbelt

A seatbelt 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.

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).

npm: @luizsantiago/spec-seatbelt 2.2.x

Install

npx @luizsantiago/spec-seatbelt install

What you need

| 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 |

What install does

| Lands in your project | Purpose | | --- | --- | | .cursor/skills/ + .claude/skills/ | Hub, phase references, sister skills | | .specs/seatbelt/scripts/ | Python gate scripts | | .specs/STATE.md, .specs/features/, … | Project memory | | .cursor/rules/engineering-baseline.mdc | Always-on Cursor rule |

Re-run install anytime to refresh skills; your .specs/ decisions and STATE.md are kept.

| Need | Command | | --- | --- | | First time / upgrade | install | | Existing codebase | project-init (optional) | | Something looks wrong | doctor | | Full CLI list | --help |

Token cost

Progressive loading is the main cost win: one working set per turn, not the entire playbook.

| Profile | Est. tokens | When | | ---: | ---: | --- | | Naive full dump (don’t) | ~31k | Loading every skill + reference every message | | Specify turn | ~9k | /specify — hub + specify.md + standards | | Tasks turn | ~10k | /tasks — hub + tasks.md + task-graph skill | | Execute /loop (one wave) | ~4k | One implement wave (inline or parallel) | | Verify turn | ~6k | Independent reviewer stack |

Savings vs full dump: ~72% (Specify), ~86% (Execute). Numbers from lib/token-cost.js; CI guardrails in test/test_token_cost.test.js. Order-of-magnitude only — not a billing API.

More: Token efficiency

How the pieces fit together

Four ideas stack — full explanation: Concepts

| Idea | What it is | What it does | | --- | --- | --- | | Spec-driven | Written plan before code | spec.md + tasks.md; evidence before “done” | | Seatbelt | 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 · How it works · Quick start

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.

| Tier | Typical scope | Path | | --- | --- | --- | | Quick | ≤3 files, no new deps | /quick → verify → commit | | Simple | Small localized change | /specify → /loop → /verify | | Medium | New feature, <10 tasks | /specify → /tasks → /loop → /verify → /archive | | Complex | APIs, architecture, infra | + /discuss, /plan, optional security/QA on verify | | Parallel | Splittable work | Above + /task-graph when 3+ tasks |

Rules and examples: Concepts → Complexity tiers

Hub and skills (summary)

Install copies a hub (agent-architecture.md), phase references (references/*.md), and sister skills (security, task-graph, …). The agent loads one phase file at a time.

| Load order | Layer | Role | Examples | | ---: | --- | --- | --- | | 1 | Hub | Contract, complexity router, gate schedule | agent-architecture.md | | 2 | Reference | One phase procedure per turn | specify.md, implement.md, validate.md | | 3 | Sister (optional) | Cross-cutting depth, on demand | engineering-standards.md, task-graph-engineering.md | | 4 | Gate | Automatic check at the boundary | validate-spec, loop-plan, check-commit |

Conditional sisters (appsec.md, qa-strategy.md, …) load one at a time on Verify when risk warrants it.

Full map: Skills and hub

Gates (summary)

Scripts in .specs/seatbelt/scripts/. Exit ≠ 0 → stop and fix.

| When | Gate | What it blocks | | --- | --- | --- | | Before approving spec | validate-spec | Incomplete or untestable spec | | Before approving tasks | analyze-artifacts | Spec ↔ tasks drift | | Before approving tasks | validate-tasks | Bad tasks; missing graph when 3+ tasks | | Each /loop wave | loop-plan | Blocked dependencies; shows parallel groups | | Each commit | check-commit | Non-Conventional commit message | | Before “done” | validate-state | Fake PASS without test evidence | | After Verify FAIL | lessons | Ungrounded “lessons learned” | | After Verify PASS | archive-feature | (CLI) folds feature into domain memory |

Full reference: Gates · Gates and guarantees

Documentation

| Doc | For | | --- | --- | | Agent commands | Every /specify, /loop, /verify, … — purpose, when, examples | | Quick start | First ten minutes | | Concepts | Spec-driven + seatbelt + loop + graph | | Skills and hub | What each skill file does | | Gates | How each gate works | | FAQ | Common questions | | Changelog | Full version history |

Start after install: Quick start · Agent commands

Upgrading

npx @luizsantiago/spec-seatbelt install

| Version | What you gain | | --- | --- | | 2.2.x | Seatbelt paths & markers; doctor Execute hints; docs split from README | | 2.1.x | loop-plan + parallel /loop waves | | 2.0.x | Package rename → @luizsantiago/spec-seatbelt | | 1.1.x | project-init for brownfield repos | | 0.9.x | archive-feature + domain memory merge |

Full history: CHANGELOG · Releases

Renamed from @luizsantiago/agentic-harness. Run install once after switching. Legacy .specs/harness/scripts/ and AGENTIC-HARNESS markers still work on 2.x until install migrates them; planned removal in 3.0.

Contributing

See CONTRIBUTING.md — tests, gate freeze policy, local npm run seatbelt -- install.

Credits

Spec Seatbelt adapts open ideas; we did not invent spec-driven phases, loop design, or task-graph rules.

Core lineage

| Source | License | How we use it | | --- | --- | --- | | tlc-spec-driven | CC-BY-4.0 | Phase model, .specs/ memory, gate lineage | | addyosmani/agent-skills | MIT | Discuss patterns, definition-of-done | | graph-engineering | MIT | Task-graph topology, stop rules, parallel merge |

Loop & ecosystem

| Source | License | How we use it | | --- | --- | --- | | loop-engineering | MIT | Operational loop patterns; doctor score metaphor | | Addy Osmani — Loop engineering | — | Essay lineage | | awesome-harness-engineering | CC0 | Ecosystem taxonomy |

Adjacent (not vendored)

DeepCode · RepoGraph

Extended attribution: docs/guide/credits.md

License

MIT