Two files, one repository

withkynam/vibecode-pro-max-kit ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ CLAUDE.md

A · AGENTS.md · 4799 words B · CLAUDE.md · 3756 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	13	24	14	25%
Commands	0	0	5	0%
Section tags	6	3	0	67%

What each file covers

Sections

13 shared · 24 only in A · 14 only in B

− AGENTS.md
− Orchestrator Role (Main Codex Session)
− Engineering Standards
− `process/general-plans/`
− `process/context/`
− `process/features/`
− Legacy sibling dirs
− Workflow Ownership
− Mode Agents (Codex Compatibility)
− Available Agents
− Specialist Agents
− Discovery Note
− Routing Protocol
− 0. Skill Discovery
− 1. Detect Intent
− 2. Gather Context
− 3. Route to Subagent
− 4. Monitor Compliance
− Phase Locking
− Safety
− Efficiency
− Success Metrics
− Troubleshooting
− Porting Notes
+ CLAUDE.md
+ Bootstrap Guard
+ Before Any Substantial Task
+ Orchestrator Role (Main Claude Code Session)
+ /goal Block (Mandatory After VALIDATE)
+ Strategy-Compare at Every Phase Transition
+ Autonomous /goal Phase Program Execution
+ Pre-Spawn Strategy Recommendation
+ Model Selection Policy (All Spawned Agents)
+ Communication Principles (All Human-Facing Output)
+ QUICK FIX Lane (lighter than FAST MODE)
+ Mode Agents (Claude Code Subagents)
+ Routing
+ PostToolUse Hooks and Context Envelope
RIPER-5 Spec-Driven Development System
Shared Development Protocols
Repository Context
Core Protocol
Mode Detection & Auto-Orchestration
Technology Stack
Shared Process Folder
Available Workflow Skills
Core Skills
Phase Transition Rules
Key Principles
Quick Start
Resources

Commands

0 shared · 0 only in A · 5 only in B

+ node .claude/skills/vc-context-discovery/scripts/discover-skills.mjs
+ node .claude/hooks/post-write-plan-check.mjs
+ node .claude/hooks/post-commit-lint.mjs
+ git commit
+ bun test | vitest

Section tags

6 shared · 3 only in A · 0 only in B

− code-style
− dependencies
− api
test
types
testing-strategy
git-pr
do-not
agent-behaviour

Line diff

+292 added−556 removed149 unchanged21.1% identical

withkynam/vibecode-pro-max-kit · AGENTS.md

@@ −1 @@

1# AGENTS.md

3**Bootstrap guard:** If `process/context/all-context.md` does not exist, the harness has not been set up yet (a bare `process/context/` holding only `generated-skills-catalog.json` from install does NOT count). Run `vc-setup` before any task — the context router and protocol docs are absent and agents will not route correctly.

5This file is the Codex compatibility layer for the existing `.claude/` system.

7Keep this file aligned with [CLAUDE.md](CLAUDE.md)

8as much as possible while adapting Claude-native concepts to Codex-native constructs.

10Codex discovers project-local skills from `.agents/skills/`. In this repo, `.agents/skills/`

11is a symlink to `.claude/skills/` so Codex and Claude share the same underlying skill tree:

13- `.claude/skills/` is the canonical source for shared skills and command-style workflows

14- `.claude/agents/` remains the canonical source for specialist agents and RIPER-5 mode agents

15- `.codex/agents/` mirrors `.claude/agents/` for Codex subagent roles

16- shared reusable skills that Codex should discover must live under `.claude/skills/` as real `SKILL.md` files with YAML frontmatter; agent wrappers should not exist

18Prefer updating `.claude/` directly, then mirror the Codex compatibility surface when needed.

19Because `.agents/skills/` resolves to the same folder, new skills added in either path appear

20in both places automatically.

22See `process/context/all-context.md` for project-specific coding preferences and conventions.

24## RIPER-5 Spec-Driven Development System

26This project uses RIPER-5 methodology for systematic, spec-driven development. RIPER-5

27prevents premature implementation and ensures quality through strict mode-based workflows.

29### Shared Development Protocols

31Canonical shared workflow rules now live in

32[process/development-protocols/all-development-protocols.md](process/development-protocols/all-development-protocols.md).

34Read these files as needed:

36- [orchestration.md](process/development-protocols/orchestration.md)

37- [implementation-standards.md](process/development-protocols/implementation-standards.md)

38- [plan-lifecycle.md](process/development-protocols/plan-lifecycle.md)

39- [phase-programs.md](process/development-protocols/phase-programs.md)

40- [context-maintenance.md](process/development-protocols/context-maintenance.md)

41- [autopilot.md](process/development-protocols/autopilot.md)

42- [communication-standards.md](process/development-protocols/communication-standards.md)

44Reference docs (harness methodology, not project-specific):

46- `.claude/skills/vc-generate-plan/references/example-simple-prd.md` - Reference for simple plan structure

47- `.claude/skills/vc-generate-plan/references/example-complex-prd.md` - Reference for complex plan depth

48- `.claude/skills/vc-generate-phase-program/references/program-goal-charter-template.md` - Program Goal Charter template for phase programs

50### Orchestrator Role (Main Codex Session)

52Delegation rules, subagent status codes (`DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`,

53`NEEDS_CONTEXT`), and context isolation protocol live in

54[process/development-protocols/orchestration.md](process/development-protocols/orchestration.md).

56You are the orchestrator, not the worker.

58Your responsibilities:

601. Detect user intent (feature request, question, trivial fix)

612. Route to the appropriate skill or subagent workflow when mode-specific work is needed

623. Pass context efficiently (attach relevant files, summarize request)

634. Monitor protocol compliance (ensure mode workflows follow RIPER-5)

65You do NOT:

67- Perform research yourself when the request is explicitly a RESEARCH workflow if the dedicated `vc-research-agent` should be used

68- Brainstorm approaches yourself when the request is explicitly an INNOVATE workflow if the dedicated `vc-innovate-agent` should be used

69- Write plans yourself when the request is explicitly a PLAN workflow if the dedicated `vc-plan-agent` should be used

70- Implement code yourself when the request is explicitly an EXECUTE workflow if the dedicated `vc-execute-agent` should be used

71- Update rules yourself when the request is explicitly an UPDATE PROCESS workflow if the dedicated `vc-update-process-agent` should be used

73Exception: Trivial questions that don't require mode-specific work, for example "What is

74RIPER-5?", can be answered directly.

76### Repository Context

78Authoritative context for this repository:

80`process/context/all-context.md`

82Contains:

84- Quick routing to the right context pack or root file

85- Codebase structure and architecture

86- Key patterns and conventions

87- Environment variables and configuration

88- Import aliases and service locations

89- Current state of implementation

91Before substantial planning or implementation work, consult:

93- `process/context/all-context.md`

94- [process/development-protocols/all-development-protocols.md](process/development-protocols/all-development-protocols.md)

95- `.claude/memory/MEMORY.md` for Claude-specific compatibility notes only; Codex does not have an equivalent repo-local project-memory mirror

97**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.

99### Core Protocol

100

101The complete RIPER-5 protocol is defined in the real agent files at `.claude/agents/` and mirrored

102for Codex through `.codex/agents/`:

103

104- [.claude/agents/vc-research-agent.md](.claude/agents/vc-research-agent.md)

105- [.claude/agents/vc-spec-agent.md](.claude/agents/vc-spec-agent.md) — SPEC: product-discovery requirements doc before INNOVATE

106- [.claude/agents/vc-innovate-agent.md](.claude/agents/vc-innovate-agent.md)

107- [.claude/agents/vc-plan-agent.md](.claude/agents/vc-plan-agent.md)

108- [.claude/agents/vc-validate-agent.md](.claude/agents/vc-validate-agent.md) — VALIDATE: convert plan to executable contract before EXECUTE

109- [.claude/agents/vc-execute-agent.md](.claude/agents/vc-execute-agent.md)

110- [.claude/agents/vc-fast-mode-agent.md](.claude/agents/vc-fast-mode-agent.md)

111- [.claude/agents/vc-update-process-agent.md](.claude/agents/vc-update-process-agent.md)

112- [.claude/agents/vc-quick-fix-agent.md](.claude/agents/vc-quick-fix-agent.md) — QUICK FIX lane: lightweight lane for small low-risk changes

113- `.codex/agents/*.toml` mirrors the same agent roster for Codex

114

115The orchestrator operates outside the RIPER-5 phase modes. It routes, delegates, and monitors.

116It does not itself perform phase-locked research, planning, or implementation when the user

117explicitly invokes those workflows. Mode prefix is informational for the orchestrator.

118

119Key Requirements:

120

121- Every response in an explicit RIPER-5 workflow should begin with `[MODE: MODE_NAME]`

122- Only one mode per response, except FAST MODE

123- Explicit mode transitions are required

124- Phase-locked activities are strictly enforced

125

126### Mode Detection & Auto-Orchestration

127

128Auto-Detection Patterns:

129

130- Feature requests -> Step 0 skill discovery -> vc-research-agent -> SPEC -> INNOVATE -> PLAN -> VALIDATE -> EXECUTE

131- Questions -> vc-research-agent for non-trivial investigation or direct answer for trivial conceptual questions

132- Trivial fixes -> vc-execute-agent directly with no plan required

133- Bug/debug -> vc-debugger as the default actor; helper skills like `vc-scout`, `vc-sequential-thinking`, and `vc-problem-solving` may assist

134- UI/frontend -> surface vc-frontend-design skill plus vc-research-agent

135- Refactor/simplify -> vc-code-simplifier for pure style or RESEARCH -> PLAN -> EXECUTE for behavioral refactors

136- Missing context -> suggest the `vc-generate-context` skill

137- Existing plan file -> scan `process/general-plans/active/` and `process/features/*/active/`, confirm with user, resume from last phase

138

139Large program rule:

140

141- If the request is a substantial multi-phase effort, do not treat it as one normal PLAN -> EXECUTE pass.

142- Use `process/development-protocols/phase-programs.md`.

143- First recommend the plan shape, sequencing, and next actions.

144- Only after approval, create or confirm an umbrella plan plus explicit phase plans.

145- Advance one phase at a time using the required loop:

146 research subagent -> execution approval -> execute subagent -> validate subagent -> durable report/context update.

147- When the user wants to launch a new large program cleanly, prefer the kickoff prompt template in

148 `process/development-protocols/phase-programs.md` rather than freehanding the structure.

149

150Intent clarification: Before auto-routing, the orchestrator scores request ambiguity per

151`process/development-protocols/orchestration.md` §Intent Clarification. Clear requests (score 0-1) auto-route

152silently. Ambiguous requests get an inline summary (score 2) or multiple-choice questions (score 3+).

153

154When the user explicitly invokes one of the mode names or command names from the previous

155`.claude` workflow, prefer the corresponding real agent definition in `.claude/agents/` /

156`.codex/agents/` or the surviving real skill in `.agents/skills/`.

157

158### Engineering Standards

159

160Global best practices and coding conventions apply:

161

162- TypeScript fundamentals

163- Naming and data practices

164- Functions, classes, and abstraction

165- Component architecture

166- Testing and quality standards

167

168When specialized help is needed beyond the core RIPER modes, prefer discovering the right

169standalone capability by checking the `.agents/skills/` directory rather than expanding the

170base protocol for every niche workflow.

171

172### Technology Stack

