CooperativeAICoding

A framework that gives Product, Developers, and AI a single, shared way of working — so that software is built to clear objectives, within agreed technical guardrails, without the AI wandering off and burning tokens rebuilding things that already work.

Development is a team game, and normally this would involve Product working with Developers and Quality Assurance to build a good product, with continuous feedback from Product to Developers, Developers to Product, and QA to Developers and Product — all about capabilities, general product functionality, and look and feel.

The Problem

AI allows us to move faster, but this also means communication involves AI putting its own spin on the product, the coding, and how the QA is written. The plan of this framework is to make AI part of the team and stop AI from going its own way with a product.

AI when given vague or general descriptions tends to:

• get lost and add endpoints or features that weren't asked for,
• spend a lot of tokens creating, then recreating, the same work, and
• produce large-scale changes at high speed that overwhelm teams and destabilise production.

The goal is to give AI and all team members a source of truth for the product. Create guardrails around this so AI can build a solution that developers can maintain, following the Product flow, and also give AI a place to feed back what it cannot do. This also allows developers to keep to the idea of changing as little production code as possible and to use AI to create more testable code.

How It Works

The framework is defined in three areas:

• The Project brief, which is the why we are doing this, plus general development rules and structure, where each solution's code lives (including across multiple repositories), infrastructure/secrets policy, and gives AI the software engineering practices to employ and how the developers it is working with define these ideas.
• The solution specification, which is where developers define the reason for each solution, give AI the solution-specific guidance, and set it up to successfully move quickly — including its repo scaffold (file layout, tests, commands), its security rules, and the infrastructure and pipeline it needs. Solutions can start from named boilerplates (a scaffold preset plus a security baseline) in template/_forms/boilerplates.json instead of being hand-written from scratch.
• The item — one page, one endpoint, or one database model — which defines the purpose of the single thing we are creating and what we need from it, and is designed to be built iteratively. Items can declare what must be built before them, so the AI never guesses at build order across a multi-solution project. AI can do the task and, instead of burning tokens trying to implement something it can't understand, it says "I can't implement this" and allows the developers to tell it how to implement it, or go to Product and rethink the feature.

Global Setup

Before any item is built, Product and Developers define the shared rules:

• Objectives & customers (Product) — what the software is for and who it serves.
• Technology & formats (Developers) — the tech stack, the platforms the solution must run on, and the formats it must support.
• Coding standards — general techniques the AI must follow (e.g. DRY, SOLID). Each standard must be defined: what it means here and how the AI should apply it.
• Frameworks — which global frameworks are in use and how they should be upgraded.
• Security — how users are authenticated, how endpoints are protected, and how permissions are enforced.
• Design — a place for Product to link UI/UX references, attach images or descriptions, and define their customers.

The aim of the technology rules is that any new endpoint the AI creates works with the target platform and is written so that build errors are less likely.

Items

Once the global setup is complete, the system is broken into sub-sections, and each sub-section is an item — the smallest thing this framework plans, builds and iterates. An item comes in one of three kinds, each with its own form:

Kind	What it is	Form
Page	one screen, panel, or command group of a website or application	page.md
Endpoint	one API resource and its operations	endpoint.json
Model	one table or data model	database-model.json

Nothing here assumes a front end. A backend-only project has no pages at all — it is endpoints and models, and everything below reads the same for them. Item is the word the commands already use: /new-item page|endpoint|model.

Each item also names the deliverable it works towards — see Deliverables, below.

Each item is defined once by Product, then built up iteratively by Developers — starting from the simplest working version and growing toward the final system one iteration at a time (changing data models, adding behaviour, and so on).

Item Layout

Product — fixed question (asked once):

• Why do we have this item? — the overall objective of this page, endpoint, or model.

Product — iterative questions:

• How should it look? (pages and screens)
• What information do we want to record?
• What are the use cases? Who uses this item, and how do they use it under different conditions?
• Who should be able to use it? (This sets the security expectations for developers.)

Product — and why it matters:

• What does this do for customers, and for the business?

Product plans these, with the AI if they like (/product), and signs them: sign-off 1.

Developers — questions:

