Implementation tutorial / Portable build

Build the control plane before the team.

Your first success is not twelve agents. It is one feature that can move from command to engineer to independent review, fail, and resume without hidden conversation state.

Build ordercontracts → scanner → coordinator → one loop → full team

Start with the vertical slice

00 / The operating split

Decide who is allowed to decide.

Reliability comes from assigning every responsibility to the right kind of system. If an agent is enforcing sequence or code is interpreting product intent, the boundary has already drifted.

Deterministic code

Enforces mechanics

Parse modes and arguments
Allocate numbers and paths
Scan for required artifacts
Wait at review barriers
Calculate rounds and routes

Same state → same next step

Probabilistic AI

Exercises judgment

Interview and clarify intent
Interpret the codebase
Choose an implementation
Evaluate quality through one lens
Explain evidence and tradeoffs

Bounded context → reasoned artifact

Human authority

Owns irreversible choices

Approve scope and intent
Resolve repeated failure
Accept policy changes
Review the pull request
Merge—or decline to merge

Agents propose · humans govern

01 / Smallest working slice

Prove one complete retry before adding roles.

The narrow slice exercises every hard architectural problem: entrance, coordination, mutation, independent evaluation, a deterministic verdict, and append-only recovery.

01 · Main conversation

Command

Normalize a feature request and adopt the coordinator.

/feature "Add sync status"

02 · Control plane

Coordinator

Assign paths, launch work, validate outputs, and route.

scan → run → require

03 · Subagent

Engineer

Read a brief, change code, test it, and report evidence.

001.02-eng-*.md

04 · Fresh subagent

Reviewer

Inspect code and report PASS, NOTES, or NEEDS WORK.

001.03-cr-*.md

PASS / PASS WITH NOTESWrite summary → open pull request → human reviews

NEEDS WORKAppend engineer round 2 → append review round 2

Proof gate

Delete the conversation, invoke resume, and reach the same next step from files alone. Until that works, you have a prompt chain—not a system.

02 / Build sequence

Earn each layer with a proof.

Select a maturity level. The sequence stays cumulative: later capability never substitutes for an earlier invariant.

01
Protocol
Name the state before writing prompts.
Define feature directories, filename grammar, allowed verdicts, round math, and completion conditions.
Proof
A path can tell you feature, order, owner, and round.
02
Scanner
Derive state from durable evidence.
List artifacts, find the first missing contract, reconstruct sequence, and detect incomplete review sets.
Proof
Fresh process + same directory = same state.
03
Coordinator
Implement routing as a state machine.
Parse full, brief-first, and resume modes. Launch only the owner of the next missing output.
Proof
No prompt can skip a prerequisite.
04
Vertical slice
Add one engineer and one reviewer.
Require the engineer report before review. Route NEEDS WORK back with the whole evidence set.
Proof
A failed review produces an append-only second round.
05
Definition
Add discovery, architecture, and design.
Give each role one output and only the policies it needs. Keep interactive discovery in the main conversation.
Proof
Every handoff can be inspected without transcript history.
06
Independent gates
Expand to four parallel reviewers.
Code, security, performance, and fidelity run with fresh context. The barrier waits for all four.
Proof
One NEEDS WORK blocks the combined verdict.
07
Isolation
Move mutable work into a worktree.
Commit discovery to main, create one feature branch, and keep review history beside the implementation.
Proof
A concurrent feature cannot disturb this checkout.
08
Compounding
Add evidence, backlog, and governed learning.
Log decisions centrally, sweep adjacent scope into GitHub once, rank it against ICP, and let analysts propose—never silently apply—policy changes.
Proof
A human can trace why a rule should change.

03 / Repository scaffold

Give every responsibility an address.

This is a portable starting structure. The directory names may change; the ownership boundaries should not.

your-project/

commands/
  feature.md             # parse + route only
agents/
  orchestrator.md        # state-machine contract
  discovery.md           # interactive requirements
  engineer.md            # implementation judgment
  code-review.md         # independent gate
skills/
  language-principles/
    SKILL.md              # ecosystem doctrine
  artifact-format/
    SKILL.md              # output schema
orchestrator/
  scan                    # deterministic state scan
  validate                # path + verdict checks
