Architecture

Capstan's architecture is organized around three pillars -- AI agents, full-stack web, and self-evolution -- unified by 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.

Unified Architecture

Capstan serves two primary roles from a shared Bun-native runtime:

                        Capstan
           ┌──────────────┼──────────────┐
           │              │              │
     AI Agent        Full-Stack      Self-Evolution
     Pillar          Web Pillar      Pillar
           │              │              │
  createSmartAgent   defineAPI()     Evolution Engine
  Tool Validation    HTTP/MCP/A2A   Experience Capture
  Context Compress   React SSR      Strategy Distill
  Skills + Memory    defineModel    Skill Promotion
  Checkpoints        Policies       SqliteEvolutionStore
  Harness Mode       Auth/OAuth     Utility Feedback
           │              │              │
           └──────────────┼──────────────┘
                   Shared Runtime
          (Bun-native, Node.js compatible)

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 + View

Each element has a distinct role:

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 and the smart agent loop
• Tool execution with validation, timeout, and concurrent dispatch
• Shell, browser, and runtime coordination
• Memory, compression, and context management
• Approvals, interventions, and checkpoints
• Event streaming and evolution capture

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:

1. Read the contract (Graph)
2. Plan a change
3. Execute through the harness (Harness)
4. Verify through feedback (Feedback)
5. Release through structured workflows (Release)
6. 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:

Agent Layer

Contract Layer

Surface Layer

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.