A harness engineering framework for agent-first software development. Not a wrapper around existing tools. A purpose-built development OS where specialized agents implement, test, and document work under a structured execution protocol - with shared context, machine-verifiable acceptance criteria, and low-friction handoffs that let one engineer drive multi-agent workflows without losing state.
"When something failed, the fix was almost never 'try harder.' The fix was: what capability is missing, and how do we make it legible and enforceable for the agent?"
Ryan Lopopolo, "Harness engineering: leveraging Codex in an agent-first world," OpenAI · Feb 2026The work I keep for myself is the ADR (architecture decision record): pressure-testing the design one-on-one with the architect agent until the shape of the work is right. The architect files the tickets from the finalized decision - scoped, prioritized, and auto-assigned.
The sign-offs I keep - ADR approval, promotion out of Intake - are a hand on the wheel by choice, not steps the machinery requires: the steward agent promotes what it files, the repair loop promotes its own, and the system runs the same when I step back. What the hand buys is priority steering across a hundred-plus-ticket backlog.
The formal one: the evaluator finds a defect, files the ticket, and the repair loop promotes and completes it - no human touches it. Organic ones run alongside: the steward spots a backlog pattern, pulls the data, and messages the architect to write the ADR and file the tickets; simpler fixes are filed directly or routed to the debugger; the steward also files tickets to automate work it notices itself doing by hand. Lessons feed back into each role's working memory, so a lesson doesn't have to be learned twice. That's the shift that matters: removing the human from every step where a human was never the bottleneck.
create is architecturally different. The backlog is a live state machine with transactional guarantees. A ticket promoted to ready is picked up automatically: the system writes the agent-scoped prompt, launches the session, and dispatches by priority with no clipboard and no paste. Each agent registers its session, claims work, executes under a structured SOP, runs RED→GREEN→REFACTOR, and submits for review through a single HTTP API. Shared scratchpads carry context across sessions, ISC (Ideal State Criteria) tables make "done" binary, and structured reflection captures what the next agent needs.
AI-assisted: AI tools are used inside an existing process. Efficiency improves 10–20%. The loop is still human-driven, the context is rebuilt every prompt, and "done" is subjective.
create / AI-first: Processes are redesigned around agents as the primary builders. The framework handles dispatch, context continuity, structured handoffs between specialists, and machine-verifiable quality gates - end to end, with zero manual copy-paste. Humans provide direction and architectural judgment. The gain is multiplicative, and it compounds because the system, scratchpads, and memory get better over time.
Agents don't assist the developer - they are the primary builders. create is designed from the ground up to make agents' work legible, bounded, and enforceable. Every component - the session protocol, the backlog schema, the SOP library, the work packages - exists to maximize what agents can reliably do, with the human reserved for direction-setting and cross-ticket judgment.
A single engineer can run multiple agents in parallel across unrelated concerns. Within a single ticket, structured phase boundaries let one specialist hand off to the next without context loss: a production five-phase migration ran Agent A → Agent B → Agent A → Agent C → Agent A without a restart. Work that would serialize a solo engineer runs concurrently.
All implementation work is test-driven: RED → GREEN → REFACTOR is a mechanical rule enforced by the verification gate, not a guideline. Machine-verifiable acceptance criteria (ISC format) make pass/fail binary. The evaluator auto-resolves routine reviews. No work reaches "done" without passing automated validation.
Agent sessions generate structured scratchpads that persist across context limits. The remember substrate - the agent-memory store agents read at session start - means agents start sessions knowing what the fleet has already learned. Knowledge compounds across every session, every agent, every project.
create is one half of a pair of products that share a single seam. create is where the work happens; remember is the memory that persists across it. They speak one protocol - SLF (Substrate · Lens · Frame) - over a single interface: create reads context and writes captures to remember through render(substrate, lens, frame) → receipt, and every access leaves a signed receipt you can audit. The two are being split into separate codebases whose only shared code is SLF.
The receipt-and-grant enforcement across that seam is designed; the memory it runs on is live today.
Every backlog item moves through five stages with automated transitions. Agents claim work, the system tracks conflicts, and the human sees a real-time view of what every agent is doing and why.
Every backlog item in the ready state includes a table of Ideal State Criteria - binary, pass/fail conditions with explicit verification methods. No "it should work" or subjective sign-offs.
| # | Criterion | Verified how | |---|-----------------------------------|----------------------| AC1 Migrations 029–038 applied cleanly alembic current == head AC2 All 6 new models importable pytest -k test_models AC3 Rollback to 028 succeeds alembic downgrade -1
All state changes go through a single HTTP API server. No UI required. Agents make REST calls; the dashboard reflects state in real time via WebSocket. The API has atomic writes, 10-retry exponential backoff, and file-lock conflict detection.
curl -X PATCH http://localhost:5176/api/backlog/PCC-1846 \ -H "Content-Type: application/json" \ -d '{ "status": "in_progress", "assignedAgent": "bob" }'
The dashboard reads as a kanban board, and a fair first reaction is that boards with AI attached are everywhere right now. The board is only the rendering. Underneath it, the backlog is a finite state machine (a fixed set of statuses and a fixed set of legal moves between them), and the properties that make the numbers on this page possible live in that layer, not in the UI.
The complete transition behavior of the system is one data structure. Every status names the statuses it may legally reach, and a request for any move not on the list is refused with a 422 (the HTTP code for a request the server understood and rejected) before any work happens. Every writer goes through the same validator - the API, the daemons, and the dispatch scripts alike - and the test suite walks every status pair, so an illegal move that somehow appeared would fail the build before it could fail in production.
const VALID_TRANSITIONS = { intake: ["ready", "cancelled"], ready: ["in_progress", "blocked", "review", ...], in_progress: ["review", "blocked", "ready", ...], review: ["done", "in_progress", ...], blocked: ["ready", "in_progress", ...], };
A language model's output is nondeterministic, so nothing a model says is allowed to drive a status change directly. An agent claiming its work is finished is only an event, and the event lands only if the table has an edge for it. For the finishing move it does not: the transition to done is reserved to the review processor, after the gates have run, and a human override is an explicit, recorded flag rather than a loophole. An agent that tries anyway gets a refusal, not a merge.
"Status transition in_progress → done is not permitted
via HTTP API. Only the review-processor may finalize
tickets. Submit for review with status=review, or pass
humanOverride=true for manual dashboard approval."
The seven review gates are parallel regions in the statechart sense (Harel's 1987 extension of state machines): each holds its own pass or fail, and a ticket closes only when every region agrees. Most gates are deterministic code - lint, tests, scope checks. The judgment gates run as separate reviewer agents: the builder never grades its own work.
Recorded state can drift from reality - a process dies holding a claim, and no exit handler runs. A reconciliation layer re-derives the truth by observation: session liveness from heartbeat freshness, stale claims released automatically, a post-merge watchdog comparing the running build against the repository head. The schema refuses illegal moves; drift it cannot see is corrected by observation.
This is the loop every create ticket runs through. The orchestration is structured by the create backbone and its dashboard, not by a single autonomous agent: tickets carry their own acceptance criteria, prompt templates, and agent assignments; the dashboard generates the agent-scoped prompt on each status transition and launches the session directly. Everything from promotion onward runs unattended: prompt generation, priority-ordered dispatch, session launch, review, and close.
Every ticket runs the same six phases - from a planning agent's decomposition all the way to an automated review gate's auto-close. The dashboard owns dispatch and gating; specialists own execution; the operator sequences the backlog and reviews at decision points.
A planning agent (Alex for architecture, Bea for product requirements) reads the goal and produces a structured plan. The plan is filed as one or more create tickets via the API - each with a scoped AC table, an assignment to the right specialist (builder, test architect, refactorer), and the prompt template appropriate to that specialist's SOP.
Tickets arrive in intake already well-formed - scoped, prioritized, and assigned, with automated readiness validation confirming AC quality and checking for collisions with in-flight work. Tickets in ready are dispatchable; tickets in intake are not. Promotion is where relative priority is steered - by policy, or by an operator's hand when they want one. Nothing mechanical requires a human here.
Once a ticket is ready, the system dispatches it automatically - no operator action. It composes an agent-scoped prompt from the ticket's AC, file references, prompt template, and constraints, then launches the session directly. Dispatch is priority-ordered and interleaves medium and low work so nothing goes stale. No clipboard, no paste, no manual prompt engineering.
Agent: bob Ticket: PCC-2327 - Migrate create to better-sqlite3 Context: [Files, prior scratchpad, related ADR] AC: ISC table - binary pass/fail rows Constraints: TDD required, do not touch migration 028 Lifecycle: /session bob PCC-2327
The agent registers its session via the /session lifecycle (POST /api/sessions), claims the ticket (PATCH backlog → in_progress), creates a scratchpad from template, executes under the relevant SOP and TDD protocol, runs verification, and submits for review (PATCH → review). Because the prompt staged by Launch already carries full context, the agent never has to ask "what's the goal" or "which files matter."
Submission to review triggers a multi-stage gate that runs without operator intervention: ESLint (TypeScript), Ruff (Python), Cargo (Rust), 2,000+ Jest/Cargo/Ruff tests across the fleet, Evelyn's eval (machine-verifiable AC check, validated end to end), Quinn (code review SOP), Sentinel (security review where applicable), and Stewart's pre-commit gate - seven independent gates in all. Every gate is binary and audit-logged.
Pass: the ticket auto-closes to done. The operator is notified but does not click anything. Fail: the ticket flips back to in_progress and the dispatcher automatically relaunches the same agent session with a structured fix-it prompt that names the failed gate (which ISC row, which lint rule, which test) and the specific correction needed - up to a capped number of retries before it escalates to a human. No restart, no manual paste.
When a review gate fails, the answer is never "try rephrasing the prompt." The create dashboard composes a structured Relaunch prompt that names the failed gate (which ISC row, which lint rule, which test, which review note), states the specific correction needed, re-attaches the original context, and relaunches the same agent session automatically. This is structured error correction - a rule-based recovery loop with an ISC-anchored bar, not vibes - and it is what makes the framework converge instead of spin.
create doesn't have a single "AI assistant." It has a network of specialized agents, each with their own SKILL.md that defines triggers, guardrails, sub-skills, and output formats. Routing is automatic - the right agent activates based on context keywords, not manual selection. And the skills aren't frozen: each one is continually evaluated and refined as the fleet learns what works, so the agents get sharper over time rather than drifting stale.
Skills don't require manual selection. Keywords in context trigger the right agent automatically: "requirements" → Bea · "architecture" / "ADR" → Alex · "debug" / "error" → Doug · "test" / "coverage" → Tessa · "security" / "audit" → Sentinel · "review" → Quinn. Each SKILL.md defines its trigger set, output format, and what it must not do - the three components that make routing reliable rather than hopeful.
Governance in create is automation-first, not approval-first. Requiring human sign-off on every agent action would create the exact bottleneck create is designed to eliminate. Instead, the system evaluates completed work automatically against objective criteria - and only escalates when it genuinely can't make the call.
When an agent submits work, Evelyn runs immediately: acceptance criteria (ISC table), linting, regression tests. All checks are binary pass/fail - no subjective scoring. The full audit trail is persisted in SQLite and visible in the dashboard.
If all checks pass: the ticket is automatically marked done and the human is notified. If any check fails: the ticket is routed back to the responsible agent with the failure details. No human in the loop for either outcome.
When Evelyn can't determine pass/fail with confidence - genuinely ambiguous architectural decisions, novel failure patterns, out-of-bounds behavior - she escalates to the human with a structured evidence package. Human judgment is reserved for decisions that actually require it.
Global guardrails in .agent-data/guardrails/global.md define mechanical rules: never write to .env*, never run rm -rf, never push --force to main, never commit secrets. These aren't reminders. They're validated by automated test suites that run on every change. An agent that violates a guardrail rule fails the verification gate.
The guardrail set grows over time. As the system surfaces new failure modes, new rules are proposed - and once approved, they become enforced gates like the rest. Governance evolves rather than ossifies: the rulebook tightens around exactly the mistakes the fleet has actually made.
Three architectural constraints govern every component of create, enforced by architecture boundary tests rather than left as design preferences:
Today every agent is dispatched to the Claude CLI, and each ticket carries a recommended model. Dispatch runs through a provider adapter, so switching to another provider is a configuration change, not a rewrite. We can move tomorrow and not lose a beat.
When an agent submits work for review, Evelyn runs independently against the objective acceptance criteria. For work that clearly meets every AC row with test evidence: Evelyn auto-approves. For ambiguous cases: Evelyn escalates to human with a structured evidence package - what passed, what's uncertain, why it's being escalated. This reduces review load by 80%+ without sacrificing oversight.
The goal is not to remove humans from decisions - it's to ensure humans only make decisions that genuinely require judgment. Routine completions don't need human attention. Architectural risks do.
Every agent session generates a structured scratchpad at .agent-data/scratchpads/active/. The scratchpad tracks: the decomposition plan, the status of each sub-task, the Task Brief sent to each sub-agent, what the sub-agent returned, whether it met the AC, and the accumulating Synthesis. When an agent hits a context limit, it writes its state and stops cleanly. The next invocation reads the scratchpad, identifies the last completed sub-task, and resumes from there. No restart from zero. No duplicate work.
## Decomposition Plan | # | Sub-task | Agent | Status | | 1 | Implement model | Bob | ✅ Done | | 2 | Write tests | Tessa | 🔨 WIP | | 3 | Generate docs | Bea | ⏳ Wait | ## Sub-task 1: Result [What Bob returned] [AC evaluation: met ✅ / failed ❌] ## Synthesis [Accumulating unified deliverable]
When Stewart promotes a backlog item to ready, create auto-generates a Work Package - a curated handoff document that contains everything an agent needs to start immediately. Not a pointer to the ticket. A self-contained brief with the problem statement, acceptance criteria, file references, and quick-start commands. No "can you explain this?" back-and-forth.
Problem Statement: Clear description of what and why Acceptance Criteria: Binary ISC table - pass/fail only Files to Modify: Exact paths, what to change Quick-Start: Commands to verify env before writing Starter Context: Relevant code excerpts, not full files Constraints: What not to touch, hard limits
Work packages are the link between "human writes a ticket" and "agent starts work." They are the automated prompt engineering layer - structured context that makes agent output reliable rather than hopeful.
Every agent follows a mandatory sequence. Not as a recommendation - as a protocol enforced by the framework and audited by the session API.
# 1. Register - collision detection, session index curl -X POST localhost:5176/api/sessions -d '{"sessionId":"bob-pcc-1846-2026-04-13","agentName":"bob"}' # 2. Load context - scratchpad auto-created from template if new curl localhost:5176/api/sessions/bob-pcc-1846-2026-04-13/context?backlogId=PCC-1846 # 3. Claim - prevents double-assignment, marks in_progress curl -X PATCH localhost:5176/api/backlog/PCC-1846 -d '{"status":"in_progress","assignedAgent":"bob"}' # ... work happens ... scratchpad updated every 3-5 actions ... # 4. Submit - triggers Evelyn; never ask the human first curl -X PATCH localhost:5176/api/backlog/PCC-1846 -d '{"status":"review"}' # 5. End - session archived, reflection written curl -X DELETE localhost:5176/api/sessions/bob-pcc-1846-2026-04-13
All implementation work in create is test-driven. This is not a coding convention. It is a mechanical constraint enforced by the verification gate. Any PR or session submission that lacks a RED→GREEN→REFACTOR trace fails automatically before it reaches human review.
Tessa generates failing tests before Bob writes a line of implementation. Bob implements only enough to pass. Remy reviews the clean implementation for refactoring opportunities. The cycle is the process - not something bolted onto it afterwards.
npx jest \ --config jest.config.verification.js \ --runInBand \ --bail \ --passWithNoTests \ --forceExit # Covers: core API unit tests, hook validation, # steward guardrails, approval queue, skill triggers, # architecture boundary checks - 150+ suites in this # fast gate (2,000+ across the full fleet suite)
Stub implementations (throw new Error('Not implemented'), empty returns, TODO placeholders) are rejected by the verification gate in production files. If full implementation isn't possible in scope, a new backlog item is created - not a placeholder left in code.
create generates structured observability artifacts automatically. Not after-the-fact documentation - live signals produced as work happens.
Automated daily check reports capture backlog state, session activity, agent throughput, and test coverage metrics. Structured JSON + Markdown. Available at .agent-data/reports/daily-check-[date].json.
Every agent action is logged to .agent-data/events/event-log.yaml - which agent, which ticket, what action, timestamp. Full audit trail of everything the agent network has done.
Every review decision generates a structured evaluation result: what was checked, which AC rows passed, what evidence was cited, whether the decision was auto-resolved or escalated and why.
Completed scratchpads are archived to .agent-data/scratchpads/archive/YYYY-MM/. Every decision made during execution - what sub-tasks were decomposed, which sub-agents were spawned, what they returned - is preserved. Agent decisions are auditable, not ephemeral.
Every number below comes from the live ticket archive and git history, graded against Addy Osmani's agentic-autonomy framework. create lands as a real Level 5 system: managed by exception, not managed by hand.
10% of all throughput is defect-repair on the system's own output - filed, dispatched, and verified by the same pipeline that shipped the original change. Most agentic tooling can't claim this.
Under 8% of merged changes were later reverted, with zero lost work. Every agent works in an isolated, detached worktree; nothing lands on main without integration.
33% of all tickets receive automated review feedback and get caught and corrected before a human would ever have seen them - across 7 independent gates run by a separate grading process, not agent self-report.
Source: internal GTM grading against the live ticket archive, backlog API, and git history.
When agents do the building, the scarce skill is no longer writing the code. What's left is judgment: defining what good looks like, evaluating what the agents produce, and designing the system that makes them reliable. That is the work that compounds.
Because the building no longer requires hand-writing the code, the door opens to anyone who can define what good looks like and hold the work to it. And it raises the value of deep technical knowledge rather than retiring it: shaping the incoming requirements, the scope, the priorities, and the definition of done is architect's work, and it is what separates a system that produces the right thing from one that produces plausible output quickly.
Work runs sequentially, one task at a time. Context switches are expensive. Tests are deferred. Documentation follows (never). State lives in one head. When that person steps away, nothing moves.
Parallel agent sessions execute concurrently across unrelated concerns. Tests are generated before implementation. Documentation is produced alongside code. State is persistent and auditable. The system works whether or not anyone is at the keyboard.
What create unlocks isn't "AI writes my code." It's institutional execution capacity: the ability to run more work, in parallel, with higher confidence than any one person could sustain, and to get measurably better at it over time, because remember compounds what the agent network learns.
create is not a collection of prompts and a kanban board. It is a purpose-built engineering system designed to make agent-first development reliable, auditable, and continuously improving. Every component - the session protocol, the approval queue, the work packages, the automated Launch / Relaunch dispatch loop, the TDD enforcement, the scratchpad continuity - exists to answer one question: what capability is missing, and how do we make it legible to the agent?