opencode-missions

OpenCode plugin for mission planning, delegated feature execution, structured worker handoffs, and milestone validation. It re-implements the mission lifecycle locally and does not require Droid CLI, Factory runtime files, or any external mission service.

What it provides

• OpenCode mission tools for creating, planning, running, pausing, resuming, and completing missions
• One-worker-at-a-time feature delegation through OpenCode child sessions
• Structured worker handoffs with verification evidence, test coverage notes, and discovered issues
• Automatic scrutiny and user-testing validator features after each completed milestone
• Completion gates that block unresolved handoff items, failed validation assertions, and missing milestone validators
• Optional /mission command, orchestrator agent, worker agent, validator agents, and mission orchestration skill
• Global mission state under Factory-compatible storage when Droid is installed, or OpenCode storage otherwise

Install

For the fastest setup in the current project:

npm install -g opencode-missions
opencode-missions install

Then add the npm plugin to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-missions@latest"]
}

For a different project directory:

opencode-missions install /path/to/project

The install command is idempotent. It copies optional OpenCode assets into the project:

• opencode/agents/* to .opencode/agents/
• opencode/commands/* to .opencode/commands/
• opencode/skills/* to .opencode/skills/

OpenCode installs npm plugins automatically with Bun at startup after the package is listed in config.

Manual config

If you do not want the optional assets, only add the plugin entry:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-missions@latest"]
}

If you want the included /mission command and agent presets without using the installer, copy the package opencode/agents, opencode/commands, and opencode/skills directories into your project's .opencode/ directory.

Usage

After enabling the plugin, use the mission tools directly or install the included /mission command and mission agents:

/mission Build and validate the requested feature through mission mode.

The orchestrator creates a mission workspace, writes mission artifacts and feature plans, starts one worker per feature, receives structured handoffs, injects milestone validators, and refuses completion until implementation and validation work are complete.

Mission state is stored under:

~/.factory/missions/

when a droid executable is available on PATH. If Droid is not installed, the plugin falls back to:

~/.opencode/missions/

FACTORY_HOME_OVERRIDE is respected for isolated development and tests. When Factory environment variables indicate a non-production environment and droid is installed, the Factory-compatible root is ~/.factory-dev/missions/.

Missions created by earlier versions under project-local .opencode/droid-missions/missions/ are not moved automatically. Move or recreate those missions explicitly if you need them in global storage.

Local development install

From this repo:

bun install
bun run build
npm pack

Then point OpenCode at the packed tarball through the plugin array:

{
  "plugin": ["opencode-missions@file:/absolute/path/opencode-missions-0.1.0.tgz"]
}

Direct local source installs are useful for debugging, but npm/tarball installs better match how OpenCode resolves plugin dependencies.

Tools

• droid_mission_create
• droid_mission_write_artifact
• droid_mission_write_features
• droid_mission_start
• droid_mission_end_feature
• droid_mission_pause
• droid_mission_status
• droid_mission_complete
• droid_mission_dismiss_handoff_items
• droid_mission_list

Development

bun install
bun run test
bun run typecheck
bun run build
bun run check:no-droid
bun run ci

Release

npm version patch
git push --follow-tags
npm publish --access public

Troubleshooting

• Mission tools are not visible: confirm opencode.json contains "plugin": ["opencode-missions@latest"], then restart OpenCode.
• /mission is not visible: run opencode-missions install in the project root or copy the optional assets manually.
• A mission will not complete: run droid_mission_status and resolve pending features, validation features, handoff issues, or validation-state assertions.
• Direct edits to mission state fail: use the mission tools instead of editing global mission system files such as state.json, features.json, or progress_log.jsonl.
• Local tarball install cannot find dependencies: use npm pack and reference the packed .tgz, or install from npm with opencode-missions@latest.