@wpro-eng/opencode-config

Wpromote's proprietary OpenCode plugin that keeps team developers' configurations in lockstep. This repo contains both the plugin code AND the team's shared skills, agents, commands, plugins, instructions, and MCP configs.

How It Works

When installed, this plugin:

1. Discovers team assets bundled in the npm package
2. Installs team skills, plugins, and MCPs via symlinks to your OpenCode config
3. Injects team agents, commands, and instructions into OpenCode's runtime config
4. Respects your local overrides and explicit disables

Priority Order

1. Your local configs — always win
2. Team configs — fill in the gaps

Installation

1. Add to your OpenCode config

In ~/.config/opencode/opencode.json:

{
  "plugin": ["@wpro-eng/opencode-config"]
}

2. Restart OpenCode

The plugin will automatically discover and install team assets on startup.

Configuration

Create ~/.config/opencode/wpromote.json (or for project-level .opencode/wpromote.json):

{
  "disable": ["skill:example", "agent:verbose-debugger"],
  "installMethod": "link"
}

Options

| Option | Type | Default | Description | | --------------- | --------------------------- | --------------- | ----------------------------------------------------------- | | disable | string[] | [] | Assets to disable (see below) | | installMethod | "link" | "copy" | "link" | How to install skills/plugins/MCPs | | agentNames | "lotr" | "descriptive" | "descriptive" | Agent naming theme (see below) | | orchestration | object | defaults | Runtime orchestration controls, limits, and fallback policy |

Agent Name Themes

Agents can be displayed with either plain role-based names or Tolkien character names. Set agentNames in your config:

{
  "agentNames": "lotr"
}

| Role | "descriptive" (default) | "lotr" | | ------------ | ------------------------- | ------------- | | Orchestrator | orchestrator | gandalf | | Explorer | explorer | legolas | | Researcher | researcher | radagast | | Planner | planner | treebeard | | Implementer | implementer | celebrimbor | | Architect | architect | elrond | | Analyst | analyst | galadriel | | TDD | tdd | aragorn | | Deep Work | deepwork | samwise |

The theme affects agent names everywhere: in the agent list, slash commands, delegation routing, and cross-references between agents. Agent markdown files use template variables (e.g. {{explorer}}) so cross-references resolve correctly regardless of theme.

When using the disable list, use the themed name (the name that appears after applying your chosen theme). For example, with "descriptive" theme, disable with "agent:orchestrator" instead of "agent:gandalf".

Orchestration Runtime Configuration

All fields below show their defaults. You only need to include fields you want to override.

{
  "orchestration": {
    "providerMode": "copilot",
    "features": {
      "delegation": true,
      "diagnostics": true,
      "vision": true,
      "continuousLoop": true,
      "selfHealing": true
    },
    "limits": {
      "maxConcurrent": 3,
      "maxRetries": 2,
      "maxIterations": 25,
      "retryBackoffMs": 1500,
      "taskTimeoutMs": 120000
    },
    "runtimeFallback": {
      "enabled": true,
      "retryOnErrors": [400, 401, 403, 408, 429, 500, 502, 503, 504, 529],
      "maxFallbackAttempts": 2,
      "cooldownSeconds": 30,
      "timeoutSeconds": 30,
      "notifyOnFallback": true,
      "providerOrder": ["copilot", "native"]
    },
    "hooks": {
      "disabled": [],
      "telemetry": true
    },
    "notifications": {
      "enabled": true,
      "maxItems": 100
    },
    "categories": {
      "routing": {},
      "maxConcurrent": {}
    },
    "recovery": {
      "autoResumeOnStart": true
    },
    "tmux": {
      "enabled": false,
      "sessionPrefix": "wpo"
    }
  }
}

Tmux support is optional and only active when orchestration.tmux.enabled is true and OpenCode is running inside a tmux session. When enabled, a dedicated tmux session ({sessionPrefix}-{opencode-session-id}) is created for each OpenCode session, and each subagent task gets its own window inside that session. Windows are automatically cleaned up when tasks complete, fail, stop, or parent sessions end. Use tmux switch-client -t wpo-* to peek at agent work.

Feature flags (orchestration.features) toggle individual orchestration capabilities. Set any to false to disable that feature while keeping the rest active.

Category policies are optional. Use orchestration.categories.routing to override provider mode per task category (for example, "quick": "native") and orchestration.categories.maxConcurrent to cap active tasks per category (for example, "quick": 1).