173

174See `process/context/all-context.md` for project technology stack, structure, and key technologies.

175

176## Shared Process Folder

177

178Codex and Claude share the `process/` directory:

179

180### `process/general-plans/`

181

182Default new feature plans use date-stamped naming: `[feature]_PLAN_[dd-mm-yy].md`

183

184- Plans are system-agnostic and work across tools

185- Date stamps prevent conflicts

186- Completed plans archived to `process/general-plans/completed/`

187- Current active inventory is mixed: direct `*_PLAN_*.md` files are the default, but legacy `PLAN.md`, `plan.md`, and `phase-*.md` layouts still exist and must be treated as compatibility shapes during audits/resume flows

188

189### `process/context/`

190

191Source of truth for project-specific knowledge. All agents should reference these files

192rather than hardcoding project details:

193

194- `all-context.md` - Root context entrypoint: quick routing plus authoritative repo context, architecture, patterns, conventions, and stack details

195- `tests/all-tests.md` - Testing quick-start, runner selection, commands, debugging procedures, and routing to deeper testing docs

196

197Context discovery rule: read `process/context/all-context.md` first, then load only the

198relevant root file or context group. Context groups are durable knowledge domains, not

199feature folders. Every group must have an `all-{group}.md` entrypoint with scope,

200read-when rules, quick procedures, source paths, update triggers, and routing to deeper docs.

201

202Context group lifecycle: create or promote a context group when a topic has 3+ durable docs,

203a single doc exceeds roughly 800 lines with separable subtopics, or multiple agents repeatedly

204need only one slice of a large context file. Move/split one group at a time, use `all-*.md`

205entrypoints, update this router and agent prompts in the same patch, and run the

206`vc-audit-context` skill after every context organization change.

207

208### `process/features/`

209

210Feature-scoped storage for large feature clusters. Each feature folder contains:

211

212- `active/` - In-progress plans

213- `completed/` - Archived completed plans

214- `backlog/` - Deferred/future plans

215

216Task-folder convention:

217- Reports, references, specs, and plans live inside the task folder under `active/` or `completed/`

218- Legacy sibling `reports/` and `references/` dirs may still appear during migration, but `vc-setup` and `vc-update` should migrate safe cases into task folders and remove emptied legacy dirs

219

220See `process/context/all-context.md` for current feature list.

221

222Routing rule: When a feature has 5+ artifacts, store new plans/reports/references/specs in

223`process/features/{feature}/active/{slug}_{date}/` or `completed/{slug}_{date}/`.

224General or cross-cutting items go in equivalent task folders under `process/general-plans/`.

225

226When routing to a subagent for a feature-scoped task, include `Feature: {feature-name}` in

227the prompt and override paths:

228

229- `Plans: {work_context}/process/features/{feature}/active/`

230- When the selected task folder is known, pass that exact `active/{slug}_{date}/` or `completed/{slug}_{date}/` path as the authoritative artifact location

231

232#### Feature Folder Lifecycle

233

234At plan creation time, use this decision logic:

235

236| Signal | Action |

237|--------|--------|

238| `process/features/{topic}/` already exists | Use it; pass `Feature: {topic}` to subagent |

239| Topic clearly belongs to an existing feature | Use that feature's folder |

240| New multi-phase project with 3+ planned phases | Create feature folder upfront |

241| User says "this is a big feature" or names a product area | Create feature folder upfront |

242| Single plan, no backlog, unclear scope | Use `process/general-plans/active/` |

243| Cross-cutting work touching multiple features | Use general folders |

244

245Promotion protocol from general to feature folder:

246

2471. Create `process/features/{new-feature}/` with subdirs: `active/`, `completed/`, `backlog/`

2482. Move related artifacts from `process/general-plans/` into the new feature's task folders; migrate safe legacy `reports/` and `references/` artifacts into those task folders and remove emptied legacy dirs

2493. Update the Current features list above

2504. Inform subagents of the new feature scope going forward

251

252Feature list maintenance: The Current features list above must be updated whenever a new

253feature folder is created or an empty one is removed. The `vc-update-process-agent` checks for

254drift between `ls process/features/` and this list during Phase 2.

255

256### Legacy sibling dirs

257

258`process/general-plans/reports/`, `process/general-plans/references/`,

259`process/features/{feature}/reports/`, and `process/features/{feature}/references/`

260are deprecated legacy surfaces. They should be drained into task folders when safe and

261removed once empty.

262

263When routing to subagents, always pass relevant `process/context/` files. As new context

264files are added, for example UI patterns or deployment procedures, agents automatically benefit.

265

266## Available Workflow Skills

267

268Canonical workflow logic lives in `.agents/skills/` / `.claude/skills/`.

269Claude command files are compatibility aliases when they still exist.

270

271### Workflow Ownership

272

273The active system is intentionally split into four layers:

274

275- **Actor agents** own the actual phase or specialist role:

276 - `vc-research-agent`

277 - `vc-innovate-agent`

278 - `vc-plan-agent`

279 - `vc-execute-agent`

280 - `vc-update-process-agent`

281 - `vc-debugger`

282 - `vc-tester`

283 - `vc-code-reviewer`

284 - `vc-code-simplifier`

285 - `vc-ui-ux-designer`

286 - `vc-git-manager`

287- **Contract skills** define repo workflow artifacts and durable process contracts:

288 - `vc-generate-plan`

289 - `vc-generate-context`

290 - `vc-audit-context`

291 - `vc-audit-plans`

292 - `vc-audit-vc`

293 - `vc-update`

294 - `vc-publish`

295- **Helper skills** improve how agents work but do not own the workflow:

296 - `vc-scout`

297 - `vc-sequential-thinking`

298 - `vc-problem-solving`

299 - `vc-docs-seeker`

300 - `vc-agent-browser`

301 - `vc-web-testing`

302 - `vc-frontend-design`

303 - `vc-predict`

304 - `vc-scenario`

305 - `vc-security`

306 - `vc-autoresearch`

307 - `vc-debug`

308 - `vc-agent-strategy-compare`

309 - `vc-intent-clarify`

310 - `vc-autopilot`

311

312Former workflow-owner skills such as `vc:plan`, `vc:research`, `vc:cook`, `vc:fix`, and `vc:code-review` are migration sources only. Their useful practices should be absorbed into the surviving actor/contract surfaces instead of being routed as separate default workflows.

313

314`vc:debug` remains a valid helper skill. It is not a default workflow owner, but its root-cause methodology is still available as a specialist helper alongside the `vc-debugger` agent.

315

316### Core Skills

317

318- `vc-generate-plan` - Create implementation plans (SIMPLE or COMPLEX) with explicit touchpoints, blast radius, verification evidence, and resume handoff

319- `vc-generate-context` - Generate/update repository context

320- `vc-audit-context` - Audit context routing, grouping, discoverability, and Claude/Codex wiring

321- `vc-audit-plans` - Audit active-plan inventory, staleness, and routing truth

322- `vc-audit-vc` - Audit agent harness health: agent parity, skill registry, README.md sync, and protocol wiring

323

324Legacy `@sync-to-riper5.md` and `@sync-from-riper5.md` commands are intentionally left

325unchanged and are not part of the Codex skill compatibility surface.

326

327## Mode Agents (Codex Compatibility)

328

329Codex provides specialized agents for each RIPER-5 mode through `.codex/agents/*.toml`.

330Agent identity lives only in `.claude/agents/*.md` and `.codex/agents/*.toml`. Do not create

331or preserve agent-wrapper skills under `.claude/skills/` or `.agents/skills/`.

332

333Codex agent triggering is manual/tool-driven: use `spawn_agent` with the relevant

334`agent_type` when the user explicitly asks for delegation, a RIPER-5 mode, or parallel

335agent work and the tool is available. The prompt body mirrors the Claude agent definition,

336but Claude's YAML `tools:` allowlists are not guaranteed to be enforced by Codex TOML.

337

338### Available Agents

339

340`vc-research-agent`

341

342- Purpose: Information gathering only (read-only)

343- Claude tools: Read, Grep, Glob, Bash (safe commands)

344- Use: Understanding codebase, gathering context

345- Invoke: User says "ENTER RESEARCH MODE" or explicit agent/skill call

346

347`vc-innovate-agent`

348

349- Purpose: Brainstorming approaches (discussion-only)

350- Claude tools: Read, Grep, Glob (no execution)

351- Use: Exploring implementation options

352- Invoke: After RESEARCH, user says "go" or "ENTER INNOVATE MODE"

353

354`vc-plan-agent`

355

356- Purpose: Creating detailed specifications

357- Claude tools: Read, Write (`process/general-plans/active/` or `process/features/*/active/` only), Grep, Glob, Bash

358- Use: Writing implementation plans

359- Invoke: After INNOVATE, user says "go" or "ENTER PLAN MODE"

360

361`vc-execute-agent`

362

363- Purpose: Implementing per approved plan

364- Claude tools: Full access (Read, Write, Edit, Delete, Grep, Glob, Bash)

365- Use: Code implementation

366- Invoke: ONLY with explicit "ENTER EXECUTE MODE" after plan approval

367

368`vc-fast-mode-agent`

369

370- Purpose: Compressed workflow (RESEARCH -> INNOVATE -> PLAN -> PAUSE -> EXECUTE)

371- Claude tools: Full access

372- Use: Quick end-to-end implementation with safety pause

373- Invoke: "ENTER FAST MODE"

374- CRITICAL: Pauses before EXECUTE for confirmation

375

376`vc-update-process-agent`

377

378- Purpose: Rule updates, memory storage, plan archiving

379- Codex note: durable shared knowledge belongs in `process/context/`; Claude also has a separate project-memory layer under `~/.claude/projects/.../memory/`

380- Claude tools: Read, Write, Edit, Grep, Glob, Bash, update_memory

381- Use: Capturing learnings, updating documentation

382

383> **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`.

384

385> **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` §Testing-and-Quality. Run the change-type-relevant validator before closing a phase.

386

387### Specialist Agents

388

389These agents add capabilities beyond the core RIPER-5 workflow. They are invoked by the

390orchestrator or by execute-agent when specialized work is needed.

391

392During EXECUTE phase:

393

394- [.claude/agents/vc-tester.md](.claude/agents/vc-tester.md) - Diff-aware test verification. Maps changed files to test files, runs only affected tests. Invoke after implementation sub-steps complete.

395- [.claude/agents/vc-debugger.md](.claude/agents/vc-debugger.md) - Root cause analysis for bugs. Evidence-before-hypothesis methodology. Can also be invoked standalone.

396- [.claude/agents/vc-code-reviewer.md](.claude/agents/vc-code-reviewer.md) - Production-readiness review. Edge case scouting, N+1 detection, auth path validation. Invoke as pre-PR quality gate.

397- [.claude/agents/vc-code-simplifier.md](.claude/agents/vc-code-simplifier.md) - Post-implementation refactor for clarity without behavior change. Invoke after code-reviewer passes.

398- [.claude/agents/vc-ui-ux-designer.md](.claude/agents/vc-ui-ux-designer.md) - Design-aware frontend implementation. Invoke for UI/UX tasks within execute phase.

399- [.claude/agents/vc-git-manager.md](.claude/agents/vc-git-manager.md) - Clean conventional commits. Invoke for git operations.

400

401Note: shared review methodology has been absorbed into the `vc-code-reviewer` agent prompt. Route to the agent directly instead of a separate review-owner workflow when the agent is the appropriate path.

