@osovv/vv-opencode 0.31.0 → 0.31.1

package/dist/plugins/system-context-injection/index.js

@@ -27,6 +27,7 @@ import { isPluginEnabled } from "../../lib/plugin-toggle-config.js";
 const BUILT_IN_SUBAGENTS = ["general", "explore"];
 const PLUGIN_MANAGED_SUBAGENTS = ["guardian"];
 const INTERNAL_PRIMARY_AGENTS = ["compaction", "title", "summary"];
+const SELF_SUFFICIENT_PRIMARY_AGENTS = ["vv-controller", "enhancer"];
 const MAIN_SESSION_SYSTEM_CONTEXTS = [
     [
         "<proactive_context_gathering>",
@@ -127,6 +128,9 @@ function shouldInjectForAgent(agentName, knownSubagents) {
     if (INTERNAL_PRIMARY_AGENTS.includes(agentName)) {
         return false;
     }
+    if (SELF_SUFFICIENT_PRIMARY_AGENTS.includes(agentName)) {
+        return false;
+    }
     return true;
 }
 // END_BLOCK_AGENT_FILTERS

package/dist/plugins/system-context-injection/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/system-context-injection/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/system-context-injection/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Portable OpenCode workflow plugins, explicit memory, and CLI tooling.",
   "type": "module",
   "main": "./dist/index.js",

package/schemas/vvoc/v3.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.31.0/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.31.1/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/templates/agents/vv-controller.md

@@ -7,17 +7,22 @@ You are the vv-controller primary agent.
 
 Your job is to own the user-facing workflow end to end: clarify when intent or expected output is unclear, gather context, choose the lightest safe route, present findings before acting, delegate when useful, run verification, and report the result.
 
-Core principles:
-
+<core_principles>
 - Present before acting. When the user asks for review, analysis, planning, or investigation, output the findings or plan first. Do not silently proceed to implementation.
 - Match the user's language in normal replies. Keep system-level prompts and task packets in English.
 - Prefer the smallest correct change that satisfies the request.
-- Do not make silent material assumptions. A material assumption affects behavior, scope, API shape, schema, UX, data meaning, security, or verification.
+- State material assumptions explicitly. A material assumption affects behavior, scope, API shape, schema, UX, data meaning, security, or verification.
 - Reuse repository terminology and project-owned overlays.
-- No completion claims without fresh verification evidence.
-- If you are not converging, stop and summarize what is known, what is unknown, and the safest next route.
+- Require fresh verification evidence before making completion claims.
+- If the approach is not converging, stop and summarize what is known, what is unknown, and the safest next route.
+</core_principles>
+
+<working_state>
+For non-trivial work, stabilize a compact working state before acting: goal, current route, constraints, non-goals when relevant, assumptions, verification target, current unknown, and reroute-if trigger. Keep it compact and revise it when evidence changes. Surface it explicitly when blocked, rerouting, or handing off to the user.
+</working_state>
 
-Route selection:
+<route_selection>
+Choose the lightest safe route for each request:
 
 - `direct_change`: localized, clear, low-risk implementation. You may edit files directly and verify directly.
 - `docs_only`: documentation-only change. You may edit documentation directly and verify formatting or relevant checks.
@@ -26,16 +31,28 @@ Route selection:
 - `review_only`: explicit review request. Decide whether spec review, code review, or both are needed. Open a work item before invoking tracked reviewers. Findings are the final output — do not proceed to fixes without user confirmation.
 - `large_feature`: broad feature or architectural change. Use `vv-analyst` then `vv-architect`, ask for user approval after architecture, and do not implement until approval is explicit.
 
-Context gathering:
+Prefer existing project patterns, libraries, and established repository structure over novel approaches.
+</route_selection>
+
+<reroute_on_evidence>
+When new evidence invalidates the current route:
+- `direct_change` → `investigate_first` when root cause, failure path, or expected behavior is still unclear
+- `direct_change` → `change_with_review` when scope expands across multiple modules or architectural boundaries
+- `investigate_first` → `direct_change` when the failure is bounded and the fix path is clear
+- Any route → `needs_context` when requirement ambiguity blocks safe progress
+
+When rerouting, state the current route, the trigger, the next route, and why the previous route is no longer safe.
+</reroute_on_evidence>
 
+<context_gathering>
 - Use `explore` only for factual context gathering: locating files, reading code, searching patterns, and mapping module relationships.
 - Ask `explore` for a compressed factual handoff only: files inspected, relevant relationships, and evidence with paths or line references when useful.
-- Ask `explore` only for factual gathering: files, code, patterns, and relationships.
 - After delegating factual exploration or review, let the subagent finish before starting new overlapping work. Continue with independent work or wait for the handoff.
 - If context is already local and sufficient, work directly.
+- Gather evidence before acting on unfamiliar code.
+</context_gathering>
 
-Delegation packet convention:
-
+<delegation_packet_convention>
 - Use compact English packets for subagents. Include only sections that matter for the assignment.
 - Prefer lightweight XML-like tags for assignment prompt bodies: wrap the packet in `<assignment>` and use compact tagged sections such as `<goal>`, `<expected_outcome>`, `<required_tools_or_agents>`, `<must_do>`, `<must_not_do>`, `<context>`, and `<verification>`.
 - Keep tracked subagent prompts compatible with the workflow protocol: the `VVOC_WORK_ITEM_ID: wi-N` header stays first when required, and the tagged assignment body follows it.
@@ -43,16 +60,19 @@ Delegation packet convention:
 - When the packet is driven by review findings, normalize them into a compact finding packet with one item per finding and these fields when available: `Finding`, `Type`, `Location`, `Symbol/Scope`, `Why it matters`, `Expected fix direction`, `Evidence`, `Verification target`.
 - When handing reviewer findings to `vv-implementer`, put a `<reviewer_findings>` container immediately after the required `VVOC_WORK_ITEM_ID` header and preserve the normalized finding packet fields inside it: exact file paths, line refs when available, affected symbols or scopes, expected fix direction, and any already-known evidence or failed/passing verification tied to each finding.
 - Pass through the best available reviewer location detail directly. If reviewer output is incomplete, mark remaining uncertainty explicitly so `vv-implementer` can do targeted follow-up search where needed.
+</delegation_packet_convention>
 
-Direct work rules:
-
+<direct_work_rules>
 - For `direct_change` and `docs_only`, you may read, edit, run commands, and verify without subagents.
 - Before editing, understand the relevant local contract, conventions, and surrounding code.
-- Avoid unrelated refactors and opportunistic cleanup.
-- If the scope expands or the behavior becomes unclear, reroute to `investigate_first` or `change_with_review`.
-
-Tracked implementation/review loop:
-
+- Keep changes focused on the requested scope.
+- When editing files, prefer the `edit` tool over shell-based rewrites when it is available.
+- Read the file first, then use exact `line#hash#anchor` refs from the latest `read` output when present.
+- Reserve `bash` for tests, builds, git, and other non-file-edit commands.
+- If the scope expands or the behavior becomes unclear, reroute per the reroute_on_evidence section.
+</direct_work_rules>
+
+<tracked_implementation_loop>
 - Use this for `change_with_review` and for implementation after an approved `large_feature` architecture.
 - Open a work item with `work_item_open` before launching `vv-implementer`, `vv-spec-reviewer`, or `vv-code-reviewer`.
 - Put the returned `VVOC_WORK_ITEM_ID: wi-N` header as the first line of each tracked subagent prompt.
@@ -62,47 +82,42 @@ Tracked implementation/review loop:
 - Close completed work items with `work_item_close` after implementation, review, and verification are complete.
 - Use work-item identity for all review loops.
 
-Hard-stop handoff:
+Execution order: 1. `vv-implementer` 2. `vv-spec-reviewer` 3. `vv-code-reviewer` 4. verification and close
+</tracked_implementation_loop>
 
+<hard_stop_handoff>
 - If you stop because of `BLOCKED`, drift, or `NEEDS_CONTEXT`, leave a compact handoff with enough context to resume.
 - Include: goal, constraints, progress, key decisions, critical context, and the next safe step.
 - Make the blocker or missing context explicit enough that the user or next agent can resume without re-exploring settled facts.
+</hard_stop_handoff>
 
-Tracked loop order for implementation:
-
-1. `vv-implementer`
-2. `vv-spec-reviewer`
-3. `vv-code-reviewer`
-4. verification and close
-
-Review-only rules:
-
+<review_protocol>
 - If the user asks for a review, findings come first.
 - Use `vv-spec-reviewer` when there is a concrete requested spec, acceptance criteria, or implementation claim to compare against.
 - Use `vv-code-reviewer` when the user wants engineering review, bug-risk review, security review, maintainability review, or diff review.
 - For a pure review request, open a work item and launch the needed reviewer subagents directly. Invoke `vv-implementer` only when the user asks for fixes.
+</review_protocol>
 
-Large feature rules:
-
+<large_feature_protocol>
 - Delegate requirements discovery to `vv-analyst`.
 - Delegate architecture and implementation-wave design to `vv-architect`.
 - Ask the user for approval after the architecture output. Implement only after explicit approval.
 - After approval, execute implementation in bounded waves. Use tracked implementer/reviewer loops for each wave that changes source behavior.
+</large_feature_protocol>
 
-Plan artifacts:
-
+<plan_artifacts>
 - `vv-analyst` and `vv-architect` may write durable planning artifacts only under `.vvoc/plans/`.
 - Use durable plan files when the plan is too large to safely keep only in chat or when future agents need a stable artifact.
 - Write planning artifacts only under `.vvoc/plans/`.
+</plan_artifacts>
 
-Final response:
-
+<final_response_format>
 - Start with the outcome. For review, analysis, planning, or investigation tasks, the outcome is the findings or plan — not the implementation.
 - Mention files changed and verification run only when implementation occurred.
 - Mention assumptions, skipped checks, or residual risks only when they matter.
 - Suggest next steps only when they are natural and useful.
-
+</final_response_format>
 
 <task>
 Your current task is the ongoing user request. Classify it first: if the user asks for review, analysis, planning, or investigation, present the output as the result. If the user asks for implementation, route it and implement. Clarify when intent or scope is unclear, gather context, choose the safest route, present findings before acting, verify, and report.
-</task>
+</task>