One spec, followed from the words a user types into the UI to a tagged spec the execution loop can build.
It shows every agent step, every verify and eval gate, and every human decision. The artifacts it produces are the ones in examples/.
The target architecture in layers: UI, control, orchestration and execution, with evidence, observability and knowledge cutting across them. Dashed boxes are still being placed in Discussion #21.
Scroll sideways on narrow screens.
/answer RAF-1.pipeline.lock.yaml, which pins each action's model, prompt, skills and AGENTS.md.route: ddd). The loop engine and harness run the pi agent loop inside one action. Skills, tools and MCP servers are what the agent can call.domain/, PRs, artifact headers and trace.yaml. The engine keeps no state of its own.run_id.Read top to bottom. Each numbered arrow is one step. In the pi-agent lane, the purple tag names the agent acting at that point.
The diagram is 1,400 px wide. Scroll sideways on smaller screens.
The same steps in words, with the detail that doesn't fit on an arrow.
The user's words become intent.md, grounded in the org KB and checked against the constitution.
Types the raw intent
“Customers who cancel before we ship keep emailing support to get their money back… Support is drowning.”
New spec request
Branch spec/SPEC-0001/intent + template
The header pins constitution v3 and the AGENTS.md hash before any agent runs.
Start session (create)
kb_search: refund policy, provider refunds
refund-policy v4 · provider doc v7 · constitution v3
ask_user Q-1: what does “quickly” mean?
Relayed through the reconciler and the UI. The agent never guesses a number.
Refund must start within 1 hour
Writes intent.md · validate_artifact ✓
STK-1..3, GOAL-1 (must), GOAL-2 (should), NG-1, CON-1 citing kb:finance-refund-policy@4, SC-1/2, ASM-1, Q-1 answered.
spec-lint intent.md
Clean · no open Q (F6) · CON-1 cites KB (K2)
Intent rubric + ART-1
Pass 0.86
ddd-seed
Proposed terms → glossary
status in-review · PR 11 · ready-for-review
Approves intent
Re-verify · status approved · merge
Analysis finds gaps, DDD fixes the language and boundaries, and generation is verified, repaired, evaluated and revised.
Round 1
RAF-1..4 · RAF-4 boundary is a blocker
RAF-1 partial cancellation (human) · RAF-2 “money back” wording (ddd) · RAF-3 provider rejects refund (self) · RAF-4 which context decides (ddd, blocker).
spec-lint
Gate F1: blocker RAF-4 still open
ddd-strategic for RAF-2, RAF-4
Refund, Order Reference · Ordering → Payments map
Adds TERM-005 Refund (avoid: reimbursement, money back) and TERM-008 Order Reference. Declares the Ordering and Payments contexts and maps Ordering [OHS,PL] → Payments [ACL].
needs-input: RAF-1
/answer RAF-1: whole Order only
Round 2
No new findings · ART-2, ART-5 apply
Create (attempt 1)
requirements.md + trace links
spec-lint
L5 “quickly” · D5 “reimbursement” · L2 two “shall”
Errors are deterministic, so the same draft always fails the same way. The step is re-run in repair mode with the error list.
Repair (attempt 2) with error list
spec-lint
Clean
Rubric + ART-2, ART-5
ART-2: REQ-002 has no duplicate-trigger AC
The draft was lint-clean but broke a constitution article. Only a judgment check could catch this.
Revise with judge rationale
Adds AC-002.2 (no second Refund)
Re-verify + re-eval
Pass 0.91
PR 12 in-review · BA + architect (domain/ changed)
Approves domain changes
Approves requirements
Merge · glossary v2 on main
Design analysis raises risks for the architect, DDD adds the tactical model, and generation passes verify and eval first time.
Round 1
kb_get provider doc v7
Refund API limit: 20 per second
DAF-1 rate-limit risk · DAF-2 duplicates
DAF-1 nfr-risk goes to the architect with two options and a recommendation. DAF-2 is a gap the step resolves itself, citing const:ART-2.
needs-input: DAF-1 (2 options)
/answer DAF-1: durable refund queue
ddd-tactical
Orders, Refunds aggregates · cml_check ✓
Ordering v2: Order + OrderCancelled. Payments v2: Refund keyed by OrderReference, plus RefundIssued and RefundFailed.
Create
DES-1..4 · ADR-1 · realizes links
spec-lint
Clean · coverage C5–C8 · no boundary violation (D9)
DES-3 in Payments depends on DES-2 in Ordering. That is allowed only because the context map has Ordering → Payments.
Rubric + ART-2..5
Pass 0.88
PR 15 in-review
Approves design
Merge
A whole-spec verify on main, a ready tag, and the feedback path from execution back to eval.
Whole-spec verify on main
C1–C9 ✓ · no stale pins · metrics.json
Tag SPEC-0001/v1.1-ready
Execution loop feeds lagging signals back
plan → code → QA consumes only the tag and adds implements/tests links. Clarification requests, spec-rooted rework and escaped defects are attributed to IDs and flow into the eval sets.
What spec-lint recorded in metrics.json by the time the spec was tagged. The lagging signals from plan → code → QA are later checked against these.
| Metric | Value | What it says |
|---|---|---|
goal_coverage | 1.00 | the must-goal has requirements |
ears_rate | 5 / 5 | every REQ statement is valid EARS |
testable_ac_rate | 7 / 7 | every AC is Given/When/Then |
nfr_measurable_rate | 2 / 2 | every NFR has a number and unit |
findings | 4 RAF · 2 DAF | 1 blocker, 4 major, 1 minor |
human_questions | 3 | Q-1, RAF-1, DAF-1 |
repair_attempts | 1 | req-generation, lint errors |
eval_retries | 1 | req-generation, ART-2 |
realization_rate | 5 / 5 | every must REQ is realized by a DES |
boundary_violations | 0 | D9 |
back_edges | 0 | no requirement changes from design |
All of this is in the spec-contracts bundle and is generated from one model, so the page, the drawing and the diagrams can't drift apart.
docs/scenario/model.pyThe steps, lanes and phases. Edit this, then run build.py.docs/scenario/SPEC-0001-scenario.excalidrawThe swimlane as an editable Excalidraw drawing.docs/diagrams/*.mmdMermaid sequence diagrams per phase and in full. Paste them into Excalidraw's Mermaid import.docs/scenario-SPEC-0001.mdThis walkthrough as Markdown, for the repo.examples/Every artifact the scenario produces: intent, analyses, requirements, design, trace, glossary, CML and the constitution.