OpenCode

betterspec integrates with OpenCode in two complementary ways:

1. Global plugin — install once, works across all your projects
2. Project scaffold — betterspec init creates agent files for OpenCode in your project

Global Plugin (Recommended)

Add betterspec to the plugin array in your opencode.json (global or project-level):

{
  "plugin": ["betterspec@git+https://github.com/betterspec/betterspec.git"]
}

Restart OpenCode. That's it.

The plugin automatically:

• Auto-discovers betterspec skills from the skills/ directory
• Injects spec context into every LLM call — active changes, task progress, and enforcement rules
• Warns on unspecced edits — if an agent edits a file not covered by any active spec, a warning is injected

Project Scaffold (betterspec init)

Running betterspec init with OpenCode selected creates four specialized agent definition files:

betterspec init
# Select your AI tool: OpenCode

Agent Files in .opencode/agents/

The Golden Rule

The builder never validates its own work.

The Builder and Validator agents are intentionally separate roles. The Validator runs with a clean context (no build history), so it can catch errors that self-review misses — the same reason code review exists in human teams.

Workflow

A typical workflow with OpenCode and betterspec:

1. Propose a change: betterspec propose "Add rate limiting"
2. Switch to the Planner agent to flesh out specs
3. Switch to the Builder agent to implement tasks
4. Switch to the Validator agent to review the work
5. If issues are found, the Builder fixes them
6. The Archivist archives the change and extracts knowledge