• How can we do this? Can we build this, or is there a better way?
• What happens with errors, and with scenarios that could occur?
• What technical challenges are there?
• What tests should the AI create?
• What questions do we have for Product?
• What should the data model look like?
• Is there anything that must not be saved permanently, or must survive between screens? (A constraint if there is one — not a design to impose.)
• How will we know it works? What must be true for this to be accepted?
• What endpoints should be used?

Developers talk their answers through with Product, which refines the idea. When both are happy, and QA has reviewed the item and planned how to test it, they sign together: sign-off 2. /build checks both (and QA's verdict, never QA's tests) before it plans. A sign-off names the change round it covers, so a new round needs new sign-offs. A change after sign-off 2 to the project's roles or testing floor, or to the solution's security, reopens it, because that is what Dev and Product agreed against. Other changes mean re-translating, not re-signing.

The AI Workflow

For each item (and each iteration), the AI follows a defined loop. Before it, /translate turns each brief into a terse spec where every line names the answer it came from, and anything it cannot tell becomes an UNKNOWN line rather than a guess; a build will not start while one is open.

0. Scaffold — the first time an approved item is built in a solution with no code yet, the AI creates the repo skeleton from that solution's spec (a named boilerplate, or its own file layout/tests/commands) as its own approved plan, before any feature is built.
1. Plan — the AI generates a plan from the spec, opening with an approval card: ten plain-English lines saying what changes, which deliverable it advances, what it reuses, which rules it touches and the debt expected. People approve from the card; the plan beneath it is for the AI. It checks the item's declared dependencies are already built, checks its code map and reuses existing methods rather than rebuilding them, and confirms the change doesn't need new infrastructure (which is its own approved plan, never a side effect of a feature).
2. Review & execute — the developer reviews and updates the plan, then executes it.
3. Report back — once complete, the AI runs the solution's test/build commands and updates the plan document with what it did, how each use case was implemented, and what test scenarios it created. It also updates the code map (ai-only/Code_map.md): one row per method it created or changed — what it does in one line, and which other files and methods it uses.
4. Declare debt — the AI lists any technical debt it created or anything it failed to implement, each with an ID (D1, D2, …). People then decide on each, in the brief: pay it down in a change round, or accept it with a reason. /debt walks them through it, and spec-lint notes any nobody has decided on.

The AI should not spend ages trying to fix or reimagine something. It builds the item simply and clearly records where it fell short and what debt it introduced.

Iterations

A change says what it affects. Every spec line cites the answer it came from, so when a brief changes, node tools/spec-lint.mjs --impact lists each spec, and each line in it, that now reads differently from its source. /build refuses a stale spec until it is re-translated, so nothing is built from an old reading of the brief.

After the first build, each further iteration defines what needs to change:

• Change in use case?
• Change in tests?
• Change in UI/UX?
• Change in technology?
• Change in data model?
• Change in endpoints?
• How should existing technical debt or earlier AI failures be addressed?

QA sign-off

QA is the quality check and the sign-off. It is a track of its own, owned by a person, and not part of how the AI builds.

• Before work starts, QA reviews each item in qa/<solution>/<item>.md and answers six questions:
  1. Can I test this?
  2. How should I test this?
  3. What tests should I be doing?
  4. Are they manual, or can I automate them?
  5. What questions do I have for Product?
  6. What problems do I see?
• Questions for Product go to Product directly. Their answers reach the build the normal way, through the brief.
• QA keeps a regression suite, qa/regression.md, that answers "does the application still work and do what is expected?" The automated tests run every time, through each solution's regression command in its pipeline. QA runs the manual ones.
• When QA is happy, they ask the AI (/qa) for whatever they need to test: automated tests in the solution's repo, scripts for the manual ones, and any testability hooks in the app as their own approved plan. The AI never fixes a failing test or the app; a failure becomes a new development round.
• A deliverable is done when QA signs it off in qa/signoff.md. When the AI builds a deliverable's last item it stops and waits. brief-lint reports which deliverables are built and waiting on QA.

Kept apart on purpose. /translate and /build never read qa/. If the AI that builds an item can see QA's tests, it builds to pass them, and a passing run stops telling anyone anything. QA's tests come on top of the developers' testing floor, never instead of it.

Deliverables

Iterating needs something to iterate towards, or "smallest change" just means "smallest change forever".

The Project Brief names the deliverables in order, each with what makes it done — the first is usually the MVP, the smallest version genuinely worth putting in front of someone. Every item names the deliverable it serves, so a build says which one the change advances.

