Open Source · MIT · v1.3.0
capivaOS — Spec-Driven Development Harness for Claude Code
capivaOS is an open-source (MIT) harness that turns Claude Code into a development pipeline with mandatory phases — spec → plan → implement → verify → deliver — enforced by a state machine with hooks that block out-of-phase writes, merges without a spec and transitions without a quality gate. Installs as a plugin in two commands.
MIT · v1.3.0 · official marketplace plugin · dogfooded by Capiva
The problem
You've seen it: the agent agrees to the plan, writes three files and by the fourth has already forgotten what you agreed on. Claude Code is powerful and undisciplined. It writes plausible code — and plausible isn't correct. Without enforcement, the agent skips the spec, forgets the plan mid-session and piles up debt that shows up in production weeks later. Prompt discipline doesn't survive the context window: it has to be infrastructure.
> agrees on the plan with the agent✓ file 1 · ✓ file 2 · ✓ file 3✗ file 4: ignores the agreed plan
A prompt asks.
A harness prevents.
An instruction in the prompt degrades as the context fills; a hook that blocks out-of-phase writes works the same in the first minute and in the tenth session.
What is a harness?
A harness is all the infrastructure around the model — tools, rules, quality gates and memory — that turns an LLM into a reliable agent: Agent = Model + Harness. capivaOS is the development harness for Claude Code: the layer that enforces engineering discipline on the agent. Full guide: What is an AI Harness?
How it works
Five mandatory phases, with a fast lane for low-risk tasks. Each phase produces an auditable artifact and is protected by a mechanical guard:
GRILL_SPEC
Spec + acceptance criteria
Writing code before the spec is approved
Select a phase to see what it produces and what it blocks.
View as a table
| Phase | Produces (artifact) | Blocks (guard) |
|---|---|---|
| GRILL_SPEC | Spec + acceptance criteria | Writing code before the spec is approved |
| PLAN | Implementation plan | Implementing without a plan derived from the spec |
| IMPLEMENT | Code + tests | Merging without acceptance criteria met |
| TEST_VERIFY | Quality report | Transitioning with coverage < 75–80% or new linter warnings |
| FINISH | Delivery + updated board | Closing without green gates |
Phase hooks prevent: writing code before the spec is approved, merging PRs without acceptance criteria, state transitions below the 75–80% coverage floor, and any new linter warnings. The task board in .board/sprint-state.md persists across sessions.
> merge PR #42✗ Blocked: coverage 71% < 75% floor> fix → re-run✓ gate PASS · transition allowed
Install in 30 seconds
/plugin marketplace add iB2/capivaOS/capiva:init
Blueprints included: .NET, Python/FastAPI, Next.js — and the pipeline itself is stack-agnostic.
Why we built this
Capiva runs its own projects on it — real dogfooding: this website is built and maintained by the very pipeline this page announces. capivaOS was born as the development layer of the internal harness described in AI Harness in Practice.
Extracted from real use on projects in Brazil, the US and the UK — it is not a speculative framework.
capivaOS is the published version of the development layer of Capiva's internal harness — in use since March 2026 across 12 simultaneous projects, full stack: code, infra and hosting. In a single night of autonomous operation, the pipeline delivered 14 tasks as 14 pull requests in ~11 hours — each with an approved spec, green tests and per-phase quality gates on record, and merges always human. 6 public releases in the first week (v1.0.0 → v1.3.0). The guards described on this page are readable in the code, under MIT.
Frequently asked questions
A spec-driven development harness for Claude Code, open-source under MIT, installed as a marketplace plugin. It enforces a 5-phase pipeline (GRILL_SPEC → PLAN → IMPLEMENT → TEST_VERIFY → FINISH) through a state machine: hooks mechanically block out-of-phase writes, merges without an approved spec and transitions without a quality gate. Sprint state persists in .board/sprint-state.md across sessions. Current version v1.3.0.
Prompts are suggestion; capivaOS is enforcement. Instructions degrade as the context window fills and disappear between sessions — the agent "forgets" the rule exactly when it matters most. In capivaOS, discipline is infrastructure: a hook that blocks writing code before the spec is approved works in the first minute and in the tenth session, regardless of what's in the context. It's the difference between asking and preventing.
Three structural differences: (1) mechanical enforcement — executable guards that block out-of-phase actions, not documentation conventions that depend on human discipline; (2) persistent state — the board and current phase survive session end and context compactions; (3) numeric quality gates — 75-80% coverage floors and zero new linter warnings as transition conditions, not recommendations.
Yes. It's a Claude Code plugin: /plugin marketplace add iB2/capivaOS and /capiva:init in your existing repo. Init detects the project context and configures the board and guards without restructuring the repository. It coexists with existing CI/CD — capivaOS gates run BEFORE the commit/PR, complementing (not replacing) your CI pipeline.
.NET, Python/FastAPI and Next.js, defining per-stack code and testing standards. The pipeline itself is stack-agnostic: phases and guards don't depend on language, and new blueprints are extensible from the existing ones.
For low-risk changes there's the fast lane, which shortens the pipeline. For everything else, the math is: the cost of writing a spec and a plan is fixed and small; the cost of reworking plausible-but-wrong code is variable and compounding — technical debt, regressions and debugging weeks later in production. The harness trades predictable minutes for unpredictable hours.
The phase transition is blocked and the agent receives the objective reason (coverage below the floor, new warnings, acceptance criteria not met). It fixes and retries — the human is only called at the defined approval checkpoints, not on every failure. A gate failure is a correction loop, not an interruption.
Yes: quality floors, human checkpoints and per-stack standards are configurable per project. What is not configurable is silently skipping a phase — that's the whole point of the harness.
capivaOS is built on Claude Code's plugin, hook and skill system, and that's where it operates today. The ARTIFACTS it produces (specs, plans, acceptance criteria, reports) are open markdown, readable by any tool — your data lock-in is zero.
Free and open-source, MIT license, no commercial telemetry. The code is at github.com/iB2/capivaOS. There is no paid tier of the plugin; Capiva monetizes harness implementation services for companies, not capivaOS.
Capiva, an AI boutique that runs its own client projects on capivaOS every day (Brazil, US and UK) — the plugin is the published version of the development layer of the company's internal harness. Versioned releases (v1.3.0 as of July 2026).
Two commands in Claude Code: /plugin marketplace add iB2/capivaOS and then /capiva:init in your repository. From there, your first task enters the pipeline: the agent walks you through the spec before letting any code be written.
Throwaway prototypes or one-off scripts: the spec cost doesn't pay off on code you'll discard — use the fast lane or don't install it at all. A repository with no tests: the coverage gates assume an existing suite; in that case start by building the test base (the pipeline helps from there). And if your workflow already has equivalent enforcement (mandatory human spec review + blocking CI gates), capivaOS replicates what you already have — the difference is it enforces it INSIDE the agent session, before the commit.
Start now
Prefer to talk? 20 min on how to apply it to your team →