Weave turns a declarative .weave configuration into normalized agent intent, lets the engine compose that intent into a harness-agnostic system plan, and lets adapters translate that plan into concrete behavior inside a target harness.

This page explains how Weave’s layered architecture works, what each layer owns, and how data flows from your .weave file to running agents.

flowchart TD
  User[User or Project<br/>outside Weave]

  subgraph ConfigPackages["@weaveio/weave-config + @weaveio/weave-core"]
    ConfigSources[Configuration Sources<br/>built-ins + global + project]
    ConfigLayer[Load + Normalize Config<br/>discover, parse, validate,<br/>resolve prompts, merge]
    NormalizedConfig[Normalized Weave Config<br/>single source of declared intent]
    ConfigSources --> ConfigLayer --> NormalizedConfig
  end

  subgraph EnginePackage["@weaveio/weave-engine"]
    Engine[Compose System Plan<br/>agents, prompts, categories,<br/>workflows, policies,<br/>model and skill intent]
  end

  subgraph AdapterPackage["@weaveio/weave-adapter-*"]
    HarnessContext[Harness-Owned Context<br/>available models, selected model,<br/>available skills, lifecycle events]
    Adapter[Adapter Translator<br/>target-specific materialization]
    HarnessArtifacts[Harness Artifacts<br/>plugins, config, commands,<br/>tools, permissions, runtime wiring]
    HarnessContext --> Adapter --> HarnessArtifacts
  end

  subgraph HarnessLayer["Harness Runtime"]
    Harness[Harness Runtime<br/>OpenCode, Pi, Claude Code,<br/>Codex, or future targets]
    RunningAgents[Running Agent Experience<br/>primary agents, delegated specialists,<br/>reviews, audits, workflows]
    Harness --> RunningAgents
  end

  User --> ConfigSources
  NormalizedConfig --> Engine
  Engine --> Adapter
  Adapter -. supplies explicit context .-> Engine
  HarnessArtifacts --> Harness
  Harness -. events and capabilities .-> Adapter

Weave’s architecture is organized into four layers, each with clear ownership boundaries.

What it does: Collects and normalizes your declared intent.

What it owns:

• Reading built-in defaults, global user preferences, and project-specific .weave files
• Parsing the DSL syntax
• Validating the parsed structure
• Resolving prompt references into usable prompt inputs
• Merging built-in, global, and project intent into one final config

The configuration layer answers: What did the user declare?

It describes what you want the agent system to be: agents and their roles, categories and routing hints, workflows and gates, prompt text or prompt references, model preferences, skill references, abstract tool and policy permissions, and disabled agents, hooks, or skills.

The output is not a harness plugin or runtime object. It is still Weave-owned, harness-agnostic intent.

What it does: Composes the system plan from normalized configuration.

What it owns:

• Normalized agent descriptors
• Generated category shuttle agents
• Prompt and delegation intent
• Model preference intent
• Skill matching decisions from adapter-provided skill context
• Abstract policy and lifecycle decisions
• Workflow execution intent
• Durable Runtime Store records under .weave/runtime/**

The engine answers: What should exist?

It takes normalized configuration and produces higher-level Weave concepts. The engine does not inspect harness UI state, discover harness resources, or register concrete runtime hooks. When it needs harness facts, the adapter passes those facts in explicitly.

What it does: Translates engine output for a specific harness.

What it owns:

• Discovering available harness models
• Reading selected model state if the harness exposes it
• Discovering and loading harness skills
• Mapping abstract tool permissions to concrete tool names
• Turning agent descriptors into harness-specific agent definitions
• Registering harness commands, plugins, hooks, or runtime callbacks
• Emulating missing features when the harness does not support them natively

The adapter answers: How does this work in this specific harness?

Adapters consume the engine output and materialize it in the target harness. Each harness has its own adapter package: @weaveio/weave-adapter-opencode, @weaveio/weave-adapter-pi, and so on.

See Adapters for more about how adapters work and which harnesses are supported.

What it does: Runs the concrete agent experience.

What it owns:

• UI presentation
• Tool execution
• Model invocation
• Lifecycle events
• The final agent experience

The harness is the concrete execution environment. At runtime, harness events flow back to the adapter. The adapter maps those events into Weave’s abstract policy surfaces where applicable, keeping harness details out of the engine.

Here’s how data flows from your .weave file to running agents:

1. You write a .weave file declaring agents, categories, workflows, prompts, and policies.
2. The config layer discovers built-in, global, and project config layers, parses the DSL, validates the structure, resolves prompt references, and merges everything into one normalized config.
3. The engine composes that config into harness-agnostic agent descriptors, prompt intent, category shuttles, workflows, policies, model intent, and skill intent.
4. The adapter supplies harness-owned context (available models, selected model, available skills, lifecycle events) back to the engine when needed, then translates the engine output into concrete harness behavior.
5. The harness runs the agents, invokes tools, emits lifecycle events, and presents the UI.

The adapter boundary is the key architectural concept that makes Weave harness-agnostic.

The rule: The engine may compose Weave intent, but it should not make harness-specific assumptions. If a decision requires knowing what a harness supports, what the user selected in a harness UI, where a harness stores resources, or how a harness registers callbacks, that decision belongs in the adapter.

Why this matters: Weave normalizes intent. Adapters translate to concrete harness behavior. This separation means:

• The engine can evolve without knowing about every harness.
• Adapters can fill feature gaps when a harness lacks native support.
• New harnesses can be supported by writing a new adapter without changing the engine.

Example: Model Resolution

The engine defines model preference intent: you declare models: ["claude-sonnet-4"] in your agent config. The adapter discovers what models the harness actually has available, checks what the user selected in the harness UI, and supplies that context to the engine. The engine resolves the final model choice using a pure helper function. The adapter then formats that choice into the harness-specific model field.

The engine never queries the harness UI or model registry itself. The adapter never rewrites the engine’s resolution logic.

Example: Skill Discovery

The engine defines skill matching rules: you declare skills: ["git-rebase"] in your agent config, and the engine filters that list against disabled.skills. The adapter discovers and loads skills from harness-specific directories (OpenCode skill directories, Pi skill directories, etc.). The adapter passes the available skills to the engine. The engine resolves the final skill list. The adapter materializes those skills in the harness.

The engine never scans ~/.weave/skills/ or .weave/skills/ itself. The adapter never rewrites the engine’s matching logic.

• DSL Configuration - Learn how to write .weave files
• Agents - Understand how agents are declared and composed
• Adapters - See which harnesses are supported and how adapters work
• CLI - Command-line interface reference