A deliverable is a stopping point, not a date. When the last item naming it is built, the AI stops there, says what the deliverable now does end to end, and waits — because a point for people to evaluate direction is worth nothing if the AI builds straight past it. That is the whole reason for naming them.

Guiding principles for changes:

• The AI should change only what the change case requires, making the smallest possible change to avoid breaking production code.
• Assume all existing code is working in production — even if it looks broken.
• The AI should score each change by how token-intensive it is likely to be.
• Secret values never go into code, config, or logs — they're referenced by name from a store the infrastructure block points at.
• Infrastructure and pipelines are their own approved plans — never a side effect of building a feature (see /pipeline, below).

This is not an exhaustive list. Product and Developers need space to define what else each item requires and how the AI should implement those changes.

Decisions taken deliberately

Things this framework was asked for and chose not to do, recorded so they don't have to be re-argued:

• People can read anything the AI writes, and nobody has to. What people want is the outputs. So the AI's own files in ai-only/ are written for the AI: terse, one fact per line, as few tokens as clarity allows. They stay plain English, never a private shorthand, so anyone can open one and take over. The routine read-back is done by tools/spec-lint.mjs: every line must cite the brief answer it came from, and a line that cannot is invented scope. What people do read is kept short and plain: the UNKNOWN lines, the approval card, and the round reports. This roughly halved what a translate-and-build reads, from about 21,000 tokens to about 10,600, and cut a build alone from about 11,100 to about 2,400 (estimated at four characters a token, on the example project).

• "Item", not "page". A page is one kind of item, alongside endpoints and database models. A backend-only project has no pages and loses nothing.

• A testing floor, not a list of tests. The Project Brief states the level of cover expected of every change and what isn't worth testing; items list their own acceptance checks on top. A list of things to test reads to an AI as permission to skip everything not on it.

• Constraints, not implementation answers. Questions ask what must be true of the product, not how to build it — "the basket survives moving between pages", never "hold the basket in memory". An answer about mechanism becomes a requirement the AI then honours, and a passing thought turns into a design nobody chose.

• Plain English, not Given/When/Then. Gherkin is more precise and it is not free: a form that has to be written in a syntax is a form Product stops filling in, and the briefs only work because anyone can answer them. Precision is bought back where it pays — the acceptance checks, the endpoint and model forms (which are structured JSON), and the test cases in the app's Test environment, which is the one place a Given/When/Then shape could still earn its keep.

• Deliverables as stopping points, not dates. They exist to force a pause for evaluating direction, which a date does not do.

Working with agents other than Claude Code

The commands, in each agent's own format. coperativeai init --agents <list> gives a project the commands for the agents its team uses:

Agent	Key	Where	Invoked as
Claude Code	claude (default)	.claude/commands/	/build
Cursor	cursor	.cursor/skills/<name>/SKILL.md	/build
Codex CLI	codex	.agents/skills/<name>/SKILL.md	$build
Gemini CLI	gemini	.gemini/commands/<name>.toml	/build
GitHub Copilot	copilot	.github/prompts/<name>.prompt.md	/build
opencode	opencode	.opencode/commands/<name>.md	/build
Kiro CLI	kiro	.kiro/prompts/<name>.md	its prompt menu

Every one is a pointer to the same procedure in ai-only/procedures/, generated from .claude/commands/ by tools/agent-commands.mjs. A test fails if any drifts from its source. coperativeai update remembers which agents a project chose. The formats follow each agent's integration as GitHub's Spec Kit documents it. Where an agent passes no arguments (Cursor, Codex, Copilot, Kiro), the pointer takes them from the conversation.

One brief, every agent's native guardrails. /emit-guardrails writes the project's rules out in the shape each tool actually reads: AGENTS.md at the root (which Kiro always includes and Cursor accepts as a plain-markdown alternative to .mdc rules), CLAUDE.md, Kiro steering files under .kiro/steering/, Cursor rules under .cursor/rules/, or Copilot instructions. Generated from the same spec, so there is one place to change a rule and no second copy to drift.

Generated files carry a header saying so, and a file without that header is never overwritten — it was written by a person.

What is enforced, in Claude Code. Hooks in .claude/settings.json run tools/hooks/guard.mjs before and after every write. They refuse:

