@osovv/vv-opencode 0.35.11 → 0.35.13

package/CHANGELOG.md

@@ -1,9 +1,33 @@
+## <small>0.35.13 (2026-06-14)</small>
+
+### Summary
+
+This release introduces interview UX guardrails to the vv-spec module, adding a roadmap preview, per-section progress markers, honest depth estimates that expand rather than limit context, and a standardized question-card format with per-section recap. These changes make decision-tree walks more transparent and predictable while ensuring critical forks are never skipped. Additionally, the project metadata is polished with an MIT LICENSE, live CI/coverage badges, and aligned repository topics for improved discoverability.
+
+* feat(vv-spec): add interview UX guardrails — roadmap, progress, depth estimate, recap ([d05aef9](https://github.com/osovv/vv-opencode/commit/d05aef9))
+* docs: polish repo metadata, add LICENSE, live badges, and aligned topics ([4fbe4e7](https://github.com/osovv/vv-opencode/commit/4fbe4e7))
+
+## <small>0.35.12 (2026-06-13)</small>
+
+### Summary
+
+This release introduces an inline execution mode choice for the vv-execute plugin, giving you more control over how commands are launched. The release process now automatically generates a changelog summary for each version, ensuring every release includes a clear, user-friendly overview of changes. Additionally, several fixes improve the reliability of summary generation, including support for single-line summary envelopes and corrected configuration handling.
+
+* fix(release): accept single-line summary envelopes ([f2b7b93](https://github.com/osovv/vv-opencode/commit/f2b7b93))
+* fix(release): use valid opencode summary config ([9b8b38d](https://github.com/osovv/vv-opencode/commit/9b8b38d))
+* feat(release): add mandatory AI-generated release changelog summary ([592615d](https://github.com/osovv/vv-opencode/commit/592615d))
+* feat(vv-execute): add inline execution mode choice ([4822a7a](https://github.com/osovv/vv-opencode/commit/4822a7a))
+
 ## <small>0.35.11 (2026-06-13)</small>
 
+### Summary
+
+This release makes the release and upgrade path easier to trust by tightening changelog validation and improving compatibility with generated conventional-changelog output. Users get clearer upgrade notes backed by GitHub Releases and jsDelivr, while maintainers get stronger automated checks around the artifacts that ship each release.
+
 * fix(release): make changelog patterns compatible with conventional-changelog format ([582c2f4](https://github.com/osovv/vv-opencode/commit/582c2f4))
 * test(upgrade): add multi-version changelog, graceful degradation, and prerelease tests ([3f634db](https://github.com/osovv/vv-opencode/commit/3f634db))
 * feat(release): add CHANGELOG.md validation to release-check ([2e37a77](https://github.com/osovv/vv-opencode/commit/2e37a77))
 * feat(release): add GitHub Releases and jsDelivr-based changelog for vvoc upgrade ([e0f9863](https://github.com/osovv/vv-opencode/commit/e0f9863))
 * feat(release): integrate changelog generation into release-bump ([b90a079](https://github.com/osovv/vv-opencode/commit/b90a079))
 * chore(config): add changelog and commitlint configuration ([88dc806](https://github.com/osovv/vv-opencode/commit/88dc806))
-* chore(config): add commitlint commit-msg hook ([888abf1](https://github.com/osovv/vv-opencode/commit/888abf1))
+* chore(config): add commitlint commit-msg hook ([888abf1](https://github.com/osovv/vv-opencode/commit/888abf1))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 osovv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,8 +4,11 @@
 
 <p>
   <a href="https://www.npmjs.com/package/@osovv/vv-opencode"><img src="https://img.shields.io/npm/v/%40osovv%2Fvv-opencode?style=flat&label=npm&color=blue" alt="npm"></a>
+  <a href="https://github.com/osovv/vv-opencode/actions/workflows/publish.yml"><img src="https://github.com/osovv/vv-opencode/actions/workflows/publish.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/osovv/vv-opencode/releases"><img src="https://img.shields.io/github/v/release/osovv/vv-opencode?style=flat&label=release" alt="release"></a>
+  <a href="https://github.com/osovv/vv-opencode"><img src="https://img.shields.io/github/stars/osovv/vv-opencode?style=flat&color=yellow" alt="stars"></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-bun-%23f9f9f9?style=flat&logo=bun" alt="bun"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat" alt="MIT"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/osovv/vv-opencode?style=flat&color=green" alt="MIT"></a>
 </p>
 
 ---
@@ -147,6 +150,7 @@ Setting up OpenCode for serious daily work means juggling config files, agent pr
 | `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 a global OpenCode config preset |
 | `vvoc completion` | Install shell completions |
 | `vvoc upgrade` | Upgrade global package and run follow-up sync |
@@ -276,11 +280,18 @@ bun run release:bump patch   # or minor, major, prerelease, or explicit semver
 This will:
 1. Reject if the worktree is dirty
 2. Bump `package.json` via `npm version --no-git-tag-version`
-3. Update `schemas/vvoc/v3.json` `$id` to the new version
-4. Run `release:check` for consistency
-5. Create a release commit and annotated tag `vX.Y.Z`
-6. Push the current branch and the created tag to `origin`
-
+3. Generate a required AI release summary with `opencode --pure run`
+4. Prepend a `### Summary` section plus conventional commit details to `CHANGELOG.md`
+5. Update `schemas/vvoc/v3.json` `$id` to the new version
+6. Run `release:check` for consistency
+7. Create a release commit and annotated tag `vX.Y.Z`
+8. Push the current branch and the created tag to `origin`
+
+Required local release prerequisite:
+- `opencode` must be available from `PATH`.
+- 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`.
 Run `release:bump` from a checked-out branch with push access to `origin`. The tag push is what triggers the publish workflow.
 
 The GitHub Actions workflow triggers on `v*` tag pushes, verifies the tag matches
@@ -305,3 +316,9 @@ The workflow uses npm provenance/trusted publishing (`id-token: write`) and does
 ## 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.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/cli.js

@@ -16,7 +16,7 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v0.2.10 - Aligned module dependency metadata with the actual imported command tree.]
+//   LAST_CHANGE: [v0.2.11 - Aligned meta description with package.json, README, and GitHub repo; license and badge polish.]
 // END_CHANGE_SUMMARY
 import { defineCommand, runMain } from "citty";
 import completion from "./commands/completion.js";
@@ -40,7 +40,7 @@ const main = defineCommand({
     meta: {
         name: "vvoc",
         version: packageVersion,
-        description: "Install and sync vv-opencode plugins for OpenCode.",
+        description: "Portable OpenCode workflow toolkit — 6 plugins, managed agents & skills, a spec-to-code pipeline, security, and the vvoc CLI.",
     },
     subCommands: {
         completion,

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,mBAAmB;AACnB,kBAAkB;AAClB,wBAAwB;AACxB,uDAAuD;AACvD,+FAA+F;AAC/F,oYAAoY;AACpY,4BAA4B;AAC5B,iBAAiB;AACjB,qBAAqB;AACrB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,oEAAoE;AACpE,wCAAwC;AACxC,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,uGAAuG;AACvG,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,UAAU,MAAM,0BAA0B,CAAC;AAClD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAC9C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,aAAa,MAAM,8BAA8B,CAAC;AACzD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,iCAAiC;AACjC,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;AAEjD,MAAM,IAAI,GAAG,aAAa,CAAC;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,cAAc;QACvB,WAAW,EAAE,oDAAoD;KAClE;IACD,WAAW,EAAE;QACX,UAAU;QACV,MAAM;QACN,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,OAAO;QACP,gBAAgB,EAAE,aAAa;QAC/B,MAAM;QACN,MAAM;QACN,IAAI;QACJ,MAAM;QACN,IAAI;QACJ,OAAO;QACP,OAAO;KACR;CACF,CAAC,CAAC;AACH,+BAA+B;AAE/B,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,mBAAmB;AACnB,kBAAkB;AAClB,wBAAwB;AACxB,uDAAuD;AACvD,+FAA+F;AAC/F,oYAAoY;AACpY,4BAA4B;AAC5B,iBAAiB;AACjB,qBAAqB;AACrB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,oEAAoE;AACpE,wCAAwC;AACxC,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,4HAA4H;AAC5H,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,UAAU,MAAM,0BAA0B,CAAC;AAClD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAC9C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,aAAa,MAAM,8BAA8B,CAAC;AACzD,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,MAAM,MAAM,sBAAsB,CAAC;AAC1C,OAAO,IAAI,MAAM,oBAAoB,CAAC;AACtC,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,OAAO,MAAM,uBAAuB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,iCAAiC;AACjC,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;AAEjD,MAAM,IAAI,GAAG,aAAa,CAAC;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,+HAA+H;KAClI;IACD,WAAW,EAAE;QACX,UAAU;QACV,MAAM;QACN,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,OAAO;QACP,gBAAgB,EAAE,aAAa;QAC/B,MAAM;QACN,MAAM;QACN,IAAI;QACJ,MAAM;QACN,IAAI;QACJ,OAAO;QACP,OAAO;KACR;CACF,CAAC,CAAC;AACH,+BAA+B;AAE/B,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.35.11",
-  "description": "Portable OpenCode workflow plugins, explicit memory, and CLI tooling.",
+  "version": "0.35.13",
+  "description": "Portable OpenCode workflow toolkit — 6 plugins, managed agents & skills, a spec-to-code pipeline, security, and the vvoc CLI.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,13 +11,21 @@
   },
   "keywords": [
     "opencode",
+    "opencode-plugin",
     "plugins",
     "workflow",
-    "guardian",
-    "xdg",
-    "grace",
+    "agent-workflow",
+    "ai-agent",
+    "agent-framework",
+    "llm",
+    "spec-to-code",
     "bun",
-    "citty"
+    "cli",
+    "typescript",
+    "developer-tools",
+    "guardian",
+    "prompt-engineering",
+    "security"
   ],
   "bin": {
     "vvoc": "./dist/cli.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.35.11/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.35.13/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/templates/skills/vv-execute/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: vv-execute
-description: Use when given a path to a plan.xml — walks tasks in dependency order, dispatches vv-implementer with extracted contracts, verifies acceptance criteria, and tracks progress via workflow work items
+description: Use when given a path to a plan.xml — validates the plan, assesses execution complexity, asks the user to choose classic subagent-driven or inline current-session execution, then walks tasks in dependency order with verification and commits
 ---
 
 <skill>
 <identity>
-You are the vv-execute skill. Your job is to execute a plan.xml from .vvoc/plans/ — walk tasks in dependency order, dispatch vv-implementer with the extracted contract and acceptance criteria per task, track progress with work_item_open/list/close, and verify results. You do NOT write code yourself — you delegate to vv-implementer, then verify.
+You are the vv-execute skill. Your job is to execute a plan.xml from .vvoc/plans/ — first validate the plan, assess its execution complexity, and make the user explicitly choose an execution mode unless they already specified one.
+
+Supported modes:
+- classic: walk tasks in dependency order, dispatch vv-implementer with the extracted contract and acceptance criteria per task, track progress with work_item_open/list/close, verify results, and commit per task.
+- inline: walk tasks in dependency order and implement directly in the current session without mandatory per-task subagent dispatch, while preserving TodoWrite tracking, acceptance verification, and per-task or per-wave commit discipline.
+
+Do not mutate files until the execution mode is explicit. In classic mode, delegate implementation to vv-implementer. In inline mode, write code yourself in the current session.
 </identity>
 
 <language>
@@ -83,11 +89,47 @@ You are the vv-execute skill. Your job is to execute a plan.xml from .vvoc/plans
   <check>Each task has &lt;acceptance&gt; with at least one &lt;criterion&gt;</check>
   <action>If any check fails, stop and report the issue with line numbers. Do not proceed with broken plan.</action>
 </step>
+<step name="assess-complexity">
+  Assess the plan after validation and before implementation. Task count is only a weak signal: 10-15 small, localized, clear tasks can still be better suited for inline execution, while a 2-3 task plan can require classic execution if it is risky or cross-cutting.
+
+  Consider:
+  - total task count and whether tasks are small/mechanical or broad/ambiguous
+  - number of target files and whether changes stay localized
+  - dependency graph shape and coupling between tasks
+  - whether public APIs, package exports, CLI behavior, setup flow, config locations, persistence, security, migrations, or user data handling change
+  - clarity and verifiability of acceptance criteria
+  - whether the plan requires architectural decisions, broad refactors, or integration-heavy coordination
+
+  Recommend inline when tasks are clear, localized, mechanically verifiable, and low-risk even if there are many small tasks.
+  Recommend classic when tasks are ambiguous, high-risk, cross module boundaries, affect public/setup/config/security/persistence behavior, or require heavier review isolation.
+</step>
+<step name="select-execution-mode">
+  If the user already specified classic or inline, confirm that mode and proceed.
+
+  If the user did not specify a mode, stop and ask them to choose. Do not auto-pick. Present a compact assessment and recommendation in the user's language, then offer exactly two choices:
+
+  <format>
+  Plan complexity assessment:
+  - N tasks
+  - M target files
+  - dependency/coupling summary
+  - risk signals found or not found
+  - acceptance criteria clarity
+
+  Recommended mode: inline|classic
+
+  Choose execution mode:
+  1. inline — execute in this session
+  2. classic — delegate each task to vv-implementer
+  </format>
+
+  Wait for the user's answer before editing files, opening implementation work items, dispatching vv-implementer, or running implementation commands.
+</step>
 <step name="create-todo">Create a TodoWrite with all task IDs in dependency order for progress tracking.</step>
 </pre-execution>
 
-<per-task-cycle>
-<principle>Each task runs as an independent unit with its own work item and implementer dispatch. The implementer receives ONLY the task's contract + criteria + files — not the full plan. This keeps context lean and focused.</principle>
+<classic-workflow>
+<principle>Use this workflow only when execution mode is classic. Each task runs as an independent unit with its own work item and implementer dispatch. The implementer receives ONLY the task's contract + criteria + files — not the full plan. This keeps context lean and focused.</principle>
 
 <step name="extract">
 Use extract-task to pull the full task content. Collect:
@@ -114,12 +156,12 @@ Every material finding from plan.xml must be enumerated explicitly in the packet
 <step name="dispatch">
 Open a work item with work_item_open for this task (e.g. "Implement &lt;component&gt;").
 Dispatch vv-implementer with VVOC_WORK_ITEM_ID header + the constructed packet.
-The implementer writes code, runs tests, commits, and returns a status.
+The implementer writes code, runs tests, and returns a status. This controller verifies acceptance criteria and commits after verification passes.
 </step>
 
 <step name="handle-status">
   <case name="done">
-    Implementer returned DONE. Use task-files to verify files exist. Run the test command from the plan (if specified). Verify each acceptance criterion.
+    Implementer returned DONE. Use task-file to verify files exist. Run the test command from the plan (if specified). Verify each acceptance criterion.
     Optionally dispatch vv-spec-reviewer to confirm contract compliance.
     If verification fails: re-dispatch implementer with failure details.
     If verification passes: proceed to close.
@@ -178,10 +220,62 @@ The task's changes are already committed. Mark the task complete in TodoWrite. C
 If all tasks are done → proceed to completion.
 Otherwise → move to the next task in dependency order.
 </step>
-</per-task-cycle>
+</classic-workflow>
+
+<inline-workflow>
+<principle>Use this workflow only when execution mode is inline. Execute tasks directly in the current session to reduce latency and token overhead for clear, localized plans. Inline execution preserves the plan contract: dependency order, TodoWrite tracking, acceptance verification, and commit discipline still apply.</principle>
+
+<step name="extract">
+Use extract-task to pull the full task content. Collect:
+- Task id and title
+- File path
+- Code snippet (from CDATA)
+- Acceptance criteria
+- Dependencies (task_id list)
+</step>
+
+<step name="prepare-context">
+Read the target file and any directly relevant local contracts, tests, or surrounding implementation before editing. Keep context bounded to the current task or wave. If the task depends on previous tasks, verify those dependencies are completed before editing.
+</step>
+
+<step name="implement-inline">
+Apply the smallest correct change that satisfies the task contract and acceptance criteria. Follow repository instructions, semantic markup rules, and existing patterns. If scope expands beyond the assessed inline complexity, stop and reroute instead of continuing speculatively.
+</step>
+
+<step name="verify">
+Run the acceptance criteria for the task or wave. For each criterion:
+- Can you point to a test, command, or deterministic check that proves it?
+- Does the check pass?
+- Did the inline implementation miss any edge cases?
+
+If criteria fail with a clear local cause, fix and rerun verification.
+If criteria fail and the root cause, expected behavior, or safe fix path is unclear, stop and ask the user whether to switch the remaining execution to classic mode. Do not silently dispatch vv-implementer from inline mode.
+</step>
+
+<step name="commit">
+Commit after each task by default. Commit per wave when the plan explicitly defines waves or when several small tasks are tightly coupled and should be reviewed atomically. Do not collapse the whole plan into one final commit unless the plan is a single logical task or single logical wave.
+
+Use the repository's existing commit style. Inspect recent commits before committing. Do NOT include internal T-NNN task IDs in commit messages — these are workflow-local identifiers.
+
+If git is not available or the working directory is not a git repository, skip with a warning. If the commit fails (e.g. nothing to commit, hook rejection), report the failure and stop. Do not silently proceed.
+</step>
+
+<step name="close">
+Mark the task complete in TodoWrite after its acceptance criteria pass and its task/wave commit is complete or intentionally skipped with a warning. If all tasks are done → proceed to completion. Otherwise → move to the next task in dependency order.
+</step>
+
+<reroute>
+Inline mode is allowed only while the work remains clear, bounded, and low-risk. Stop and ask the user whether to switch to classic mode when:
+- the implementation crosses unexpected module or architecture boundaries
+- public API, CLI behavior, package exports, setup flow, config locations, persistence, security, migrations, or user data handling become materially affected and were not already part of the inline assessment
+- acceptance criteria are ambiguous or incomplete
+- verification fails without a clear local cause
+- repeated inline attempts do not converge
+</reroute>
+</inline-workflow>
 
 <model-selection>
-<principle>Use the least powerful model that can handle each role:</principle>
+<principle>In classic mode, use the least powerful model that can handle each delegated role:</principle>
 <rule>Mechanical tasks (1-2 files, clear contract, standard patterns) → fast/default role</rule>
 <rule>Integration tasks (multi-file, coordination, state management) → smart role</rule>
 <rule>Review tasks (spec-reviewer, code-reviewer) → smart role</rule>
@@ -189,11 +283,11 @@ Otherwise → move to the next task in dependency order.
 </model-selection>
 
 <completion>
-<step name="summary">Report to the user: which tasks were completed, how many files were created/modified, and whether all acceptance criteria passed.</step>
+<step name="summary">Report to the user: selected execution mode, which tasks were completed, how many files were created/modified, and whether all acceptance criteria passed.</step>
 <step name="next">Ask the user: would you like a review? (vv-review can check the implementation against the spec).</step>
 </completion>
 
 <task>
-Your current task is the ongoing user request. Read the plan.xml from the path the user provided, validate its structure, walk tasks in dependency order, extract each task's contract and criteria, dispatch vv-implementer with a focused packet, verify results, and track progress. Use the grep helpers to navigate the plan. Do not write code — delegate to vv-implementer.
+Your current task is the ongoing user request. Read the plan.xml from the path the user provided, validate its structure, assess execution complexity, and ensure the user explicitly chooses classic or inline mode unless they already specified one. Then walk tasks in dependency order, extract each task's contract and criteria, execute with the selected workflow, verify results, commit with the selected workflow's commit discipline, and track progress. Use the grep helpers to navigate the plan.
 </task>
 </skill>

package/templates/skills/vv-spec/SKILL.md

@@ -14,6 +14,9 @@ You are the vv-spec skill. Your job is to interview the user, understand what th
 </language>
 
 <decision_tree_interview>
+<invariant>
+UX cues (roadmap, progress markers, depth estimates, checkpoints) are TRANSPARENT WRAPPERS around the decision-tree walk — they make the depth visible, never shallower. Conflict rule: if any cue would tempt skipping a branch or accepting a shallow answer, the depth wins and the cue is dropped. The decision tree is still walked relentlessly, one point at a time, recommendation-first, dependency-ordered.
+</invariant>
 <principle>Walk down the decision tree relentlessly. Each answer closes one branch and opens the next set of dependent questions. Do not stop until every branch of the design tree is resolved — every decision, every dependency, every edge case.</principle>
 <principle>Ask ONE question at a time. Never present multiple questions in a single message. Each question must resolve exactly one decision point.</principle>
 <principle>For every question, provide YOUR recommended answer with reasoning. The user can accept it or override. This makes the interview fast — most answers land with a single word.</principle>
@@ -22,11 +25,23 @@ You are the vv-spec skill. Your job is to interview the user, understand what th
 <principle>Understand the full landscape: purpose, constraints, success criteria, non-goals, edge cases, existing code patterns.</principle>
 <principle>When the decision tree reaches a fork (2-3 viable approaches), present all options with trade-offs. Lead with your recommendation and explain why. The user picks one — that closes the fork and the tree continues from that branch.</principle>
 <principle>When presenting design sections, do it one section at a time. After each section: "Does this look right?" If yes, move to the next. If no, resolve concerns before continuing.</principle>
-<principle>Cover every section: architecture, components, data flow, error handling, testing.</principle>
+<principle>Cover every section of the spec template: goal, architecture, tech-stack, components, data-flow, error-handling, testing, non-goals. The roadmap shown at the start IS the coverage checklist. A section is "closed" only when its template element is fully decidable.</principle>
 <principle>YAGNI ruthlessly: prune dead branches — remove unnecessary features from every approach.</principle>
 <principle>After design is confirmed, synthesize the spec yourself. You are the expensive model — deep analysis and architectural design are your responsibility, not a subagent's.</principle>
+<principle>Open the interview with a DECISION-TREE ROADMAP: show the spec template sections (goal, architecture, tech-stack, components, data-flow, error-handling, testing, non-goals) AND the major forks that may arise within each. State traversal order (highest-impact first). The purpose is predictability of the full landscape, not brevity — the user is working, so a large honest surface is welcome. Note the tree is dynamic: the branch actually taken depends on answers, but every reachable fork is shown up front.</principle>
+<principle>Mark the CURRENT SECTION on every question message (a short header). The user must always know their location in the tree. This reduces disorientation in long interviews; it does not skip content.</principle>
+<principle>After the first substantive exchange, give an HONEST DEPTH ESTIMATE (approximate decision points remaining). If the estimate is high (roughly 12–15+), do NOT shorten the interview. Surface it as a signal that the prompt/context needs upgrading: offer the user ways to provide richer context up front (existing PRD, requirements doc, reference project, voice description), or propose decomposition into sub-projects. A large estimate means MORE context, not fewer questions.</principle>
+<principle>After closing each section, post a ONE-LINE RECAP of the decisions made in it, then show what sections remain. This is a coherence checkpoint — every branch inside the section was already walked to its leaf, so the recap confirms fixation rather than skipping deliberation. It lets the user catch a misunderstanding immediately instead of discovering it in the final spec.</principle>
+<principle>Format every question as a CARD: (1) one-line context — why this decision matters, (2) the question itself, (3) your recommendation with reasoning, (4) any codebase evidence found before asking. Predictable structure lowers per-step cognitive cost without lowering depth.</principle>
 </decision_tree_interview>
 
+<acceleration_guardrails>
+<rule>Do NOT offer a "fast mode" that skips decision points. Skipping sacrifices depth.</rule>
+<rule>The ONLY allowed acceleration is PREFILL-AND-CONFIRM, and only when the user explicitly requests it. The agent fills a section with its own recommendations and reasoning, then the user confirms or overrides point by point. Every decision is still made explicitly — only typing is saved, never deliberation.</rule>
+<rule>If the user says "just do it" or "skip ahead", apply prefill-and-confirm for the mechanical parts, but still walk every genuine fork — forks are where the design lives.</rule>
+<rule>A section recap is allowed to be terse. A fork presentation is never terse — trade-offs must be visible.</rule>
+</acceleration_guardrails>
+
 
 <spec_document_format>
 <rule>Load the spec template from references/spec-template.xml. Fill every element with the decisions confirmed during the interview.</rule>