Migrating from v0

Weave vNext is a ground-up rewrite of the original opencode-weave alpha. The core ideas are the same (agent configuration, categories, prompt customization) but the architecture, syntax, and package structure have changed substantially.

What was v0? The v0 release (opencode-weave) was an OpenCode-exclusive plugin. Configuration lived in .opencode/weave-opencode.jsonc (project) and ~/.config/opencode/weave-opencode.jsonc (global) and was tightly coupled to OpenCode's plugin system. Workflows were defined as JSONC files in .opencode/workflows/. Weave vNext decouples the configuration layer from any single harness.

What Changed

1. Configuration format: .weave DSL instead of JSON

v0 used JSONC files at .opencode/weave-opencode.jsonc (project) or ~/.config/opencode/weave-opencode.jsonc (global):

// .opencode/weave-opencode.jsonc  (v0)
{
  "agents": {
    "my-agent": {
      "prompt": "You are a helpful assistant.",
      "model": "claude-sonnet-4-5"
    }
  }
}

vNext uses the .weave DSL, a block-structured, declarative config language:

agent my-agent {
  prompt "You are a helpful assistant."
  models ["claude-sonnet-4-5"]
  mode subagent
}

Key syntax differences:

Concept	v0 (JSON)	vNext (DSL)
Agent definition	"agents": { "name": { ... } }	agent name { ... }
Single model	"model": "..."	models ["..."] (ordered list)
Category patterns	"categories": { "name": { "patterns": [] } }	category name { patterns [...] }
Prompt file	"promptFile": "path.md"	prompt_file "path.md"
Tool permissions	Not supported	tool_policy { read allow ... }
Workflows	JSONC files in .opencode/workflows/	workflow name { step ... } in .weave/config.weave

2. Harness-agnostic architecture

v0 was an OpenCode plugin. It only worked with OpenCode. vNext introduces a layered architecture:

.weave DSL  →  weave-core (parse)  →  weave-engine (compose)  →  adapter (harness)

The same .weave config file works with any supported adapter:

• @weaveio/weave-adapter-opencode
• @weaveio/weave-adapter-claude-code
• @weaveio/weave-adapter-pi

3. Package structure

v0	vNext
opencode-weave (single package)	@weaveio/weave-core + @weaveio/weave-config + @weaveio/weave-engine + adapter

4. Configuration file locations

v0	vNext
.opencode/weave-opencode.jsonc (project)	.weave/config.weave (project)
~/.config/opencode/weave-opencode.jsonc (global)	~/.weave/config.weave (global)
Prompt files in .opencode/prompts/	Prompt files in .weave/prompts/
Workflows in .opencode/workflows/*.jsonc	Workflows in .weave/config.weave as workflow blocks

5. Prompt templates

vNext prompt files are rendered as Mustache templates with access to engine-computed data:

You are {{agent.name}}.

{{{delegation.section}}}

v0 prompt files were static strings with no template rendering.

6. Tool policies

v0 had no tool policy system. vNext agents declare an abstract capability map:

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

Adapters map these abstract permissions to harness-specific tool names and permission models.

Step-by-Step Migration Path

Step 1: Install vNext packages

bun add @weaveio/weave-core @weaveio/weave-config @weaveio/weave-engine
bun add @weaveio/weave-adapter-opencode   # or your target harness

Remove the old package:

bun remove opencode-weave

Step 2: Create the .weave directory

mkdir .weave
mkdir .weave/prompts

If you had prompt files in .opencode/prompts/, copy them to .weave/prompts/.

Step 3: Translate your JSON config to .weave DSL

For each agent in your v0 JSON config, create a corresponding agent block. Use the DSL reference for full syntax.

v0 example (.opencode/weave-opencode.jsonc):

{
  "agents": {
    "reviewer": {
      "prompt_file": "reviewer.md",
      "model": "claude-sonnet-4-5",
      "temperature": 0.2
    }
  },
  "categories": {
    "backend": {
      "patterns": ["src/api/**"],
      "prompt_append": "Focus on API contracts."
    }
  }
}

vNext equivalent:

agent reviewer {
  prompt_file "reviewer.md"
  models ["claude-sonnet-4-5"]
  mode subagent
  temperature 0.2
}

category backend {
  patterns ["src/api/**"]
  prompt_append "Focus on API contracts."
}

Step 4: Update your adapter initialization

Replace OpenCode plugin registration with the adapter initialization pattern. See Getting Started for a minimal example.

Step 5: Verify

Run your build and type-check:

bun run build
bun run typecheck

Deprecated Features

The following v0 features have no direct equivalent in vNext (as of this release):

v0 Feature	Status in vNext
OpenCode-specific hook names	Replaced by abstract tool_policy
opencode.json weave key	Superseded by .weave/config.weave
Single-model model field	Replaced by ordered models list
agents.weft.review_models / agents.warp.review_models JSON field	Replaced by review_models DSL field on agent blocks. See below.

Migrating review_models from v0 JSON

If you had a v0 config with review_models on an agent, translate the JSON array to the DSL field directly:

v0 (.opencode/weave-opencode.jsonc):

{
  "agents": {
    "warp": {
      "model": "claude-opus-4",
      "review_models": ["openai/gpt-5", "anthropic/claude-sonnet-4-5"]
    }
  }
}

vNext (.weave/config.weave):

agent warp {
  models ["anthropic/claude-opus-4"]
  review_models ["openai/gpt-5", "anthropic/claude-sonnet-4-5"]
}

Note that review_models is an opt-in field in vNext. Built-in agents omit it by default to avoid unexpected cost. Your override merges with the built-in declaration; all other fields are preserved. See Review Models for full details.

Getting Help

• DSL Reference: full .weave language reference
• Agent Configuration: built-in and custom agents
• Categories: domain routing
• Adapters: harness-specific setup