Curated, opinionated OpenCode plugin set for spec-first, review-driven, safer agentic development — with managed agents, skills, safety plugins, and the vvoc CLI.
bun add -g @osovv/vv-opencode
vvoc installThat'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, review, and reflection skills.
To scope everything to the current project instead of the global OpenCode config:
vvoc install --scope project
vvoc launch --scope projectProject scope writes only to ./.opencode/ and ./.vvoc/. A normal opencode launch may still apply OpenCode's native config discovery and merge behavior; vvoc launch --scope project is the hard sandbox path and starts OpenCode with OPENCODE_CONFIG and VVOC_CONFIG pinned to those local files, so you can smoke-test vv-opencode in one repository without mutating your primary global setup.
Already installed? Run
vvoc syncanytime to refresh plugins, prompts, skills, and presets.
vvoc keeps larger agentic work from jumping straight into edits. The process turns a request into explicit artifacts first, then executes the approved plan with bounded implementation and review loops.
Request / idea
↓
vv-spec
asks clarifying questions
writes .vvoc/specs/<id>/spec.xml
waits for spec approval
↓
vv-plan
reads the approved spec
writes .vvoc/specs/<id>/plan.xml
defines tasks, contracts, dependencies, and acceptance criteria
waits for plan approval
↓
vv-execute
applies the approved plan task by task
runs implementation + review internally
verifies before moving on
↓
Verified result
Inside vv-execute:
Each plan task
↓
vv-implementer
implements the focused task and runs targeted verification
↓
vv-spec-reviewer
checks whether the result matches the approved spec
↓
vv-code-reviewer
checks bugs, regressions, maintainability, and missing tests
↓
verification
pass → next task
fail → bounded retry loop
needs context / blocked → stop and ask the user
All artifacts for one feature live together:
.vvoc/specs/<id>/
spec.xml # what should be built and why
design-context.xml # optional design memory
plan.xml # how to implement and verify it
Specs and plans use a top-level lifecycle status: draft while being written, approved after explicit user approval, and applied after successful execution. vv-execute archives applied artifact packages by moving the entire spec package directory .vvoc/specs/<id>/ to .vvoc/specs/archive/<id>-<timestamp>/.
Plans and specs are XML documents, making every element grep-able:
# Extract tasks from plan
grep '<id>T-' .vvoc/specs/*/plan.xml
# Extract all acceptance criteria
grep '<criterion>' .vvoc/specs/*/plan.xml
# Extract dependency graph
grep '<task_id>' .vvoc/specs/*/plan.xml
# Extract method signatures
grep '/\*\*' .vvoc/specs/*/plan.xml
# Extract all modules from architecture
grep '<name>' .vvoc/specs/*/plan.xmlManaged skills are installed by vvoc. vv-controller explicitly routes vv-spec, vv-plan, and vv-review; vv-execute and vv-reflect are available as managed skills for plan execution and durable session memory.
OpenCode is a strong, flexible base for agentic coding, but it intentionally leaves the development process mostly up to you: when to clarify requirements, when to plan, when to investigate first, when to review, and how to keep longer runs safe. That flexibility is powerful, but it can also make agent work feel loose and inconsistent.
vv-opencode adds a curated process layer on top of OpenCode:
- Formalized trajectories — small changes stay direct, unclear bugs start with investigation, large changes go through spec and plan, and risky implementation uses review loops
- Spec-first by default — turn broad requests into explicit specs, plans, and review gates before implementation
- Review-driven execution — keep implementation, spec review, and code review as separate steps instead of one agent silently doing everything
- Portable model choices — use roles like
vv-role:smartandvv-role:fastin shared agents, then map those roles per machine or project - Long-run safety — Guardian auto-approves routine low-risk permission requests, leaves risky ones to OpenCode's manual approval flow, and secrets redaction reduces accidental leakage
- Safer edits — hashline-backed
editties changes to freshreadoutput so agents are less likely to write against stale line numbers
| Area | What you get |
|---|---|
| Plugins | A curated set of OpenCode plugins that make agentic work more structured, portable, and safer without hand-wiring each piece yourself |
| Agent System | A default controller that picks the right path: direct changes for small work, investigation before unclear fixes, and implementer/reviewer loops for risky changes |
| Skills | Guided workflows for turning ideas into specs, specs into plans, plans into execution, reviews into findings, and long sessions into reusable memory |
| Spec-to-Code Pipeline | A repeatable path from request → spec → plan → implementation → review, so agents do not silently skip requirements or acceptance criteria |
| One-Click Setup | Recreate the same opinionated workflow on a new machine or project with vvoc install / vvoc sync |
| CLI Tooling | Operate and diagnose the setup from one CLI: install, sync, launch, status, doctor, roles, presets, plugin toggles, completion, and upgrade |
| Long-Run Safety | Guardian keeps safe long/AFK runs moving by auto-approving routine low-risk permissions, while risky actions stay in OpenCode's manual approval flow; secrets redaction reduces accidental leakage |
| Model Roles | Put roles like vv-role:smart or vv-role:fast in shared agents and skills instead of hardcoded model IDs, then choose provider/model mappings per environment |
| Workflow Tracking | Replace free-form multi-agent chaos with explicit work items, bounded review rounds, reviewer result collection, and hard stops when more context is needed |
| Plugin | What it helps you do |
|---|---|
| WorkflowPlugin | Keep multi-agent work structured with explicit work items, bounded implementation/review loops, reviewer result collection, and safe stops when more context is needed. |
| ModelRolesPlugin | Use semantic model roles instead of hardcoded model IDs in OpenCode agents, subagents, and command configs — e.g. vv-role:smart, vv-role:fast — then map those roles per machine or project. |
| GuardianPlugin | Keep long or AFK agent runs moving by auto-approving routine low-risk permission requests. If something looks risky, Guardian does not auto-approve it and leaves the decision to OpenCode's normal manual approval flow. |
| HashlineEditPlugin | Make agent edits safer by tying changes to fresh read output, reducing wrong-line and stale-context edits. |
| SystemContextInjectionPlugin | Give primary agents the vvoc workflow rules and skill discovery automatically, while keeping subagents focused and avoiding prompt pollution. |
| SecretsRedactionPlugin | Reduce accidental secret leakage by redacting tokens, keys, emails, and other sensitive values before messages are sent to the model. |
Workflow work items are opened with explicit intent. For implementation loops, controllers use:
{
"items": [
{
"key": "implement-feature",
"title": "Implement feature",
"mode": "implementation",
"requiredReviewers": ["spec", "code"]
}
]
}For review-only reports, use "mode": "review_only". In review-only mode, reviewer FAIL is a completed finding result: required reviewers are collected independently, parallel spec and code reviewers may both return FAIL, and the item does not route to vv-implementer unless the user explicitly requests fixes.
| Command | Purpose |
|---|---|
vvoc init |
Interactive bootstrap flow |
vvoc install |
Non-interactive setup and scaffolding |
vvoc sync |
Refresh plugin entry, agents, prompts, skills, config |
vvoc launch |
Launch OpenCode with deterministic OPENCODE_CONFIG and VVOC_CONFIG sources |
vvoc status |
Show current installation state |
vvoc doctor |
Diagnose setup problems (exits non-zero on issues) |
vvoc config validate |
Validate canonical vvoc.json |
vvoc role list|set|unset |
Manage model role assignments |
vvoc preset list|show|<name> |
Inspect or apply named presets |
vvoc guardian config |
Print or write guardian section |
vvoc plugin list |
List OpenCode plugin entries |
vvoc plugin enable|disable |
Toggle a vvoc-managed plugin on or off |
vvoc patch-provider stepfun-ai|zai|openai |
Patch an OpenCode provider preset in global or project scope |
vvoc completion |
Install shell completions |
vvoc upgrade |
Upgrade global package and run follow-up sync; sync failure is reported as a partial upgrade |
vvoc version |
Print installed version |
# View current assignments
vvoc role list
vvoc role list --scope effective
# Assign models to roles
vvoc role set default openai/gpt-5.4
vvoc role set team-review anthropic/claude-sonnet-4-5 --scope project
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
vvoc preset vv-osovv-cheapBuilt-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.
Mutating commands default to global for backward compatibility. Add --scope project to write a project-local layer. Read/diagnostic commands accept --scope global|project|effective, where effective resolves in this order:
- explicit env override (
VVOC_CONFIG/OPENCODE_CONFIG) - nearest project layer
- global layer
- built-in defaults when the command/runtime permits defaults
Canonical project-local paths:
OpenCode config → ./.opencode/opencode.json(c)
vvoc config → ./.vvoc/vvoc.json
Managed agent prompts → ./.vvoc/agents/*.md
Managed skills → ./.vvoc/skills/*/SKILL.md
Spec package directory → ./.vvoc/specs/<id>/
spec.xml # normative spec document (required)
design-context.xml # curated design memory (optional)
plan.xml # implementation plan (created by vv-plan)
Legacy root-level ./opencode.json and ./opencode.jsonc are intentionally not used as vvoc project layers.
Global OpenCode config → $XDG_CONFIG_HOME/opencode/opencode.json
Global vvoc config → $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/<id>/spec.xml
Optional design context → ./.vvoc/specs/<id>/design-context.xml
Implementation plans → ./.vvoc/specs/<id>/plan.xml
Persisted data → $XDG_DATA_HOME/vvoc/
Repository memory → ./.vvoc/lessons/*.xml (lazy vv-reflect fallback)
./.vvoc/runbooks/*.xml (lazy vv-reflect fallback)
Schema is versioned and published with the package — source of truth at schemas/vvoc/v3.json. The current config contract is strict: vvoc.json must be canonical version 3 and include required sections such as plugins. Existing v1/v2/pre-role, incomplete, malformed, or otherwise invalid config files fail instead of being migrated or repaired. vvoc install and vvoc sync may create a fresh canonical config when no config exists, but they refuse to rewrite an invalid existing vvoc.json; fix the file manually and rerun vvoc sync.
vvoc status and vvoc doctor are diagnostic exceptions: they report the selected config path and validation problem without normalizing or rewriting the file. vvoc upgrade can still finish the package installation when the follow-up vvoc sync fails; in that case it reports a partial upgrade, leaves config unchanged, and tells you to fix vvoc.json manually before rerunning vvoc sync.
Runtime compatibility is current-only. Guardian permission replies use the current OpenCode permission reply path (with the current HTTP reply fallback), Hashline edit refs must use current hash/context anchors, and sync writes current managed agents without deleting old pre-rename user or command entries.
Runtime plugins load the effective vvoc.json once during OpenCode startup and share the same immutable config snapshot for the lifetime of the process. There is no live reload; restart OpenCode after changing vvoc.json.
Use vvoc launch when you want the vvoc-selected config files to be the only files OpenCode sees for this run:
vvoc install --scope project
vvoc launch --scope project -- run "hello"vvoc launch --scope project is strict and non-mutating: if .opencode/opencode.json or .vvoc/vvoc.json is missing, it fails with a hint to run vvoc install --scope project. --scope effective follows the layered lookup order, and --scope global uses the global config paths.
All prompt files are scaffolded by vvoc install / vvoc sync:
| Agent | When it helps |
|---|---|
vv-controller |
Default primary agent that routes small changes, investigations, reviews, and larger feature work through the right workflow |
enhancer |
Improves rough requests before execution when a clearer prompt would help |
vv-implementer |
Applies a focused approved change and verifies it before reporting completion |
vv-spec-reviewer |
Checks whether implementation matches the requested spec and acceptance criteria |
vv-code-reviewer |
Looks for bugs, regressions, maintainability risks, and missing tests |
investigator |
Finds the root cause first when behavior is unclear or a failure needs diagnosis |
guardian |
Supports GuardianPlugin by auto-approving routine low-risk permission requests and leaving risky ones for manual approval |
Five workflow skills are scaffolded alongside agents:
| Skill | When to use it | What it gives you |
|---|---|---|
vv-spec |
You have a feature or creative request and no agreed contract yet | A guided interview, recommended options, and a saved spec in .vvoc/specs/<id>/spec.xml |
vv-plan |
A spec is approved and ready to implement | A task-level implementation plan with file targets, contracts, dependencies, and acceptance criteria |
vv-execute |
A plan is approved and you want it applied step by step | Ordered execution with verification and applied spec/plan archival |
vv-review |
You want findings, not fixes | A review-only workflow that reports spec/code issues and stops before implementation |
vv-reflect |
A long development, debugging, ops, or investigation session produced reusable knowledge | Durable notes in existing docs or .vvoc/lessons / .vvoc/runbooks for future agents |
Spec and plan artifacts stay XML so requirements, tasks, acceptance criteria, and dependencies remain easy to grep and review.
vv-reflect creates .vvoc/lessons and .vvoc/runbooks lazily only after approved fallback writes. It prefers an existing repository documentation convention when there is a high-confidence match.
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.
bun install # Install dependencies
bun run check # Typecheck + lint + format check + test
bun run fmt # Auto-format source files
bun run release:check # Verify package/schema release consistencyGit hooks managed via lefthook.
tmpdir="$(mktemp -d)"
bun run build
bun dist/cli.js install --config-dir "$tmpdir"
bun dist/cli.js status --config-dir "$tmpdir"bun run release:check
bun run check
bun run pack:checkThe release flow is automated via a local wrapper and a tag-gated GitHub Actions workflow.
bun run release:bump patch # or minor, major, prerelease, or explicit semverThis will:
- Reject if the worktree is dirty
- Bump
package.jsonvianpm version --no-git-tag-version - Generate a required AI release summary with
opencode --pure run - Prepend a
### Summarysection plus conventional commit details toCHANGELOG.md - Update
schemas/vvoc/v3.json$idto the new version - Run
release:checkfor consistency - Create a release commit and annotated tag
vX.Y.Z - Push the current branch and the created tag to
origin
Required local release prerequisite:
opencodemust be available fromPATH.- The summary model defaults to
deepseek/deepseek-v4-flash. - Override with
VVOC_RELEASE_SUMMARY_MODEL=provider/model. - Override the per-attempt timeout with
VVOC_RELEASE_SUMMARY_TIMEOUT_MS=120000. Runrelease:bumpfrom a checked-out branch with push access toorigin. The tag push is what triggers the publish workflow.
The GitHub Actions workflow triggers on v* tag pushes, verifies the tag matches
package.json, runs full validation (typecheck, lint, fmt check, tests, build, pack
check, release:check), and publishes to npm with --provenance.
bun run release:checkThis verifies that package.json name, version, and schemas/vvoc/v3.json $id and
config format version are all consistent. Run it independently anytime.
The workflow uses npm provenance/trusted publishing (id-token: write) and does not publish on normal branch pushes. Configure npm trusted publishing for this GitHub repository/package, or adapt the publish step to use an NPM_TOKEN secret if token-based publishing is required.
RTK is a CLI proxy that reduces token usage for common developer commands. The interactive vvoc init flow recommends it after setup.
MIT — see LICENSE.