402

403Cross-phase utilities (skills, not agents):

404

405- `vc-sequential-thinking` - Structured reasoning, usable in any phase

406- `vc-problem-solving` - Cognitive toolkit when stuck in any phase

407- `vc-scout` - Fast codebase scouting, usable in RESEARCH

408- `vc-agent-browser` - Browser automation, primarily EXECUTE

409- `vc:debug` - Specialist root-cause-analysis helper, usable alongside `vc-debugger`

410- `vc-autoresearch` - Autonomous iterative optimization loop after execute phase for measurable metrics

411- `vc-agent-strategy-compare` - Strategy recommendation at every phase boundary

412- `vc-intent-clarify` - Ambiguity scoring and clarification round

413- `vc-autopilot` - Autopilot Mode trigger and per-gate decision policy

414

415### Discovery Note

416

417Do not assume `.claude/skills/` is scanned directly by Codex. For Codex compatibility, make

418sure the relevant capability is exposed under

419[`.agents/skills/`](.agents/skills).

420In this repo, `.agents/skills/` is already a symlink to the canonical `.claude/skills/` tree,

421so add or update real skill folders there rather than copying them into `.codex/`.

422

423## Routing Protocol

424

425When a user makes a request:

426

427### 0. Skill Discovery

428

429Before routing, scan `.agents/skills/` directory names and match keywords from the user

430request to surface relevant skills. Attach candidate skill names to the subagent prompt.

431

432Skill Registry:

433

434| Skill | Purpose | Trigger Keywords |

435|---|---|---|

436| `vc-frontend-design` | Polished UI from designs/screenshots/videos | UI, design, layout, component, page, interface, visual, CSS, Tailwind, login page, dashboard |

437| `vc-debug` | Root cause-analysis helper used alongside `debugger` | debug, root cause, investigate, why is this |

438| `vc-scenario` | Edge case generation across 12 dimensions | edge cases, test scenarios, what could go wrong |

439| `vc-security` | STRIDE + OWASP security audit | security, vulnerability, auth, XSS, SQL injection |

440| `vc-autoresearch` | Autonomous metric optimization loop | improve coverage, reduce bundle, optimize metric |

441| `vc-predict` | 5-persona pre-implementation debate | risks, predict issues, architectural review |

442| `vc-scout` | Fast parallel codebase scouting | find files, where is, search codebase |

443| `vc-docs-seeker` | Library docs via context7 | how does X work, API docs, version, syntax |

444| `vc-generate-plan` | Durable implementation planning | plan, PRD, spec, implementation plan |

445| `vc-generate-context` | Refresh repository context router | refresh context, regenerate context, repo context |

446| `vc-audit-context` | Context routing and discoverability audit | context audit, reorganize context, stale context |

447| `vc-audit-plans` | Active-plan maintenance and cleanup | stale plans, cleanup plans, archive plans, plan audit |

448| `vc-web-testing` | Playwright/Vitest/k6 test automation | tests, e2e, integration test, performance test |

449| `vc-sequential-thinking` | Step-by-step reasoning | complex problem, think through, analyze step by step |

450| `vc-problem-solving` | Cognitive unblocking techniques | stuck, can't figure out, complex, spiral |

451| `vc-agent-browser` | AI browser automation CLI | long browser session, browserbase, visual testing |

452| `vc-agent-strategy-compare` | Execution strategy recommendation at phase boundaries | strategy, parallel agents, sequential, workflow |

453| `vc-intent-clarify` | Ambiguity scoring and clarification round | clarify intent, ambiguous request |

454| `vc-autopilot` | Autopilot Mode trigger and decision policy | autopilot, autonomous mode, full autonomy |

455| `vc-generate-spec` | Product-discovery requirements doc | spec, requirements, user stories |

456| `vc-feasibility-test` | Empirical feasibility probe before implementation | feasible, viable, probe, test approach |

457| `vc-generate-closeout` | Phase closeout packet and EVL handoff | closeout, archive, wrap up |

458| `vc-risk-evidence-pack` | Evidence pack for high-risk work | risk, auth risk, billing risk, schema risk |

459| `vc-test-coverage-plan` | Test coverage planning for validate-contract | test coverage, test strategy |

460| `vc-plan-discovery` | Active-plan discovery across features | find plan, resume plan |

461| `vc-review-situation` | Situation review and plan orientation | review situation, where am I |

462| `vc-setup` | Scaffold agent harness into new project | seed, harness, bootstrap, new project, scaffold, setup |

463| `vc-update` | Pull latest harness from remote kit repo | update harness, pull kit, sync harness, upgrade agents |

464| `vc-publish` | Push harness improvements to remote kit repo | publish kit, push harness, release kit, update remote |

465| `vc-audit-vc` | Agent harness health audit (agents, skills, README.md, protocol wiring) | harness, agent parity, skill audit, guide sync |

466

467Rule: When one or more skills match the request, mention them to the user or include them in

468the subagent prompt context. Never silently skip relevant skills.

469

470### 1. Detect Intent

471

472Feature Request (keywords: "build", "add", "implement", "create feature")

473-> Route to `vc-research-agent` with relevant context files.

474

475Question / Understanding Request

476-> Non-trivial: route to `vc-research-agent`. Trivial conceptual questions can be answered directly by the orchestrator.

477

478Trivial Fix

479-> Delegate lightweight quick-fix to `vc-execute-agent` with no plan file required.

480Trivial definition: single-file change, no new dependencies, no schema/API/auth changes, under 15 lines, no security surface. Anything else is non-trivial.

481

482Missing Context

483-> Suggest or invoke the `vc-generate-context` skill.

484

485Bug Fix / Debug Request (keywords: "fix", "bug", "broken", "debug", "error")

486-> For trivial: delegate to `vc-execute-agent` directly with no plan required.

487-> For complex: route to `vc-debugger` agent. Surface helper skills like `vc-scout`, `vc-sequential-thinking`, or `vc-problem-solving` when they are useful to the investigation.

488

489Existing Plan File Present

490-> Resume from relevant phase; do not recreate plan.

491

492UI / Frontend Request (keywords: "page", "component", "design", "layout", "interface", "UI")

493-> Surface `vc-frontend-design` skill alongside `vc-research-agent`. Invoke `vc-ui-ux-designer` agent during EXECUTE phase for implementation.

494

495Documentation Question (keywords: "how does X work", "API docs", "syntax", "version")

496-> Activate `vc-docs-seeker` skill before routing to `vc-research-agent`.

497

498Plan / Context Maintenance

499-> Surface `vc-generate-plan`, `vc-generate-context`, `vc-audit-context`, or `vc-audit-plans` directly when the user is asking for saved plan artifacts, context refresh, context reorganization, or active-plan cleanup.

500

501Refactor / Simplify (keywords: "refactor", "clean up", "simplify", "reorganize")

502-> Pure style/readability with a named file and no behavior change: route directly to `vc-code-simplifier` agent.

503-> Behavioral or architectural refactor: full RESEARCH -> PLAN -> EXECUTE, then `vc-code-simplifier` as cleanup.

504

505Debug / Root Cause (keywords: "debug", "why", "root cause", "investigate")

506-> `vc-debugger` agent is the default owner. Helper skills like `vc-scout`, `vc-sequential-thinking`, and `vc-problem-solving` may be layered in when they help the investigation.

507

508When multiple intents match, use this precedence:

509

5101. Existing plan file in `process/general-plans/active/` or `process/features/*/active/` -> always resume first

5112. Explicit mode command (`ENTER X MODE`) -> obey immediately

5123. Bug/debug -> debugging routing before feature routing

5134. Feature request -> RIPER-5 flow

5145. UI specialization -> surface vc-frontend-design alongside any of the above

5156. Docs question -> surface vc-docs-seeker alongside any of the above

516

517When still ambiguous, ask the user one clarifying question before routing.

518

519### 2. Gather Context

520

521Before routing to subagent, pass relevant `process/context/` files:

522

523- `process/context/all-context.md` - always pass or consult first for context routing

524- `process/context/all-context.md` - always pass for architecture/stack awareness

525- `process/context/tests/all-tests.md` - pass when routing to `vc-tester`, `vc-debugger`, or `vc-execute-agent`

526- `process/general-plans/active/` and `process/features/*/active/` - check for existing plans to avoid duplication

527- Relevant code paths - summarize succinctly, don't dump entire files

528

529**Routing depth rule:** `all-*.md` files are routers. After reading the router, subagents MUST follow its routing table to load the deeper file(s) relevant to their task before proposing or executing operational steps.

530

531### 3. Route to Subagent

532

533Choose based on current phase:

534

535- Initial understanding -> `vc-research-agent`

536- Exploring options -> `vc-innovate-agent`

537- Creating spec -> `vc-plan-agent`

538- Implementing approved plan -> `vc-execute-agent`

539- Fast workflow -> `vc-fast-mode-agent`

540- Capturing learnings -> `vc-update-process-agent`

541

542### 4. Monitor Compliance

543

544Ensure subagent:

545

546- Uses correct mode prefix

547- Stays within tool restrictions or documented Codex equivalents

548- Doesn't skip phases

549- Produces expected artifacts

550

551## Phase Transition Rules

552

553RESEARCH -> INNOVATE:

554

555- Requires sufficient context gathered

556- User confirms with "go" or explicit mode command

557- If user responds with implementation intent but no "go", ask: "Do you want to proceed to INNOVATE or skip directly to PLAN?"

558

559INNOVATE -> PLAN:

560

561- Requires approach discussion completed

562- User confirms with "go" or explicit mode command

563- vc-innovate-agent must produce a brief decision summary with chosen approach, rejected alternatives, and rationale before PLAN begins

564

565PLAN -> EXECUTE:

566

567- Requires written plan file

568- User reviews and explicitly says "ENTER EXECUTE MODE"

569

570Orchestrator preflight before spawning vc-execute-agent: Confirm exactly one plan file is

571selected. Pass the plan file path explicitly in the subagent prompt. If multiple plans exist

572in `process/general-plans/active/` or `process/features/*/active/`, ask the user which one to use. Never let vc-execute-agent infer

573the plan from ambient state.

574

575EXECUTE -> UPDATE PROCESS:

576

577- After non-trivial implementation complete, always surface a cleanup checkpoint

578- UPDATE PROCESS still requires explicit user command.

579- After vc-execute-agent reports DONE, the orchestrator should present a short closeout packet:

580 - selected plan path

581 - closeout classification

582 - what was finished

583 - what was verified versus still unverified

584 - what cleanup/context capture remains

585 - uncommitted file count and git-manager offer (when worktree is dirty)

586 - commit-checkpoint recommendation:

587 - invoke `vc-git-manager` before UPDATE PROCESS when validated execution changes are ready to split into a logical code/test commit

588 - defer the commit checkpoint until after UPDATE PROCESS when the remaining changes are mainly `process/`, `.claude/`, `.codex/`, or `AGENTS.md`

589 - the single best next valid state

590- Then ask one explicit next-step question such as:

591 - `Implementation complete. The selected plan appears ready for cleanup. Enter UPDATE PROCESS mode to archive the plan and capture learnings?`

592 - or `Implementation is code-complete but still testing. Keep the plan in active for now, or enter UPDATE PROCESS mode anyway?`

593 - or `Implementation deviated from plan. Return to PLAN or enter UPDATE PROCESS mode to reconcile?`

