@osovv/vv-opencode

Portable OpenCode workflow toolkit — one command bootstraps a managed agent ecosystem, skill-driven spec-to-code pipeline, security-and-productivity plugins, and a unified CLI.

Quick Start

bun add -g @osovv/vv-opencode
vvoc install

That's it. vvoc install pins the package, scaffolds managed agents and skills, writes canonical config, and sets vv-controller as your default OpenCode agent with auto-triggered spec, planning, and review skills.

To scope everything to the current project instead of the global OpenCode config:

vvoc install --scope project

Already installed? Run vvoc sync anytime to refresh plugins, prompts, skills, and presets.

Spec-to-Code Pipeline

The core workflow is a three-stage pipeline with independent review gates at each level:

User request
    │
    ▼ auto-trigger
vv-spec  ───────────────────────────────────────→  .vvoc/specs/*.xml
    │   Grill-me interview (one question at a time)
    │   Decision tree with recommended answers
    │   vv-analyst + vv-architect synthesis
    │
    ├── ① Spec review: requirements correct, complete, unambiguous?
    │
    ▼ auto-trigger (after approval)
vv-plan  ───────────────────────────────────────→  .vvoc/plans/*-plan.xml
    │   Interface contracts with JSDoc behavior descriptions
    │   Acceptance criteria per task (grep: `<criterion-N>`)
    │   Dependency ordering (grep: `<depends-on>`)
    │   Three-layer review model: spec → plan → code
    │
    ├── ② Plan review: every spec requirement → task? Contracts match spec?
    │
    ▼ auto-trigger (after approval)
vv-implementer → vv-spec-reviewer → vv-code-reviewer
    │   Workflow tracked loop with work items
    │   Spec review checks: code matches spec?
    │   Code review checks: implementation matches plan contracts?
    │
    ├── ③ Code review: interfaces correct? All AC pass?
    │
    ▼
Done

XML grep

Plans and specs are XML documents, making every element grep-able:

# Extract tasks from plan
grep '<task-[0-9]\+>' .vvoc/plans/*.xml

# Extract all acceptance criteria
grep '<criterion-[0-9]\+>' .vvoc/plans/*.xml

# Extract dependency graph
grep '<depends-on>task-' .vvoc/plans/*.xml

# Extract method signatures
grep '/\*\*' .vvoc/plans/*.xml

# Extract all components from plan
grep '<component>' .vvoc/plans/*.xml

All three skills are auto-triggered by vv-controller via its built-in <skill_trigger_rule> — no slash commands needed. The controller checks whether vv-spec, vv-plan, or vv-review applies before routing any request.

Why vv-opencode?

Setting up OpenCode for serious daily work means juggling config files, agent prompts, plugin wiring, model role assignments, and permission rules — every time, on every machine.

vv-opencode collapses that into a single vvoc install. It owns the wiring so you don't have to:

• Six plugins, one entry — all plugins are exported from a single pinned package entry
• Managed agent & skill system — vv-controller auto-triggers vv-spec, vv-plan, and vv-review skills before routing to domain-specialized subagents
• Model roles & presets — assign models to roles (smart, fast, vision, …) and switch provider presets with one command
• Security-first — a guardian agent reviews permission requests, secrets are redacted from LLM-bound chat
• Stale-line-number defense — hashline-backed edit prevents write-against-wrong-snapshot bugs

Features

The Six Plugins

CLI at a Glance

Model Roles & Presets

# View current assignments
vvoc role list

# Assign models to roles
vvoc role set default openai/gpt-5.4
vvoc role set smart openai/vv-gpt-5.5-xhigh
vvoc role set fast openai/gpt-5.4-mini

# Switch provider presets
vvoc preset vv-openai
vvoc preset vv-zai
vvoc preset vv-deepseek
vvoc preset vv-minimax
vvoc preset vv-osovv

Built-in role IDs: default, smart, fast, vision + any custom lowercase-hyphenated IDs.

Presets are partial — applying one only changes the roles it defines. Managed built-in presets (vv-*) are refreshed on every vvoc install/vvoc sync; user-defined presets are preserved as-is.

Config & Data Layout

OpenCode config          → OpenCode-managed paths (global or project)
vvoc.json (canonical)    → $XDG_CONFIG_HOME/vvoc/vvoc.json
Managed agent prompts    → $XDG_CONFIG_HOME/vvoc/agents/*.md  (global)
                           ./.vvoc/agents/*.md                 (project)
Managed skills           → $XDG_CONFIG_HOME/vvoc/skills/*/SKILL.md  (global)
                           ./.vvoc/skills/*/SKILL.md               (project)
Spec documents           → ./.vvoc/specs/*
Planning artifacts       → ./.vvoc/plans/*
Persisted data           → $XDG_DATA_HOME/vvoc/

Schema is versioned and published with the package — source of truth at schemas/vvoc/v3.json.

Managed Agents

All prompt files are scaffolded by vvoc install / vvoc sync:

Managed Skills

Three XML-based skills are scaffolded alongside agents:

Skills are loaded by OpenCode at session start through config.skills.paths (registered by the SystemContextInjectionPlugin). The vv-controller agent's <skill_trigger_rule> ensures they are invoked automatically when the user's request matches their trigger conditions.

Local Development

bun install             # Install dependencies
bun run check           # Typecheck + lint + format check + test
bun run fmt             # Auto-format source files

Git hooks managed via lefthook.

Smoke-test the built CLI

tmpdir="$(mktemp -d)"
bun run build
bun dist/cli.js install --config-dir "$tmpdir"
bun dist/cli.js status --config-dir "$tmpdir"

Full release verification

bun run check
bun run build
bun run pack:check

Publishing

bun run check && bun run build && npm publish

Publishing is manual from the terminal. No CI publish workflows.

Optional: RTK

RTK is a CLI proxy that reduces token usage for common developer commands. The interactive vvoc init flow recommends it after setup.