AGENTS.md

1# AGENTS.md
2 
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.
4 
5This file is the Codex compatibility layer for the existing `.claude/` system.
6 
7Keep this file aligned with [CLAUDE.md](CLAUDE.md)
8as much as possible while adapting Claude-native concepts to Codex-native constructs.
9 
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:
12 
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
17 
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.
21 
22See `process/context/all-context.md` for project-specific coding preferences and conventions.
23 
24## RIPER-5 Spec-Driven Development System
25 
26This project uses RIPER-5 methodology for systematic, spec-driven development. RIPER-5
27prevents premature implementation and ensures quality through strict mode-based workflows.
28 
29### Shared Development Protocols
30 
31Canonical shared workflow rules now live in
32[process/development-protocols/all-development-protocols.md](process/development-protocols/all-development-protocols.md).
33 
34Read 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 
44Reference docs (harness methodology, not project-specific):
45 
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
49 
50### Orchestrator Role (Main Codex Session)
51 
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).
55 
56You are the orchestrator, not the worker.
57 
58Your responsibilities:
59 
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)
64 
65You do NOT:
66 
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
72 
73Exception: Trivial questions that don't require mode-specific work, for example "What is
74RIPER-5?", can be answered directly.
75 
76### Repository Context
77 
78Authoritative context for this repository:
79 
80`process/context/all-context.md`
81 
82Contains:
83 
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
90 
91Before substantial planning or implementation work, consult:
92 
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
96 
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.
98 
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