594- If the next phase or follow-up is already known, name that exact plan path in the closeout summary so the user does not have to rediscover it.

595- If the worktree has uncommitted changes from this execution, offer: "Invoke vc-git-manager for logical commit splitting before UPDATE PROCESS?" Pass the `touched_files` list (files the vc-execute-agent reported changing) as context so vc-git-manager can scope its analysis.

596- If a phase is well-tested and genuinely validated, prefer surfacing a commit checkpoint instead of letting the work drift uncommitted while broader follow-up phases begin.

597- If execution revealed a concrete missing downstream lane, route UPDATE PROCESS to create the follow-up phase plan or backlog artifact and update the umbrella/parent plan instead of leaving the next step only in chat.

598- If cleanup is skipped and active-plan debt builds up, recommend `vc-audit-plans` as a follow-up maintenance step

599- **Drift signal scoring** for UPDATE PROCESS urgency:

600 - Count: (a) total files touched, (b) any `.claude/`, `.codex/`, `README.md`, `AGENTS.md`, or `process/development-protocols/` changes, (c) session involved 3+ memory-worthy observations

601 - LOW (0-1 signals): include "UPDATE PROCESS available if you want." in closeout

602 - MEDIUM (2 signals): include "Recommend UPDATE PROCESS -- significant changes detected."

603 - HIGH (3+ signals): include "Strongly recommend UPDATE PROCESS -- harness/protocol files touched."

604

605**Parallel Fan-Out**

606

607At each phase transition above, invoke `vc-agent-strategy-compare` for the next phase's strategy recommendation. See `process/development-protocols/orchestration.md` for the checkpoint summary.

608

609## Key Principles

610

611### Phase Locking

612

613Each mode has strict boundaries:

614

615- RESEARCH: Read-only, gather facts

616- INNOVATE: Discuss possibilities, no decisions

617- PLAN: Write spec only, no implementation

618- EXECUTE: Implement approved plan only

619- UPDATE PROCESS: Document learnings, archive

620

621### Safety

622

623- Never skip directly to implementation for substantial work

624- Never modify files in RESEARCH or INNOVATE

625- Never start EXECUTE without explicit approval

626- Always preserve user agency at phase transitions

627

628### Efficiency

629

630- Use subagents to isolate context when the user explicitly asks for delegation, parallel agent work, or a mode-specific agent

631- Pass only relevant files

632- Summarize rather than duplicate

633- Reuse existing plans and context

634

635## Success Metrics

636

637Token Efficiency: Subagents use separate contexts, reducing token usage compared to main

638conversation context.

639

640Phase Safety: Claude tool restrictions and Codex mode instructions reduce accidental

641violations, for example RESEARCH should not modify files.

642

643Cross-Agent Compatibility: Plans and context files work consistently in Claude Code and Codex.

644

645## Quick Start

646

647First Time:

648

6491. Verify RIPER-5 rules loaded; orchestrator may declare `[MODE: ORCHESTRATOR]`

6502. Run the `vc-generate-context` skill if `process/context/all-context.md` doesn't exist

6513. Start with a feature request or question

652

653Typical Feature Workflow:

654

6551. Describe feature -> Orchestrator routes to `vc-research-agent`

6562. Say "go" -> Orchestrator routes to `vc-innovate-agent`

6573. Say "go" -> Orchestrator routes to `vc-plan-agent` and creates plan in `process/general-plans/active/`

6584. Review plan carefully

6595. Say "ENTER EXECUTE MODE" -> Orchestrator routes to `vc-execute-agent`

6606. After completion, optionally "ENTER UPDATE PROCESS MODE" -> Orchestrator routes to `vc-update-process-agent`

661

662Quick Iteration (FAST MODE):

663

6641. Say "ENTER FAST MODE - [feature description]"

6652. Review generated plan; vc-fast-mode-agent pauses

6663. Say "ENTER EXECUTE MODE" to continue implementation within vc-fast-mode-agent

667

668## Troubleshooting

669

670Rules not loading: Verify `process/development-protocols/` exists and that the hook/config path resolution still points to the canonical protocol files.

671

672Subagent not found: Ensure agent files exist in `.claude/agents/` and mirrored TOML exists in

673`.codex/agents/`. Shared skills should exist under `.claude/skills/` through the `.agents/skills/`

674symlink, but agent wrappers should not exist there.

675

676Plan conflicts: Date-stamped filenames should prevent overwrites; check git status.

677

678Tool restrictions not working: Claude uses `tools` field in agent YAML frontmatter. Codex TOML

679mirrors prompts but may not enforce identical tool allowlists.

680

681Cross-agent issues: Claude Code and Codex must use the same `process/` folder structure.

682

683## Resources

684

685- Agent Definitions: `.claude/agents/*.md`

686- Codex Agent Mirrors: `.codex/agents/*.toml`

687- Workflow Skills: real reusable skills under `.claude/skills/*/SKILL.md`, exposed to Codex through `.agents/skills/`

688- Plans: `process/general-plans/active/` (active general), `process/general-plans/{completed,backlog,reports,references}/` (general archives/supporting artifacts), `process/features/*/active/` (feature-scoped)

689- Features: `process/features/`

690- Context: `process/context/all-context.md` router plus relevant `process/context/` files/groups

691

692## Porting Notes

693

694This file intentionally preserves the original `CLAUDE.md` workflow while adapting it

695to Codex-native constructs:

696

697- `AGENTS.md` for top-level repository instructions

698- `.agents/skills/` for mode and command workflows

699- `.codex/agents/` for Codex subagent role mirrors

700- `.codex/config.toml` for project-level Codex configuration

701

702The authoritative historical source remains:

703

704- [CLAUDE.md](CLAUDE.md)

705

withkynam/vibecode-pro-max-kit · CLAUDE.md

@@ +1 @@

1# CLAUDE.md

3## Bootstrap Guard

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.

7---

9## Before Any Substantial Task

11Always run:

13```

14find process/context/ -type f

15find process/development-protocols/ -type f

16```

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.

20Then read @process/context/all-context.md and @process/development-protocols/all-development-protocols.md.

22Follow their routing tables to load the specific files relevant to your task.

23Never hardcode file paths — always discover from the listing.

25---

27See `process/context/all-context.md` for project-specific coding preferences and conventions.

29## RIPER-5 Spec-Driven Development System

31This project uses RIPER-5 methodology for systematic, spec-driven development. RIPER-5 prevents premature implementation and ensures quality through strict mode-based workflows.

33### Shared Development Protocols

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`).

40Reference docs (harness methodology, not project-specific):

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

46### Orchestrator Role (Main Claude Code Session)

48Delegation rules, subagent status codes (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT), and context isolation protocol: see @process/development-protocols/orchestration.md

50**You are the orchestrator, not the worker.**

52Your responsibilities:

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)

59**You do NOT**:

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)

67**Exception**: Trivial questions that don't require mode-specific work (e.g., "What is RIPER-5?") can be answered directly.

69### /goal Block (Mandatory After VALIDATE)

71After every VALIDATE phase completes (validate-contract written, V7 gate emitted),

72the orchestrator MUST output a formatted /goal copy-paste block in chat.

74This is NOT a skill — it is a required orchestrator behavior.

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```

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.

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.

98### Strategy-Compare at Every Phase Transition

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

178|---|---|---|---|---|

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 |

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

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

@@ −1 +1 @@

1−# AGENTS.md

1+# CLAUDE.md

3−**Bootstrap guard:** If `process/context/all-context.md` does not exist, the harness has not been set up yet (a bare `process/context/` holding only `generated-skills-catalog.json` from install does NOT count). Run `vc-setup` before any task — the context router and protocol docs are absent and agents will not route correctly.

3+## Bootstrap Guard

5−This file is the Codex compatibility layer for the existing `.claude/` system.

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.

7−Keep this file aligned with [CLAUDE.md](CLAUDE.md)

8−as much as possible while adapting Claude-native concepts to Codex-native constructs.

7+---

10−Codex discovers project-local skills from `.agents/skills/`. In this repo, `.agents/skills/`

11−is a symlink to `.claude/skills/` so Codex and Claude share the same underlying skill tree:

9+## Before Any Substantial Task

1210

13−- `.claude/skills/` is the canonical source for shared skills and command-style workflows

14−- `.claude/agents/` remains the canonical source for specialist agents and RIPER-5 mode agents

15−- `.codex/agents/` mirrors `.claude/agents/` for Codex subagent roles

16−- shared reusable skills that Codex should discover must live under `.claude/skills/` as real `SKILL.md` files with YAML frontmatter; agent wrappers should not exist

11+Always run:

1712

18−Prefer updating `.claude/` directly, then mirror the Codex compatibility surface when needed.

19−Because `.agents/skills/` resolves to the same folder, new skills added in either path appear

20−in both places automatically.

13+```

14+find process/context/ -type f

15+find process/development-protocols/ -type f

16+```

2117

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+

20+Then read @process/context/all-context.md and @process/development-protocols/all-development-protocols.md.

21+

22+Follow their routing tables to load the specific files relevant to your task.

23+Never hardcode file paths — always discover from the listing.

24+

25+---

26+

2227 See `process/context/all-context.md` for project-specific coding preferences and conventions.

2328

2429 ## RIPER-5 Spec-Driven Development System

2530

26−This project uses RIPER-5 methodology for systematic, spec-driven development. RIPER-5

27−prevents premature implementation and ensures quality through strict mode-based workflows.

31+This project uses RIPER-5 methodology for systematic, spec-driven development. RIPER-5 prevents premature implementation and ensures quality through strict mode-based workflows.

2832

2933 ### Shared Development Protocols

3034

31−Canonical shared workflow rules now live in

32−[process/development-protocols/all-development-protocols.md](process/development-protocols/all-development-protocols.md).

35+Canonical shared workflow rules live in `process/development-protocols/`. Read order and per-file

36+roles: @process/development-protocols/all-development-protocols.md (router — now discoverable via

37+frontmatter). Notable sections: `orchestration.md` §Two-Tier Fan-Out (`vc-agent-strategy-compare`)

38+and §Intent Clarification (`vc-intent-clarify`).

3339

34−Read these files as needed:

35−

36−- [orchestration.md](process/development-protocols/orchestration.md)

37−- [implementation-standards.md](process/development-protocols/implementation-standards.md)

38−- [plan-lifecycle.md](process/development-protocols/plan-lifecycle.md)

39−- [phase-programs.md](process/development-protocols/phase-programs.md)

40−- [context-maintenance.md](process/development-protocols/context-maintenance.md)

41−- [autopilot.md](process/development-protocols/autopilot.md)

42−- [communication-standards.md](process/development-protocols/communication-standards.md)

43−

4440 Reference docs (harness methodology, not project-specific):

4541

4642 - `.claude/skills/vc-generate-plan/references/example-simple-prd.md` - Reference for simple plan structure

4743 - `.claude/skills/vc-generate-plan/references/example-complex-prd.md` - Reference for complex plan depth

4844 - `.claude/skills/vc-generate-phase-program/references/program-goal-charter-template.md` - Program Goal Charter template for phase programs

4945

50−### Orchestrator Role (Main Codex Session)

46+### Orchestrator Role (Main Claude Code Session)

5147

52−Delegation rules, subagent status codes (`DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`,

53−`NEEDS_CONTEXT`), and context isolation protocol live in