Recovery policies are optional. orchestration.recovery.autoResumeOnStart controls whether queued/running/retrying task records from prior sessions are automatically restored into queued state on startup.

Note: Configuration changes take effect on restart. After modifying your config, restart OpenCode to apply the changes.

Disable Syntax

{
  "disable": [
    "skill:verbose-logger", // Disable specific skill
    "agent:heavy-model", // Disable specific agent
    "command:dangerous-cmd", // Disable specific command
    "plugin:auto-formatter", // Disable specific plugin
    "instruction:old-guide", // Disable specific instruction
    "mcp:expensive-api", // Disable specific MCP
    "deprecated-thing" // Disable across ALL types (bare name)
  ]
}

Overriding Team Configs

The plugin respects local configurations. Your local settings always take precedence over team defaults.

Override Priority

1. Your local OpenCode config (opencode.json)     ← Highest priority
2. Explicit disable list (wpromote.json)
3. Local skill directories (~/.config/opencode/skill/<name>/)
4. Team configuration from this repo               ← Lowest priority

By Asset Type

| Asset Type | How to Override | How to Disable | | --------------- | ------------------------------------------------------------- | -------------------------------------- | | Skill | Create ~/.config/opencode/skill/<name>/SKILL.md | "skill:<name>" in disable list | | Agent | Add to opencode.json: { "agents": { "<name>": {...} } } | "agent:<name>" in disable list | | Command | Add to opencode.json: { "commands": { "<name>": {...} } } | "command:<name>" in disable list | | Plugin | Disable team plugin, add your own to plugins directory | "plugin:<name>" in disable list | | Instruction | Cannot override (only append). Disable and add your own. | "instruction:<name>" in disable list | | MCP | Add to opencode.json MCP config section | "mcp:<name>" in disable list |

Examples

Override a team agent with different settings:

// ~/.config/opencode/opencode.json
{
  "agents": {
    "team-agent": {
      "model": "claude-sonnet-4-20250514",
      "temperature": 0.5
    }
  }
}

Disable multiple team assets:

// ~/.config/opencode/wpromote.json
{
  "disable": [
    "skill:verbose-logger",
    "agent:heavy-model",
    "instruction:old-conventions"
  ]
}

Override a skill with your own version:

# Create your local skill directory
mkdir -p ~/.config/opencode/skill/my-skill

# Add your SKILL.md
cat > ~/.config/opencode/skill/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: My customized version
---
Your custom skill content here...
EOF

Completely disable a skill you don't use:

// ~/.config/opencode/wpromote.json
{
  "disable": ["skill:unused-skill"]
}

What's Included

Agents (agent/)

Pre-configured agent definitions with model, temperature, and system prompts. There are three primary agents (you talk to them directly) and seven subagents (they run in the background, delegated by the primary agent). The planner is available as both. Names shown below use the default "descriptive" theme, with "lotr" names in parentheses.

Primary Agents

| Agent | Model | What it does | | -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | orchestrator (gandalf) | Claude Opus 4 | The default orchestrator. Classifies your request, breaks it into tasks, delegates to the right subagents in parallel, and assembles the final result. Handles everything from quick fixes to multi-step projects. | | deepwork (samwise) | Claude Opus 4 | A higher-rigor variant for long-running complex work. Runs a sustained execution loop with tighter milestone verification, aggressive parallelism, and continuous health monitoring. Use when a task needs hours of autonomous work without hand-holding. | | planner (treebeard) | GPT-5.4 | Read-only planning and analysis agent. Can explore codebases, search the web, and run safe shell commands, but cannot edit files or run mutating commands. Use directly when you want to think through a problem, review a plan, or explore before committing to changes. Also available as a subagent for delegation. |

Subagents

