Turn an idea or existing system into ambiguity-free requirements, grounded specifications, executable plans, verified code, and durable project state.

Skills

Skill	Purpose
`make-requirements`	Formal requirements from an idea — multi-phase discovery, Zero-Ambiguity Gate
`retro-requirements`	Reverse-engineer an existing codebase into structured requirements
`grill-me`	Deep disambiguation interview before planning or requirements
`make-plan`	Multi-document implementation plan from requirements
`preflight`	13-dimension quality audit of any plan, requirements, or artifact
`exec-plan`	Execute a plan — implement → verify → commit loop with quality reviews
`roadmap`	Live feature-set roadmap — make, update, review, archive
`analyze-project`	Analyze repo and create/refresh CodeOps-aware `AGENTS.md` guidance
`analyze-agents`	Run the project-level specialist check on demand — proposals or a recorded None, with check state
`setup-codeops`	Set up or migrate CodeOps in a git repo
`setup-routing`	Configure per-role subagent model and policy routing
`upgrade-plan`	Upgrade legacy CodeOps artifacts to current schema
`techdocs`	VitePress-compatible architecture docs and ADRs
`github-issues`	Read and manage GitHub issues via `gh` CLI
`clean-comments`	Audit and clean source comments without changing behavior
`git-commit`	Guarded commit — verify, stage deliberately, Conventional Commit message
`outcome-review`	Review local opt-in outcome metrics (requires `metrics.enabled: true`)

Installation

One command installs everything CodeOps owns: the skills, the subagents, and the OpenCode plugin entry in your config.

# Global (recommended) — available in every OpenCode project
curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash

# Project-only — files live in ./.opencode and are committed with the repo
curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash -s -- --project

The same installer runs directly through npm:

npx -y opencode-codeops@latest install
npx -y opencode-codeops@latest update    # alias of install

install/update writes the skills and subagents onto the filesystem (OpenCode discovers those only from disk), then registers the plugin in the OpenCode config by calling OpenCode 2's own opencode plugin add command, so standards injection and CODEOPS_PLUGIN_ROOT are enabled. Restart OpenCode after installing for the plugin to load. Pass --no-plugin to manage the config yourself.

The installer also places the shared _shared/ and references/ documents beside the installed skills/ directory (for example ~/.config/opencode/_shared), so the skills' relative links to them resolve at their installed location. An existing directory with either name is only replaced with --force.

The scope is auto-detected: inside a CodeOps project (a git repo with .opencode/ or codeops/.codeops.yml) it installs into ./.opencode and registers the plugin in the project config; anywhere else it installs globally into ~/.config/opencode and the global config. Pass --project or --global to force one. OpenCode 2's CLI manages package plugins globally, so a project-scope install registers the plugin globally with a note while the skills and agents stay project-scoped.

If you prefer to register the plugin manually instead, add it to your opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["opencode-codeops"]
}

Pin a version with CODEOPS_VERSION (an npm dist-tag or exact version; defaults to latest):

CODEOPS_VERSION=1.6.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash

install/update pins the plugin in the OpenCode config to the installer's own version, so the plugin and the installed files cannot drift apart; run update to move both to a new version.

Re-running the installer upgrades an existing install in place. It replaces only the files this package owns, recorded in .opencode-codeops.json. Files you author yourself, or install with another tool, are left untouched.

Check or remove an install:

npx -y opencode-codeops@latest status
npx -y opencode-codeops@latest uninstall

status reports the installed skills and agents versions and the configured plugin entry, so a mismatch is visible. Use --dry-run to preview an install; a same-named file the package does not own is skipped with a warning, and --force replaces it. uninstall removes the skills and subagents but leaves the plugin entry in your config; remove opencode-codeops from the plugins array by hand to fully disable it.

Local development

OpenCode 2's opencode plugin add accepts npm or Git package specifiers only, so a checkout is loaded through a local plugin file. Place a one-line re-export in a plugin directory and link the installed files to the checkout so edits are picked up without reinstalling:

# Plugin — project scope (use ~/.config/opencode/plugins/ for every project)
mkdir -p .opencode/plugins
printf 'export { default } from "%s/plugin/index.ts"\n' "$PWD" > .opencode/plugins/codeops.ts

# Skills and agents — link instead of copy
node bin/index.mjs install --link --global --no-plugin

Pass --no-plugin so the checkout entry is not overwritten by a registered npm plugin.

Setup

After installing the plugin and the files, initialize CodeOps in your project:

/setup-codeops

This creates the codeops/ layout, scaffolds codeops/codeops.json and codeops/.codeops.yml, installs the skills and the 12 CodeOps subagent files into .opencode/, and adds a managed section to AGENTS.md.

Commit the result:

git add codeops/ .opencode/ AGENTS.md
git commit -m "chore: initialize CodeOps"

