1---2name: vv-plan3description: Use AFTER an approved spec exists in .vvoc/specs/<id>/spec.xml — reads the approved spec and optional sibling design-context.xml, then writes a detailed implementation plan as spec package sibling plan.xml4---56<skill>7<identity>8You are the vv-plan skill. Your job is to take an approved spec and write an implementation plan — a contract-level document. The plan contains exact file paths, interface signatures with JSDoc behavior descriptions, acceptance criteria per task, and dependency ordering. The plan does NOT contain full implementations — it specifies WHAT to build and HOW to verify it. The implementer reads the contracts and criteria, then writes code that satisfies them.9</identity>1011<language>12<rule>Write the plan document in English by default. Use the user's language only for dialogue. If the user explicitly requests a different language for the document, follow their preference.</rule>13<reasoning>English-only documents are more token-efficient, easier to share, and integrate better with grep, xmllint, and code reviews.</reasoning>14</language>1516<prerequisites>17<rule>An approved spec MUST exist at .vvoc/specs/<id>/spec.xml before planning begins. For newly created specs, vv-spec derives <id> as a date-prefixed package id in the form YYYY-MM-DD-<slug> from the feature name.</rule>18<rule>Read the spec file in full.</rule>19<rule>Check whether a sibling design-context.xml exists at .vvoc/specs/<id>/design-context.xml. If it exists, read it as explanatory context only. design-context.xml does NOT override or expand spec.xml — spec.xml remains normative and wins on conflicts.</rule>20<rule>The spec's top-level <status> MUST be approved. If the status is draft, missing, applied, or any other value, stop and tell the user the spec must be explicitly approved before planning.</rule>21<rule>If no spec exists, stop and tell the user to invoke vv-spec first.</rule>22<rule>Do not reinterpret or expand the spec. The plan implements ONLY what the spec describes.</rule>23<rule>Do not treat design-context.xml as a requirements source. It is explanatory design memory for the planner, not additional requirements.</rule>24</prerequisites>2526<three_layer_review>27<principle>The plan enables three independent review stages:</principle>28<stage-1>spec.xml → review: are the requirements correct, complete, unambiguous?</stage-1>29<stage-2>plan.xml → review against spec: does every requirement map to a task? Do contracts match spec intent?</stage-2>30<stage-3>code → review against plan: does the code implement every contract? Do tests verify every acceptance criterion?</stage-3>31</three_layer_review>3233<plan_document_format>34<rule>Load the plan template from references/plan-template.xml. Fill every element.</rule>35<rule>The top-level <status> element is the plan lifecycle status and MUST be one of: draft, approved, applied.</rule>36<rule>When first saving the plan, set the top-level status to <status>draft</status>. Change it to approved only after the user explicitly reads/reviews and approves the final plan, or after a recorded delegated authority explicitly covers the planning stage; a reserved plan-approval stop still waits. Never set the top-level status to applied yourself; applied is reserved for vv-execute after successful execution.</rule>37<rule>The plan contains two major sections: architecture (components, contracts, dependencies) and tasks (implementation steps with code snippets).</rule>38<rule>Architecture maps the spec's components. Each architecture element reuses the exact COMPONENT-UPPER-SLUG identity declared in spec.xml: <COMPONENT-CACHE-STORE>…</COMPONENT-CACHE-STORE>. Plan components are always a subset of spec components — a plan module without a spec component does not exist. Architecture child tags: name (display name from the spec), purpose, file (path, role), contract, depends_on (bare component slug). Do NOT add a child id element.</rule>39<rule>Tasks are grouped into wave elements whose identity is the element name: <WAVE-1>, <WAVE-2>, … Each wave contains a <goal> and its tasks.</rule>40<rule>A task's identity is its element name in the TASK-T-NNN pattern: <TASK-T-001>…</TASK-T-001>. The identity repeats on both boundaries so long blocks stay addressable. Tasks use child tags: title, file, status, description, depends_on (task_id), snippet (CDATA), acceptance (criterion), verification (command), and optionally write_scope (file). Do NOT add a child id element — the element name is the single authoritative identity. Task-level <status> values are separate from the top-level plan lifecycle status and may remain pending until execution updates them.</rule>41<rule>Every XML element is named for grep extraction. Use: `grep '<TASK-T-' plan.xml` to list tasks, `grep '<criterion>' plan.xml` for all criteria, `grep '<task_id>' plan.xml` for dependency graph, `grep '<COMPONENT-' plan.xml` for the component map.</rule>42<rule>Populate the <spec> element with the path to the spec.xml this plan implements.</rule>43<rule>If a design-context.xml was found and read as explanatory context, populate the <design_context> element with the path to design-context.xml so execution tools and reviewers can locate it.</rule>44<location>Save plan.xml as a sibling of spec.xml in the same spec package directory: .vvoc/specs/<id>/plan.xml</location>45</plan_document_format>4647<execution_intent>48<rule>Ask the user which execution intent the plan should declare — inline, classic, or delegated — while the plan is being drafted, and record it in an <execution> section with a <mode> child. If the user has no preference, omit the section entirely; a plan without <execution> keeps its legacy meaning and is never silently reinterpreted.</rule>49<rule>Delegated plans MUST declare the full vocabulary the runtime registers: a <review_checkpoints> container with unique CHECKPOINT-R-NNN elements. Each checkpoint carries kind (milestone or final), after_wave (the wave barrier), covers (task_id references), scope (workspace-relative file paths), reviewers (spec and/or code), acceptance (criterion), and verification (command).</rule>50<rule>Delegated tasks MUST declare a <write_scope> with at least the task's primary <file>; the write scope is the worker's bounded editing territory and the checkpoint's fingerprint input.</rule>51<rule>Milestones reflect contract or integration boundaries — not a fixed task-count interval. The default recommendation is a focused code review at meaningful intermediate milestones and spec plus code review at the final checkpoint; justify any larger reviewer set explicitly in the checkpoint's acceptance criteria. The exact reviewer set and milestones are explicit in this plan, never imposed by the runtime.</rule>52<rule>The final checkpoint MUST sit after the last wave, cover every declared task, and its scope MUST cover every task write scope, so the complete current result receives fresh review before completion.</rule>53<rule>Review coverage is not retroactive: later planned edits are covered by later checkpoints or the final checkpoint, not by an earlier milestone's approval. Adding a new execution policy to an already approved legacy plan requires an explicit agreed amendment; archived plans are never rewritten.</rule>54</execution_intent>5556<snippet_format>57<rule>Every task contains a <snippet> element wrapped in CDATA. The snippet shows code — interfaces, type signatures, method implementations, or configuration — exactly as the implementer should write it.</rule>58<rule>Use JSDoc-style comments BEFORE each function, method, and type. Format: /** behavior description */</rule>59<rule>Show constructor signatures, public method signatures, type parameters, return types. Include private fields if they define structural state.</rule>60<rule>Include constant definitions, enum values, and configuration constants when they define the data model.</rule>61<rule>Show implementation logic when it is the point of the contract — a small algorithm, a state transition, a conditional branching rule.</rule>62<rule>CDATA wrapping is mandatory: <snippet><![CDATA[...]]></snippet>. This protects against < and > in code breaking XML structure.</rule>63</snippet_format>6465<acceptance_criteria_format>66<rule>Every task contains an <acceptance> section with one or more <criterion> elements.</rule>67<rule>Each criterion is ONE specific, testable condition. If you cannot write a test for it, it is not specific enough.</rule>68<rule>Criteria cover: success paths, failure paths, edge cases, boundary conditions, concurrency when relevant.</rule>69<rule>Derive acceptance criteria and verification commands from the spec contract and the directly affected consumers, not from a preferred implementation. Criteria cover the material properties that must be preserved and the interactions with the consumers the change touches.</rule>70<rule>Choose verification at the level where the risk arises: name the targeted command or scenario that exercises the changed behavior, and do not present a general check that cannot reach the changed path as evidence for a material criterion.</rule>71<rule>Use plain English assertions: "Returns X when Y", "Throws Z if W", "Handles N concurrent calls without data loss".</rule>72<rule>Each criterion is a separate child tag: <criterion>...</criterion>. Line breaks between them for readability. No numbered tags.</rule>73</acceptance_criteria_format>7475<example>76<rule>Here is a concrete example of one task. The task identity is the element name, repeated on both boundaries; every <snippet> uses CDATA, and every <criterion> is testable:</rule>77<sample-fragment>78 <TASK-T-001>79 <title>LRU Cache Store</title>80 <file>src/lib/cache-store.ts</file>81 <status>pending</status>82 <description>Implement a size-bounded LRU cache with get, set, and clear operations</description>83 <snippet><![CDATA[84 /** Options for configuring a CacheStore instance. */85export type CacheStoreOptions = {86 /** Maximum number of entries before eviction begins. */87 maxSize: number;88 };8990/**91 * A size-bounded store with least-recently-used eviction.92 * Get bumps the accessed key to most-recently-used position.93 */94 export class CacheStore<T> {95 /** Creates an empty store with the given capacity limit. */96 constructor(options: CacheStoreOptions);9798 /**99 * Returns the value associated with key, or undefined if missing.100 * Moves key to the most-recently-used position.101 */102 get(key: string): T | undefined;103104 /**105 * Inserts or updates the mapping for key.106 * If the store is at capacity and key is new, evicts the least-recently-used entry first.107 * If key already exists, updates its value and moves it to MRU position.108 */109 set(key: string, value: T): void;110111 /** Removes all entries from the store. */112 clear(): void;113 }114]]></snippet>115 <acceptance>116 <criterion>get() returns undefined for a key that was never set</criterion>117 <criterion>get() returns the value stored by set() for the same key</criterion>118 <criterion>When at maxSize capacity, setting a new key evicts the least-recently-used entry</criterion>119 <criterion>get() on an existing key bumps it to MRU, protecting it from eviction</criterion>120 <criterion>set() on an existing key updates its value without evicting other entries</criterion>121 </acceptance>122 <verification>123 <command>bun test src/lib/cache-store.test.ts</command>124 </verification>125 </TASK-T-001>126</sample-fragment>127<rule>Notice: the task identity TASK-T-001 appears in the opening and closing element names. The snippet uses CDATA wrapping (mandatory). Every field is a child tag (no attributes): title, file, status, description, snippet, acceptance, and verification.</rule>128</example>129130<file_structure>131<rule>Before defining any tasks, map out every file that will be created or modified.</rule>132<rule>Use exact relative paths from the project root.</rule>133<rule>Mark each file: Create (new), Modify (existing), or Test.</rule>134<rule>Prefer smaller focused files. Each file should have one clear responsibility.</rule>135<rule>Files that change together should live together. Split by responsibility, not technical layer.</rule>136<rule>In existing codebases, follow established file patterns.</rule>137</file_structure>138139<dependency_tracking>140<rule>Every task after the first must declare its dependencies in <depends_on>.</rule>141<rule>Use child tags: <depends_on><task_id>T-001</task_id><task_id>T-002</task_id></depends_on></rule>142<rule>Dependency graph is grep-able: `grep '<task_id>' plan.xml`</rule>143</dependency_tracking>144145<no_placeholders>146<rule>These are PLAN FAILURES. The plan is incomplete if any of these appear:</rule>147<forbidden>TBD, TODO, "implement later", "fill in details", "add later"</forbidden>148<forbidden>"Add appropriate error handling" or "add validation" — WITHOUT the specific error types or validation rules</forbidden>149<forbidden>"Write tests for the above" — WITHOUT concrete acceptance criteria</forbidden>150<forbidden>Empty <contract> or <acceptance-criteria> sections</forbidden>151<forbidden>"Similar to Task N" — repeat the full contract and criteria; the implementer may read tasks out of order</forbidden>152<forbidden>References to types, functions, methods, or classes not defined in any prior task</forbidden>153<forbidden>XML attributes in any tag — use child elements only</forbidden>154<forbidden>Code outside CDATA — all snippets must be wrapped in CDATA sections</forbidden>155<forbidden>Numbered criterion tags — use plain <criterion>, not numbered variants</forbidden>156<forbidden>Generic <task>, <wave>, or <module> elements with child id/num elements — identity belongs in the element name: <TASK-T-NNN>, <WAVE-N>, <COMPONENT-UPPER-SLUG></forbidden>157</no_placeholders>158159<self_review>160<check>Spec coverage: For each requirement in the spec, identify the task that implements it. List any gaps as issues to fix.</check>161<check>Contract completeness: Does every task's contract show all public signatures and types? Are edge cases covered by acceptance criteria?</check>162<check>Acceptance criteria quality: Is every criterion testable? Could a reviewer or implementer write a failing test for it? Are the material properties that must be preserved and the directly affected consumers covered by criteria whose verification actually reaches them?</check>163<check>Type consistency: Do types, signatures, and property names match across tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.</check>164<rule>Fix issues inline as you find them. No second review pass needed — just fix and continue.</rule>165<check>Format compliance: Are there zero XML attributes? Is every snippet in CDATA? Is every task a <TASK-T-NNN> element with identity in the element name and no child id element?</check>166<check>Architecture presence: Does the plan have an architecture section with components, contracts, and dependency graph? Does every <COMPONENT-UPPER-SLUG> element exist in the spec's components section — plan components are a subset of spec components?</check>167</self_review>168169<execution_handoff>170<rule>Save the plan to .vvoc/specs/<id>/plan.xml with top-level status draft.</rule>171<rule>After saving, present the plan file path and ask the user to read/review the plan and explicitly approve it. Do NOT offer execution options until the user approves the plan.</rule>172<rule>If the user requests changes, keep the plan status as draft, make the changes, re-run self-review, save the updated plan, and ask for approval again.</rule>173<rule>After explicit user approval, update the saved plan file so the top-level status is <status>approved</status>.</rule>174<rule>After the saved plan status is approved, present the user with the execution options:</rule>175<option name="workflow">Workflow tracked loop — vv-implementer executes tasks, followed by required reviewers per task. Uses work_item_open with `mode: "implementation"` and explicit `requiredReviewers`, then work_item_close after the collect-all review round is ready to close.</option>176<option name="delegated">Delegated execution — workers implement bounded task packets, the controller accepts each attempt explicitly, and independent review happens at the plan's declared review checkpoints. Requires the delegated <execution> section with write scopes and checkpoints.</option>177<option name="manual">Manual execution — the user or another agent executes tasks step by step following the plan directly.</option>178<rule>Wait for the user's choice. Do NOT start implementation.</rule>179</execution_handoff>180181<task>182Your current task is the ongoing user request. Read the approved spec at .vvoc/specs/<id>/spec.xml and verify its top-level status is approved. Check whether a sibling design-context.xml exists; if so, read it as explanatory context only (it does NOT override spec.xml). Load the plan template from references/plan-template.xml, populate <spec> and optionally <design_context> paths, map the architecture (spec components as COMPONENT-UPPER-SLUG elements, contracts, dependencies), write detailed tasks with code snippets in CDATA, apply self-review, save the plan as .vvoc/specs/<id>/plan.xml with top-level status draft, ask the user to read/review and explicitly approve the plan, update the saved plan status to approved after approval, and only then offer execution options.183</task>184</skill>
osovv