Context-driven, plan-first development for AI coding assistants. Turns vibe coding into structured execution with human review gates, dependency-aware task scheduling, and pluggable storage backends.
Status: Active development · v0.1.8 · MIT with Commons Clause
- What It Does
- Key Features
- Tech Stack
- Prerequisites
- Getting Started
- Architecture
- Workflow
- Agents
- Tools Reference
- Skills
- Configuration
- Storage Model
- Available Scripts
- Testing
- CI/CD
- Project Structure
- Troubleshooting
- Further Reading
- License
opencode-warcraft is an OpenCode plugin that wraps AI coding sessions in a structured development workflow. Instead of letting an AI assistant free-form code changes, Warcraft enforces:
- Feature scoping -- every unit of work starts with a named feature
- Plan-first development -- complex work gets a written plan reviewed and approved by a human before any code is touched
- Task decomposition -- plans are parsed into dependency-aware tasks with explicit verification steps
- Delegated execution -- tasks are dispatched to specialized worker agents (Mekkatorque) with full context
- Blocker handling -- when a worker gets stuck, the system surfaces the blocker for human decision
- State tracking -- every feature, plan, and task has persistent state across sessions
The result: AI-assisted development that is auditable, resumable, and doesn't go off the rails.
- Two workflow modes: Planned (full plan-approve-execute cycle) and Direct (create task, execute immediately) for work of any size
- 6 specialized agents: Khadgar (hybrid planner/orchestrator), Mimiron (pure planner), Saurfang (lean orchestrator), Brann (read-only researcher), Mekkatorque (implementation worker), Algalon (reviewer/debugger)
- 16 tools across 9 domain modules for feature/plan/task/context/status/diagnostics/editing
- 17 built-in skills for plan authoring, TDD, code review, debugging, parallel exploration, and more
- Dual storage backends: Filesystem-backed (simple JSON files) or beads-backed (dependency-aware issue tracker via
br) - Dependency-aware scheduling: Tasks declare dependencies; the system computes runnable order and blocks execution of tasks with unmet deps
- Hash-anchored file editing:
warcraft_hashline_edituses xxHash32 line anchors for safe, conflict-resistant edits - Compaction-resilient: Hooks inject state recovery prompts after context window compaction so agents don't lose their place
- Built-in MCP servers: grep.app (code search) and Exa AI (web search) pre-configured
- Configurable per-agent models: Override model, temperature, skills, and variants per agent role
| Component | Technology |
|---|---|
| Runtime | Bun 1.3.9+ |
| Language | TypeScript (ES2022, ESM) |
| Monorepo | Bun workspaces |
| Formatter/Linter | Biome 2.4+ |
| Testing | bun:test (describe/it/expect) |
| Plugin Host | OpenCode @opencode-ai/plugin |
| Issue Tracking | beads_rust (br) -- optional |
| CI/CD | GitHub Actions |
| Package Registry | npm |
- OpenCode -- the AI coding assistant that hosts this plugin. Install from opencode.ai:
curl -fsSL https://opencode.ai/install | bash # or: npm install -g opencode-ai # or: brew install anomalyco/tap/opencode
- Bun 1.3.9+ -- install from bun.sh (required for development; OpenCode uses Bun to auto-install npm plugins)
- Node.js 20+ -- for npm publishing and some tooling
- Git -- for version control and E2E tests
brCLI (optional) -- required only if usingbeadsMode: "on". Install viacargo install beads_rustor check beads_rust docs- EXA_API_KEY (optional) -- for the built-in Exa web search MCP server
git clone https://github.com/minhtri2710/opencode-warcraft.git
cd opencode-warcraftbun installbun run buildThis builds warcraft-core first (dependency), then opencode-warcraft (generates the skill registry and bundles the plugin).
bun run testRuns all workspace unit tests plus the smoke E2E lane (~2,494 tests).
bun run lintRuns TypeScript type checking on both packages, then Biome linting.
The plugin is published to npm. Add it to your project's opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-warcraft"]
}OpenCode auto-installs npm plugins at startup via Bun (cached in ~/.cache/opencode/node_modules/).
For local development, run the plugin in dev mode from the package directory:
cd packages/opencode-warcraft
opencode plugin devAlternatively, you can install from a local clone by placing a symlink or the built plugin in .opencode/plugins/ (project-level) or ~/.config/opencode/plugins/ (global).
Create ~/.config/opencode/opencode_warcraft.json:
{
"beadsMode": "off",
"agentMode": "unified",
"agents": {
"khadgar": {
"model": "claude-sonnet-4-20250514"
}
}
}See Configuration for all options.
opencode-warcraft/
├── packages/
│ ├── warcraft-core/ # Domain logic (services, stores, types)
│ │ └── src/
│ │ ├── agents-md/ # AGENTS.md generation service
│ │ ├── beads/ # Beads-backed storage layer
│ │ ├── config/ # User configuration service
│ │ ├── context/ # Persistent context file management
│ │ ├── feature/ # Feature lifecycle service
│ │ ├── filesystem/ # Filesystem-backed storage layer
│ │ ├── git/ # Git client abstraction
│ │ ├── outcomes/ # Structured error handling (ok/degraded/fatal)
│ │ ├── plan/ # Plan CRUD, approval, dependency graphs
│ │ ├── state/ # Store factory and interfaces
│ │ ├── task/ # Task service, state machine, sync, scheduling
│ │ ├── utils/ # Shared utilities (paths, slugs, JSON locking)
│ │ ├── types.ts # Core domain types
│ │ └── index.ts # Public API surface
│ │
│ └── opencode-warcraft/ # OpenCode plugin (agents, tools, hooks, MCP)
│ ├── src/
│ │ ├── agents/ # 6 agent definitions + shared prompt fragments
│ │ ├── execution/ # Blocked check, dependency check, task dispatch
│ │ ├── hooks/ # System prompt, compaction, variant hooks
│ │ ├── mcp/ # Built-in MCP server configs (grep.app, Exa)
│ │ ├── resolution/ # Feature resolution, session capture
│ │ ├── skills/ # Skill loading, registry, file loader
│ │ ├── tools/ # 16 tools across 9 domain modules
│ │ ├── utils/ # Prompt budgeting, formatting, sanitization
│ │ ├── container.ts # DI composition root
│ │ └── index.ts # Plugin entry point (hook/tool/MCP registration)
│ ├── skills/ # 17 built-in skill definitions (SKILL.md files)
│ ├── templates/ # Prompt templates and MCP server configs
│ ├── schema/ # JSON Schema for user configuration
│ └── scripts/ # Skill registry generator, E2E preflight
│
├── docs/ # User-facing documentation
│ ├── quickstart.md
│ ├── plan-authoring.md
│ └── troubleshooting.md
├── eval/ # Evaluation/audit test suites
├── biome.json # Formatter/linter config
└── package.json # Workspace root
opencode-warcraft (plugin)
│
├── warcraft-core (domain)
│ └── simple-git
│
├── @opencode-ai/plugin (peer)
│
└── MCP servers (optional)
├── grep-mcp (grep.app)
└── exa-mcp-server (Exa AI)
User Request
│
▼
┌─────────────────┐ ┌──────────────────┐
│ Primary Agent │────▶│ warcraft_* │
│ (Khadgar / │ │ tools │
│ Saurfang) │ └────────┬─────────┘
└─────────────────┘ │
▼
┌────────────────────────┐
│ warcraft-core │
│ services │
│ (Feature, Plan, │
│ Task, Context) │
└────────┬───────────────┘
│
┌────────┴───────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Filesystem │ │ Beads (br) │
│ Stores │ │ Stores │
│ (JSON files) │ │ (JSONL DB) │
└──────────────┘ └──────────────┘
Tasks move through 8 states with enforced transitions:
┌─────────────┐
│ pending │◀──────────────────┐
└──────┬──────┘ │
│ │
┌────────────┼────────────┐ │
▼ ▼ ▼ │
┌─────────────┐ ┌────────────┐ ┌───────────┐ │
│ dispatch_ │ │in_progress │ │ cancelled │─────┘
│ prepared │ └──────┬─────┘ └───────────┘
└──────┬──────┘ │
│ ┌────┼────┬────────┐
▼ ▼ ▼ ▼ ▼
┌────────────┐ ┌────┐ ┌───────┐ ┌────────┐
│in_progress │ │done│ │blocked│ │failed │
└────────────┘ └────┘ └───┬───┘ └───┬────┘
│ │
▼ ▼
┌────────────┐ ┌────────┐
│dispatch_ │ │pending │
│prepared │ └────────┘
└────────────┘
Key invariant: done -> in_progress is never allowed in strict mode.
The full plan-approve-execute cycle:
1. warcraft_feature_create({ name: 'user-auth', request: 'Add OAuth2 login' })
2. Clarify requirements with the user
3. warcraft_plan_write({ content: '# User Auth\n\n## Discovery\n...' })
4. warcraft_plan_read() # Review draft
5. warcraft_plan_approve() # Human approval gate → auto-syncs tasks
6. warcraft_execute({ task: '01-setup-db' }) # Returns task() payload
7. Issue the returned task() call # Launches Mekkatorque worker
8. warcraft_status() # Check progress
9. Repeat steps 6-8 for remaining tasks
Skip the plan entirely:
1. warcraft_feature_create({ name: 'fix-typo', request: 'Fix typo in header' })
2. warcraft_task_create({ name: 'fix header typo', description: '...' })
3. warcraft_execute({ task: '01-fix-header-typo' })
4. Issue the returned task() call
When a worker encounters an ambiguity:
1. warcraft_status() # Shows blocker details
2. Ask the user for a decision # Via question() tool
3. warcraft_execute({
task: '03-auth-flow',
continueFrom: 'blocked',
decision: 'Use OAuth2 PKCE flow because...'
})
4. Issue the returned task() call # Relaunches worker with decision
When direct tasks outgrow the simple path:
1. warcraft_task_expand() # Scaffolds a plan from pending manual tasks
2. warcraft_plan_write({ useScaffold: true })
3. warcraft_plan_approve() # Triggers task sync
4. Continue with planned execution
opencode-warcraft defines 6 specialized agents organized into two tiers:
| Agent | Role | What It Does |
|---|---|---|
| Khadgar | Hybrid Planner/Orchestrator | Detects phase from feature state; handles both planning and execution. Classifies intent, delegates research to Brann and implementation to Mekkatorque, manages context, writes plans, and coordinates the full lifecycle. Default in unified mode. |
| Mimiron | Pure Planner | Never executes code. Interviews users, classifies work complexity, flags AI-slop patterns, writes structured plans with discovery/non-goals/ghost-diffs sections. Delegates review to Algalon. |
| Saurfang | Lean Orchestrator | Delegates everything by default. Checks task dependencies, coordinates delegated execution, verifies results, handles failure recovery (3 consecutive failures triggers revert + user escalation). |
| Agent | Role | What It Does |
|---|---|---|
| Brann | Explorer/Researcher | Read-only. Runs 3+ tools in parallel, discovers documentation, retrieves external data. Never creates or modifies files. |
| Mekkatorque | Implementation Worker | Executes tasks directly, never delegates. Follows 5-step flow: Understand → Orient → Implement → Verify → Report. Reports STATUS: done/blocked/failed/partial. |
| Algalon | Reviewer/Debugger | Evaluates plan quality across 4 criteria (clarity, verification, context completeness, big picture). Outputs OKAY/REJECT verdict. Also handles code review on request. |
Configure in opencode_warcraft.json:
"agentMode": "unified"-- uses Khadgar as the single hybrid agent (default)"agentMode": "dedicated"-- uses Mimiron for planning, Saurfang for orchestration
| Tool | Description |
|---|---|
warcraft_feature_create |
Create a new feature with name, request, ticket, and priority. Recommends workflow mode (planned/direct/instant). |
warcraft_feature_complete |
Mark the active feature as completed. |
| Tool | Description |
|---|---|
warcraft_plan_write |
Write or update plan.md for a feature. Supports scaffold mode from pending manual tasks. |
warcraft_plan_read |
Read plan content and approval status. |
warcraft_plan_approve |
Approve the plan for execution. Auto-syncs tasks after approval with rollback on failure. |
| Tool | Description |
|---|---|
warcraft_tasks_sync |
Parse plan into tasks, reconcile with existing tasks. Supports preview mode. |
warcraft_task_create |
Create a manual/direct task without a plan. |
warcraft_task_expand |
Promote pending manual tasks into a plan scaffold. |
warcraft_task_update |
Update task status, summary, blocker, learnings, or report. Enforces state machine. |
warcraft_execute |
Prepare a runnable task for execution and return the task() payload to launch Mekkatorque. Handles blocked resume, dispatch guards (max 5 attempts), and dependency checks. |
| Tool | Description |
|---|---|
warcraft_context_write |
Write a persistent context file (decisions, architecture notes) for the active feature. |
warcraft_status |
Get feature/task status including blockers, runnable tasks, promotion hints, and next action guidance. |
warcraft_agents_md |
Initialize, sync, or apply AGENTS.md updates from feature context. |
| Tool | Description |
|---|---|
warcraft_doctor |
Run diagnostic checks: stuck tasks, missing heartbeats, blocked features, scheduler warnings. |
warcraft_skill |
Load a registered Warcraft skill by name. Runtime access restricted by agent allowlist. |
warcraft_hashline_edit |
Hash-anchored file editing using LINE#ID format with xxHash32. Supports replace/append/prepend, file delete, file rename. Path-validated (absolute + project root containment). |
17 built-in skills provide specialized instructions for agents:
| Skill | When It's Used |
|---|---|
warcraft |
Core plan-first workflow reference |
writing-plans |
Structuring multi-step plans before coding |
executing-plans |
Step-by-step plan execution with review checkpoints |
brainstorming |
Pre-creative-work exploration and requirements gathering |
test-driven-development |
Red-Green-Refactor implementation flow |
systematic-debugging |
Encountering bugs or test failures |
code-reviewer |
Reviewing implementation against plan/task specs |
requesting-code-review |
Finishing a task with an explicit review pass |
receiving-code-review |
Evaluating and applying review feedback |
verification-before-completion |
Running verification before claiming success |
finishing-a-development-branch |
Summarizing and preparing handoff |
parallel-exploration |
Fan-out read-only research with Brann |
dispatching-parallel-agents |
2+ independent tasks worked in parallel |
subagent-driven-development |
Executing plans with independent task workers |
agents-md-mastery |
Bootstrapping and maintaining AGENTS.md |
br |
beads_rust CLI reference for issue tracking |
writing-skills |
Creating or updating built-in skills |
Skills are loaded on-demand via warcraft_skill("skill-name") and restricted per-agent by allowlists.
Warcraft configuration lives at ~/.config/opencode/opencode_warcraft.json. All fields are optional.
{
"$schema": "https://raw.githubusercontent.com/minhtri2710/opencode-warcraft/main/packages/opencode-warcraft/schema/opencode_warcraft.schema.json",
"beadsMode": "off",
"agentMode": "unified",
"enableToolsFor": ["my-feature"],
"disableSkills": ["br"],
"disableMcps": ["websearch"],
"parallelExecution": {
"strategy": "bounded",
"maxConcurrency": 3
},
"agents": {
"khadgar": {
"model": "claude-sonnet-4-20250514",
"temperature": 0.7,
"skills": ["extra-skill"],
"autoLoadSkills": ["warcraft"],
"variant": "custom-variant"
},
"mekkatorque": {
"model": "claude-sonnet-4-20250514"
}
}
}| Option | Type | Default | Description |
|---|---|---|---|
beadsMode |
"on" | "off" |
"off" |
Storage backend. "on" requires br CLI. |
agentMode |
"unified" | "dedicated" |
"unified" |
Single hybrid agent (Khadgar) or split planner/orchestrator (Mimiron + Saurfang). |
enableToolsFor |
string[] |
[] |
Feature names that enable Warcraft tools (empty = always enabled). |
disableSkills |
string[] |
[] |
Globally disable specific skills by name. |
disableMcps |
string[] |
[] |
Disable built-in MCP servers ("websearch", "grep_app"). |
parallelExecution |
object | { strategy: "unbounded" } |
Control concurrent worker execution. |
agents.<name> |
object | varies | Per-agent overrides for model, temperature, skills, autoLoadSkills, variant. |
beadsMode controls only the storage backend -- not execution semantics or workflow shape.
Data lives in the project directory under docs/<feature-name>/:
docs/
└── user-auth/
├── feature.json # Feature metadata (status, workflow path, etc.)
├── plan.md # The plan document
├── context/ # Persistent context files
│ ├── architecture.md
│ └── decisions.md
└── tasks/
├── 01-setup-database/
│ ├── status.json # Task state (status, dependencies, worker session)
│ ├── spec.md # Generated task specification
│ └── report.md # Worker completion report
└── 02-auth-service/
└── status.json
Plan approval uses SHA-256 hash comparison stored in feature.json.
Data lives in .beads/ managed by the br CLI:
- Features map to epic beads
- Tasks map to task beads with dependency edges
- Plan content syncs to epic bead description
- Approval tracked via bead labels
- Task state stored in bead artifacts (
task_state,feature_state,plan_approval, etc.) WorkflowIntelligenceServicecombines BR readiness data with BV (Beads Viewer) planning/triage data
The beads subsystem adds dependency cycle detection, transition journaling for crash recovery, and scheduling advisory via graph analytics.
| Command | Description |
|---|---|
bun run build |
Build both packages (warcraft-core first, then opencode-warcraft) |
bun run test |
Run all workspace unit tests + smoke E2E lane |
bun run test:e2e:host |
Host-backed E2E lane (requires git and br CLI) |
bun run lint |
TypeScript type checking + Biome linting |
bun run format |
Auto-fix formatting with Biome |
bun run format:check |
Check formatting without fixing |
bun run release:check |
Full pre-release validation (install, build, test, lint, format check) |
| Command | Package | Description |
|---|---|---|
bun run test --filter warcraft-core |
warcraft-core | Run core package tests only |
bun run test --filter opencode-warcraft |
opencode-warcraft | Run plugin package tests only |
bun run generate-skills |
opencode-warcraft | Regenerate registry.generated.ts from skill SKILL.md files |
opencode plugin dev |
opencode-warcraft | Start plugin in development mode |
# All tests (unit + smoke E2E)
bun run test
# Single package
bun run test --filter warcraft-core
bun run test --filter opencode-warcraft
# Single test file
bun test packages/warcraft-core/src/task/task-service.test.ts
# E2E lanes
bun run test:e2e:host # Requires git + br CLITests are co-located with source files using *.test.ts:
src/
├── feature/
│ ├── feature-service.ts
│ └── feature-service.test.ts
├── task/
│ ├── task-service.ts
│ └── task-service.test.ts
- Framework:
bun:testwithdescribe/it/expect - Mocking:
spyOnfor dependency mocking - E2E Helpers:
packages/opencode-warcraft/src/e2e/helpers/test-env.tsfor test environment setup, lane detection, and host preflight checks - Coverage: Available via
bun test --coverage
| Package | Source Files | Test Files | Total Lines |
|---|---|---|---|
| warcraft-core | 57 | 55 | ~29,800 |
| opencode-warcraft | ~60 | ~30 | ~15,000 |
Two GitHub Actions workflows:
Runs on every push to main and all PRs:
- Install dependencies (
bun install --frozen-lockfile) - Build both packages
- Run all tests with coverage
- TypeScript type checking
- Biome format/lint checking
- Upload coverage artifact (14-day retention)
Triggered by v* tags:
- Full build + test + type check + lint
- Upload npm package artifact
- Publish
opencode-warcraftto npm with provenance - Create GitHub Release with auto-generated release notes
| Service | Responsibility |
|---|---|
FeatureService |
Feature lifecycle: create, list, get active, update status, complete, reopen |
PlanService |
Plan CRUD and SHA-256 approval with auto-revocation on content change |
TaskService |
Task sync from plans, CRUD, dependency resolution, spec generation, scheduling |
ContextService |
Persistent markdown context files per feature (decisions, architecture, notes) |
ConfigService |
User config at ~/.config/opencode/opencode_warcraft.json with in-memory caching |
AgentsMdService |
AGENTS.md generation from codebase scanning and context file extraction |
| Component | Responsibility |
|---|---|
Store Factory |
Creates filesystem or beads stores based on beadsMode |
BeadGateway |
Low-level br CLI wrapper for all bead operations |
BeadsRepository |
High-level CRUD over beads with consistent error handling |
BvGateway |
BV (Beads Viewer) CLI adapter for planning/triage intelligence |
WorkflowIntelligenceService |
Combines BR + BV data into cached scheduling snapshots |
EventLogger |
JSONL event logger for operator observability |
OperationOutcome |
Typed result envelope with ok/degraded/fatal severity levels |
| Rule | Convention |
|---|---|
| Indent | 2 spaces |
| Quotes | Single quotes |
| Semicolons | Always |
| Trailing commas | Always |
| Line width | 120 characters |
| Imports | ESM with .js extension; import type for type-only |
| Naming | PascalCase types, camelCase functions, UPPER_SNAKE constants, kebab-case files |
| Error handling | Structured errors with codes (throw new XError(code, msg, details)) |
| Tool responses | toolSuccess() / toolError() helpers |
Symptom: warcraft_status() shows a task with status blocked
Recovery:
- Read the blocker details from
warcraft_status()output - Make a decision on how to resolve the ambiguity
- Resume the worker:
warcraft_execute({ task: '03-blocked-task', continueFrom: 'blocked', decision: 'Use approach A because ...' }) - Issue the returned
task()call
Symptom: Task remains in dispatch_prepared after a worker session ended
Recovery: Run warcraft_doctor() which detects stuck tasks and provides recovery guidance. The system includes a dispatch recovery counter (max 5 attempts) to prevent infinite loops.
Symptom: Tools fail with "beads not initialized" errors
Check:
- Verify
brCLI is installed:br --version - Initialize beads in the project:
br init - Verify config:
cat ~/.config/opencode/opencode_warcraft.json
beadsMode only selects the storage backend -- switching it doesn't change execution semantics.
# Clean and rebuild
bun run --filter warcraft-core clean && bun run --filter opencode-warcraft clean
bun run build
# Regenerate skill registry (if skills changed)
cd packages/opencode-warcraft && bun run generate-skills# Run a single test file for debugging
bun test packages/warcraft-core/src/task/task-service.test.ts
# Type check both packages
bun run lint| Document | Description |
|---|---|
| Quickstart | End-to-end workflow walkthrough |
| Plan Authoring | How to write plans that sync cleanly into tasks |
| Troubleshooting | Common issues and recovery steps |
| Warcraft Tools | Complete tool inventory |
| Data Model | Artifact layout and schemas |
| Beads Architecture | Beads subsystem deep dive with Mermaid diagrams |
| Core Package | warcraft-core services overview |
| Plugin Package | opencode-warcraft plugin reference |
| Packages Guide | Package boundary guide for contributors |
MIT with Commons Clause -- Copyright (c) 2026 minhtri2710
The Commons Clause restricts the right to "Sell" the Software: you may not provide it to third parties for a fee whose value derives entirely or substantially from the Software's functionality. All other MIT rights (use, modify, distribute, sublicense) are preserved.