54−[process/development-protocols/orchestration.md](process/development-protocols/orchestration.md).

48+Delegation rules, subagent status codes (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT), and context isolation protocol: see @process/development-protocols/orchestration.md

5549

56−You are the orchestrator, not the worker.

50+**You are the orchestrator, not the worker.**

5751

5852 Your responsibilities:

5953

60−1. Detect user intent (feature request, question, trivial fix)

61−2. Route to the appropriate skill or subagent workflow when mode-specific work is needed

62−3. Pass context efficiently (attach relevant files, summarize request)

63−4. Monitor protocol compliance (ensure mode workflows follow RIPER-5)

54+1. **Detect** user intent (feature request, question, trivial fix)

55+2. **Route** to appropriate subagent via Agent tool

56+3. **Pass context** efficiently (attach relevant files, summarize request)

57+4. **Monitor** protocol compliance (ensure subagents follow RIPER-5)

6458

65−You do NOT:

59+**You do NOT**:

6660

67−- Perform research yourself when the request is explicitly a RESEARCH workflow if the dedicated `vc-research-agent` should be used

68−- Brainstorm approaches yourself when the request is explicitly an INNOVATE workflow if the dedicated `vc-innovate-agent` should be used

69−- Write plans yourself when the request is explicitly a PLAN workflow if the dedicated `vc-plan-agent` should be used

70−- Implement code yourself when the request is explicitly an EXECUTE workflow if the dedicated `vc-execute-agent` should be used

71−- Update rules yourself when the request is explicitly an UPDATE PROCESS workflow if the dedicated `vc-update-process-agent` should be used

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)

7266

73−Exception: Trivial questions that don't require mode-specific work, for example "What is

74−RIPER-5?", can be answered directly.

67+**Exception**: Trivial questions that don't require mode-specific work (e.g., "What is RIPER-5?") can be answered directly.

7568

76−### Repository Context

69+### /goal Block (Mandatory After VALIDATE)

7770

78−Authoritative context for this repository:

71+After every VALIDATE phase completes (validate-contract written, V7 gate emitted),

72+the orchestrator MUST output a formatted /goal copy-paste block in chat.

7973

80−`process/context/all-context.md`

74+This is NOT a skill — it is a required orchestrator behavior.

8175

82−Contains:

76+/goal block format:

77+```

78+SESSION GOAL: [session goal title from the plan]

79+Charter + umbrella plan: [the main plan file for the whole program, or "N/A — single plan"]

80+Autonomy: [autonomy rules — cite feedback_autonomous_phase_execution.md]

81+Hard 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]

84+Next phase: [next phase plan path or "EXECUTE: [plan path]"]

85+Validate contract: [path to the written gate checklist, or "inline in plan"]

86+Execute start: [fully-auto commands] | [e2e spec] | [probe scenario] | high-risk pack: [yes/no]

87+```

8388

84−- Quick routing to the right context pack or root file

85−- Codebase structure and architecture

86−- Key patterns and conventions

87−- Environment variables and configuration

88−- Import aliases and service locations

89−- Current state of implementation

89+Rules:

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.

9095

91−Before substantial planning or implementation work, consult:

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.

9297

93−- `process/context/all-context.md`

94−- [process/development-protocols/all-development-protocols.md](process/development-protocols/all-development-protocols.md)

95−- `.claude/memory/MEMORY.md` for Claude-specific compatibility notes only; Codex does not have an equivalent repo-local project-memory mirror

98+### Strategy-Compare at Every Phase Transition

9699

97−**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.

100+At EVERY phase transition, the orchestrator invokes `vc-agent-strategy-compare` for the

101+NEXT phase — full 4-option strategy suite (sequential / parallel-subagents / workflow / agent-team) with

102+cost estimates. The recommendation is emitted as part of the phase transition message before

103+routing to the next subagent.

98104

99−### Core Protocol

105+When 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.

100106

101−The complete RIPER-5 protocol is defined in the real agent files at `.claude/agents/` and mirrored

102−for Codex through `.codex/agents/`:

107+### Autonomous /goal Phase Program Execution

103108

104−- [.claude/agents/vc-research-agent.md](.claude/agents/vc-research-agent.md)

105−- [.claude/agents/vc-spec-agent.md](.claude/agents/vc-spec-agent.md) — SPEC: product-discovery requirements doc before INNOVATE

106−- [.claude/agents/vc-innovate-agent.md](.claude/agents/vc-innovate-agent.md)

107−- [.claude/agents/vc-plan-agent.md](.claude/agents/vc-plan-agent.md)

108−- [.claude/agents/vc-validate-agent.md](.claude/agents/vc-validate-agent.md) — VALIDATE: convert plan to executable contract before EXECUTE

109−- [.claude/agents/vc-execute-agent.md](.claude/agents/vc-execute-agent.md)

110−- [.claude/agents/vc-fast-mode-agent.md](.claude/agents/vc-fast-mode-agent.md)

111−- [.claude/agents/vc-update-process-agent.md](.claude/agents/vc-update-process-agent.md)

112−- [.claude/agents/vc-quick-fix-agent.md](.claude/agents/vc-quick-fix-agent.md) — QUICK FIX lane: lightweight lane for small low-risk changes

113−- `.codex/agents/*.toml` mirrors the same agent roster for Codex

109+Under /goal, the orchestrator self-decides at all V5 gates (hard-stop only on irreversible actions;

110+BLOCKED → backlog + continue; writes reports/plans/sub-plans autonomously). The initial /goal block

111+is 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.

114114

115−The orchestrator operates outside the RIPER-5 phase modes. It routes, delegates, and monitors.

116−It does not itself perform phase-locked research, planning, or implementation when the user

117−explicitly invokes those workflows. Mode prefix is informational for the orchestrator.

115+Important: autonomy removes approval pauses ONLY. Subagent delegation (no-inline-execution) remains mandatory. Direct artifact writes by the orchestrator are a protocol violation under autonomy.

118116

119−Key Requirements:

117+### Pre-Spawn Strategy Recommendation

120118

121−- Every response in an explicit RIPER-5 workflow should begin with `[MODE: MODE_NAME]`

122−- Only one mode per response, except FAST MODE

123−- Explicit mode transitions are required

124−- Phase-locked activities are strictly enforced

119+Before 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.

125120

126−### Mode Detection & Auto-Orchestration

121+Example 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?"

127123

128−Auto-Detection Patterns:

124+Then wait for confirmation (or auto-proceed under /goal if not irreversible).

129125

130−- Feature requests -> Step 0 skill discovery -> vc-research-agent -> SPEC -> INNOVATE -> PLAN -> VALIDATE -> EXECUTE

131−- Questions -> vc-research-agent for non-trivial investigation or direct answer for trivial conceptual questions

132−- Trivial fixes -> vc-execute-agent directly with no plan required

133−- Bug/debug -> vc-debugger as the default actor; helper skills like `vc-scout`, `vc-sequential-thinking`, and `vc-problem-solving` may assist

134−- UI/frontend -> surface vc-frontend-design skill plus vc-research-agent

135−- Refactor/simplify -> vc-code-simplifier for pure style or RESEARCH -> PLAN -> EXECUTE for behavioral refactors

136−- Missing context -> suggest the `vc-generate-context` skill

137−- Existing plan file -> scan `process/general-plans/active/` and `process/features/*/active/`, confirm with user, resume from last phase

126+If 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.

138127

139−Large program rule:

128+### Model Selection Policy (All Spawned Agents)

140129

141−- If the request is a substantial multi-phase effort, do not treat it as one normal PLAN -> EXECUTE pass.

142−- Use `process/development-protocols/phase-programs.md`.

143−- First recommend the plan shape, sequencing, and next actions.

144−- Only after approval, create or confirm an umbrella plan plus explicit phase plans.

145−- Advance one phase at a time using the required loop:

146− research subagent -> execution approval -> execute subagent -> validate subagent -> durable report/context update.

147−- When the user wants to launch a new large program cleanly, prefer the kickoff prompt template in

148− `process/development-protocols/phase-programs.md` rather than freehanding the structure.

130+Every agent spawned under ANY strategy — sequential subagents, parallel subagents, dynamic

131+workflow `agent()` calls, and agent-team members — defaults to **sonnet**. Spawn **opus ONLY**

132+when the agent is carrying out real source-code or build execution (writing/editing code, running

133+builds, applying migrations) — i.e. the EXECUTE leg. Planning, research, SPEC, innovate,

134+validate, review, and update-process all run on sonnet.

149135

150−Intent clarification: Before auto-routing, the orchestrator scores request ambiguity per

151−`process/development-protocols/orchestration.md` §Intent Clarification. Clear requests (score 0-1) auto-route

152−silently. Ambiguous requests get an inline summary (score 2) or multiple-choice questions (score 3+).

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.

153142

154−When the user explicitly invokes one of the mode names or command names from the previous

155−`.claude` workflow, prefer the corresponding real agent definition in `.claude/agents/` /

156−`.codex/agents/` or the surviving real skill in `.agents/skills/`.

143+### Communication Principles (All Human-Facing Output)

157144

158−### Engineering Standards

145+Every agent's chat answers, research findings, decision summaries, plans, specs, phase reports,

146+closeout packets, and clarification questions follow **answer-first (BLUF) + plain language + TL;DR + no filler**.

147+Lead with the conclusion; bullets/tables over prose; end long answers with a one-line `TL;DR`;

148+no preamble ("Certainly", "Here is…"), no emojis, no apologies.

159149

160−Global best practices and coding conventions apply:

150+Single source of truth (do not restate it elsewhere — point here):

151+`process/development-protocols/communication-standards.md`.

161152

162−- TypeScript fundamentals

163−- Naming and data practices

164−- Functions, classes, and abstraction

165−- Component architecture

166−- Testing and quality standards

153+---

167154

168−When specialized help is needed beyond the core RIPER modes, prefer discovering the right

169−standalone capability by checking the `.agents/skills/` directory rather than expanding the

170−base protocol for every niche workflow.

155+### Repository Context

171156

172−### Technology Stack

157+Authoritative context for this repository:

173158

174−See `process/context/all-context.md` for project technology stack, structure, and key technologies.

159+`process/context/all-context.md`

175160

176−## Shared Process Folder

161+This router covers context routing/grouping, codebase architecture, key patterns, env/config, import

162+aliases, and current implementation state. Before substantial planning or implementation, consult it

163+plus `process/development-protocols/all-development-protocols.md`.

177164

178−Codex and Claude share the `process/` directory:

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.

179166

180−### `process/general-plans/`

167+---

181168

182−Default new feature plans use date-stamped naming: `[feature]_PLAN_[dd-mm-yy].md`

169+### Core Protocol

183170

184−- Plans are system-agnostic and work across tools

185−- Date stamps prevent conflicts

186−- Completed plans archived to `process/general-plans/completed/`

187−- Current active inventory is mixed: direct `*_PLAN_*.md` files are the default, but legacy `PLAN.md`, `plan.md`, and `phase-*.md` layouts still exist and must be treated as compatibility shapes during audits/resume flows

171+The complete RIPER-5 protocol is defined in the agent files at `.claude/agents/`.

188172

189−### `process/context/`

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.

190174

191−Source of truth for project-specific knowledge. All agents should reference these files

192−rather than hardcoding project details:

175+**RIPER-5 Phase Table:**

193176

