Architecture
Capstan's architecture is organized around five kernels and a shared source of truth. This page describes the conceptual model, the current package boundaries, and the golden loop that ties them together.
TypeScript-First Design
Capstan's implementation is TypeScript-first. This is an execution choice, not long-term dogma. The goal is to maximize agent legibility, shared tooling, and iteration speed while the application contract is still converging.
- Coding agents are highly effective in TypeScript-first repositories
- One language keeps runtime, scaffolding, verification, and docs close
- The current web and tooling stack is fastest to evolve in TypeScript
- Early package boundaries stay easier to change while the kernel model settles
Source of Truth
Capstan's working application vocabulary is:
Domain + Resource + Capability + Task + Policy + Artifact + ViewEach element has a distinct role:
| Element | Role |
|---|---|
| Domain | The bounded business space and its language |
| Resource | Stable entities and their relations |
| Capability | Executable business actions with semantics |
| Task | Long-running or stateful executions |
| Policy | Rules for access, approval, redaction, and budget |
| Artifact | Durable outputs produced by the system |
| View | Human-facing projections of the graph |
Today this vocabulary is materialized through framework definitions, generated contracts, manifests, and scaffolded application output.
Five-Kernel Architecture
Kernel 1: Graph
The Graph kernel defines and materializes the shared application contract.
- Application schema
- Resource and capability registry
- Dependency graph
- Machine-readable project index
- Projection inputs for human and machine surfaces
Kernel 2: Harness
The Harness kernel runs agent work against the application.
- Task lifecycle
- Tool execution
- Shell, browser, and runtime coordination
- Memory and compaction
- Approvals and interventions
- Event streaming
Kernel 3: Surface
The Surface kernel exposes the application to humans and other agents through shared runtime contracts.
- Machine-facing execution and discovery surfaces (HTTP, MCP, A2A, OpenAPI)
- Generated agent-operating contracts (AGENTS.md, starter prompts)
- Operator-facing projections for inspection, approval, input handoff, retry, and supervision
- Search and execution entry points over the same underlying runtime state
Kernel 4: Feedback
The Feedback kernel closes the repair loop.
- Type and schema validation
- Tests and assertions
- Runtime diagnostics
- Evals and regression checks
- Structured error reporting
Kernel 5: Release
The Release kernel turns application state into operable software.
- Environment schema
- Secret requirements
- Migrations
- Preview environments
- Health checks
- Rollout and rollback
Golden Loop
The five kernels are connected by a golden loop that Capstan makes native:
- Read the contract (Graph)
- Plan a change
- Execute through the harness (Harness)
- Verify through feedback (Feedback)
- Release through structured workflows (Release)
- Expose updated surfaces to humans and agents (Surface)
This loop applies to both human developers and AI agents operating on the application. The contract is the shared coordination point.
Package Boundaries
The five kernels do not map one-to-one to package names. The current packages are organized by layer:
Contract Layer
| Package | Responsibilities |
|---|---|
@zauso-ai/capstan-core | Capabilities, policies, routes, and runtime contracts |
@zauso-ai/capstan-router | File-based routing and manifest generation |
@zauso-ai/capstan-db | Model definitions, migrations, and CRUD generation |
@zauso-ai/capstan-auth | Authentication, API keys, OAuth, and permissions |
Harness Layer
| Package | Responsibilities |
|---|---|
@zauso-ai/capstan-ai | Agent work, durable/recurring execution |
@zauso-ai/capstan-cron | Scheduled tasks and background jobs |
Surface Layer
| Package | Responsibilities |
|---|---|
@zauso-ai/capstan-agent | Machine surfaces (MCP, A2A, OpenAPI, agent manifest) |
@zauso-ai/capstan-react | Human application shell (React SSR, client router) |
@zauso-ai/capstan-dev | Local development server, runtime inspection |
@zauso-ai/capstan-cli | Operational commands and scaffolding |
Feedback and Release
Feedback and release responsibilities are currently distributed across @zauso-ai/capstan-core, @zauso-ai/capstan-cli, and generated app assertions. These packages handle verification, structured diagnostics, build output, and deployment contracts.
Scaffolding
create-capstan-app establishes the default project structure, generates agent-readable guides and starter workflows, and keeps new applications aligned with the framework's current contract.
Long-Term Boundary
Capstan distinguishes between two future layers:
- Framework layer: contract definition, projections, verification, release contracts, and developer tooling. Stays TypeScript-friendly.
- Host layer: durable execution, process control, sandboxing, and system integrations. May move to a lower-level runtime (e.g. Rust) if needed for stability or portability.