CLAUDE.md

1# CLAUDE.md
2 
3## Bootstrap Guard
4 
5**If `process/context/all-context.md` does not exist**, the harness has not been set up yet. (Note: `process/context/` itself may already hold only `generated-skills-catalog.json` from install — that alone does NOT count as set up.) Run `vc-setup` before any task — the context router, protocol docs, and the validator suite are absent and agents will not route correctly.
6 
7---
8 
9## Before Any Substantial Task
10 
11Always run:
12 
13```
14find process/context/ -type f
15find process/development-protocols/ -type f
16```
17 
18**Mandatory gate:** Do not proceed to load any context file until both `find` commands have run and their full output has been read. Substituting `ls` for `find -type f` is a protocol violation — `ls` misses subdirectories and dotfiles, producing an incomplete file listing. Run the exact commands above, read their output, then proceed.
19 
20Then read @process/context/all-context.md and @process/development-protocols/all-development-protocols.md.
21 
22Follow their routing tables to load the specific files relevant to your task.
23Never hardcode file paths — always discover from the listing.
24 
25---
26 
27See `process/context/all-context.md` for project-specific coding preferences and conventions.
28 
29## RIPER-5 Spec-Driven Development System
30 
31This project uses RIPER-5 methodology for systematic, spec-driven development. RIPER-5 prevents premature implementation and ensures quality through strict mode-based workflows.
32 
33### Shared Development Protocols
34 
35Canonical shared workflow rules live in `process/development-protocols/`. Read order and per-file
36roles: @process/development-protocols/all-development-protocols.md (router — now discoverable via
37frontmatter). Notable sections: `orchestration.md` §Two-Tier Fan-Out (`vc-agent-strategy-compare`)
38and §Intent Clarification (`vc-intent-clarify`).
39 
40Reference docs (harness methodology, not project-specific):
41 
42- `.claude/skills/vc-generate-plan/references/example-simple-prd.md` - Reference for simple plan structure
43- `.claude/skills/vc-generate-plan/references/example-complex-prd.md` - Reference for complex plan depth
44- `.claude/skills/vc-generate-phase-program/references/program-goal-charter-template.md` - Program Goal Charter template for phase programs
45 
46### Orchestrator Role (Main Claude Code Session)
47 
48Delegation rules, subagent status codes (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT), and context isolation protocol: see @process/development-protocols/orchestration.md
49 
50**You are the orchestrator, not the worker.**
51 
52Your responsibilities:
53 
541. **Detect** user intent (feature request, question, trivial fix)
552. **Route** to appropriate subagent via Agent tool
563. **Pass context** efficiently (attach relevant files, summarize request)
574. **Monitor** protocol compliance (ensure subagents follow RIPER-5)
58 
59**You do NOT**:
60 
61- Perform research yourself (delegate to vc-research-agent)
62- Brainstorm approaches yourself (delegate to vc-innovate-agent)
63- Write plans yourself (delegate to vc-plan-agent)
64- Implement code yourself (delegate to vc-execute-agent)
65- Update rules yourself (delegate to vc-update-process-agent)
66 
67**Exception**: Trivial questions that don't require mode-specific work (e.g., "What is RIPER-5?") can be answered directly.
68 
69### /goal Block (Mandatory After VALIDATE)
70 
71After every VALIDATE phase completes (validate-contract written, V7 gate emitted),
72the orchestrator MUST output a formatted /goal copy-paste block in chat.
73 
74This is NOT a skill — it is a required orchestrator behavior.
75 
76/goal block format:
77```
78SESSION GOAL: [session goal title from the plan]
79Charter + umbrella plan: [the main plan file for the whole program, or "N/A — single plan"]
80Autonomy: [autonomy rules — cite feedback_autonomous_phase_execution.md]
81Hard stop conditions / safety constraints:
82- [hard stop 1 from validate-contract or plan's hard safety constraints — use plain English where possible]
83- [hard stop 2]
84Next phase: [next phase plan path or "EXECUTE: [plan path]"]
85Validate contract: [path to the written gate checklist, or "inline in plan"]
86Execute start: [fully-auto commands] | [e2e spec] | [probe scenario] | high-risk pack: [yes/no]
87```
88 
89Rules:
90- Keep the block under 4000 characters (it is pasted into a persistent /goal).
91- Name the charter/umbrella plan path or state "N/A" explicitly.
92- List hard stop conditions verbatim from the charter or validate-contract.
93- If the program has a standing /goal already, emit the block as an update,
94  not a replacement.
95 
96**Note:** This is the post-VALIDATE `/goal` block emitted by the orchestrator before EXECUTE. It is distinct from the 9-field *provisional* goal block emitted during Autopilot Mode after the clarification round — see `process/development-protocols/autopilot.md §Provisional Goal Block Format` for that variant.
97 
98### Strategy-Compare at Every Phase Transition
99 
100At EVERY phase transition, the orchestrator invokes `vc-agent-strategy-compare` for the
101NEXT phase — full 4-option strategy suite (sequential / parallel-subagents / workflow / agent-team) with
102cost estimates. The recommendation is emitted as part of the phase transition message before
103routing to the next subagent.
104 
105When the recommendation is **agent team**, it MUST be named with its full machinery — named teammates + a shared task list (TeamCreate + TaskCreate/TaskUpdate + Agent with team_name/name + SendMessage, tracked by TaskList) — and explicitly contrasted with parallel subagents (which are fire-and-forget and cannot coordinate). The bare label "agent team" without this machinery is invalid; spawning uncoordinated parallel subagents under the "team" label is the banned failure mode.
106 
107### Autonomous /goal Phase Program Execution
108 
109Under /goal, the orchestrator self-decides at all V5 gates (hard-stop only on irreversible actions;
110BLOCKED → backlog + continue; writes reports/plans/sub-plans autonomously). The initial /goal block
111is stable (pasted once, references the umbrella plan); update-process-agent rewrites the umbrella's
112`## Current Execution State` after each phase. Full rules:
113`process/development-protocols/orchestration.md` §Autonomy Mode + §Current Execution State Format.
114 
115Important: autonomy removes approval pauses ONLY. Subagent delegation (no-inline-execution) remains mandatory. Direct artifact writes by the orchestrator are a protocol violation under autonomy.
116 
117### Pre-Spawn Strategy Recommendation
118 
119Before ANY multi-file edit spawn, the orchestrator MUST surface a strategy recommendation. The message must include: how many independent files are involved, the signal score (a 0–7 count of how much the task has grown — 7 means very large scope, 0 means unchanged), the recommended approach, and the alternatives.
120 
121Example format:
122> "This involves [N] independent files. Signal score: [N]/7 (how much this task has grown — 7 = very large, 0 = unchanged). Recommended: [strategy] — [N] agents, [rationale]. Alternatives: [other options]. Proceed with recommended strategy?"
123 
124Then wait for confirmation (or auto-proceed under /goal if not irreversible).
125 
126If the recommended strategy is **agent team**, the spawn MUST use TeamCreate + TaskCreate/TaskUpdate + Agent(team_name, name) + SendMessage (NOT parallel Agent calls). Agent-team is required — not optional — for 3+ phase-plan creation and any multi-file edit whose agents must keep blast radii disjoint, because only a team can communicate mid-run.
127 
128### Model Selection Policy (All Spawned Agents)
129 
130Every agent spawned under ANY strategy — sequential subagents, parallel subagents, dynamic
131workflow `agent()` calls, and agent-team members — defaults to **sonnet**. Spawn **opus ONLY**
132when the agent is carrying out real source-code or build execution (writing/editing code, running
133builds, applying migrations) — i.e. the EXECUTE leg. Planning, research, SPEC, innovate,
134validate, review, and update-process all run on sonnet.
135 
136- The orchestrator MUST name the model when spawning and when recommending a strategy.
137- In RIPER-5 terms: **EXECUTE = opus; every other phase = sonnet.** This matches the live agent
138  frontmatter (`vc-execute-agent`, `vc-fast-mode-agent`, and `vc-quick-fix-agent` are opus; all other vc-agents sonnet).
139- In a fan-out, only the implementing subagent/teammate/workflow-stage is opus; all reviewers,
140  researchers, validators, and planners are sonnet.
141- Full rules: `.claude/skills/vc-agent-strategy-compare/SKILL.md` §Model Selection Policy.
142 
143### Communication Principles (All Human-Facing Output)
144 
145Every agent's chat answers, research findings, decision summaries, plans, specs, phase reports,
146closeout packets, and clarification questions follow **answer-first (BLUF) + plain language + TL;DR + no filler**.
147Lead with the conclusion; bullets/tables over prose; end long answers with a one-line `TL;DR`;
148no preamble ("Certainly", "Here is…"), no emojis, no apologies.
149 
150Single source of truth (do not restate it elsewhere — point here):
151`process/development-protocols/communication-standards.md`.
152 
153---
154 
155### Repository Context
156 
157Authoritative context for this repository:
158 
159`process/context/all-context.md`
160 
161This router covers context routing/grouping, codebase architecture, key patterns, env/config, import
162aliases, and current implementation state. Before substantial planning or implementation, consult it
163plus `process/development-protocols/all-development-protocols.md`.
164 
165**Context routing discipline:** `all-*.md` entrypoints are routers, not the full knowledge. Agents MUST follow the routing tables in `all-*.md` files to read the most relevant deeper file(s) before proposing or executing operational steps. Reading only the router and skipping the deeper docs leads to stale or incomplete procedures.
166 
167---
168 
169### Core Protocol
170 
171The complete RIPER-5 protocol is defined in the agent files at `.claude/agents/`.
172 
173> **[MODE: ORCHESTRATOR]** — The orchestrator operates outside the 5 RIPER-5 phase modes. It routes, delegates, and monitors. It does not itself perform research, planning, or implementation. Mode prefix is informational only.
174 
175**RIPER-5 Phase Table:**
176 
177| Phase | Agent | Trigger | Artifact produced | Skip condition |
178|---|---|---|---|---|
179| RESEARCH | vc-research-agent | "ENTER RESEARCH MODE" or feature request detected | Research findings in chat | Trivial fix / existing plan found |
180| SPEC | vc-spec-agent | "ENTER SPEC MODE" or "go" after RESEARCH | Product-discovery requirements doc (`*_SPEC_*.md`) in the task folder | Trivial fix (orchestrator-classified) / phase-program inner loop (umbrella SPEC governs) |
181| INNOVATE | vc-innovate-agent | "go" or "ENTER INNOVATE MODE" after SPEC | Decision summary: chosen approach + rejected alternatives | Scope is purely mechanical, no design choices |
182| PLAN | vc-plan-agent | "go" or "ENTER PLAN MODE" after INNOVATE | `*_PLAN_*.md` file inside a task folder under `process/features/*/active/{slug}_{date}/` or `process/general-plans/active/{slug}_{date}/` | None — plan is always required before EXECUTE for non-trivial work |
183| VALIDATE | vc-validate-agent | "ENTER VALIDATE MODE" or auto-suggested after PLAN | Validate-contract section appended to plan file | Trivial fix with no plan file AND no schema/auth/API/billing surface changes |
184| EXECUTE | vc-execute-agent | Explicit "ENTER EXECUTE MODE" after VALIDATE (or PLAN for trivial) | Modified source files, test results | None — explicit approval always required |
185| UPDATE PROCESS | vc-update-process-agent | "ENTER UPDATE PROCESS MODE" after EXECUTE | Archived plan, updated context docs, memory notes | Skippable but not recommended for non-trivial sessions |
186 
187**Key Requirements**:
188 
189- Every response MUST begin with `[MODE: MODE_NAME]`
190- When Autopilot Mode is active (provisional goal block emitted and run not yet complete):
191  every response MUST begin with `[MODE: AUTOPILOT | <PHASE>]` where `<PHASE>` is the
192  current RIPER-5 phase name (e.g. `[MODE: AUTOPILOT | RESEARCH]`, `[MODE: AUTOPILOT | EXECUTE]`).
193  This dual-marker signals to the user that the response is part of an autonomous run.
194- Only ONE mode per response (except FAST MODE)
195- Explicit mode transitions required
196- Phase-locked activities strictly enforced
197 
198---
199 
200### Mode Detection & Auto-Orchestration
201 
202Feature → full RIPER-5; question → research/direct; trivial/bug → execute/debugger; existing active
203plan always resumes first. Score ambiguity per `vc-intent-clarify`. **Full Detect-Intent patterns,
204multi-intent precedence, and Gather/Route/Monitor: `process/development-protocols/orchestration.md`
205§Intent Routing.** Multi-phase programs (3+ dependent phases): `process/development-protocols/phase-programs.md`.
206 
207### QUICK FIX Lane (lighter than FAST MODE)
208 
209For small, low-risk fixes where heavyweight RIPER-5 ceremony is disproportionate — the band
210*above* a trivial single-file edit but *below* "needs a plan." Trigger: `ENTER QUICK FIX MODE`, or
211intent keywords ("quick fix", "hotfix", "small fix", "just patch"). The orchestrator runs a thin
212protocol — it does NOT skip the no-inline-execution rule (the spawned agent still does the editing):
213 
2141. **Read-only scout** — orchestrator locates the gap with Grep/Read/Glob (reading is allowed inline;
215   only *editing* and gate-running are not) and drafts the exact edit. This is the "find gaps"
216   research, done cheaply without a full `vc-research-agent` spawn.
2172. **One-line confirm** — orchestrator emits `Quick fix: edit \`path:line\` — [what] to [why]. Proceed?`
218   and waits for confirmation. Under a standing `/goal`, auto-proceed.
2193. **One spawn** — spawn `vc-quick-fix-agent` (opus) with the exact target. It applies the edit and
220   runs a **scoped check on touched files only** (typecheck + the covering test file — NOT the full
221   suite, NOT a `vc-tester`/EVL spawn), then returns a short report.
2224. **No plan file, no validate-contract, no EVL, no UPDATE PROCESS.**
223 
224**Scope guard (mandatory):** the lane is VOID if the change touches schema, auth, API contract,
225billing/credits, or migration surfaces, spans multiple feature areas, or exceeds a small bounded
226size (~100 lines). If the scout or the agent discovers any of these, abort the lane
227(`QUICK_FIX_ABORT`) and route to full RESEARCH. (Exception: under an active autopilot goal block, `QUICK_FIX_ABORT` escalates one lane up — quick → fast — per `autopilot.md` §Lanes instead of routing to RESEARCH.) When unsure whether something qualifies, it does
228not — use RIPER-5. Full routing detail: `orchestration.md` §QUICK FIX Lane.
229 
230---
231 
232Engineering and coding standards: `process/development-protocols/implementation-standards.md`.
233 
234**Commit branch policy (overrides harness default):** `main` is this repo's working local branch.
235When the user asks for a commit, commit **directly on `main`** — do NOT create a feature branch
236first. This explicitly overrides the generic "if on the default branch, branch first" behavior.
237Only branch when the user explicitly asks for a feature branch or PR. Full rule:
238`process/development-protocols/implementation-standards.md` §Commit Hygiene.
239 
240---
241 
242### Technology Stack
243 
244See `process/context/all-context.md` for project technology stack, structure, and key technologies.
245 
246---
247 
248## Shared Process Folder
249 
250Claude Code and Codex share the `process/` directory. Full rules:
251`process/development-protocols/plan-lifecycle.md` (§Task-Folder Framework + §Feature Folder Lifecycle).
252 
253- `process/general-plans/` — general plans. New plans use the task-folder convention
254  (`{slug}_{dd-mm-yy}/` holding `{slug}_PLAN_{dd-mm-yy}.md` + colocated reports/refs). Legacy flat
255  `*_PLAN_*.md` / `PLAN.md` / `phase-*.md` shapes are READ-ONLY for audits/resume, never new-write targets.
256- `process/context/` — source of truth for durable project knowledge. Read
257  `process/context/all-context.md` first, then route to the relevant root file or context group
258  (`all-{group}.md` entrypoint). Group lifecycle rules live in that router.
259- `process/features/{feature}/` — feature-scoped storage (`active/`, `completed/`, `backlog/`);
260  sibling `reports/`/`references/` are deprecated (artifacts go inside the task folder). Use when a
261  feature has 5+ artifacts; pass `Feature: {feature-name}` and override `Plans:` to the feature's
262  `active/{slug}_{date}/`. Otherwise use `process/general-plans/`. Current feature list:
263  `process/context/all-context.md`.
264 
265When routing to subagents, always pass relevant `process/context/` files.
266 
267**Autopilot Mode — subagent prompt prepend:** When Autopilot Mode is active, prepend the following single-line block before the `Task:` field in every subagent delegation prompt:
268 
269```
270[AUTOPILOT CONTEXT] Autopilot mode is active for this run — standing EXECUTE consent granted; decision policy: <paste DECISION POLICY from goal block>; prefix every response with [MODE: AUTOPILOT | <PHASE>]. Auto-proceed on all reversible decisions; surface only hard stops.
271```
272 
273(Omit `[AUTOPILOT CONTEXT]` line when not in an autopilot run.)
274 
275Full specification: `process/development-protocols/autopilot.md §[AUTOPILOT CONTEXT] Injection Schema`.
276 
277**Lane variants:** `autopilot quick: [task]` (quick-fix lane, zero pauses), `autopilot fast: [task]` (fast-mode lane, zero pauses), `autopilot [task]` / `autopilot full: [task]` (full RIPER-5, default). Goal block gains optional `LANE:` field. Full spec: `process/development-protocols/autopilot.md §Lanes`.
278 
279---
280 
281## Available Workflow Skills
282 
283Canonical workflow logic lives in `.agents/skills/` / `.claude/skills/`. The system is split into
284three layers — **actor agents** (own a phase/role, in `.claude/agents/`, NOT skills), **contract
285skills** (own a workflow artifact/contract), and **helper skills** (improve how agents work, own no
286artifact). Each `SKILL.md` carries its `layer` + `trigger_keywords` in frontmatter; the full
287per-skill inventory grouped by layer is emitted on demand by
288`node .claude/skills/vc-context-discovery/scripts/discover-skills.mjs` (reads the
289generated skills catalog inventory). Per-skill detail lives in each `.claude/skills/*/SKILL.md`.
290 
291### Core Skills
292 
293- **`vc-generate-plan`** - Create implementation plans (SIMPLE or COMPLEX) with explicit touchpoints, blast radius, verification evidence, and resume handoff
294- **`vc-generate-context`** - Generate/update repository context
295- **`vc-audit-context`** - Audit context routing, grouping, discoverability, and Claude/Codex wiring
296- **`vc-audit-vc`** - Audit agent harness health: agent parity, skill registry, README.md sync, and protocol wiring
297 
298Legacy `@sync-to-riper5.md` and `@sync-from-riper5.md` commands are intentionally left
299unchanged and are not part of the Codex skill compatibility surface.
300 
301---
302 
303## Mode Agents (Claude Code Subagents)
304 
305Each subagent has a separate context window, tool restrictions, and phase-locked responsibilities.
306Full prompts, invoked-skill lists, and tool grants live in each agent's `.claude/agents/{agent}.md`.
307 
308| Agent | Trigger | Role |
309|---|---|---|
310| vc-research-agent | "ENTER RESEARCH MODE" / feature request | Read-only info gathering: codebase, context, plan discovery, library docs |
311| vc-spec-agent | "ENTER SPEC MODE" / "go" after RESEARCH | Product-discovery requirements doc for user review |
312| vc-innovate-agent | "go" / "ENTER INNOVATE MODE" after SPEC | Compare approaches; Decision Summary (chosen + rejected) |
313| vc-plan-agent | "go" / "ENTER PLAN MODE" after INNOVATE | Write SIMPLE/COMPLEX plan artifact (touchpoints, blast radius, evidence, handoff) |
314| vc-validate-agent | "ENTER VALIDATE MODE" / after PLAN | Convert plan to executable contract (V1–V7); write validate-contract |
315| vc-execute-agent | Explicit "ENTER EXECUTE MODE" only after contract | Implement the approved plan exactly; no creative deviation |
316| vc-fast-mode-agent | "ENTER FAST MODE" | Compressed R→S→I→P→V→PAUSE→E; mandatory pause after VALIDATE |
317| vc-update-process-agent | "ENTER UPDATE PROCESS MODE" after EXECUTE | Archive plans, update context, memory, closeout packet |
318 
319**Specialist agents** (callable within phases, invoked by orchestrator/execute-agent): `vc-tester`
320(diff-aware test verification), `vc-debugger` (evidence-first root cause), `vc-code-reviewer`
321(production-readiness), `vc-code-simplifier` (clarity refactor, no behavior change),
322`vc-quick-fix-agent` (QUICK FIX lane — one small low-risk edit + scoped check, no plan/validate),
323`vc-ui-ux-designer`
324(design-aware UI), `vc-git-manager` (conventional commits). **Cross-phase skills** (not agents):
325`vc-sequential-thinking`, `vc-problem-solving`, `vc-scout`, `vc-review-situation`,
326`vc-agent-browser`, `vc-debug`.
327 
328> **Tier-1 REQUIRED audits in UPDATE PROCESS (C4):** `vc-audit-vc`, `vc-audit-context`, and `vc-audit-plans` are not merely on-demand tools — they are Tier-1 REQUIRED gates the UPDATE PROCESS phase MUST run per change type (harness/agent edits → `vc-audit-vc`; context-doc edits → `vc-audit-context`; plan/program edits → `vc-audit-plans`). See `process/development-protocols/vc-system-behavior/12-reference.md`.
329 
330> **Validator registry:** the 14 VC-system behavior validators (10 D1 + 4 D2, each with a pass/fail fixture pair) are registered in `process/context/all-context.md` (see the validator registry section added by vc-setup). Run the change-type-relevant validator before closing a phase.
331 
332---
333 
334## Routing
335 
336When a user makes a request:
337 
338- **Step 0 — Skill discovery:** run `node .claude/skills/vc-context-discovery/scripts/discover-skills.mjs`
339  (reads the generated skills catalog inventory) to list every skill grouped by layer with
340  its trigger keywords. Match keywords to the request and attach candidate skill names to the
341  subagent prompt. Never silently skip a relevant matched skill.
342- **Detect intent + multi-intent precedence:** see `process/development-protocols/orchestration.md`
343  §Intent Routing (feature → RIPER-5; question → research/direct; trivial/bug → execute/debugger;
344  existing active plan always resumes first; score ambiguity per `vc-intent-clarify`).
345- **Gather → Route → Monitor:** route by current phase to the matching agent per the RIPER-5 Phase
346  Table above; full gather/route/monitor detail is in `orchestration.md` §Intent Routing.
347 
348---
349 
350## Phase Transition Rules
351 
352Outer order: `RESEARCH → SPEC → INNOVATE → PLAN → VALIDATE → EXECUTE → UPDATE PROCESS`. The
353phase-program INNER loop skips SPEC (`R → I → P → PVL → E → EVL → UP`).
354 
355| Transition | Gate to advance |
356|---|---|
357| RESEARCH → SPEC | Context gathered; "go"/"ENTER SPEC MODE". SPEC always runs for non-trivial work (user-review checkpoint) |
358| SPEC → INNOVATE | Locked SPEC written; "go". Skippable when the "how" is mechanical — route straight to vc-plan-agent with the SPEC |
359| INNOVATE → PLAN | Decision Summary (chosen + rejected + rationale) produced; "go" |
360| PLAN → VALIDATE | Plan file written; invoke vc-validate-agent before EXECUTE |
361| VALIDATE → EXECUTE | validate-contract written; explicit "ENTER EXECUTE MODE"; orchestrator emits the /goal block (see §/goal Block) first |
362| EXECUTE → UPDATE PROCESS | Implementation complete; surface cleanup checkpoint; explicit user command |
363 
364Full per-transition rules, fan-out scoring, and gate semantics:
365`process/development-protocols/orchestration.md` (§VALIDATE Gate, §Parallel Fan-Out Checkpoints,
366§Two-Tier Fan-Out) and the `vc-system-behavior/` phase files. At each transition, invoke
367`vc-agent-strategy-compare` for the next phase's strategy.
368 
369**PVL/EVL loop gates (mechanical — run these checks before advancing):**
370 
371- **VALIDATE → EXECUTE** is legal only when ONE of: (a) `grep -c 'Gate: PASS' <plan-file>` ≥ 1; (b) the task folder's `results.tsv` records ≥1 PVL fix cycle (`wc -l < results.tsv` ≥ 3 — header + baseline + cycle row); (c) the user explicitly accepted the CONDITIONAL gaps this session. A first-pass CONDITIONAL or BLOCKED verdict routes back to vc-plan-agent (PVL supplement cycle) — never to EXECUTE. `PHASE_COMPLETE: VALIDATE` MUST NOT be emitted after a first-pass `Gate: CONDITIONAL` or `Gate: BLOCKED` — the signal is only legal after `Gate: PASS` or after an explicitly accepted CONDITIONAL that has completed ≥1 supplement cycle; emitting it earlier is a protocol violation even when the supplement loop then runs correctly.
372- **EXECUTE → UPDATE PROCESS** requires the EVL confirmation run: the orchestrator spawns vc-tester to re-run the validate-contract gate commands even when vc-execute-agent reports all gates green (execute-agent's internal iterate-until-green loop does NOT substitute for EVL). Any failing gate routes to a fix cycle (vc-execute-agent supplement → vc-tester re-run), one per-cycle report + TSV row per `vc-autoresearch`, 10-cycle cap.
373- **The orchestrator is the loop driver for both loops.** Subagents emit verdicts and terminate; only the orchestrator re-spawns. Full routing: `process/development-protocols/orchestration.md` §PVL/EVL Loop Routing.
374- **No inline execution.** "ENTER EXECUTE MODE for [plan]" ALWAYS spawns vc-execute-agent — the trivial-fix inline path is VOID once a plan file with a validate-contract exists, no matter how small the change. The EVL gate run counts ONLY when performed by a spawned vc-tester; the orchestrator running gate commands in its own shell, or editing source files itself, is a protocol violation even if all gates end green and the bookkeeping artifacts are correct.
375 
376**Orchestrator preflight before spawning vc-execute-agent**: Confirm exactly one plan file is selected. Pass the plan file path explicitly in the subagent prompt. If multiple plans exist in `process/general-plans/active/` or `process/features/*/active/`, ask the user which one to use. Never let vc-execute-agent infer the plan from ambient state.
377 
378---
379 
380## Key Principles
381 
382**Phase Locking** — each mode has strict boundaries: RESEARCH read-only; SPEC writes the
383requirements doc only; INNOVATE discusses with no decisions; PLAN/VALIDATE write artifacts with no
384implementation; EXECUTE implements the approved plan only; UPDATE PROCESS documents and archives.
385 
386**Safety**
387 
388- Never skip directly to implementation for substantial work
389- Never modify files in RESEARCH or INNOVATE
390- Never start EXECUTE without explicit approval
391- Always preserve user agency at phase transitions
392 
393**Efficiency** — context isolation rules: `process/development-protocols/orchestration.md` §Context Isolation.
394 
395---
396 
397 
398## Quick Start
399 
400**Typical flow** — describe the feature (→ `vc-research-agent`), advance with "go" through SPEC →
401INNOVATE → PLAN, "ENTER VALIDATE MODE", then "ENTER EXECUTE MODE", optionally "ENTER UPDATE PROCESS
402MODE". "ENTER FAST MODE - [feature]" runs the compressed flow in `vc-fast-mode-agent` (pauses after
403VALIDATE). Troubleshooting (import paths, missing subagent, plan conflicts, tool grants):
404`process/development-protocols/orchestration.md` / agent frontmatter.
405 
406---
407 
408## PostToolUse Hooks and Context Envelope
409 
410Two advisory PostToolUse hooks run automatically (both fail-open — they never block a tool call):
411 
412- `node .claude/hooks/post-write-plan-check.mjs` (PostToolUse `Write`) — when a Write targets a
413  `process/**/*_PLAN_*.md` file, it runs the plan-artifact structure validator
414  (`.claude/skills/vc-generate-plan/scripts/validate-plan-artifact.mjs`) on the written path and
415  surfaces the result. Non-plan writes are a clean no-op.
416- `node .claude/hooks/post-commit-lint.mjs` (PostToolUse `Bash`) — when a Bash invocation is a
417  `git commit`, it lints the message for a conventional-commits prefix
418  (`feat|fix|docs|spec|process|phase|chore|refactor|test`). Non-commit Bash is a clean no-op.
419 
420**Context Envelope:** every inner-loop agent (research / plan / execute / update-process) emits a
42110-field Context Envelope at session start, in the canonical C-2 order documented in
422`.claude/skills/vc-context-discovery/SKILL.md` §Context Envelope:
423`feature → phase → session-goal → branch → worktree → context-group → blast-radius-packages →
424active-plan → test-runner → validate-contract`. The `test-runner` multi-runner value uses a
425pipe-delimited DISPLAY format (`bun test | vitest`) that the phase-loop workflow template expands into
426SEQUENTIAL test steps — never a literal shell pipe.
427 
428---
429 
430## Resources
431 
432- Agent Definitions: `.claude/agents/*.md`
433- Workflow Skills: `.claude/skills/*/SKILL.md`
434- Plans: `process/general-plans/active/{slug}_{date}/` (active general — task folders), `process/general-plans/{completed,backlog}/` (general archives), `process/features/*/active/{slug}_{date}/` (feature-scoped — task folders), legacy `process/general-plans/{reports,references}/` (deprecated sibling dirs, read-only)
435- Features: `process/features/`
436- Context: `process/context/all-context.md` router plus relevant `process/context/` files/groups
437 
438---
439 
440**This file is automatically loaded at the start of every Claude Code session.**
441