reference-architecture.md

Reference Architecture

Layering

1. Model and tool SDKs provide transport, streaming, and raw tool-calling primitives.
2. The coding-agent runtime layer provides task lifecycle, turn execution, failure handling, completion semantics, state transitions, and delegation contracts.
3. Policies, hooks, skills, and commands extend behavior without redefining runtime invariants.
4. Product shells and domain-specific agents shape UX, branding, and context-specific rules.

Control Flow

1. User creates or resumes a task.
2. Runtime assembles execution context.
3. Model produces tool calls, text, or a completion attempt.
4. Runtime executes tools and emits journal events.
5. Policy layer may intercept execution or stopping.
6. Runtime updates state and either continues, blocks on required action, compacts, or completes.

Architectural Claim

The runtime layer should be narrow enough to embed inside a larger orchestrator, yet opinionated enough to prevent each coding agent from rediscovering the same semantics independently.