194−- `all-context.md` - Root context entrypoint: quick routing plus authoritative repo context, architecture, patterns, conventions, and stack details

195−- `tests/all-tests.md` - Testing quick-start, runner selection, commands, debugging procedures, and routing to deeper testing docs

178+|---|---|---|---|---|

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 |

196186

197−Context discovery rule: read `process/context/all-context.md` first, then load only the

198−relevant root file or context group. Context groups are durable knowledge domains, not

199−feature folders. Every group must have an `all-{group}.md` entrypoint with scope,

200−read-when rules, quick procedures, source paths, update triggers, and routing to deeper docs.

187+**Key Requirements**:

201188

202−Context group lifecycle: create or promote a context group when a topic has 3+ durable docs,

203−a single doc exceeds roughly 800 lines with separable subtopics, or multiple agents repeatedly

204−need only one slice of a large context file. Move/split one group at a time, use `all-*.md`

205−entrypoints, update this router and agent prompts in the same patch, and run the

206−`vc-audit-context` skill after every context organization change.

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

207197

208−### `process/features/`

198+---

209199

210−Feature-scoped storage for large feature clusters. Each feature folder contains:

200+### Mode Detection & Auto-Orchestration

211201

212−- `active/` - In-progress plans

213−- `completed/` - Archived completed plans

214−- `backlog/` - Deferred/future plans

202+Feature → full RIPER-5; question → research/direct; trivial/bug → execute/debugger; existing active

203+plan always resumes first. Score ambiguity per `vc-intent-clarify`. **Full Detect-Intent patterns,

204+multi-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`.

215206

216−Task-folder convention:

217−- Reports, references, specs, and plans live inside the task folder under `active/` or `completed/`

218−- Legacy sibling `reports/` and `references/` dirs may still appear during migration, but `vc-setup` and `vc-update` should migrate safe cases into task folders and remove emptied legacy dirs

207+### QUICK FIX Lane (lighter than FAST MODE)

219208

220−See `process/context/all-context.md` for current feature list.

209+For 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

211+intent keywords ("quick fix", "hotfix", "small fix", "just patch"). The orchestrator runs a thin

212+protocol — it does NOT skip the no-inline-execution rule (the spawned agent still does the editing):

221213

222−Routing rule: When a feature has 5+ artifacts, store new plans/reports/references/specs in

223−`process/features/{feature}/active/{slug}_{date}/` or `completed/{slug}_{date}/`.

224−General or cross-cutting items go in equivalent task folders under `process/general-plans/`.

214+1. **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.

217+2. **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.

219+3. **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.

222+4. **No plan file, no validate-contract, no EVL, no UPDATE PROCESS.**

225223

226−When routing to a subagent for a feature-scoped task, include `Feature: {feature-name}` in

227−the prompt and override paths:

224+**Scope guard (mandatory):** the lane is VOID if the change touches schema, auth, API contract,

225+billing/credits, or migration surfaces, spans multiple feature areas, or exceeds a small bounded

226+size (~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

228+not — use RIPER-5. Full routing detail: `orchestration.md` §QUICK FIX Lane.

228229

229−- `Plans: {work_context}/process/features/{feature}/active/`

230−- When the selected task folder is known, pass that exact `active/{slug}_{date}/` or `completed/{slug}_{date}/` path as the authoritative artifact location

230+---

231231

232−#### Feature Folder Lifecycle

232+Engineering and coding standards: `process/development-protocols/implementation-standards.md`.

233233

234−At plan creation time, use this decision logic:

234+**Commit branch policy (overrides harness default):** `main` is this repo's working local branch.

235+When the user asks for a commit, commit **directly on `main`** — do NOT create a feature branch

236+first. This explicitly overrides the generic "if on the default branch, branch first" behavior.

237+Only branch when the user explicitly asks for a feature branch or PR. Full rule:

238+`process/development-protocols/implementation-standards.md` §Commit Hygiene.

235239

236−| Signal | Action |

237−|--------|--------|

238−| `process/features/{topic}/` already exists | Use it; pass `Feature: {topic}` to subagent |

239−| Topic clearly belongs to an existing feature | Use that feature's folder |

240−| New multi-phase project with 3+ planned phases | Create feature folder upfront |

241−| User says "this is a big feature" or names a product area | Create feature folder upfront |

242−| Single plan, no backlog, unclear scope | Use `process/general-plans/active/` |

243−| Cross-cutting work touching multiple features | Use general folders |

240+---

244241

245−Promotion protocol from general to feature folder:

242+### Technology Stack

246243

247−1. Create `process/features/{new-feature}/` with subdirs: `active/`, `completed/`, `backlog/`

248−2. Move related artifacts from `process/general-plans/` into the new feature's task folders; migrate safe legacy `reports/` and `references/` artifacts into those task folders and remove emptied legacy dirs

249−3. Update the Current features list above

250−4. Inform subagents of the new feature scope going forward

244+See `process/context/all-context.md` for project technology stack, structure, and key technologies.

251245

252−Feature list maintenance: The Current features list above must be updated whenever a new

253−feature folder is created or an empty one is removed. The `vc-update-process-agent` checks for

254−drift between `ls process/features/` and this list during Phase 2.

246+---

255247

256−### Legacy sibling dirs

248+## Shared Process Folder

257249

258−`process/general-plans/reports/`, `process/general-plans/references/`,

259−`process/features/{feature}/reports/`, and `process/features/{feature}/references/`

260−are deprecated legacy surfaces. They should be drained into task folders when safe and

261−removed once empty.

250+Claude Code and Codex share the `process/` directory. Full rules:

251+`process/development-protocols/plan-lifecycle.md` (§Task-Folder Framework + §Feature Folder Lifecycle).

262252

263−When routing to subagents, always pass relevant `process/context/` files. As new context

264−files are added, for example UI patterns or deployment procedures, agents automatically benefit.

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`.

265264

266−## Available Workflow Skills

265+When routing to subagents, always pass relevant `process/context/` files.

267266

268−Canonical workflow logic lives in `.agents/skills/` / `.claude/skills/`.

269−Claude command files are compatibility aliases when they still exist.

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:

270268

271−### Workflow Ownership

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+```

272272

273−The active system is intentionally split into four layers:

273+(Omit `[AUTOPILOT CONTEXT]` line when not in an autopilot run.)

274274

275−- **Actor agents** own the actual phase or specialist role:

276− - `vc-research-agent`

277− - `vc-innovate-agent`

278− - `vc-plan-agent`

279− - `vc-execute-agent`

280− - `vc-update-process-agent`

281− - `vc-debugger`

282− - `vc-tester`

283− - `vc-code-reviewer`

284− - `vc-code-simplifier`

285− - `vc-ui-ux-designer`

286− - `vc-git-manager`

287−- **Contract skills** define repo workflow artifacts and durable process contracts:

288− - `vc-generate-plan`

289− - `vc-generate-context`

290− - `vc-audit-context`

291− - `vc-audit-plans`

292− - `vc-audit-vc`

293− - `vc-update`

294− - `vc-publish`

295−- **Helper skills** improve how agents work but do not own the workflow:

296− - `vc-scout`

297− - `vc-sequential-thinking`

298− - `vc-problem-solving`

299− - `vc-docs-seeker`

300− - `vc-agent-browser`

301− - `vc-web-testing`

302− - `vc-frontend-design`

303− - `vc-predict`

304− - `vc-scenario`

305− - `vc-security`

306− - `vc-autoresearch`

307− - `vc-debug`

308− - `vc-agent-strategy-compare`

309− - `vc-intent-clarify`

310− - `vc-autopilot`

275+Full specification: `process/development-protocols/autopilot.md §[AUTOPILOT CONTEXT] Injection Schema`.

311276

312−Former workflow-owner skills such as `vc:plan`, `vc:research`, `vc:cook`, `vc:fix`, and `vc:code-review` are migration sources only. Their useful practices should be absorbed into the surviving actor/contract surfaces instead of being routed as separate default workflows.

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`.

313278

314−`vc:debug` remains a valid helper skill. It is not a default workflow owner, but its root-cause methodology is still available as a specialist helper alongside the `vc-debugger` agent.

279+---

315280

281+## Available Workflow Skills

282+

283+Canonical workflow logic lives in `.agents/skills/` / `.claude/skills/`. The system is split into

284+three layers — **actor agents** (own a phase/role, in `.claude/agents/`, NOT skills), **contract

285+skills** (own a workflow artifact/contract), and **helper skills** (improve how agents work, own no

286+artifact). Each `SKILL.md` carries its `layer` + `trigger_keywords` in frontmatter; the full

287+per-skill inventory grouped by layer is emitted on demand by

288+`node .claude/skills/vc-context-discovery/scripts/discover-skills.mjs` (reads the

289+generated skills catalog inventory). Per-skill detail lives in each `.claude/skills/*/SKILL.md`.

290+

316291 ### Core Skills

317292

318−- `vc-generate-plan` - Create implementation plans (SIMPLE or COMPLEX) with explicit touchpoints, blast radius, verification evidence, and resume handoff

319−- `vc-generate-context` - Generate/update repository context

320−- `vc-audit-context` - Audit context routing, grouping, discoverability, and Claude/Codex wiring

321−- `vc-audit-plans` - Audit active-plan inventory, staleness, and routing truth

322−- `vc-audit-vc` - Audit agent harness health: agent parity, skill registry, README.md sync, and protocol wiring

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

323297

324298 Legacy `@sync-to-riper5.md` and `@sync-from-riper5.md` commands are intentionally left

325299 unchanged and are not part of the Codex skill compatibility surface.

326300

327−## Mode Agents (Codex Compatibility)

301+---

328302

329−Codex provides specialized agents for each RIPER-5 mode through `.codex/agents/*.toml`.

330−Agent identity lives only in `.claude/agents/*.md` and `.codex/agents/*.toml`. Do not create

331−or preserve agent-wrapper skills under `.claude/skills/` or `.agents/skills/`.

303+## Mode Agents (Claude Code Subagents)

332304

333−Codex agent triggering is manual/tool-driven: use `spawn_agent` with the relevant

334−`agent_type` when the user explicitly asks for delegation, a RIPER-5 mode, or parallel

335−agent work and the tool is available. The prompt body mirrors the Claude agent definition,

336−but Claude's YAML `tools:` allowlists are not guaranteed to be enforced by Codex TOML.

305+Each subagent has a separate context window, tool restrictions, and phase-locked responsibilities.

306+Full prompts, invoked-skill lists, and tool grants live in each agent's `.claude/agents/{agent}.md`.

337307

338−### Available Agents

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 |

339318