• a sign-off written by the AI;
• a QA review marked happy by the AI;
• any write in QA's sign-off sheet;
• a write that adds a secret value (a private key, or an AWS, GitHub, Slack, Anthropic, OpenAI, Stripe or Google token).

After a spec is written, they hand spec-lint's findings straight back to the AI. These are the rules whose breaking cannot be undone by editing a file afterwards. Other agents get none of this yet.

What travels and what does not, stated plainly because it is discovered otherwise: the guardrails travel — house rules with their definitions, the testing floor, the security baseline, the deliverable in progress, and the working agreement including stop and say so rather than guess. The machinery does not — plan approval, model and effort per item, run cost, deny-by-default policy and the sandbox live in the app and its commands. This repository's own AGENTS.md is the worked example, honest gaps included.

How this differs from OpenSpec, Kiro, and friends

Spec-driven development is not a new idea and this is not the only tool doing it. Two come up every time: OpenSpec, which is free, and Kiro, which is not. (Read September 2026. All three move — if this section is stale, it is this repository's fault, not theirs.)

OpenSpec is a CLI you install with npm. It keeps living requirements in openspec/specs/, in-flight work in changes/, and finished work in archive/ by date, driven by five commands: explore, propose, apply, verify, archive. Requirements are SHALL statements with WHEN/THEN scenarios. It works with thirty-plus coding agents and has a year of monthly releases behind it.

The difference that matters most is who writes the source of truth. In OpenSpec the AI drafts the spec and you review it. Here, people answer plain-English questions and the AI translates them — it never authors the brief it will later build from. Both are defensible, and they fail differently: reviewing a generated spec is exactly where "it wrote what it felt like and I skimmed it" lives, while ours costs you real typing before anything happens, and a form nobody fills in produces nothing at all.

	OpenSpec	This
The spec is written by	the AI; you review it	people; the AI translates it
Aimed at	a developer with a coding agent	Product, Developers and QA, as separate roles
Requirements are	SHALL + WHEN/THEN scenarios	plain English (see Decisions taken deliberately, above)
A change is	a proposal folder, archived when applied	a round appended to the item's brief, which is permanent
Repositories	the one you initialise it in	several, each solution naming its repo and local path
Agents	thirty-plus, generated per tool	seven, generated per tool from one source; the app adds Ollama and Claude subscriptions

What OpenSpec does well

• Starting costs nothing. One npm command, and it generates the command files for whichever agent you already use. Copying a folder — what this framework asks — is more friction than that.
• Agent-agnostic in practice, not in ambition. Thirty-plus tools, kept working across releases. This is the single biggest thing it has and we don't.
• A change is a delta, not an edit. In-flight work is a folder of its own and the living spec stays clean, so "what is being changed right now" is always answerable.
• Verify is its own step. Checking the implementation against the spec is a command somebody can be made to run, rather than a good intention at the end of a build.
• Precise without being a syntax tax. SHALL and WHEN/THEN are checkable, and cheap enough that engineers actually write them.
• It is a year old. Other people have already found the edges. Nothing here has that.

What OpenSpec does badly

Our reading, and a trade it has chosen rather than a list of bugs:

• The AI writes the thing meant to constrain the AI. Human review is the only gate, and review of generated prose is the weakest gate in software.
• No seat for anyone but a developer. Nothing separates Product's "why" from a developer's "how", so a spec folder is all Product and QA get.
• One repository. Real products span several; nothing in it knows that.
• No cost control. Which model, how hard it thinks, and what a run spent are all outside its scope — while its own docs recommend high-reasoning models.
• Nothing flows back. There is no channel for the AI to declare debt, or to say "I can't implement this" and have that become work somebody sees. The specification is one-directional.
• No reuse ledger, so nothing stops an agent rebuilding what already exists — the failure this framework's code map was built for.
• The why scatters. Archiving by date is tidy, but a feature's reasoning ends up spread across dated folders instead of sitting beside the thing it explains.

And Kiro

Second-hand — from a developer who uses it daily, not from our own use. It does steering files per repository, specialist subagents (one that knows Terraform, one Ansible, one that reads AWS), interactive design before the agent runs, and it is an IDE as well as an agent. It is more mature than anything here and you are paying for it. Being free is not the interesting difference; feedback running back from the AI is, and cost, and the multi-repository case.

Choose accordingly

One developer, one repository, specs without ceremony — OpenSpec is the lighter tool, and it would be dishonest to pretend otherwise. A team where Product and QA have to be in the loop, work spans several repositories, and somebody has to see the cost and the debt — that is what this is for.

Templates

The working layout lives in template/. You fill in the forms — prose briefs (the project brief and page briefs) are Markdown you answer under question headings; record-style forms (endpoints, database models, solution specs) are JSON with answer fields and entry lists. Either way you write plain English; the AI — Claude, or whichever model your team uses — translates them into structured specs, working out the skills it needs, and mirrors your folders in its own workspace.

• template/Project_brief.md — plain questions about the whole project, including where each solution's code lives and your infrastructure/secrets policy. Filled in once.
• template/_forms/ — blank master forms to copy: one application-spec.json for every solution (set its solutionType to website, api, database, or application), item forms (page.md, endpoint.json, database-model.json), and boilerplates.json — named scaffold presets and security baselines a solution spec can adopt by name.
• template/<solution>/ — one folder per solution (e.g. frontEnd/, backend/); each item is a file inside it, like frontEnd/page1.md or backend/userLogin.md.
• template/ai-only/ — the AI's workspace, written by the AI and read and approved by people (see its README). It holds the translate bridge and the ; the specs the AI translates, mirroring your solution folders (e.g. → ), with each item's plans and round reports; and one supporting index, the , so the AI reuses methods it already built instead of rebuilding them.

See template/README.md for the full layout and step-by-step flow.

Getting started

Install it from npm, then run it in any project:

npm install -g coperativeai
cd my-project
coperativeai init

That puts the project brief, the blank forms, QA's regression suite and sign-off sheet, the ten commands and the checks into the folder you run it in — on Windows, macOS or Linux, with nothing to build. It never overwrites: a file that already exists is left alone and named in the report. Add --dry-run to see it first.

Keeping a project up to date. After npm update -g coperativeai, run coperativeai update in the project:

• Framework files nobody changed are replaced.
• Files you edited are kept, with the new version beside them as <file>.update to compare.
• Your answers (the briefs, AGENTS.md, QA's suite and sign-off) are never touched.

It tells the difference from .coperativeai.json, a record of what was installed (commit it). A project made before that record existed is recognised from every version the framework has ever shipped.

Looking for the desktop app? Swarm is built with this framework and lives in its own repository, with its installers and build steps. The framework itself needs no binary at all — INSTALL.md — and runs wherever Claude Code runs.

New here? HOW-TO-USE.md is the practical, start-to-finish walkthrough — filling in a brief, translating it, building, and iterating. It uses ten Claude Code slash commands. Other agents can follow the same steps by reading the command files in .claude/commands/, which are plain Markdown:

• /draft [folder] — for a codebase that already exists: fill the brief in from the code, sourced and marked, with a few multiple-choice questions at the end instead of a blank form. The AI's answers stay the AI's until you accept them.
• /translate <brief> — turn a filled-in brief into a structured spec + skills.
• /new-item <type> <solution> <name> — copy a blank page/endpoint/model form into a solution folder.
• /build <spec> — build the next iteration of an approved spec, then report back and log debt.
• /verify <spec>: a second opinion after a build, ideally from a fresh session or another model. Each acceptance check gets a verdict (proves, weak, missing, failing) citing a file and line. It reports and never fixes.
• /debt [project]: walk a person through the debt builds declared. For each: pay it down next as a change round, accept it with a reason, or leave it. It drafts the decision into the brief for them to accept, and never decides or signs.
• /pipeline <solution> — create the solution's CI/CD pipeline and missing infrastructure from its spec, as its own approved plan. Secret values are never written into code — they're referenced by name from stores you control.
• /emit-guardrails [targets] — write the project's rules out in other agents' native formats (AGENTS.md, CLAUDE.md, Kiro steering, Cursor rules) from the same spec. One brief, every agent's guardrails — see below.
• /product [idea or brief]: plan an idea with Product. A few multiple-choice questions, then Parts 1–2 of a page brief in Product's words, marked drafted until Product accepts and signs. The AI never signs.
• /qa [automate|script|run]: help QA, only when QA asks. Writes the automation and manual scripts QA asked for, or runs the regression suite. It never fixes a failure and never signs off; see QA sign-off.