Weave vNext

Weave is a harness-agnostic prompt and agent-configuration API for AI coding assistants. A custom .weave DSL declares agents, categories, workflows, prompts, delegation intent, model preferences, and settings. Weave parses and normalizes that intent; adapters translate it into concrete harness plugins and configuration for OpenCode, Claude Code, Pi, Codex, or any future target.

Think of Weave like Neovim's API layer: Weave provides primitives and normalized configuration; adapters and users compose those primitives into a concrete harness experience.

Why Weave?

• Write once, run anywhere: define your agents and prompts once in a .weave file; adapters handle the harness-specific translation
• DSL-first: readable, declarative syntax designed for non-programmers and AI agents alike
• Composable: mix built-in agents (Loom, Shuttle, Warp, Weft) with your own custom agents and categories
• Multi-model: declare an ordered model preference list per agent; adapters resolve concrete availability

The .weave DSL

Configuration lives in .weave files. A minimal project config looks like this:

agent my-reviewer {
  description "Code review specialist"
  prompt "You are a thorough code reviewer. Focus on correctness, security, and readability."
  models ["claude-sonnet-4-5", "gpt-4o"]
  mode subagent
  temperature 0.2

  tool_policy {
    read allow
    write deny
    execute deny
    delegate deny
  }
}

category backend {
  description "Backend APIs, services, persistence"
  patterns ["src/api/**", "src/server/**", "**/*.go"]
  prompt_append "Focus on API contracts and data integrity."
}

Key Concepts

Concept	Description
Agent	A named AI persona with a prompt, model preferences, tool policy, and optional skills
Category	A domain routing rule. Glob patterns map files to specialised shuttle agents
Workflow	A multi-step pipeline with agents, completion conditions, and artifact passing
Adapter	Translates normalized Weave config into a concrete harness (OpenCode, Claude Code, etc.)
Skill	A reusable instruction set loaded into an agent's context on demand

Package Structure

Package	Responsibility
@weaveio/weave-core	DSL lexer, parser, AST, Zod schema validation, config types
@weaveio/weave-config	Builtin DSL defaults, config discovery, merge semantics
@weaveio/weave-engine	Composition APIs, HarnessAdapter interface, prompt building
@weaveio/weave-adapter-*	Harness-specific translation into plugins/configs/tools

Configuration Locations

Scope	Path	Purpose
Global	~/.weave/config.weave	User-level defaults, shared across projects
Project	.weave/config.weave	Project-level config, overrides global

Project values override global for scalars; objects deep-merge; arrays union-merge.

Next Steps

• Getting Started: install Weave and write your first .weave file
• DSL Reference: full syntax reference
• Agents: configuring built-in and custom agents
• Categories: routing work to domain specialists
• Workflows: multi-step pipelines
• Adapters: harness-specific integration
• Migrating from v0: upgrade guide from the OpenCode-exclusive alpha