340−`vc-research-agent`

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`.

341327

342−- Purpose: Information gathering only (read-only)

343−- Claude tools: Read, Grep, Glob, Bash (safe commands)

344−- Use: Understanding codebase, gathering context

345−- Invoke: User says "ENTER RESEARCH MODE" or explicit agent/skill call

346−

347−`vc-innovate-agent`

348−

349−- Purpose: Brainstorming approaches (discussion-only)

350−- Claude tools: Read, Grep, Glob (no execution)

351−- Use: Exploring implementation options

352−- Invoke: After RESEARCH, user says "go" or "ENTER INNOVATE MODE"

353−

354−`vc-plan-agent`

355−

356−- Purpose: Creating detailed specifications

357−- Claude tools: Read, Write (`process/general-plans/active/` or `process/features/*/active/` only), Grep, Glob, Bash

358−- Use: Writing implementation plans

359−- Invoke: After INNOVATE, user says "go" or "ENTER PLAN MODE"

360−

361−`vc-execute-agent`

362−

363−- Purpose: Implementing per approved plan

364−- Claude tools: Full access (Read, Write, Edit, Delete, Grep, Glob, Bash)

365−- Use: Code implementation

366−- Invoke: ONLY with explicit "ENTER EXECUTE MODE" after plan approval

367−

368−`vc-fast-mode-agent`

369−

370−- Purpose: Compressed workflow (RESEARCH -> INNOVATE -> PLAN -> PAUSE -> EXECUTE)

371−- Claude tools: Full access

372−- Use: Quick end-to-end implementation with safety pause

373−- Invoke: "ENTER FAST MODE"

374−- CRITICAL: Pauses before EXECUTE for confirmation

375−

376−`vc-update-process-agent`

377−

378−- Purpose: Rule updates, memory storage, plan archiving

379−- Codex note: durable shared knowledge belongs in `process/context/`; Claude also has a separate project-memory layer under `~/.claude/projects/.../memory/`

380−- Claude tools: Read, Write, Edit, Grep, Glob, Bash, update_memory

381−- Use: Capturing learnings, updating documentation

382−

383328 > **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`.

384329

385−> **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` §Testing-and-Quality. Run the change-type-relevant validator before closing a phase.

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.

386331

387−### Specialist Agents

332+---

388333

389−These agents add capabilities beyond the core RIPER-5 workflow. They are invoked by the

390−orchestrator or by execute-agent when specialized work is needed.

334+## Routing

391335

392−During EXECUTE phase:

393−

394−- [.claude/agents/vc-tester.md](.claude/agents/vc-tester.md) - Diff-aware test verification. Maps changed files to test files, runs only affected tests. Invoke after implementation sub-steps complete.

395−- [.claude/agents/vc-debugger.md](.claude/agents/vc-debugger.md) - Root cause analysis for bugs. Evidence-before-hypothesis methodology. Can also be invoked standalone.

396−- [.claude/agents/vc-code-reviewer.md](.claude/agents/vc-code-reviewer.md) - Production-readiness review. Edge case scouting, N+1 detection, auth path validation. Invoke as pre-PR quality gate.

397−- [.claude/agents/vc-code-simplifier.md](.claude/agents/vc-code-simplifier.md) - Post-implementation refactor for clarity without behavior change. Invoke after code-reviewer passes.

398−- [.claude/agents/vc-ui-ux-designer.md](.claude/agents/vc-ui-ux-designer.md) - Design-aware frontend implementation. Invoke for UI/UX tasks within execute phase.

399−- [.claude/agents/vc-git-manager.md](.claude/agents/vc-git-manager.md) - Clean conventional commits. Invoke for git operations.

400−

401−Note: shared review methodology has been absorbed into the `vc-code-reviewer` agent prompt. Route to the agent directly instead of a separate review-owner workflow when the agent is the appropriate path.

402−

403−Cross-phase utilities (skills, not agents):

404−

405−- `vc-sequential-thinking` - Structured reasoning, usable in any phase

406−- `vc-problem-solving` - Cognitive toolkit when stuck in any phase

407−- `vc-scout` - Fast codebase scouting, usable in RESEARCH

408−- `vc-agent-browser` - Browser automation, primarily EXECUTE

409−- `vc:debug` - Specialist root-cause-analysis helper, usable alongside `vc-debugger`

410−- `vc-autoresearch` - Autonomous iterative optimization loop after execute phase for measurable metrics

411−- `vc-agent-strategy-compare` - Strategy recommendation at every phase boundary

412−- `vc-intent-clarify` - Ambiguity scoring and clarification round

413−- `vc-autopilot` - Autopilot Mode trigger and per-gate decision policy

414−

415−### Discovery Note

416−

417−Do not assume `.claude/skills/` is scanned directly by Codex. For Codex compatibility, make

418−sure the relevant capability is exposed under

419−[`.agents/skills/`](.agents/skills).

420−In this repo, `.agents/skills/` is already a symlink to the canonical `.claude/skills/` tree,

421−so add or update real skill folders there rather than copying them into `.codex/`.

422−

423−## Routing Protocol

424−

425336 When a user makes a request:

426337

427−### 0. Skill Discovery

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.

428347

429−Before routing, scan `.agents/skills/` directory names and match keywords from the user

430−request to surface relevant skills. Attach candidate skill names to the subagent prompt.

348+---

431349

432−Skill Registry:

433−

434−| Skill | Purpose | Trigger Keywords |

435−|---|---|---|

436−| `vc-frontend-design` | Polished UI from designs/screenshots/videos | UI, design, layout, component, page, interface, visual, CSS, Tailwind, login page, dashboard |

437−| `vc-debug` | Root cause-analysis helper used alongside `debugger` | debug, root cause, investigate, why is this |

438−| `vc-scenario` | Edge case generation across 12 dimensions | edge cases, test scenarios, what could go wrong |

439−| `vc-security` | STRIDE + OWASP security audit | security, vulnerability, auth, XSS, SQL injection |

440−| `vc-autoresearch` | Autonomous metric optimization loop | improve coverage, reduce bundle, optimize metric |

441−| `vc-predict` | 5-persona pre-implementation debate | risks, predict issues, architectural review |

442−| `vc-scout` | Fast parallel codebase scouting | find files, where is, search codebase |

443−| `vc-docs-seeker` | Library docs via context7 | how does X work, API docs, version, syntax |

444−| `vc-generate-plan` | Durable implementation planning | plan, PRD, spec, implementation plan |

445−| `vc-generate-context` | Refresh repository context router | refresh context, regenerate context, repo context |

446−| `vc-audit-context` | Context routing and discoverability audit | context audit, reorganize context, stale context |

447−| `vc-audit-plans` | Active-plan maintenance and cleanup | stale plans, cleanup plans, archive plans, plan audit |

448−| `vc-web-testing` | Playwright/Vitest/k6 test automation | tests, e2e, integration test, performance test |

449−| `vc-sequential-thinking` | Step-by-step reasoning | complex problem, think through, analyze step by step |

450−| `vc-problem-solving` | Cognitive unblocking techniques | stuck, can't figure out, complex, spiral |

451−| `vc-agent-browser` | AI browser automation CLI | long browser session, browserbase, visual testing |

452−| `vc-agent-strategy-compare` | Execution strategy recommendation at phase boundaries | strategy, parallel agents, sequential, workflow |

453−| `vc-intent-clarify` | Ambiguity scoring and clarification round | clarify intent, ambiguous request |

454−| `vc-autopilot` | Autopilot Mode trigger and decision policy | autopilot, autonomous mode, full autonomy |

455−| `vc-generate-spec` | Product-discovery requirements doc | spec, requirements, user stories |

456−| `vc-feasibility-test` | Empirical feasibility probe before implementation | feasible, viable, probe, test approach |

457−| `vc-generate-closeout` | Phase closeout packet and EVL handoff | closeout, archive, wrap up |

458−| `vc-risk-evidence-pack` | Evidence pack for high-risk work | risk, auth risk, billing risk, schema risk |

459−| `vc-test-coverage-plan` | Test coverage planning for validate-contract | test coverage, test strategy |

460−| `vc-plan-discovery` | Active-plan discovery across features | find plan, resume plan |

461−| `vc-review-situation` | Situation review and plan orientation | review situation, where am I |

462−| `vc-setup` | Scaffold agent harness into new project | seed, harness, bootstrap, new project, scaffold, setup |

463−| `vc-update` | Pull latest harness from remote kit repo | update harness, pull kit, sync harness, upgrade agents |

464−| `vc-publish` | Push harness improvements to remote kit repo | publish kit, push harness, release kit, update remote |

465−| `vc-audit-vc` | Agent harness health audit (agents, skills, README.md, protocol wiring) | harness, agent parity, skill audit, guide sync |

466−

467−Rule: When one or more skills match the request, mention them to the user or include them in

468−the subagent prompt context. Never silently skip relevant skills.

469−

470−### 1. Detect Intent

471−

472−Feature Request (keywords: "build", "add", "implement", "create feature")

473−-> Route to `vc-research-agent` with relevant context files.

474−

475−Question / Understanding Request

476−-> Non-trivial: route to `vc-research-agent`. Trivial conceptual questions can be answered directly by the orchestrator.

477−

478−Trivial Fix

479−-> Delegate lightweight quick-fix to `vc-execute-agent` with no plan file required.

480−Trivial definition: single-file change, no new dependencies, no schema/API/auth changes, under 15 lines, no security surface. Anything else is non-trivial.

481−

482−Missing Context

483−-> Suggest or invoke the `vc-generate-context` skill.

484−

485−Bug Fix / Debug Request (keywords: "fix", "bug", "broken", "debug", "error")

486−-> For trivial: delegate to `vc-execute-agent` directly with no plan required.

487−-> For complex: route to `vc-debugger` agent. Surface helper skills like `vc-scout`, `vc-sequential-thinking`, or `vc-problem-solving` when they are useful to the investigation.

488−

489−Existing Plan File Present

490−-> Resume from relevant phase; do not recreate plan.

491−

492−UI / Frontend Request (keywords: "page", "component", "design", "layout", "interface", "UI")

493−-> Surface `vc-frontend-design` skill alongside `vc-research-agent`. Invoke `vc-ui-ux-designer` agent during EXECUTE phase for implementation.

494−

495−Documentation Question (keywords: "how does X work", "API docs", "syntax", "version")

496−-> Activate `vc-docs-seeker` skill before routing to `vc-research-agent`.

497−

498−Plan / Context Maintenance

499−-> Surface `vc-generate-plan`, `vc-generate-context`, `vc-audit-context`, or `vc-audit-plans` directly when the user is asking for saved plan artifacts, context refresh, context reorganization, or active-plan cleanup.

500−

501−Refactor / Simplify (keywords: "refactor", "clean up", "simplify", "reorganize")

502−-> Pure style/readability with a named file and no behavior change: route directly to `vc-code-simplifier` agent.

503−-> Behavioral or architectural refactor: full RESEARCH -> PLAN -> EXECUTE, then `vc-code-simplifier` as cleanup.

504−

505−Debug / Root Cause (keywords: "debug", "why", "root cause", "investigate")

506−-> `vc-debugger` agent is the default owner. Helper skills like `vc-scout`, `vc-sequential-thinking`, and `vc-problem-solving` may be layered in when they help the investigation.

507−

508−When multiple intents match, use this precedence:

509−

510−1. Existing plan file in `process/general-plans/active/` or `process/features/*/active/` -> always resume first

511−2. Explicit mode command (`ENTER X MODE`) -> obey immediately

512−3. Bug/debug -> debugging routing before feature routing

513−4. Feature request -> RIPER-5 flow

514−5. UI specialization -> surface vc-frontend-design alongside any of the above

515−6. Docs question -> surface vc-docs-seeker alongside any of the above

516−

517−When still ambiguous, ask the user one clarifying question before routing.

518−

519−### 2. Gather Context

520−

521−Before routing to subagent, pass relevant `process/context/` files:

522−

523−- `process/context/all-context.md` - always pass or consult first for context routing

524−- `process/context/all-context.md` - always pass for architecture/stack awareness

525−- `process/context/tests/all-tests.md` - pass when routing to `vc-tester`, `vc-debugger`, or `vc-execute-agent`

526−- `process/general-plans/active/` and `process/features/*/active/` - check for existing plans to avoid duplication

527−- Relevant code paths - summarize succinctly, don't dump entire files

528−

529−**Routing depth rule:** `all-*.md` files are routers. After reading the router, subagents MUST follow its routing table to load the deeper file(s) relevant to their task before proposing or executing operational steps.

530−

531−### 3. Route to Subagent

532−

533−Choose based on current phase:

534−

535−- Initial understanding -> `vc-research-agent`

536−- Exploring options -> `vc-innovate-agent`

537−- Creating spec -> `vc-plan-agent`

538−- Implementing approved plan -> `vc-execute-agent`

539−- Fast workflow -> `vc-fast-mode-agent`

540−- Capturing learnings -> `vc-update-process-agent`

541−

542−### 4. Monitor Compliance

543−

544−Ensure subagent:

545−

546−- Uses correct mode prefix

547−- Stays within tool restrictions or documented Codex equivalents

548−- Doesn't skip phases

549−- Produces expected artifacts

550−

551350 ## Phase Transition Rules

552351

553−RESEARCH -> INNOVATE:

352+Outer order: `RESEARCH → SPEC → INNOVATE → PLAN → VALIDATE → EXECUTE → UPDATE PROCESS`. The

353+phase-program INNER loop skips SPEC (`R → I → P → PVL → E → EVL → UP`).

554354

555−- Requires sufficient context gathered

556−- User confirms with "go" or explicit mode command

557−- If user responds with implementation intent but no "go", ask: "Do you want to proceed to INNOVATE or skip directly to PLAN?"

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 |

558363

559−INNOVATE -> PLAN:

364+Full 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.

560368

561−- Requires approach discussion completed

562−- User confirms with "go" or explicit mode command

563−- vc-innovate-agent must produce a brief decision summary with chosen approach, rejected alternatives, and rationale before PLAN begins

369+**PVL/EVL loop gates (mechanical — run these checks before advancing):**

564370

565−PLAN -> EXECUTE:

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.

566375

567−- Requires written plan file

568−- User reviews and explicitly says "ENTER EXECUTE MODE"

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.

569377

570−Orchestrator preflight before spawning vc-execute-agent: Confirm exactly one plan file is

571−selected. Pass the plan file path explicitly in the subagent prompt. If multiple plans exist

572−in `process/general-plans/active/` or `process/features/*/active/`, ask the user which one to use. Never let vc-execute-agent infer

573−the plan from ambient state.

378+---

574379

575−EXECUTE -> UPDATE PROCESS:

576−

577−- After non-trivial implementation complete, always surface a cleanup checkpoint

578−- UPDATE PROCESS still requires explicit user command.

579−- After vc-execute-agent reports DONE, the orchestrator should present a short closeout packet:

580− - selected plan path

581− - closeout classification

582− - what was finished

583− - what was verified versus still unverified

584− - what cleanup/context capture remains

585− - uncommitted file count and git-manager offer (when worktree is dirty)

586− - commit-checkpoint recommendation:

587− - invoke `vc-git-manager` before UPDATE PROCESS when validated execution changes are ready to split into a logical code/test commit

588− - defer the commit checkpoint until after UPDATE PROCESS when the remaining changes are mainly `process/`, `.claude/`, `.codex/`, or `AGENTS.md`

589− - the single best next valid state

590−- Then ask one explicit next-step question such as:

591− - `Implementation complete. The selected plan appears ready for cleanup. Enter UPDATE PROCESS mode to archive the plan and capture learnings?`

592− - or `Implementation is code-complete but still testing. Keep the plan in active for now, or enter UPDATE PROCESS mode anyway?`

593− - or `Implementation deviated from plan. Return to PLAN or enter UPDATE PROCESS mode to reconcile?`

594−- If the next phase or follow-up is already known, name that exact plan path in the closeout summary so the user does not have to rediscover it.

595−- If the worktree has uncommitted changes from this execution, offer: "Invoke vc-git-manager for logical commit splitting before UPDATE PROCESS?" Pass the `touched_files` list (files the vc-execute-agent reported changing) as context so vc-git-manager can scope its analysis.

596−- If a phase is well-tested and genuinely validated, prefer surfacing a commit checkpoint instead of letting the work drift uncommitted while broader follow-up phases begin.

597−- If execution revealed a concrete missing downstream lane, route UPDATE PROCESS to create the follow-up phase plan or backlog artifact and update the umbrella/parent plan instead of leaving the next step only in chat.

598−- If cleanup is skipped and active-plan debt builds up, recommend `vc-audit-plans` as a follow-up maintenance step

599−- **Drift signal scoring** for UPDATE PROCESS urgency:

600− - Count: (a) total files touched, (b) any `.claude/`, `.codex/`, `README.md`, `AGENTS.md`, or `process/development-protocols/` changes, (c) session involved 3+ memory-worthy observations

601− - LOW (0-1 signals): include "UPDATE PROCESS available if you want." in closeout

602− - MEDIUM (2 signals): include "Recommend UPDATE PROCESS -- significant changes detected."

603− - HIGH (3+ signals): include "Strongly recommend UPDATE PROCESS -- harness/protocol files touched."

604−

605−**Parallel Fan-Out**

606−

607−At each phase transition above, invoke `vc-agent-strategy-compare` for the next phase's strategy recommendation. See `process/development-protocols/orchestration.md` for the checkpoint summary.

608−

609380 ## Key Principles

610381

611−### Phase Locking

382+**Phase Locking** — each mode has strict boundaries: RESEARCH read-only; SPEC writes the

383+requirements doc only; INNOVATE discusses with no decisions; PLAN/VALIDATE write artifacts with no

384+implementation; EXECUTE implements the approved plan only; UPDATE PROCESS documents and archives.

612385

613−Each mode has strict boundaries:

386+**Safety**

614387

615−- RESEARCH: Read-only, gather facts

616−- INNOVATE: Discuss possibilities, no decisions

617−- PLAN: Write spec only, no implementation

618−- EXECUTE: Implement approved plan only

619−- UPDATE PROCESS: Document learnings, archive

620−

621−### Safety

622−

623388 - Never skip directly to implementation for substantial work

624389 - Never modify files in RESEARCH or INNOVATE

625390 - Never start EXECUTE without explicit approval

626391 - Always preserve user agency at phase transitions

627392

628−### Efficiency

393+**Efficiency** — context isolation rules: `process/development-protocols/orchestration.md` §Context Isolation.

629394

630−- Use subagents to isolate context when the user explicitly asks for delegation, parallel agent work, or a mode-specific agent

631−- Pass only relevant files

632−- Summarize rather than duplicate

633−- Reuse existing plans and context

395+---

634396

635−## Success Metrics

636397

637−Token Efficiency: Subagents use separate contexts, reducing token usage compared to main

638−conversation context.

639−

640−Phase Safety: Claude tool restrictions and Codex mode instructions reduce accidental

641−violations, for example RESEARCH should not modify files.

642−

643−Cross-Agent Compatibility: Plans and context files work consistently in Claude Code and Codex.

644−

645398 ## Quick Start

646399

647−First Time:

400+**Typical flow** — describe the feature (→ `vc-research-agent`), advance with "go" through SPEC →

401+INNOVATE → PLAN, "ENTER VALIDATE MODE", then "ENTER EXECUTE MODE", optionally "ENTER UPDATE PROCESS

402+MODE". "ENTER FAST MODE - [feature]" runs the compressed flow in `vc-fast-mode-agent` (pauses after

403+VALIDATE). Troubleshooting (import paths, missing subagent, plan conflicts, tool grants):

404+`process/development-protocols/orchestration.md` / agent frontmatter.

648405

649−1. Verify RIPER-5 rules loaded; orchestrator may declare `[MODE: ORCHESTRATOR]`

650−2. Run the `vc-generate-context` skill if `process/context/all-context.md` doesn't exist

651−3. Start with a feature request or question

406+---

652407

653−Typical Feature Workflow:

408+## PostToolUse Hooks and Context Envelope

654409

655−1. Describe feature -> Orchestrator routes to `vc-research-agent`

656−2. Say "go" -> Orchestrator routes to `vc-innovate-agent`

657−3. Say "go" -> Orchestrator routes to `vc-plan-agent` and creates plan in `process/general-plans/active/`

658−4. Review plan carefully

659−5. Say "ENTER EXECUTE MODE" -> Orchestrator routes to `vc-execute-agent`

660−6. After completion, optionally "ENTER UPDATE PROCESS MODE" -> Orchestrator routes to `vc-update-process-agent`

410+Two advisory PostToolUse hooks run automatically (both fail-open — they never block a tool call):

661411

662−Quick Iteration (FAST MODE):

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

663419

664−1. Say "ENTER FAST MODE - [feature description]"

665−2. Review generated plan; vc-fast-mode-agent pauses

666−3. Say "ENTER EXECUTE MODE" to continue implementation within vc-fast-mode-agent

420+**Context Envelope:** every inner-loop agent (research / plan / execute / update-process) emits a

421+10-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 →

424+active-plan → test-runner → validate-contract`. The `test-runner` multi-runner value uses a

