# @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.

npm bun MIT

--- ## Quick Start ```bash 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: ```bash 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: ``) │ Dependency ordering (grep: ``) │ 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: ```bash # Extract tasks from plan grep '' .vvoc/plans/*.xml # Extract all acceptance criteria grep '' .vvoc/plans/*.xml # Extract dependency graph grep 'task-' .vvoc/plans/*.xml # Extract method signatures grep '/\*\*' .vvoc/plans/*.xml # Extract all components from plan grep '' .vvoc/plans/*.xml ``` All three skills are auto-triggered by `vv-controller` via its built-in `` — 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 | Area | What you get | |---|---| | **Plugins** | 6 plugins in one pinned package entry — workflow orchestration, model roles, guardian, hashline edit, system context injection, secrets redaction | | **Agent System** | `vv-controller` routes work: direct for small changes, `investigator` for bugs, implementer+reviewer loop for risky work, analyst+architect for large features | | **Skills** | `vv-spec` interviews you and writes an XML spec; `vv-plan` maps the spec to interface contracts and acceptance criteria; `vv-review` runs a review-only workflow — all auto-triggered | | **Spec-to-Code Pipeline** | `vv-spec` → spec review → `vv-plan` → plan review → `vv-implementer` → code review. Three independent review gates cover requirements, contracts, and implementation | | **One-Click Setup** | `vvoc install` or `vvoc sync` bootstraps everything — config, agents, skills, prompts, presets | | **CLI Tooling** | 15+ commands: install, sync, status, doctor, role management, presets, guardian config, shell completion, upgrade | | **Security** | GuardianPlugin reviews shell-permission requests; SecretsRedactionPlugin strips tokens before LLM requests; both configurable via `vvoc.json` | | **Model Roles** | Assign provider/model/variant to roles (`default`, `smart`, `fast`, `vision`, custom); switch between `vv-openai`, `vv-zai`, `vv-deepseek`, `vv-minimax` presets | | **Workflow Tracking** | Work items with open/list/close for tracked implementation-to-review pipelines | --- ## The Six Plugins | Plugin | What it does | |---|---| | **WorkflowPlugin** | Tracked orchestration around `task` for subagents; registers `work_item_open/list/close` tools for implementation-to-review pipelines with state-machine enforcement and round-limit gating | | **ModelRolesPlugin** | Resolves `vv-role:*` references in OpenCode config at startup; translates `:variant` suffixes into native model+variant fields | | **GuardianPlugin** | Reviews OpenCode permission requests with a constrained guardian agent and safe-deny defaults; configurable model, timeout, risk threshold | | **HashlineEditPlugin** | Replaces OpenCode's `edit` with hash-anchored variant; rewrites `read` output to `line#hash` format; rejects stale snapshots to prevent drift bugs | | **SystemContextInjectionPlugin** | Injects reusable system guidance into primary sessions without polluting subagent prompts; encourages proactive `explore` usage; registers vvoc skill directory for OpenCode skill discovery | | **SecretsRedactionPlugin** | Redacts secrets (tokens, keys, emails, UUIDs, IPs) before LLM requests; restores placeholders afterward; configurable patterns | --- ## CLI at a Glance | Command | Purpose | |---|---| | `vvoc init` | Interactive bootstrap flow | | `vvoc install` | Non-interactive setup and scaffolding | | `vvoc sync` | Refresh plugin entry, agents, prompts, skills, config | | `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\|` | Inspect or apply named presets | | `vvoc guardian config` | Print or write guardian section | | `vvoc plugin list` | List OpenCode plugin entries | | `vvoc patch-provider stepfun-ai\|zai\|openai` | Patch a global OpenCode config preset | | `vvoc completion` | Install shell completions | | `vvoc upgrade` | Upgrade global package and run follow-up sync | | `vvoc version` | Print installed version | --- ## Model Roles & Presets ```bash # 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`: | Agent | Role | |---|---| | `vv-controller` | Default primary agent — routes work to the right subagent | | `enhancer` | Prompt enhancement | | `vv-analyst` | Requirements analysis for large features | | `vv-architect` | Module/contract/wave design | | `vv-implementer` | Focused implementation with verification | | `vv-spec-reviewer` | Checks implementation against spec | | `vv-code-reviewer` | Engineering review for bugs and maintainability | | `investigator` | Root-cause analysis for unclear bugs | | `guardian` | Permission request review (plugin runtime) | --- ## Managed Skills Three XML-based skills are scaffolded alongside agents: | Skill | Trigger | Output | Grep-able | |---|---|---|---| | `vv-spec` | Creative/feature request, no spec exists | `.vvoc/specs/*.xml` | ``, ``, `` | | `vv-plan` | Approved spec exists | `.vvoc/plans/*-plan.xml` | ``, ``, ``, `/**` JSDoc | | `vv-review` | Review request | Findings report | — | Skills are loaded by OpenCode at session start through `config.skills.paths` (registered by the SystemContextInjectionPlugin). The `vv-controller` agent's `` ensures they are invoked automatically when the user's request matches their trigger conditions. --- ## Local Development ```bash 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 ```bash 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 ```bash bun run check bun run build bun run pack:check ``` --- ## Publishing ```bash bun run check && bun run build && npm publish ``` Publishing is manual from the terminal. No CI publish workflows. --- ## Optional: RTK [RTK](https://github.com/rtk-ai/rtk) is a CLI proxy that reduces token usage for common developer commands. The interactive `vvoc init` flow recommends it after setup.