Claude-Code-Workflow/.claude/skills/codex-skill-designer/phases/03-agent-design.md

Phase 3: Agent Design

Generate agent role definitions and optional phase execution detail files.

Objective

• Generate agent role files for ~/.codex/agents/ or .codex/skills/{name}/agents/
• Apply Codex-native conventions (MANDATORY FIRST STEPS, structured output)
• Preserve source content when converting from Claude
• Generate optional phase detail files for complex orchestrations

Pre-Requisites

• Read templates/agent-role-template.md for role file structure
• Read templates/command-pattern-template.md for pre-built command patterns
• Read specs/codex-agent-patterns.md for API patterns

Execution

Step 3.1: Identify Agents to Generate

// From codexSkillConfig
const agentsToGenerate = codexSkillConfig.agents.filter(a =>
  a.role_file.startsWith('.codex/skills/')  // new skill-specific agents
  || codexSkillConfig.newAgentDefinitions?.includes(a.role_file)
)

// Existing agents (already in ~/.codex/agents/) — skip generation
const existingAgents = codexSkillConfig.agents.filter(a =>
  !agentsToGenerate.includes(a)
)

Step 3.2: Generate Agent Role Files

For each agent to generate, apply the agent-role-template:

for (const agent of agentsToGenerate) {
  const roleContent = applyTemplate('templates/agent-role-template.md', {
    agent_name: agent.name,
    description: agent.responsibility,
    capabilities: agent.capabilities || inferCapabilities(agent),
    execution_process: agent.workflow || inferWorkflow(agent),
    output_format: codexSkillConfig.outputTemplate || "structured",
    key_reminders: generateReminders(agent)
  })

  const outputPath = agent.role_file.startsWith('~/')
    ? agent.role_file
    : `.codex/skills/${codexSkillConfig.name}/agents/${agent.name}.md`

  Write(outputPath, roleContent)
  generatedFiles.agents.push(outputPath)
}

Step 3.3: Agent Role File Content Structure

Each generated agent role file follows this structure:

---
name: {{agent_name}}
description: |
  {{description}}
color: {{color}}
skill: {{parent_skill_name}}
---

# {{agent_display_name}}

{{description_paragraph}}

## Core Capabilities

1. **{{capability_1}}**: {{description}}
2. **{{capability_2}}**: {{description}}
3. **{{capability_3}}**: {{description}}

## Execution Process

### Step 1: Context Loading
- Read role-specific configuration files
- Load project context (.workflow/project-tech.json)
- Understand task scope from TASK ASSIGNMENT

### Step 2: {{primary_action}}
{{primary_action_detail}}

### Step 3: {{secondary_action}}
{{secondary_action_detail}}

### Step 4: Output Delivery
Produce structured output following the template:

\`\`\`text
Summary:
- {{summary_format}}

Findings:
- {{findings_format}}

Proposed changes:
- {{changes_format}}

Tests:
- {{tests_format}}

Open questions:
- {{questions_format}}
\`\`\`

## Key Reminders

**ALWAYS**:
- Read role definition file as FIRST action
- Follow structured output template
- Stay within assigned scope
- Report open questions instead of guessing

**NEVER**:
- Modify files outside assigned scope
- Skip role definition loading
- Produce unstructured output
- Make assumptions about unclear requirements

Step 3.4: Conversion from Claude Agent Definitions

When converting from Claude skill, extract agent behavior from:

1. Task() prompts: The prompt parameter contains the agent's task instructions
2. Phase files: Phase execution detail contains the full agent interaction
3. subagent_type: Maps to existing ~/.codex/agents/ roles

// For each Task() call found in Claude source
for (const taskCall of claudeConfig.agents) {
  const existingRole = roleMapping[taskCall.subagent_type]

  if (existingRole) {
    // Map to existing Codex agent — no new file needed
    // Just reference in orchestrator's MANDATORY FIRST STEPS
    codexSkillConfig.agents.push({
      name: taskCall.subagent_type,
      role_file: `~/.codex/agents/${taskCall.subagent_type}.md`,
      responsibility: taskCall.description,
      is_new: false
    })
  } else {
    // Extract agent behavior from Claude prompt and create new role
    const newRole = extractRoleFromPrompt(taskCall.prompt)
    // Generate new role file
  }
}

Step 3.5: Command Pattern Selection

For agents that need specific command patterns, select from pre-built templates:

Pattern	Use When	Template
Explore	Agent needs codebase exploration	Parallel fan-out spawn_agent
Analyze	Agent performs multi-perspective analysis	Parallel spawn + merge
Implement	Agent writes code	Sequential spawn + validate
Validate	Agent runs tests	Iterative spawn + send_input fix cycle
Review	Agent reviews code/artifacts	Parallel spawn + aggregate
Deep Interact	Agent needs multi-round conversation	spawn + wait + send_input loop
Two-Phase	Agent needs clarification first	spawn(clarify) + send_input(execute)

Read templates/command-pattern-template.md for full pattern implementations.

Step 3.6: Generate Phase Detail Files (Optional)

For structured mode with complex phases, generate phase detail files:

if (codexSkillConfig.outputMode === "structured") {
  for (const phase of codexSkillConfig.phases) {
    if (phase.complexity === "high" || phase.agents_involved.length > 2) {
      const phaseContent = generatePhaseDetail(phase, codexSkillConfig)
      const phasePath = `.codex/skills/${codexSkillConfig.name}/phases/${phase.index}-${phase.slug}.md`
      Write(phasePath, phaseContent)
      generatedFiles.phases.push(phasePath)
    }
  }
}

Phase detail structure:

# Phase {{N}}: {{Phase Name}}

{{One-sentence description}}

## Agents Involved

| Agent | Role | Interaction Model |
|-------|------|-------------------|
{{#each phase.agents}}
| {{name}} | {{role_file}} | {{interaction_model}} |
{{/each}}

## Execution

### spawn_agent Configuration

\`\`\`javascript
const agent = spawn_agent({
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: {{role_file}} (MUST read first)
...

---

Goal: {{goal}}
Scope: {{scope}}
Context: {{context}}
Deliverables: {{deliverables}}
Quality bar: {{quality}}
`
})
\`\`\`

### Wait & Result Processing

\`\`\`javascript
const result = wait({ ids: [agent], timeout_ms: {{timeout}} })
// Process: {{result_processing}}
close_agent({ id: agent })
\`\`\`

## Output

- **Result**: {{output_description}}
- **Passed to**: Phase {{N+1}}

Step 3.7: Deployment Mapping

Generate deployment instructions:

const deploymentMap = {
  // Existing agents — no action needed
  existing: existingAgents.map(a => ({
    name: a.name,
    path: a.role_file,
    action: "already deployed"
  })),
  // New agents — need deployment
  new: agentsToGenerate.map(a => ({
    name: a.name,
    sourcePath: `.codex/skills/${codexSkillConfig.name}/agents/${a.name}.md`,
    targetPath: `~/.codex/agents/${a.name}.md`,
    action: "copy to ~/.codex/agents/"
  }))
}

Output

• Files: generatedFiles.agents[] — agent role files
• Files: generatedFiles.phases[] — optional phase detail files
• Variable: deploymentMap — deployment instructions
• TodoWrite: Mark Phase 3 completed, Phase 4 in_progress

Next Phase

Return to orchestrator, then auto-continue to Phase 4: Validation & Delivery.