feat: convert all codex agent definitions from .md to .toml format

Convert 20 agent .md files to Codex-native .toml format with proper
metadata (name, description, model, sandbox_mode, developer_instructions).
Update all 19 skill files to use agent_type references instead of .md
file paths. Remove "Read role definition" bootstrapping step from spawn
messages since TOML developer_instructions replaces it.

Agent format: YAML frontmatter + body → TOML with inline instructions
Calling schema: agent: "path.md" → agent_type: "toml_name"
Sandbox: read-only for exploration agents, workspace-write for executors

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.codex/skills/brainstorm-with-file/SKILL.md

@@ -20,7 +20,7 @@ Interactive brainstorming workflow with **documented thought evolution**. Expand
 
 **Codex-Specific Features**:
 - Parallel subagent execution via `spawn_agent` + batch `wait({ ids: [...] })`
-- Role loading via path (agent reads `~/.codex/agents/*.md` itself)
+- Role loading via TOML agent definition (agent_type parameter in spawn_agent)
 - Deep interaction with `send_input` for multi-round refinement within single agent
 - Explicit lifecycle management with `close_agent`
 
@@ -208,12 +208,10 @@ Generate key questions that guide the brainstorming exploration. Use a subagent
 
 ```javascript
 const vectorAgent = spawn_agent({
+  agent_type: "cli_explore_agent",
   message: `
 ## TASK ASSIGNMENT
 
-### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-
 ---
 
 ## Context
@@ -302,9 +300,9 @@ Spawn 3 perspective agents in parallel: Creative + Pragmatic + Systematic.
 
 | Perspective | Role File | Focus |
 |-------------|-----------|-------|
-| Creative | `~/.codex/agents/cli-explore-agent.md` | Innovation, cross-domain inspiration, challenging assumptions |
-| Pragmatic | `~/.codex/agents/cli-explore-agent.md` | Implementation feasibility, effort estimates, blockers |
-| Systematic | `~/.codex/agents/cli-explore-agent.md` | Problem decomposition, patterns, scalability |
+| Creative | `cli_explore_agent` | Innovation, cross-domain inspiration, challenging assumptions |
+| Pragmatic | `cli_explore_agent` | Implementation feasibility, effort estimates, blockers |
+| Systematic | `cli_explore_agent` | Problem decomposition, patterns, scalability |
 
 **Parallel Subagent Execution**:
 
