Architecture

5 min readFor architects & contributorsUpdated 2026-05-19

What you'll learn

• The seven runtime layers Craik composes against.
• The flow a task moves through, from request to handoff.
• The patterns Craik borrows from adjacent runtimes — and what Craik adds on top.
• The core typed contracts that make the layers interchangeable.

Layered, separable, contract-bound.

Craik is organized as a set of runtime layers. The layers should remain separable so Craik can support different model providers, tool environments, and memory backends without weakening the product thesis.

Layers

1 · Gateway

Receives human and machine requests, normalizes them, creates runtime tasks. Owns CLI / API / UI entry points, auth context, project selection, the initial policy envelope, and event streaming.

2 · Project model

Builds the current working model for a task from repo state, issues/PRs, docs, ADRs, recent handoffs, Stigmem facts, CI artifacts, and user-provided instructions. Outputs the case file, constraints, relevant facts, stale-risk warnings, contradiction warnings, and verification plan.

3 · Orchestration

Decomposes work and coordinates agents — role selection, model routing, task decomposition, parallel execution, specialist assignment, review loops, interruption handling, stateful handoff creation. Coordinates work; does not own truth.

3a · Runner adapter

Thin boundary between Craik contracts and concrete agent environments. First-class adapters: Codex, Claude, Gemini. Adapters translate case files into runner-specific context, pass policy envelopes through, and translate runner-specific artifacts back into Craik contracts.

4 · Capability

Exposes tools under explicit policy: file reads/writes, shell commands, Git ops, GitHub ops, web search, package registries, CI inspection, memory reads/writes, plugin execution. Each capability is scoped, auditable, and revocable.

5 · Memory

Stores and retrieves durable state. Backends: ephemeral (tests), local SQLite (single-user), Stigmem (real team use). Depends on capabilities — facts, provenance, scopes, trust tiers, contradiction tracking, federation, retention — not specific feature assumptions.

6 · Work graph

Connects runtime objects. Nodes: tasks, agents, handoffs, facts, decisions, issues, PRs, branches, files, docs, ADRs, commands, tests, CI runs, generated artifacts. Edges: depends on, created by, verified by, contradicts, supersedes, implements, blocks.

7 · Experience

Operator surfaces — CLI, repository dashboard, task detail view, handoff viewer, contradiction inbox, work graph explorer, capability receipt log. The runtime's read surface.

Runtime flow

A task moves through the layers in a deterministic sequence.

1. A user or system creates a task.
2. Craik creates a policy envelope.
3. Craik assembles a project case file.
4. The orchestrator selects agent roles and work decomposition.
5. Agents execute with scoped capabilities.
6. Tool use creates receipts.
7. Agents produce artifacts and findings.
8. Craik verifies required checks.
9. Memory updates are proposed or written according to policy.
10. A structured handoff is created.
11. The work graph is updated.

Borrowed patterns and Craik extensions

Adjacent agent runtimes have useful patterns. Craik adopts the ones that serve a durable runtime and adds what's needed on top.

Source pattern	Craik adoption	Craik extension
Gateway runtime	CLI/API gateway ergonomics inform entry points and session routing.	Gateway also creates policy envelopes and receipt obligations.
Workspace runtime	Project profile and local runtime state isolate work.	Case files and handoffs make workspace state portable across agents.
Skills runtime	Skills provide repeatable operating guidance.	Skills declare context contracts and capability requirements.
Tool descriptors	Tools are discovered as typed capabilities.	Capabilities require grants and produce receipts.
Orchestrator	Orchestrator decomposes complex tasks.	Orchestrator uses Stigmem-backed project memory and cannot flatten unresolved contradictions.
Specialists	Workers receive scoped context and return typed results.	Worker results become graph-linked artifacts and durable handoffs.
Task board	Task state survives the active run.	Task state becomes part of a work graph connected to facts, PRs, receipts, and decisions.
Codex / Claude / Gemini runners	Direct adapters execute work in real agent environments.	Adapters normalize outputs into Craik contracts and memory proposals.

Core runtime contracts

Craik defines stable schemas so adapters, runners, and plugins can integrate against the same product surface.

The MVP contract set: task requests · project case files · agent role manifests · capability grants · capability receipts · handoffs · proposed facts · contradiction reports · verification results · work graph events.

These contracts are more important than any single adapter language. Craik core starts as a Python 3.12+ CLI runtime, while the contracts remain the basis for interoperability with Codex, Claude, Gemini, local agent runtimes, GitHub, CI, TypeScript gateways, UI surfaces, and Stigmem.

What's next

Read nextRuntime contractsThe typed shapes every layer speaks.ReadFeaturesImplementable feature surface across the seven layers.ConceptProject modelThe foundational layer-2 object every other layer composes against.