Framework / Architecture

How the Workflow Works

The workflow is a state machine where phases produce artifacts that chain forward. Loops self-heal, and gates enforce quality. This page covers the internals.

This is the spec, not the implementation. The state machine, artifact chaining, and loops below describe what your workflow should do. How you build it depends on your agent stack. The reference example is one approach.

State Machine

Workflow as a state machine

Every workflow run is a sequence of state transitions. The current state determines what happens next. Failures do not crash the workflow; they trigger transitions to retry or escalation states.

Workflow manifest

Each run maintains a manifest that tracks state, history, artifacts, and cost. The manifest is how the workflow remembers what happened across phases.

{
  "workflow_id": "run_2026-03-10_001",
  "state": "REVIEWING",
  "phase_history": [
    { "phase": "intent", "status": "complete", "iterations": 1 },
    { "phase": "plan", "status": "complete", "iterations": 1 },
    { "phase": "build", "status": "complete", "iterations": 1 },
    { "phase": "test", "status": "complete", "iterations": 2 }
  ],
  "artifacts": {
    "intent": "specs/intent-run_001.md",
    "plan": "specs/plan-run_001.md",
    "build": "specs/build-run_001.md",
    "test_results": "specs/test-run_001.json"
  },
  "total_retries": 1,
  "escalated": false
}

Artifacts

Artifact chaining

Agents are stateless; every invocation starts from scratch. Artifact chaining solves this. Each phase produces a structured output, and the next phase's prompt template gets populated with that output via template variables.

Phase	Produces	Variable	Consumed By
Intent (optional)	Intent spec	$intent_artifact	Plan
Plan	Implementation spec	$plan_artifact	Build
Build	Code changes + tests	$build_artifact	Test
Test	Results + coverage	$test_results	Review
Review	Verdict + issues	$review_artifact	Document, Deploy
Document	Docs + changelog	$doc_artifact	Deploy
Deploy	PR reference	$deploy_artifact	Monitor

How substitution works

When Build starts, the workflow replaces ${plan_artifact} in the Build template with the actual Plan output. The agent sees the resolved content, not the variable.

# build.md template (before substitution)
## Context
Plan: ${plan_artifact}

# What the agent actually receives:
## Context
Plan: Summary: Add GET /users endpoint
Files to modify: [src/routes.ts:45, src/controllers/user.ts]
Test strategy: Unit tests for controller, integration for route

Feedback Loops

Self-healing feedback loops

Two loop types handle two failure modes: Test Retry fixes broken code and Review-Patch fixes quality issues. Both exhaust their retries before escalating.

Test retry loop

Test phase runs all tests
Tests fail; analyze failure output
Spawn builder agent with failure context
Builder applies fix
Re-run tests
Pass --> continue. Fail --> repeat (max 3x)
Exhausted --> ESCALATE

# Loop config
loops:
  test_retry:
    max: 3
    on_exhaust: escalate

Review-patch loop

Review finds blocker-severity issues
Produce structured issue list
Spawn builder with review context
Builder applies patches
Re-run tests (patches must not break tests)
Re-submit to Review
Pass --> continue. Blockers --> repeat (max 3x)
Exhausted --> ESCALATE

# Loop config
loops:
  review_patch:
    max: 3
    on_exhaust: escalate

The key distinction: Test Retry fixes broken code (it doesn't work). Review-Patch fixes quality issues (it works but has problems). Both re-test after patching, and patches must never break tests.

Escalation

When the workflow needs a human

Escalation is a feature, not a failure. The workflow tried what it could and is handing you full context. You never start from zero.

What you get on escalation

Original task: the issue that started the workflow

Plan produced: the implementation spec

Code built: all changes made by the builder

Test results: all attempts, including retries

Review findings: all issues across iterations

Blocker summary: what specifically could not be resolved

Your options

Give guidance

point the agent in the right direction and resume from the current phase.

Override gate

accept the current output and let the workflow continue.

Update layer

modify a prompt or gate, then re-run the workflow.

Abort

stop the workflow. All artifacts are preserved.

Execution

Phase execution model

Sequential by default. Each phase must complete before the next begins. Parallelization is something you opt into after the basics work, not a starting point.

Phase skipping by issue type

Type	Intent	Plan	Build	Test	Review	Doc	Deploy
Feature	Recommended	Full	Full	Full	Full	Full	Full
Bug	Optional	Targeted	Targeted	Full	Full	Min	Full
Hotfix	Skip	Min	Targeted	Full	Min	Skip	Full
Docs-only	Skip	Skip	Skip	Skip	Full	Full	Full

Notice: Review always runs, even on hotfixes. You do not get to skip it.

Quality Gates

Pass/fail between phases

A phase cannot hand off to the next until its gate passes. Gates enforce the principles: TDD via coverage gates, quality via review gates, structure via PR gates. All thresholds are configurable.

Test coverage gate

gates:
  test:
    coverage_min: 80
    all_pass: true
    new_code_covered: true
    on_fail: trigger_test_retry
    on_exhaust: escalate

Review severity gate

gates:
  review:
    max_blockers: 0
    max_critical: 2
    tech_debt_logged: true
    on_fail: trigger_review_patch
    on_exhaust: escalate

Gates connect to loops: a failed gate triggers the matching feedback loop, and when the loop exhausts, the gate triggers escalation. This is how quality requirements connect to self-healing behavior. Learn more about self-healing loops

Full Example

A complete workflow run (illustrative)

"Add GET /users endpoint," through every state, artifact, gate check, and one retry.

INTENT (optional) PASS

Raw request: "Add GET /users endpoint with pagination and auth." Requirements Analyst researches the codebase, finds the existing route structure and cursor-based pagination in /orders. Produces intent spec with EARS user stories, acceptance criteria, and explicit scope (GET only, no create/update/delete).

PLANNING PASS

Architect agent reads the codebase. Produces a plan with file:line references, test strategy, and what's explicitly out of scope.

Files: src/routes.ts:45, src/controllers/user.ts
Tests: unit + integration for GET /users

BUILDING PASS

Engineer agent writes tests first, then implements the controller and route. Follows plan exactly.

Created: tests/user.test.ts (15 tests)
Modified: src/routes.ts, src/controllers/user.ts

TESTING FAIL

14 pass, 1 fails. Route handler returns 404 instead of 200 for valid request.

TEST_RETRY iteration 1

Builder agent receives failure context. Patches route handler to register the endpoint correctly.

TESTING PASS

All 15 tests pass. Coverage: 87%. Gate passes.

REVIEWING PASS

No blockers. 1 tech-debt item logged (input validation could be stricter). Gate: 0 blockers. Pass.

DOCUMENTING PASS

Writer generates docs from actual diffs. Changelog entry, API reference, architecture decision recorded.

DEPLOYING PASS

Atomic commits created. PR opened with plan reference, test evidence, review summary. Gate: structure valid.

COMPLETE

Workflow done. 1 retry, 7 steps (with 1 retry sub-step), all gates passed.

Phase executions (including retry)

Retries needed

Gates passed

Escalations

Overview

Principles

Get Started