What the plugin does automatically

The plugin adds the CodeOps standards to every model request as system instructions, and also to every compaction summary, so they are always active:

standards/coding-standards.md — coding quality, security, testing, and working-style rules
standards/output-style.md — how to report findings, format tables, and recommend next steps

These standards are active without any user action. They do not need to be copied into AGENTS.md.

The plugin also warns (non-blocking) if any tool attempts to edit codeops/.codeops.yml directly — that file is managed exclusively by the setup-codeops skill — and if the installed skills version differs from the plugin version, so a stale install is visible.

Every session also gets a workspace-hygiene guard: the plugin exports CODEOPS_TMPDIR, a scratch directory under the OS temp directory that belongs to the running OpenCode plugin instance. Skills and agents put temporary files there and delete them when the run completes; the plugin sweeps directories abandoned by interrupted runs at startup (older than seven days), so CodeOps does not accumulate scratch data. Because OpenCode 2 does not expose a session id to shell hooks, concurrent sessions served by one instance share this directory, and no session's scratch is deleted while others may still use it. The full protocol is in _shared/workspace-hygiene.md.

Live task progress in the sidebar

While an exec-plan run is active, the sidebar shows the current run — plan, phase, task, activity (starting, implementing, verifying, reviewing, delegating, blocked, waiting, done), and the verified-task count — reported by the agent through the codeops_progress tool. The view is intentionally honest: it always shows an "as of" time; a run with no update for 10 minutes is marked "stale" instead of looking live; and nothing renders when no run is active, when the host lacks the plugin APIs, or when every call fails. The Markdown execution plan remains the single progress source of truth; the live view never gates execution.

Agent model configuration

All CodeOps subagents inherit the model of the primary agent that invoked them. No provider-specific configuration is required out of the box.

To pin specific models per role, use the setup-routing skill or add overrides directly in opencode.jsonc:

{
  "agents": {
    "demanding-executor": { "model": "anthropic/claude-opus-4-5" },
    "executor":           { "model": "anthropic/claude-haiku-4" }
  }
}

Adaptive reasoning effort

CodeOps can pick a reasoning level per dispatch instead of always inheriting the parent session's variant. A dispatch packet may carry one standalone marker line:

[codeops-effort: medium]

Reasoning-heavy skills also accept --auto-effort (use the skill's recommended level) or --auto-effort=high (explicit level), announce it, and clear it before the final run summary. Resolution order: dispatch marker, then session --auto-effort, then routing.roles.<agent>.reasoning in codeops/codeops.json, then the inherited parent variant. A level the active model does not expose resolves to the nearest exposed variant (medium becomes high on a low/high/max model). The levels are suggestions: no permission, verification step, or review gate ever reads them. The full contract is in _shared/reasoning-effort.md.

Project specialists

CodeOps can recommend project-specific specialist subagents when repository evidence shows a capability gap the twelve catalog roles and dynamic packets cannot close. Specialists are created only with your explicit approval — the --auto-design mode cannot approve them.

Detect — make-requirements, make-plan, and analyze-project run an evidence-based check and record the outcome (including a negative one); the analyze-agents skill runs the same check on demand and maintains codeops/specialist-check.json for the coverage line. At most two candidates per scope surface as lightweight, evidence-backed proposals; the creation gate applies when you choose to proceed.
Create — after you approve the candidate packet, setup-routing writes a brief at codeops/specialists/<role>.md, writes routing policy first, generates a visible agent with install_agents.py --custom <role>, and updates a managed index block in AGENTS.md with --sync-agents-md.
Route — a plan's ## Specialist Agents table maps roles to phases. During exec-plan, listed specialists are dispatched as additional reviewers or executors: they never replace a required reviewer or gate, reviewer findings use the SR-NNN prefix, and the generated agent defaults to reasoningEffort: max (override it with routing.roles.<role>.reasoning).
Fallback — a specialist is available as soon as its generated agent exists; OpenCode's discovery timing is whatever your build provides. If it is missing, invalid, or a dispatch fails, dispatch falls back to a generic subagent carrying the brief excerpt and reports the fallback. No review depends on a specialist existing.

Lifecycle checks: --check reports INVALID, MISSING, STALE, ORPHAN, HAND-AUTHORED, and AGENTS.md states; --remove-custom <role> --yes deletes the generated agent and its brief and updates the index.

Upgrading: specialist agents embed the generic template contract. When a newer plugin changes those templates, --check reports the agent as STALE; re-run python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --custom <role> (then --sync-agents-md) to regenerate it.

Requirements

OpenCode 2.0+ (this release uses the OpenCode 2 plugin API; on OpenCode 1, use opencode-codeops@1)
Bash
Python 3.8+
Git
Node.js 18+ (for the npx installer; Bun is used by OpenCode to load the plugin)
gh CLI (for the github-issues skill only)