The Playbook

How to build software with AI agents — and stay in control.

This is the operational field manual for the H1VE method. The manifesto says what we value; the principles say how we act; this playbook says exactly how to do the work — role by role, gate by gate.

Version: 1.0
Audience: Anyone running or joining an AI-assisted team.

Introduction

AI has made generating code nearly free. The cost didn't disappear — it moved. Code now arrives faster than any team can read, review, and trust it, and that gap is where risk accumulates.

H1VE closes the gap by putting human judgment at the points that matter. Humans and AI Agents · 1 Team — the agents produce, the humans decide, and every decision leaves a trace.

When to use H1VE

Multiple developers work in parallel, each with an AI agent
A silent bug in production is expensive
Someone must answer “who decided this, and why?”
The team is scaling and improvised coordination is breaking

When not to use it

A throwaway one-person prototype no one will maintain
A one-off script with no need for review
A team that doesn't use AI agents

The core idea

The AI proposes; the human decides. Every gate in this playbook is a place where that decision is made explicit and owned by a person.

The roles

H1VE defines five human roles the AI assists but never holds. On a small team one person may wear several hats — but the responsibilities never merge. A reviewer never validates their own work alone.

Founder

Owns the why

Sets the vision, scope, and priorities. Creates and assigns features, approves specs, and watches the health of the system.

May: Approve specs, set appetite, create features, view everything.
May not: Merge to main, or sign off as QA/Data on their own feature.

Architect

Owns the how

Owns the technical foundation and the final merge. Reviews the whole picture before code reaches main.

May: Approve specs and DONEs, review, and merge to main — exclusively.
May not: Skip the gates or merge without CI green and both sign-offs.

Dev

Builds with the agent

Turns an approved spec into code with the AI, only within scope, and moves the work to PR with an honest AI declaration.

May: Build their features, move dev → PR, log blockers.
May not: Code without an approved spec, or merge their own work.

Validates that it works

Independently checks that the feature does what the spec says. One half of the double gate.

May: Sign off (or reject) features in qa_data on functional grounds.
May not: Validate a feature they built themselves.

Data

Validates the integrity

Independently checks schema soundness and data integrity. The other half of the double gate.

May: Sign off (or reject) features in qa_data on data grounds.
May not: Validate a feature they built themselves.

Humans and agents

The agent drafts, generates, and proposes across every role. But the signature — the approval, the sign-off, the merge — is always human.

The work cycle

Work flows through a defined sequence. Nothing skips a step, and the board shows where everything is in real time. The cycle has two parts: a one-time foundation, then a feature loop that repeats.

The foundation (once, at the start)

Before the first line of code, the project has to exist on paper. The founder and architect, assisted by the AI, produce four documents: vision & scope, functional spec, technical spec, and the roadmap. They are the cake; every spec that follows is a slice.

Why this matters

Skipping the foundation is the most common failure. The team codes fast but without a shared north — the AI invents decisions, two devs contradict each other. The foundation costs days and saves weeks.

The feature loop (repeats per slice)

Each feature moves through nine stages, and can be parked as blocked from any of them.

Backlog
Spec
Dev + AI
Pull Request
CI
QA + Data
Architect
Main

Backlog → Spec — A feature is born, then defined. No code is written until a human approves the spec.
Spec → Dev + AI — The dev builds with the agent, strictly within the approved scope.
Dev + AI → Pull Request — Work is submitted with an honest AI declaration of what the agent generated.
Pull Request → CI — The machine checks the mechanics — types, lint, tests.
CI → QA + Data — Two independent humans validate two kinds of risk; both must sign off.
QA + Data → Architect — With both sign-offs, the feature moves to the final human gate.
Architect → Main — The architect reviews the whole picture and performs the merge — the only one who can.
Any stage → blocked — A feature can be parked as blocked from any stage, with the reason logged, without breaking the flow.

A note on ownership

A feature can sit in the backlog without an owner, but it can't enter development without one. Assigning an owner is a precondition for work — control by design.

The artifacts

H1VE runs on a small set of living documents. Each has a job, a moment, and an owner.

The foundation documents

Vision & Scope: Why the product exists, for whom, and its limits. Led by the founder.
Functional Spec: What the product does, from the user's view. Founder + architect.
Technical Spec: How it's built: stack, data model, APIs, decisions. Led by the architect.
Roadmap: The scope sliced into phases. Each item becomes a spec. A living document.

The per-feature documents