| Agent | Model | When called | What it does | | ----------------------------- | ----------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | explorer (legolas) | Claude Sonnet 4.6 | "Where is X in the codebase?" | Searches the repo fast. Uses LSP, grep, glob, and git to find files, symbols, call paths, and code patterns. Returns structured results with absolute paths and a direct answer, not just a file list. Read-only by default. | | researcher (radagast) | GPT-5.2 | "How does library X work?" | Researches external docs, OSS repos, and the web. Classifies the question (conceptual, implementation, history, or comprehensive), fetches official sources, and returns evidence-backed recommendations with links. | | implementer (celebrimbor) | GPT-5.2 Codex | "Build this end-to-end." | The workhorse implementation agent. Operates like a senior staff engineer: explores context, plans edits, executes changes, runs tests, and iterates until done. Does not stop at partial progress or ask permission for normal engineering work. | | architect (elrond) | GPT-5.2 | "What's the right architecture?" | Read-only strategic advisor. Analyzes codebases, evaluates tradeoffs, and returns a bottom-line recommendation with an action plan and effort estimate. Biases toward simplicity and existing patterns over speculative complexity. | | analyst (galadriel) | Gemini 3.1 Pro | "What's in this image/PDF?" | Multimodal analysis specialist. Handles PDFs, images, diagrams, and charts that other agents cannot process as plain text. Extracts targeted information and returns concise findings with confidence notes. Also serves as the backend for the vision tool. | | tdd (aragorn) | GPT-5.2 Codex | "Write tests for this." | Strict TDD specialist following Red-Green-Refactor. Writes a failing test first, makes it pass with minimal code, then refactors under green. Produces a test plan, TDD log, execution results, and a quality scorecard. Never writes production code without a failing test. |

Commands (command/)

Slash commands available to all team members.

| Command | Description | | --------------------- | ---------------------------------------------------------------- | | /continue | Enable continuous deepwork loop for current session | | /stop | Stop continuous loop and halt queued orchestration work | | /tasks | List active and recent subagent orchestration tasks | | /task | Show details for one subagent orchestration task | | /diagnostics | Run orchestration diagnostics with live delegation probes | | /doctor | Run deep orchestration doctor checks with actionable remediation | | /test-orchestration | Run a parallel subagent delegation torture test audit | | /wpromote-status | Show status for wpromote team config | | /wpromote-list | List all team assets from wpromote config | | /wpromote-cleanup | Remove stale cache files, broken symlinks, and unused plugins | | /example | Example command demonstrating the expected format |

Skills (skill/)

Reusable skill files that agents can load. Each skill is a directory containing SKILL.md with YAML frontmatter.

| Skill | Description | | -------------------- | ------------------------------------------------------------------------------ | | orchestration-core | Continuous loop orchestration, delegation visibility, and diagnostics workflow | | readme-editor | Craft professional README.md files for GitHub open source projects | | example | Example skill demonstrating the expected format |

Plugins (plugin/)

OpenCode hook plugins for team-wide automation.

| Plugin | Description | | ------------------------ | -------------------------------------------------------------------------------- | | wpromote-orchestration | Orchestration runtime: task tracking, tmux sessions, provider fallback, recovery | | vision-tool | Multimodal analysis via Gemini: bypasses Claude's 8000px image limit |

Instructions (instruction/)

Markdown files automatically appended to agent context (registered in manifest.json).

| Instruction | Description | | ----------------------- | ----------------------------------------------------------- | | getting-started | Quick start guide for Wpromote OpenCode | | team-conventions | Code style, git workflow, and contribution conventions | | orchestration-runtime | Orchestration controls, delegation discipline, tmux runtime |

MCPs (mcp/)

Model Context Protocol server configurations.

| MCP | Type | Endpoint | | ----------------- | ------ | -------------------------------- | | chrome-devtools | local | npx chrome-devtools-mcp@latest | | context7 | remote | https://mcp.context7.com/mcp | | exa | remote | https://mcp.exa.ai/mcp |

Development

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun test

# Type check
bun run typecheck

# Link for local testing
npm link

Adding New Configs

See CONTRIBUTING.md for how to add new skills, agents, commands, and more.

Version Pinning

The team asset version is tied to the installed plugin version. To pin to a specific version:

npm install -g @wpro-eng/[email protected]

Check the releases for available versions.

Installed Asset Locations

• Skills: ~/.config/opencode/skill/_plugins/opencode-config/
• Plugins: ~/.config/opencode/plugins/_remote_opencode-config_*.ts
• MCPs: ~/.config/opencode/mcp/_plugins/opencode-config/

Troubleshooting

Quick fixes for common issues:

| Issue | Solution | | -------------------- | ---------------------------------------------------------------- | | Asset not appearing | Check disable list in wpromote.json | | Override not working | Verify exact name match (case-sensitive) | | Stale installs | Delete ~/.config/opencode/skill/_plugins and restart | | Plugin not loading | Verify @wpro-eng/opencode-config is in opencode.json plugins |

For detailed troubleshooting, see TROUBLESHOOTING.md.

License

Proprietary - Wpromote Internal Use Only