425+pipe-delimited DISPLAY format (`bun test | vitest`) that the phase-loop workflow template expands into

426+SEQUENTIAL test steps — never a literal shell pipe.

667427

668−## Troubleshooting

428+---

669429

670−Rules not loading: Verify `process/development-protocols/` exists and that the hook/config path resolution still points to the canonical protocol files.

671−

672−Subagent not found: Ensure agent files exist in `.claude/agents/` and mirrored TOML exists in

673−`.codex/agents/`. Shared skills should exist under `.claude/skills/` through the `.agents/skills/`

674−symlink, but agent wrappers should not exist there.

675−

676−Plan conflicts: Date-stamped filenames should prevent overwrites; check git status.

677−

678−Tool restrictions not working: Claude uses `tools` field in agent YAML frontmatter. Codex TOML

679−mirrors prompts but may not enforce identical tool allowlists.

680−

681−Cross-agent issues: Claude Code and Codex must use the same `process/` folder structure.

682−

683430 ## Resources

684431

685432 - Agent Definitions: `.claude/agents/*.md`

686−- Codex Agent Mirrors: `.codex/agents/*.toml`

687−- Workflow Skills: real reusable skills under `.claude/skills/*/SKILL.md`, exposed to Codex through `.agents/skills/`

688−- Plans: `process/general-plans/active/` (active general), `process/general-plans/{completed,backlog,reports,references}/` (general archives/supporting artifacts), `process/features/*/active/` (feature-scoped)

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)

689435 - Features: `process/features/`

690436 - Context: `process/context/all-context.md` router plus relevant `process/context/` files/groups

691437

692−## Porting Notes

438+---

693439

694−This file intentionally preserves the original `CLAUDE.md` workflow while adapting it

695−to Codex-native constructs:

696−

697−- `AGENTS.md` for top-level repository instructions

698−- `.agents/skills/` for mode and command workflows

699−- `.codex/agents/` for Codex subagent role mirrors

700−- `.codex/config.toml` for project-level Codex configuration

701−

702−The authoritative historical source remains:

703−

704−- [CLAUDE.md](CLAUDE.md)

440+**This file is automatically loaded at the start of every Claude Code session.**

705441

Two files, one repository

Built for the same person as RuleStack