SPEC-NNN: Created and approved before any code. Defines scope, files touched, acceptance criteria, risks.
DONE-NNN: Created at the end, before the PR. What changed, how to test, the AI declaration.

The memory document

CLAUDE.md: The project's living memory: stack, non-negotiable rules, critical files, current state. Read before each session, updated after.

The AI declaration

Every PR records which files the AI generated and how much each was reviewed. It's not bureaucracy — it tells the reviewer where to focus and makes the whole system auditable.

The gates

The gates are where human judgment enters and where quality is enforced, not hoped for. There are three, in sequence.

Gate 1

CI — automated

The machine checks the machine: type-checking, lint, the test suite. Objective and fast. A failure sends the feature back to the dev. Necessary but not sufficient — it catches what is mechanically wrong, not what is wrong in judgment.

Gate 2

QA and Data — the double gate

The signature of H1VE. Two independent humans, validating two kinds of risk, neither of them the author of the code. The feature only advances when both sign off — then it moves to the architect automatically.

QA asks: does it do what the spec says?
Data asks: is the schema sound?

Why two gates, not one

The AI fails one way in logic and another in data. Code can be functionally correct and still corrupt the schema silently. One reviewer misses one of the two; two independent gates catch both.

Gate 3

The architect — the merge

The final human gate. The architect reviews the whole picture — CI green, both sign-offs, the DONE written — and merges to main. That authority is exclusive. The AI never merges.

The metrics

H1VE measures the health of the system, not the busyness of people.

CI pass rate: Fraction of CI runs that pass. Below ~80% signals a systemic problem — stop adding features until you know why.
Cycle time: How long a feature takes from spec to main. Rising means a bottleneck — often the architect's queue.
Gate health: How often features are rejected at QA or Data, and why. A pattern points to weak specs or AI errors slipping through.
Blocker age: How long blockers stay open. More than a few days calls for direct intervention.
Architect queue: Features waiting on the final gate. A growing queue means the merge is the bottleneck.

Measure the system

These describe the flow, not the people. Velocity that hides a broken gate is worse than slowness that keeps quality.

Anti-patterns

Knowing what to avoid is as valuable as knowing what to do. These are the failure modes H1VE exists to prevent.

Anti-pattern

Coding without a spec

“It’s a small change, I’ll just do it.” Small changes with no scope are how features sprawl and reviews lose their anchor.

Do instead: No code without an approved spec — however small the slice.

Anti-pattern

Letting the AI merge

The agent is fast and confident, so it is tempting to let it close the loop end to end.

Do instead: The merge is exclusively human. The AI proposes; the architect merges.

Anti-pattern

Skipping the foundation

Jumping straight to features feels productive but leaves the team without a shared north.

Do instead: Write the four foundation documents first. The foundation is done once.

Anti-pattern

One reviewer for everything

A single person approving spec, code, and data collapses the independence the gates depend on.

Do instead: Keep QA and Data independent — and never the author of the work.

Anti-pattern

Trusting a blank AI declaration

An empty or hand-waved declaration hides where the risk actually is.

Do instead: Require an honest, file-level AI declaration on every PR.

Anti-pattern

Velocity as the only metric

Optimizing for speed alone rewards skipping gates and accumulates silent debt.

Do instead: Measure the system's health — pass rate, gate health, blocker age — not just throughput.

Glossary

The shared vocabulary of H1VE. A common language is what turns a practice into a profession.

Gate: A checkpoint where work must be validated before it advances. H1VE has three: CI, the QA+Data double gate, and the architect's merge.
Double gate: The mechanism that defines the method: QA and Data validating independently, both required to advance.
Spec (SPEC-NNN): The approved definition of a unit of work, written and approved before any code.
Done (DONE-NNN): The closing record of a feature: what changed, how to test, what the AI generated.
AI declaration: The per-PR record of which files the AI generated and how much each was reviewed.
Appetite: The time a team is willing to spend on a feature. Scope flexes to the appetite, not the other way around.
Swim lane: The visual board of nine stages showing where every feature is in real time.
Stage: A position in the cycle: backlog, spec, dev, PR, CI, QA+Data, architect, main, or blocked.
Foundation: The four documents that define a project before the first spec.
CLAUDE.md: A project's living memory, read before each session and updated after.
Reference implementation: A tool that implements the H1VE method. The method is tool-neutral; an implementation makes it operable.

The H1VE Playbook · v1.0 · H1VE.org