docs/
  briefs/                 # append-only execution trace
  icp/                    # definition of customer value
                           # scope ideas route to your issue tracker, labeled — not a local file
db/agent_log.sqlite3      # shared decision evidence
test/orchestrator/        # state-machine contract tests

Commands

Stable entrance

Argument grammar and routing. They do not plan or implement.

Agents

Bounded judgment

One identity, approved inputs, allowed tools, and one defined output.

Skills

Reusable policy

Load domain doctrine where it changes decisions—not into every context.

Orchestrator code

Executable mechanics

Scanning and validation belong in code even when Markdown describes them.

04 / Contract tests

Test the workflow like a protocol.

The model may vary its reasoning. These invariants may not vary at all.

Invariant	Given	Expected
Exact output address	Engineer completes without its report	Stop; do not launch review
Prerequisite order	Design spec is missing	Engineering cannot start
Parallel barrier	Three of four review files exist	Wait; do not calculate verdict
Combined verdict	Any report says NEEDS WORK	Route to engineer with all reports
Round arithmetic	Round 1 begins at sequence 04	Round 2 engineer begins at 09
Append-only history	A repair round begins	Prior reports remain untouched
Resumability	Process restarts after architecture	Resume at first missing design spec
Workspace boundary	Subagent runs in worktree	Writes only allowed feature state
Shared evidence	Worktree logs a decision	Use main checkout’s database path
Human governance	All reviewers pass	Open PR; never self-merge

05 / Starter control plane

Write this before the eleventh agent.

The scanner is the source of truth. Each worker receives explicit inputs and an expected output. The loop cannot advance on a persuasive narrative alone.

Compare with the Rails orchestrator

control-plane.pseudoMinimum viable system

feature = parse(invocation)
state   = scan(feature.directory)

until state.complete?
  stage = first_missing_contract(state)

  result = run_worker(
    owner: stage.owner,
    inputs: stage.required_inputs,
    expected_output: stage.output_path
  )

  require_file(stage.output_path)

  if stage.review? && result.needs_work?
    append_next_round(feature, evidence: all_reviews)
  end

  state = scan(feature.directory)
end

open_pull_request(feature)  # human owns merge

06 / Resist premature organization

Do not build these yet.

Each item is useful eventually. None proves that your core system can hand off, fail safely, or resume.

Wait

Dashboard

Files and a clear CLI are enough until operators cannot diagnose state.

Wait

Vector memory

Start with inspectable artifacts and explicit context selection.

Wait

Dynamic agent registry

A small static route table makes ownership legible.

Wait

Autonomous skill mutation

Learning should produce a proposal with evidence and human approval.

Wait

Twelve roles

Add a specialist only when an independent decision boundary exists.

Wait

Custom orchestration framework

Use files, git, a small scanner, and the host agent runtime first.

07 / Definition of built

Your team is ready for its next role when…

A new feature receives a deterministic number and directory.
Every stage has declared inputs, one output address, and a stop condition.
A missing artifact prevents the next launch.
A failed review creates a new round without erasing the old one.
A fresh conversation resumes from the first missing contract.
The worker runs in an isolated workspace with a shared evidence path.
Passing gates open a pull request but never merge it.

That is the reusable asset: not a set of prompts, but an execution protocol another language can inhabit.

Build the control plane before the team.

Decide who is allowed to decide.

Enforces mechanics

Exercises judgment

Owns irreversible choices

Prove one complete retry before adding roles.

Command

Coordinator

Engineer

Reviewer

Earn each layer with a proof.

Name the state before writing prompts.

Derive state from durable evidence.

Implement routing as a state machine.

Add one engineer and one reviewer.

Add discovery, architecture, and design.

Expand to four parallel reviewers.

Move mutable work into a worktree.

Add evidence, backlog, and governed learning.

Give every responsibility an address.

Stable entrance

Bounded judgment

Reusable policy

Executable mechanics

Test the workflow like a protocol.

Write this before the eleventh agent.

Do not build these yet.

Dashboard

Vector memory

Dynamic agent registry

Autonomous skill mutation

Twelve roles

Custom orchestration framework

Your team is ready for its next role when…