Architecture

Architecture

The authoritative design is docs/ARCHITECTURE.md: state schema, agent contracts, generated Mermaid diagrams of every compiled graph, the numbered assumptions and open questions. This page is the short tour.

Five layers

Layer	Responsibility	Where
Prompt	Versioned, static role templates (v1.md) with typed Pydantic outputs, validated locally and repaired at most twice	scio/prompt/
Context	Just-in-time projections of state per role, artifacts passed by reference, compaction	scio/context/
Harness	Provider adapters (Anthropic, OpenAI, Fake), retries, budgets in tokens and dollars, prompt caching, OpenTelemetry tracing, cost ledger	scio/harness/
Loop	Bounded act, verify, fix loops with explicit exits: iterations, stalls, tool calls, budget, escalation caps	scio/loop/
Graph	Checkpointed LangGraph state graphs: the task graph (T0, T1, T2) and the product graph	scio/graph/, scio/product/

Supporting packages: scio/aci/ (the five agent tools and the sandbox backends), scio/toolchain/ (stack profiles, see Toolchain Profiles), scio/state/ (models, error signatures, progress fingerprints).

Roles and models

Roles are names; models are configuration (configs/models.yaml). Opus 5.5 is the router's expensive sibling: it plans, advises, gates and, in product mode, interviews and writes the spec. Sonnet 5 is the worker: coder, tester, debugger, reviewer, documenter, explorer. Haiku routes and compacts. Every role sets its effort explicitly.

The task graph

intake -> route -> prepare_repo -> { T0: t0_loop <-> verify | T1/T2: plan -> post_plan -> localize -> implement -> verify }
verify -> { checkpoint | triage -> debug -> verify | triage -> advise -> implement | plan | halt }
git_checkpoint -> { implement (next step) | review -> document -> gate -> pr_ready -> merge_wait (human) }

• Router (Haiku) classifies into T0 (one short edit loop), T1 (plan, a few files, tests) or T2 (explore first, then plan). An eval task or the CLI can pin the tier.
• Verify is ground truth in a fixed order: changes exist, the feature tests exist and pass, the whole suite passes, lint is clean. A failing check overrides any model verdict.
• Triage is a pure function stored in state and read by the edge: six signals (repeated error signature, stall, low confidence or design question, plan drift, sampled disagreement, high-impact diff) can escalate to the advisor; lint-only failures and clear first failures go to the debugger. One advisor call per step, three per T1 run, six per T2.
• Advisor review of passing high-impact diffs (ADR 0008): a diff that removes a public symbol, touches dependency or schema files, or spans more than eight files gets one Opus review before commit even when every check is green.
• Checkpoint and resume: every side effect (clone, commit, push, PR) runs under an effect log with a world probe, so a crash mid-run resumes with zero duplicated side effects (tests/durability/test_crash_resume.py).
• One writer: explorers run in parallel with read-only tools; every edit happens in a coder, debugger or documenter toolbox, asserted from trace spans.

The product graph (M7)

interview (human answers) -> specify (human approves PRODUCT.md) -> bootstrap -> [publish (human confirms)] -> done

Separate state (ProductState), the same checkpointer and effect log, its own thread ids. The bootstrap is three idempotent effects (git init, scaffold, marker commit) with the profile's lint and tests run as ground truth in between. See Product Mode and ADR 0010.

Budgets and caps

configs/budgets.yaml: per tier, tokens (billable-equivalent, cache reads counted at a tenth), dollars, advisor calls, iterations and stalls. Escalation thresholds (repeat_threshold = 3, max_stall = 2, high_impact_files = 8) were set from a recorded tuning sweep (ADR 0006) and the coupling max_stall >= repeat_threshold - 1 is enforced in code.