@@ -353,13 +351,13 @@ const perspectives = [
 // Parallel spawn - all agents start immediately
 const agentIds = perspectives.map(perspective => {
   return spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Run: `ccw spec load --category "exploration planning"`
-3. Read project tech context from loaded specs
+1. Run: `ccw spec load --category "exploration planning"`
+2. Read project tech context from loaded specs
 
 ---
 
@@ -560,13 +558,13 @@ const deepDiveResult = wait({ ids: [perspectiveAgent], timeout_ms: 600000 })
 
 ```javascript
 const deepDiveAgent = spawn_agent({
+  agent_type: "cli_explore_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: ${sessionFolder}/perspectives.json (prior findings)
-3. Run: `ccw spec load --category "exploration planning"`
+1. Read: ${sessionFolder}/perspectives.json (prior findings)
+2. Run: `ccw spec load --category "exploration planning"`
 
 ---
 
@@ -606,12 +604,12 @@ When user selects "challenge", spawn a dedicated challenge agent.
 
 ```javascript
 const challengeAgent = spawn_agent({
+  agent_type: "cli_explore_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: ${sessionFolder}/perspectives.json (ideas to challenge)
+1. Read: ${sessionFolder}/perspectives.json (ideas to challenge)
 
 ---
 
@@ -659,12 +657,12 @@ When user selects "merge", synthesize complementary ideas.
 
 ```javascript
 const mergeAgent = spawn_agent({
+  agent_type: "cli_explore_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: ${sessionFolder}/perspectives.json (source ideas)
+1. Read: ${sessionFolder}/perspectives.json (source ideas)
 
 ---
 
@@ -888,7 +886,7 @@ Dimensions guide brainstorming scope and focus:
 ```javascript
 // Safe parallel execution with error handling
 try {
-  const agentIds = perspectives.map(p => spawn_agent({ message: buildPrompt(p) }))
+  const agentIds = perspectives.map(p => spawn_agent({ agent_type: "cli_explore_agent", message: buildPrompt(p) }))
 
   const results = wait({ ids: agentIds, timeout_ms: 600000 })
 
@@ -1014,7 +1012,7 @@ Final synthesis:
 
 ### Codex Subagent Best Practices
 
-1. **Role Path, Not Content**: Pass `~/.codex/agents/*.md` path in message, let agent read itself
+1. **Agent Type, Not Path**: Use `agent_type` parameter in spawn_agent, not manual file path reading
 2. **Parallel for Perspectives**: Use batch spawn + wait for 3 perspective agents
 3. **Delay close_agent for Refinement**: Keep perspective agents alive for `send_input` reuse
 4. **Batch wait**: Use `wait({ ids: [a, b, c] })` for parallel agents, not sequential waits

.codex/skills/brainstorm/SKILL.md

@@ -69,7 +69,7 @@ Dual-mode brainstorming with CSV-driven parallel role analysis. Auto mode runs a
 │  ═══ Single Role Mode ═══                                         │
 │                                                                    │
 │  Phase 3S: Single Role Analysis (spawn_agent)                    │
-│     ├─ spawn_agent(conceptual-planning-agent)                    │
+│     ├─ spawn_agent(conceptual_planning_agent)                    │
 │     └─ Output: {role}/analysis*.md                               │
 │                                                                    │
 └──────────────────────────────────────────────────────────────────┘
@@ -536,7 +536,7 @@ if (executionMode === 'single-role') {
   Bash(`mkdir -p "${roleDir}"`)
 
   const agentId = spawn_agent({
-    agent: `~/.codex/agents/conceptual-planning-agent.md`,
+    agent_type: "conceptual_planning_agent",
     instruction: `
 Perform a ${roleName} analysis for the brainstorming session.
 
@@ -594,7 +594,7 @@ Follow the same analysis protocol as wave role analysis but with interactive ref
 
    ```javascript
    const synthesisAgent = spawn_agent({
-     agent: `~/.codex/agents/conceptual-planning-agent.md`,
+     agent_type: "conceptual_planning_agent",
      instruction: `
 ## SYNTHESIS ASSIGNMENT
 

.codex/skills/clean/SKILL.md

@@ -159,12 +159,12 @@ let exploreAgent = null
 try {
   // Launch cli-explore-agent
   exploreAgent = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS
-1. Read: ~/.codex/agents/cli-explore-agent.md
-2. Read: ${projectRoot}/.workflow/project-tech.json (if exists)
+1. Read: ${projectRoot}/.workflow/project-tech.json (if exists)
 
 ## Task Objective
 Discover stale artifacts for cleanup.

.codex/skills/issue-discover/SKILL.md

@@ -229,13 +229,13 @@ Create a new subagent with task assignment.
 
 ```javascript
 const agentId = spawn_agent({
+  agent_type: "{agent_type}",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Execute: ccw spec load --category exploration
-3. Execute: ccw spec load --category debug (known issues cross-reference)
+1. Execute: ccw spec load --category exploration
+2. Execute: ccw spec load --category debug (known issues cross-reference)
 
 ## TASK CONTEXT
 ${taskContext}

.codex/skills/issue-discover/phases/02-discover.md

@@ -114,13 +114,13 @@ const perspectiveAgents = [];
 
 selectedPerspectives.forEach(perspective => {
   const agentId = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: {projectRoot}/.workflow/specs/*.md
+1. Read: {projectRoot}/.workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/specs/*.md
 
 ---
 
@@ -192,13 +192,13 @@ agentIds.forEach(id => close_agent({ id }));
 // Only spawn if perspective requires external research
 if (selectedPerspectives.includes('security') || selectedPerspectives.includes('best-practices') || args.external) {
   const exaAgentId = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: {projectRoot}/.workflow/specs/*.md
+1. Read: {projectRoot}/.workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/specs/*.md
 
 ---
 

.codex/skills/issue-discover/phases/03-discover-by-prompt.md

@@ -234,6 +234,7 @@ while (shouldContinue && iteration < maxIterations) {
 
   iterationPlan.dimensions.forEach(dimension => {
     const agentId = spawn_agent({
+      agent_type: "cli_explore_agent",
       message: buildDimensionPromptWithACE(dimension, iteration, cumulativeFindings, iterationAceResults, iterationDir)
     });
     dimensionAgents.push({ agentId, dimension });
@@ -413,12 +414,11 @@ function buildDimensionPromptWithACE(dimension, iteration, previousFindings, ace
   );
 
   return `
-## TASK ASSIGNMENT
+## TASK ASSIGNMENT (agent_type: cli_explore_agent)
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: {projectRoot}/.workflow/specs/*.md
+1. Read: {projectRoot}/.workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/specs/*.md
 
 ---
 

.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md

@@ -80,12 +80,12 @@ Cross-reference the task description against these documents for completeness.
   const focusDirective = getAgentFocusDirective('ra', state)
 
   return spawn_agent({
+    agent_type: "requirements_analyst",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/requirements-analyst.md
-2. Read: ${projectRoot}/.workflow/project-tech.json (if exists)
+1. Read: ${projectRoot}/.workflow/project-tech.json (if exists)
 3. Read: ${projectRoot}/.workflow/specs/*.md (if exists)
 4. Read: ${projectRoot}/.workflow/.cycle/${cycleId}.progress/coordination/feedback.md (if exists)
 
@@ -163,12 +163,12 @@ PHASE_RESULT:
 ```javascript
 function spawnEPAgent(cycleId, state, progressDir) {
   return spawn_agent({
+    agent_type: "exploration_planner",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/exploration-planner.md
-2. Read: ${projectRoot}/.workflow/project-tech.json
+1. Read: ${projectRoot}/.workflow/project-tech.json
 3. Read: ${projectRoot}/.workflow/specs/*.md
 4. Read: ${progressDir}/ra/requirements.md
 
@@ -242,12 +242,12 @@ PHASE_RESULT:
 ```javascript
 function spawnCDAgent(cycleId, state, progressDir) {
   return spawn_agent({
+    agent_type: "code_developer",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/code-developer.md
-2. Read: ${progressDir}/ep/plan.json
+1. Read: ${progressDir}/ep/plan.json
 3. Read: ${progressDir}/ra/requirements.md
 
 ---
@@ -320,12 +320,12 @@ PHASE_RESULT:
 ```javascript
 function spawnVASAgent(cycleId, state, progressDir) {
   return spawn_agent({
+    agent_type: "validation_archivist",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/validation-archivist.md
-2. Read: ${progressDir}/cd/changes.log
+1. Read: ${progressDir}/cd/changes.log
 
 ---
 

.codex/skills/review-cycle/SKILL.md

@@ -50,7 +50,7 @@ Unified multi-dimensional code review orchestrator with dual-mode (session/modul
 3. **Progressive Phase Loading**: Phase docs are read on-demand when that phase executes, not all at once
 4. **Auto-Continue**: All phases run autonomously without user intervention between phases
 5. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent
-6. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS
+6. **Role via agent_type**: Subagent roles loaded via TOML `agent_type` parameter in spawn_agent (e.g., `"cli_explore_agent"`)
 7. **Optional Fix Pipeline**: Phase 6-9 triggered only by explicit `--fix` flag or user confirmation after Phase 5
 8. **Content Preservation**: All agent prompts, code, schemas preserved verbatim from source commands
 
@@ -298,12 +298,12 @@ Create a new subagent with task assignment.
 
 ```javascript
 const agentId = spawn_agent({
+  agent_type: "{agent_type}",  // TOML agent definition name (e.g., "cli_explore_agent")
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Execute: ccw spec load --category "exploration execution"
+1. Execute: ccw spec load --category "exploration execution"
 
 ---
 

.codex/skills/review-cycle/phases/02-parallel-review.md

@@ -85,17 +85,17 @@ const dimensions = ['security', 'architecture', 'quality', 'action-items', 'perf
 
 dimensions.forEach(dimension => {
   const agentId = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read review state: ${reviewStateJsonPath}
-3. Get target files: Read resolved_files from review-state.json
-4. Validate file access: bash(ls -la ${targetFiles.join(' ')})
-5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
-6. Execute: ccw spec load --category "exploration execution" (technology stack and constraints)
-7. Execute: ccw spec load --category review (review standards and checklists)
+1. Read review state: ${reviewStateJsonPath}
+2. Get target files: Read resolved_files from review-state.json
+3. Validate file access: bash(ls -la ${targetFiles.join(' ')})
+4. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
+5. Execute: ccw spec load --category "exploration execution" (technology stack and constraints)
+6. Execute: ccw spec load --category review (review standards and checklists)
 
 ---
 
@@ -124,7 +124,7 @@ Use **Deep Scan mode** for this review:
 
 ## Expected Deliverables
 
-**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 4, follow schema exactly
 
 1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
 
@@ -207,18 +207,18 @@ const dimensions = ['security', 'architecture', 'quality', 'action-items', 'perf
 
 dimensions.forEach(dimension => {
   const agentId = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read session metadata: ${sessionMetadataPath}
-3. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f)
-4. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
-5. Read review state: ${reviewStateJsonPath}
-6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
-7. Execute: ccw spec load --category "exploration execution" (technology stack and constraints)
-8. Execute: ccw spec load --category review (review standards and checklists)
+1. Read session metadata: ${sessionMetadataPath}
+2. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f)
+3. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
+4. Read review state: ${reviewStateJsonPath}
+5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
+6. Execute: ccw spec load --category "exploration execution" (technology stack and constraints)
+7. Execute: ccw spec load --category review (review standards and checklists)
 
 ---
 
@@ -247,7 +247,7 @@ Use **Deep Scan mode** for this review:
 
 ## Expected Deliverables
 
-**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
 
 1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
 
@@ -326,18 +326,18 @@ reviewAgents.forEach(id => close_agent({ id }));
 ```javascript
 // Spawn deep-dive agent
 const deepDiveAgentId = spawn_agent({
+  agent_type: "cli_explore_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read original finding: ${dimensionJsonPath}
-3. Read affected file: ${file}
-4. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
-5. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
-6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
-7. Execute: ccw spec load --category "exploration execution" (technology stack and constraints for remediation)
-8. Execute: ccw spec load --category review (review standards and checklists)
+1. Read original finding: ${dimensionJsonPath}
+2. Read affected file: ${file}
+3. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
+4. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
+5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
+6. Execute: ccw spec load --category "exploration execution" (technology stack and constraints for remediation)
+7. Execute: ccw spec load --category review (review standards and checklists)
 
 ---
 
@@ -372,7 +372,7 @@ Then apply **Deep Scan mode** for semantic analysis:
 
 ## Expected Deliverables
 
-**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
 
 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
 

.codex/skills/review-cycle/phases/04-iterative-deep-dive.md

@@ -79,18 +79,18 @@ const deepDiveAgents = [];
 
 selectedFindings.forEach(finding => {
   const agentId = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read original finding: ${dimensionJsonPath}
-3. Read affected file: ${finding.file}
-4. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${projectDir}/src --include="*.ts")
-5. Read test files: bash(find ${projectDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
-6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
-7. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-8. Read: ${projectRoot}/.workflow/specs/*.md (user-defined constraints for remediation compliance)
+1. Read original finding: ${dimensionJsonPath}
+2. Read affected file: ${finding.file}
+3. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${projectDir}/src --include="*.ts")
+4. Read test files: bash(find ${projectDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
+5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
+6. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
+7. Read: ${projectRoot}/.workflow/specs/*.md (user-defined constraints for remediation compliance)
 
 ---
 
@@ -125,7 +125,7 @@ Then apply **Deep Scan mode** for semantic analysis:
 
 ## Expected Deliverables
 
-**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
 
 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${finding.id}.json
 
@@ -190,18 +190,18 @@ const deepDiveAgents = [];
 
 selectedFindings.forEach(finding => {
   const agentId = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read original finding: ${dimensionJsonPath}
-3. Read affected file: ${finding.file}
-4. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${workflowDir}/src --include="*.ts")
-5. Read test files: bash(find ${workflowDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
-6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
-7. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-8. Read: ${projectRoot}/.workflow/specs/*.md (user-defined constraints for remediation compliance)
+1. Read original finding: ${dimensionJsonPath}
+2. Read affected file: ${finding.file}
+3. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${workflowDir}/src --include="*.ts")
+4. Read test files: bash(find ${workflowDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
+5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
+6. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
+7. Read: ${projectRoot}/.workflow/specs/*.md (user-defined constraints for remediation compliance)
 
 ---
 
@@ -237,7 +237,7 @@ Then apply **Deep Scan mode** for semantic analysis:
 
 ## Expected Deliverables
 
-**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 6, follow schema exactly
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
 
 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${finding.id}.json
 

.codex/skills/review-cycle/phases/07-fix-parallel-planning.md

@@ -100,12 +100,12 @@ for (let i = 1; i <= aggregatedPlan.groups.length; i++) {
 ```javascript
 // Spawn planning agent for a batch
 const agentId = spawn_agent({
+  agent_type: "cli_planning_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-planning-agent.md (MUST read first)
-2. Execute: ccw spec load --category planning
+1. Execute: ccw spec load --category planning
 
 ---
 

.codex/skills/review-cycle/phases/08-fix-execution.md

@@ -55,12 +55,12 @@ if (result.passRate < 100%) {
 ```javascript
 // Spawn execution agent for a group
 const execAgentId = spawn_agent({
+  agent_type: "cli_execution_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first)
-2. Execute: ccw spec load --category execution
+1. Execute: ccw spec load --category execution
 
 ---
 

.codex/skills/roadmap-with-file/SKILL.md

@@ -39,13 +39,13 @@ Create a new subagent with task assignment.
 
 ```javascript
 const agentId = spawn_agent({
+  agent_type: "{agent_type}",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+1. Read: .workflow/project-tech.json
+2. Read: .workflow/project-guidelines.json
 
 ## TASK CONTEXT
 ${taskContext}
@@ -502,13 +502,13 @@ Bash(`mkdir -p ${sessionFolder}`)
 
    if (hasCodebase !== 'none') {
      const exploreAgentId = spawn_agent({
+       agent_type: "cli_explore_agent",
        message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+1. Read: .workflow/project-tech.json
+2. Read: .workflow/project-guidelines.json
 
 ---
 
@@ -553,13 +553,13 @@ Return findings as JSON with schema:
 2. **Execute Decomposition Agent**
    ```javascript
    const decompositionAgentId = spawn_agent({
+     agent_type: "cli_roadmap_plan_agent",
      message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-roadmap-plan-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+1. Read: .workflow/project-tech.json
+2. Read: .workflow/project-guidelines.json
 
 ---
 

.codex/skills/spec-setup/SKILL.md

@@ -122,12 +122,12 @@ let exploreAgent = null
 
 try {
   exploreAgent = spawn_agent({
+    agent_type: "cli_explore_agent",
     message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json (if exists, for --regenerate)
+1. Read: .workflow/project-tech.json (if exists, for --regenerate)
 
 ---
 

.codex/skills/workflow-plan/SKILL.md

@@ -242,7 +242,7 @@ console.log(`Session: ${sessionId}`)
 console.log(`\n## Phase 2: Context Gathering\n`)
 
 const ctxAgent = spawn_agent({
-  agent: `~/.codex/agents/context-search-agent.md`,
+  agent_type: "context_search_agent",
   instruction: `
 Gather implementation context for planning.
 
@@ -376,7 +376,7 @@ TASK DESCRIPTION: ${taskDescription}" --tool gemini --mode analysis --rule analy
    ```javascript
    if (!isMultiModule) {
      const planAgent = spawn_agent({
-       agent: `~/.codex/agents/action-planning-agent.md`,
+       agent_type: "action_planning_agent",
        instruction: `
 Generate implementation plan and task JSONs.
 
@@ -421,7 +421,7 @@ ${contextPkg.conflict_risk === 'medium' || contextPkg.conflict_risk === 'high'
        const mod = uniqueModules[i]
 
        const agentId = spawn_agent({
-         agent: `~/.codex/agents/action-planning-agent.md`,
+         agent_type: "action_planning_agent",
          instruction: `
 Plan module: ${mod} (prefix: ${prefix})
 
@@ -444,7 +444,7 @@ Mark cross-module dependencies as CROSS::${'{module}'}::${'{task}'}
 
      // +1 Coordinator: integrate all modules
      const coordAgent = spawn_agent({
-       agent: `~/.codex/agents/action-planning-agent.md`,
+       agent_type: "action_planning_agent",
        instruction: `
 Integrate ${uniqueModules.length} module plans into unified IMPL_PLAN.md.
 
@@ -576,7 +576,7 @@ if (mode === 'replan') {
 
   // 2. Replan via agent
   const replanAgent = spawn_agent({
-    agent: `~/.codex/agents/action-planning-agent.md`,
+    agent_type: "action_planning_agent",
     instruction: `
 Replan ${scope === 'task' ? `task ${replanTaskId}` : 'entire session'}.
 

.codex/skills/workflow-tdd-plan/SKILL.md

@@ -269,7 +269,7 @@ console.log(`Session: ${sessionId}`)
 console.log(`\n## Phase 2: Context Gathering\n`)
 
 const ctxAgent = spawn_agent({
-  agent: `~/.codex/agents/context-search-agent.md`,
+  agent_type: "context_search_agent",
   instruction: `
 Gather implementation context for TDD planning.
 
@@ -329,7 +329,7 @@ console.log(`  Context gathered. Conflict risk: ${conflictRisk}`)
 console.log(`\n## Phase 3: Test Coverage Analysis\n`)
 
 const testAgent = spawn_agent({
-  agent: `~/.codex/agents/cli-explore-agent.md`,
+  agent_type: "cli_explore_agent",
   instruction: `
 Analyze test coverage and framework for TDD planning.
 
@@ -452,7 +452,7 @@ TASK DESCRIPTION: ${taskDescription}" --tool gemini --mode analysis --rule analy
 console.log(`\n## Phase 5: TDD Task Generation\n`)
 
 const planAgent = spawn_agent({
-  agent: `~/.codex/agents/action-planning-agent.md`,
+  agent_type: "action_planning_agent",
   instruction: `
 Generate TDD implementation plan with Red-Green-Refactor cycles.
 
@@ -628,7 +628,7 @@ if (mode === 'verify' || /* auto-verify from Phase 6 */) {
   }
 
   const verifyAgent = spawn_agent({
-    agent: `~/.codex/agents/cli-explore-agent.md`,
+    agent_type: "cli_explore_agent",
     instruction: `
 Verify TDD compliance across 4 dimensions.
 

.codex/skills/workflow-test-fix-cycle/SKILL.md

@@ -83,12 +83,12 @@ Create a new subagent with task assignment.
 
 ```javascript
 const agentId = spawn_agent({
+  agent_type: "{agent_type}",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Run: `ccw spec load --category "planning execution"`
+1. Run: `ccw spec load --category "planning execution"`
 
 ## TASK CONTEXT
 ${taskContext}
@@ -241,10 +241,10 @@ Phase 2: Test-Cycle Execution (phases/02-test-cycle-execute.md)
 5. Phase 1 Summary → **⛔ MANDATORY: Present plan and wait for user confirmation before Phase 2**
 
 **Agents Used** (via spawn_agent):
-- `test-context-search-agent` (~/.codex/agents/test-context-search-agent.md) - Context gathering (Session Mode)
-- `context-search-agent` (~/.codex/agents/context-search-agent.md) - Context gathering (Prompt Mode)
-- `cli-execution-agent` (~/.codex/agents/cli-execution-agent.md) - Test analysis with Gemini
-- `action-planning-agent` (~/.codex/agents/action-planning-agent.md) - Task JSON generation
+- `test_context_search_agent` (agent_type: test_context_search_agent) - Context gathering (Session Mode)
+- `context_search_agent` (agent_type: context_search_agent) - Context gathering (Prompt Mode)
+- `cli_execution_agent` (agent_type: cli_execution_agent) - Test analysis with Gemini
+- `action_planning_agent` (agent_type: action_planning_agent) - Task JSON generation
 
 ### Phase 2: Test-Cycle Execution
 
@@ -256,8 +256,8 @@ Phase 2: Test-Cycle Execution (phases/02-test-cycle-execute.md)
 3. Completion - Final validation → Summary → Auto-complete session
 
 **Agents Used** (via spawn_agent):
-- `cli-planning-agent` (~/.codex/agents/cli-planning-agent.md) - Failure analysis, root cause extraction, fix task generation
-- `test-fix-agent` (~/.codex/agents/test-fix-agent.md) - Test execution, code fixes, criticality assignment
+- `cli_planning_agent` (agent_type: cli_planning_agent) - Failure analysis, root cause extraction, fix task generation
+- `test_fix_agent` (agent_type: test_fix_agent) - Test execution, code fixes, criticality assignment
 
 **Strategy Engine**: conservative (iteration 1-2) → aggressive (pass >80%) → surgical (regression)
 
@@ -387,14 +387,14 @@ try {
 - None for Prompt Mode
 
 **Phase 1 Agents** (used by phases/01-test-fix-gen.md via spawn_agent):
-- `test-context-search-agent` (~/.codex/agents/test-context-search-agent.md) - Test coverage analysis (Session Mode)
-- `context-search-agent` (~/.codex/agents/context-search-agent.md) - Codebase analysis (Prompt Mode)
-- `cli-execution-agent` (~/.codex/agents/cli-execution-agent.md) - Test requirements with Gemini
-- `action-planning-agent` (~/.codex/agents/action-planning-agent.md) - Task JSON generation
+- `test_context_search_agent` (agent_type: test_context_search_agent) - Test coverage analysis (Session Mode)
+- `context_search_agent` (agent_type: context_search_agent) - Codebase analysis (Prompt Mode)
+- `cli_execution_agent` (agent_type: cli_execution_agent) - Test requirements with Gemini
+- `action_planning_agent` (agent_type: action_planning_agent) - Task JSON generation
 
 **Phase 2 Agents** (used by phases/02-test-cycle-execute.md via spawn_agent):
-- `cli-planning-agent` (~/.codex/agents/cli-planning-agent.md) - CLI analysis, root cause extraction, task generation
-- `test-fix-agent` (~/.codex/agents/test-fix-agent.md) - Test execution, code fixes, criticality assignment
+- `cli_planning_agent` (agent_type: cli_planning_agent) - CLI analysis, root cause extraction, task generation
+- `test_fix_agent` (agent_type: test_fix_agent) - Test execution, code fixes, criticality assignment
 
 **Follow-up**:
 - Session sync: `$session-sync -y "Test-fix cycle complete: {pass_rate}% pass rate"`

.codex/skills/workflow-test-fix-cycle/phases/01-test-fix-gen.md

@@ -70,13 +70,13 @@ if (input.startsWith("WFS-")) {
 ```javascript
 // Session Mode - gather from source session via test-context-search-agent
 const contextAgentId = spawn_agent({
+  agent_type: "test_context_search_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/test-context-search-agent.md (MUST read first)
-2. Run: `ccw spec load --category planning`
-3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
+1. Run: `ccw spec load --category planning`
+2. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
 
 ---
 
@@ -97,13 +97,13 @@ close_agent({ id: contextAgentId });
 
 // Prompt Mode - gather from codebase via context-search-agent
 const contextAgentId = spawn_agent({
+  agent_type: "context_search_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first)
-2. Run: `ccw spec load --category planning`
-3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
+1. Run: `ccw spec load --category planning`
+2. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
 
 ---
 
@@ -171,13 +171,13 @@ close_agent({ id: contextAgentId });
 
 ```javascript
 const analysisAgentId = spawn_agent({
+  agent_type: "cli_execution_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first)
-2. Run: `ccw spec load --category planning`
-3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
+1. Run: `ccw spec load --category planning`
+2. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
 
 ---
 
@@ -240,13 +240,13 @@ close_agent({ id: analysisAgentId });
 
 ```javascript
 const taskGenAgentId = spawn_agent({
+  agent_type: "action_planning_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
-2. Run: `ccw spec load --category planning`
-3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
+1. Run: `ccw spec load --category planning`
+2. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
 
 ---
 

.codex/skills/workflow-test-fix-cycle/phases/02-test-cycle-execute.md

@@ -85,13 +85,13 @@ return "conservative";
 ```javascript
 // Spawn agent for failure analysis
 const analysisAgentId = spawn_agent({
+  agent_type: "cli_planning_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/cli-planning-agent.md (MUST read first)
-2. Run: `ccw spec load --category planning`
-3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
+1. Run: `ccw spec load --category planning`
+2. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
 
 ---
 
@@ -152,13 +152,13 @@ close_agent({ id: analysisAgentId });
 ```javascript
 // Spawn agent for test execution/fixing
 const fixAgentId = spawn_agent({
+  agent_type: "test_fix_agent",
   message: `
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/test-fix-agent.md (MUST read first)
-2. Run: `ccw spec load --category execution`
-3. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
+1. Run: `ccw spec load --category execution`
+2. Run: `ccw spec load --category test` (test framework, coverage targets, conventions)
 
 ---