mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: Add orchestrator template and roles for executor and planner
- Created a new orchestrator template for Codex skill design, detailing structure and execution phases. - Introduced the executor role with responsibilities for task execution, including routing to backends and handling implementation. - Added the planner role for requirement breakdown, issue creation, and task dispatching, ensuring a structured planning process.
This commit is contained in:
catlog22
@@ -0,0 +1,167 @@
|
||||
# Phase 1: Requirements Analysis
|
||||
|
||||
Analyze input source and extract Codex skill configuration.
|
||||
|
||||
## Objective
|
||||
|
||||
- Parse input source (text / Claude skill / requirements doc / Codex prompt)
|
||||
- Identify agents, phases, interaction patterns
|
||||
- Determine output mode (structured package vs single prompt)
|
||||
- Produce codexSkillConfig for downstream phases
|
||||
|
||||
## Pre-Requisites
|
||||
|
||||
Read specification documents based on input source:
|
||||
- **Always**: Read `specs/codex-agent-patterns.md` for available patterns
|
||||
- **Claude conversion**: Also read `specs/conversion-rules.md`
|
||||
- **Quality reference**: Read `specs/quality-standards.md` for target criteria
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 1.1: Input Source Detection
|
||||
|
||||
```javascript
|
||||
// Determine input type from workflowPreferences
|
||||
const inputSource = workflowPreferences.inputSource
|
||||
|
||||
if (inputSource.includes("Claude Skill")) {
|
||||
// Read source Claude skill
|
||||
const sourceSkillPath = AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Path to the Claude skill to convert?",
|
||||
header: "Skill Path",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Browse", description: "I'll provide the path" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
// Read SKILL.md + phases/*.md from source
|
||||
const skillContent = Read(sourceSkillPath)
|
||||
const phaseFiles = Glob(`${sourceSkillDir}/phases/*.md`)
|
||||
} else if (inputSource.includes("Text Description")) {
|
||||
// Collect description via user interaction
|
||||
} else if (inputSource.includes("Requirements Doc")) {
|
||||
// Read requirements file
|
||||
} else if (inputSource.includes("Existing Codex")) {
|
||||
// Read existing Codex prompt for refactoring
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1.2: Skill Structure Extraction
|
||||
|
||||
For each input type, extract:
|
||||
|
||||
**From Text Description**:
|
||||
```javascript
|
||||
const codexSkillConfig = {
|
||||
name: extractSkillName(userDescription),
|
||||
description: extractDescription(userDescription),
|
||||
outputMode: workflowPreferences.outputMode,
|
||||
agents: inferAgents(userDescription),
|
||||
phases: inferPhases(userDescription),
|
||||
parallelSplits: inferParallelism(userDescription),
|
||||
interactionModel: inferInteractionModel(userDescription),
|
||||
conversionSource: null
|
||||
}
|
||||
```
|
||||
|
||||
**From Claude Skill** (conversion):
|
||||
```javascript
|
||||
// Parse Claude SKILL.md
|
||||
const claudeConfig = {
|
||||
phases: extractPhases(skillContent),
|
||||
agents: extractTaskCalls(skillContent), // Find Task() invocations
|
||||
dataFlow: extractDataFlow(skillContent),
|
||||
todoPattern: extractTodoPattern(skillContent),
|
||||
resumePatterns: findResumePatterns(skillContent) // For send_input mapping
|
||||
}
|
||||
|
||||
const codexSkillConfig = {
|
||||
name: claudeConfig.name,
|
||||
description: claudeConfig.description,
|
||||
outputMode: workflowPreferences.outputMode,
|
||||
agents: claudeConfig.agents.map(a => ({
|
||||
name: a.subagent_type,
|
||||
role_file: mapToCodexRolePath(a.subagent_type),
|
||||
responsibility: a.description,
|
||||
patterns: determinePatterns(a)
|
||||
})),
|
||||
phases: claudeConfig.phases.map(p => ({
|
||||
name: p.name,
|
||||
agents_involved: p.agentCalls.map(a => a.subagent_type),
|
||||
interaction_model: hasResume(p) ? "deep_interaction" : "standard"
|
||||
})),
|
||||
parallelSplits: detectParallelPatterns(claudeConfig),
|
||||
conversionSource: { type: "claude_skill", path: sourceSkillPath }
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1.3: Agent Inventory Check
|
||||
|
||||
Verify agent roles exist in `~/.codex/agents/`:
|
||||
|
||||
```javascript
|
||||
const existingAgents = Glob("~/.codex/agents/*.md")
|
||||
const requiredAgents = codexSkillConfig.agents.map(a => a.role_file)
|
||||
|
||||
const missingAgents = requiredAgents.filter(r =>
|
||||
!existingAgents.includes(r)
|
||||
)
|
||||
|
||||
if (missingAgents.length > 0) {
|
||||
// Mark as "needs new agent role definition"
|
||||
codexSkillConfig.newAgentDefinitions = missingAgents
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1.4: Interaction Model Selection
|
||||
|
||||
Based on agent relationships, select interaction patterns:
|
||||
|
||||
| Pattern | Condition | Result |
|
||||
|---------|-----------|--------|
|
||||
| **Standard** | Single agent, single task | `spawn → wait → close` |
|
||||
| **Parallel Fan-out** | Multiple independent agents | `spawn[] → batch wait → close[]` |
|
||||
| **Deep Interaction** | Multi-phase with context | `spawn → wait → send_input → wait → close` |
|
||||
| **Two-Phase** | Needs clarification first | `spawn(clarify) → wait → send_input(answers) → wait → close` |
|
||||
| **Pipeline** | Sequential agent chain | `spawn(A) → wait → spawn(B, with A result) → wait → close` |
|
||||
|
||||
```javascript
|
||||
codexSkillConfig.phases.forEach(phase => {
|
||||
if (phase.agents_involved.length > 1) {
|
||||
phase.interaction_model = "parallel_fanout"
|
||||
} else if (phase.interaction_model === "deep_interaction") {
|
||||
// Already set from resume pattern detection
|
||||
} else {
|
||||
phase.interaction_model = "standard"
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Step 1.5: User Confirmation
|
||||
|
||||
Present extracted configuration for user review:
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Skill "${codexSkillConfig.name}" will have ${codexSkillConfig.agents.length} agent(s) and ${codexSkillConfig.phases.length} phase(s). ${codexSkillConfig.newAgentDefinitions?.length || 0} new agent definitions needed. Proceed?`,
|
||||
header: "Confirm",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Proceed", description: "Generate Codex skill package" },
|
||||
{ label: "Adjust", description: "Modify configuration first" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `codexSkillConfig` — complete skill configuration
|
||||
- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 2: Orchestrator Design](02-orchestrator-design.md).
|
||||
@@ -0,0 +1,291 @@
|
||||
# Phase 2: Orchestrator Design
|
||||
|
||||
Generate the main Codex orchestrator document using codexSkillConfig.
|
||||
|
||||
## Objective
|
||||
|
||||
- Generate orchestrator.md (structured mode) or {skill-name}.md (single mode)
|
||||
- Apply Codex-native patterns: spawn_agent, wait, send_input, close_agent
|
||||
- Include agent registry, phase execution, lifecycle management
|
||||
- Preserve source content faithfully when converting from Claude
|
||||
|
||||
## Pre-Requisites
|
||||
|
||||
- Read `templates/orchestrator-template.md` for output structure
|
||||
- Read `specs/codex-agent-patterns.md` for pattern reference
|
||||
- If converting: Read `specs/conversion-rules.md` for mapping rules
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 2.1: Determine Output Path
|
||||
|
||||
```javascript
|
||||
const outputPath = codexSkillConfig.outputMode === "structured"
|
||||
? `.codex/skills/${codexSkillConfig.name}/orchestrator.md`
|
||||
: `~/.codex/prompts/${codexSkillConfig.name}.md`
|
||||
```
|
||||
|
||||
### Step 2.2: Generate Frontmatter
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {{skill_name}}
|
||||
description: {{description}}
|
||||
agents: {{agent_count}}
|
||||
phases: {{phase_count}}
|
||||
output_template: structured # or "open_questions" for clarification-first
|
||||
---
|
||||
```
|
||||
|
||||
### Step 2.3: Generate Architecture Diagram
|
||||
|
||||
Map phases and agents to ASCII flow:
|
||||
|
||||
```javascript
|
||||
// For parallel fan-out:
|
||||
const diagram = `
|
||||
┌──────────────────────────────────────────┐
|
||||
│ ${codexSkillConfig.name} Orchestrator │
|
||||
└──────────────┬───────────────────────────┘
|
||||
│
|
||||
┌───────────┼───────────┬────────────┐
|
||||
↓ ↓ ↓ ↓
|
||||
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
|
||||
│Agent1│ │Agent2│ │Agent3│ │AgentN│
|
||||
│spawn │ │spawn │ │spawn │ │spawn │
|
||||
└──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘
|
||||
└──────────┼───────────┘ │
|
||||
↓ │
|
||||
batch wait({ids}) ←──────────┘
|
||||
↓
|
||||
Aggregate Results
|
||||
↓
|
||||
close_agent (all)
|
||||
`
|
||||
```
|
||||
|
||||
### Step 2.4: Generate Agent Registry
|
||||
|
||||
```javascript
|
||||
const agentRegistry = codexSkillConfig.agents.map(agent => ({
|
||||
name: agent.name,
|
||||
role_file: agent.role_file, // e.g., ~/.codex/agents/cli-explore-agent.md
|
||||
responsibility: agent.responsibility,
|
||||
is_new: agent.role_file.startsWith('.codex/skills/') // skill-specific new agent
|
||||
}))
|
||||
```
|
||||
|
||||
Output as registry table in orchestrator:
|
||||
|
||||
```markdown
|
||||
## Agent Registry
|
||||
|
||||
| Agent | Role File | Responsibility | Status |
|
||||
|-------|-----------|----------------|--------|
|
||||
{{#each agents}}
|
||||
| `{{name}}` | `{{role_file}}` | {{responsibility}} | {{#if is_new}}NEW{{else}}existing{{/if}} |
|
||||
{{/each}}
|
||||
```
|
||||
|
||||
### Step 2.5: Generate Phase Execution Blocks
|
||||
|
||||
For each phase in codexSkillConfig.phases, generate the appropriate pattern:
|
||||
|
||||
**Standard Pattern** (single agent, single task):
|
||||
```javascript
|
||||
// Phase N: {{phase.name}}
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: {{agent.role_file}} (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
Goal: {{phase.goal}}
|
||||
|
||||
Scope:
|
||||
- 可做: {{phase.scope.include}}
|
||||
- 不可做: {{phase.scope.exclude}}
|
||||
|
||||
Context:
|
||||
{{phase.context}}
|
||||
|
||||
Deliverables:
|
||||
- {{phase.deliverables}}
|
||||
|
||||
Quality bar:
|
||||
- {{phase.quality_criteria}}
|
||||
`
|
||||
})
|
||||
|
||||
const result = wait({ ids: [agentId], timeout_ms: {{phase.timeout_ms || 300000}} })
|
||||
close_agent({ id: agentId })
|
||||
```
|
||||
|
||||
**Parallel Fan-out Pattern** (multiple independent agents):
|
||||
```javascript
|
||||
// Phase N: {{phase.name}} (Parallel)
|
||||
const agentIds = {{phase.agents}}.map(agentConfig => {
|
||||
return spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ${agentConfig.role_file} (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
|
||||
---
|
||||
|
||||
Goal: ${agentConfig.specific_goal}
|
||||
Scope: ${agentConfig.scope}
|
||||
Deliverables: ${agentConfig.deliverables}
|
||||
`
|
||||
})
|
||||
})
|
||||
|
||||
// Batch wait for all agents
|
||||
const results = wait({
|
||||
ids: agentIds,
|
||||
timeout_ms: {{phase.timeout_ms || 600000}}
|
||||
})
|
||||
|
||||
// Handle timeout
|
||||
if (results.timed_out) {
|
||||
const completed = agentIds.filter(id => results.status[id].completed)
|
||||
const pending = agentIds.filter(id => !results.status[id].completed)
|
||||
// Decision: continue waiting or use partial results
|
||||
}
|
||||
|
||||
// Aggregate results
|
||||
const aggregated = agentIds.map(id => results.status[id].completed)
|
||||
|
||||
// Cleanup
|
||||
agentIds.forEach(id => close_agent({ id }))
|
||||
```
|
||||
|
||||
**Deep Interaction Pattern** (multi-round with send_input):
|
||||
```javascript
|
||||
// Phase N: {{phase.name}} (Deep Interaction)
|
||||
const agent = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: {{agent.role_file}} (MUST read first)
|
||||
|
||||
---
|
||||
|
||||
### Phase A: {{phase.initial_goal}}
|
||||
Goal: {{phase.initial_goal}}
|
||||
Output: Findings + Open Questions (if any)
|
||||
|
||||
Output format for questions:
|
||||
\`\`\`
|
||||
CLARIFICATION_NEEDED:
|
||||
Q1: [question] | Options: [A, B, C] | Recommended: [A]
|
||||
\`\`\`
|
||||
|
||||
### Phase B: {{phase.followup_goal}}
|
||||
Trigger: Receive answers via send_input
|
||||
Output: Complete deliverable
|
||||
`
|
||||
})
|
||||
|
||||
// Round 1: Initial exploration
|
||||
const round1 = wait({ ids: [agent], timeout_ms: {{phase.timeout_ms || 600000}} })
|
||||
|
||||
// Check for clarification needs
|
||||
const needsClarification = round1.status[agent].completed.includes('CLARIFICATION_NEEDED')
|
||||
|
||||
if (needsClarification) {
|
||||
// Collect user answers (orchestrator responsibility)
|
||||
const answers = collectUserAnswers(round1)
|
||||
|
||||
// Continue interaction
|
||||
send_input({
|
||||
id: agent,
|
||||
message: `
|
||||
## CLARIFICATION ANSWERS
|
||||
${answers}
|
||||
|
||||
## NEXT STEP
|
||||
Proceed with Phase B: {{phase.followup_goal}}
|
||||
`
|
||||
})
|
||||
|
||||
const round2 = wait({ ids: [agent], timeout_ms: {{phase.timeout_ms || 900000}} })
|
||||
}
|
||||
|
||||
close_agent({ id: agent })
|
||||
```
|
||||
|
||||
**Pipeline Pattern** (sequential agent chain):
|
||||
```javascript
|
||||
// Phase N: {{phase.name}} (Pipeline)
|
||||
|
||||
// Stage 1
|
||||
const agent1 = spawn_agent({ message: stage1Prompt })
|
||||
const result1 = wait({ ids: [agent1] })
|
||||
close_agent({ id: agent1 })
|
||||
|
||||
// Stage 2 (uses Stage 1 output)
|
||||
const agent2 = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
...
|
||||
## PREVIOUS STAGE OUTPUT
|
||||
${result1.status[agent1].completed}
|
||||
...
|
||||
`
|
||||
})
|
||||
const result2 = wait({ ids: [agent2] })
|
||||
close_agent({ id: agent2 })
|
||||
```
|
||||
|
||||
### Step 2.6: Generate Lifecycle Management Section
|
||||
|
||||
```markdown
|
||||
## Lifecycle Management
|
||||
|
||||
### Timeout Handling
|
||||
|
||||
| Timeout | Action |
|
||||
|---------|--------|
|
||||
| Agent completes within timeout | Process result, close_agent |
|
||||
| Agent times out (partial) | Option 1: continue wait / Option 2: send_input to urge convergence / Option 3: close_agent and use partial |
|
||||
| All agents timeout | Log warning, retry with extended timeout or abort |
|
||||
|
||||
### Cleanup Protocol
|
||||
|
||||
After ALL phases complete or on error:
|
||||
1. Verify all agent IDs have been closed
|
||||
2. Report any agents still running
|
||||
3. Force close remaining agents
|
||||
|
||||
\`\`\`javascript
|
||||
const allAgentIds = [] // accumulated during execution
|
||||
allAgentIds.forEach(id => {
|
||||
try { close_agent({ id }) } catch { /* already closed */ }
|
||||
})
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Step 2.7: Write Orchestrator File
|
||||
|
||||
Apply template from `templates/orchestrator-template.md` with generated content.
|
||||
|
||||
Write the complete orchestrator to the output path.
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: `{outputPath}` — generated Codex orchestrator
|
||||
- **Variable**: `generatedFiles.orchestrator` = outputPath
|
||||
- **TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 3: Agent Design](03-agent-design.md).
|
||||
277
.claude/skills/codex-skill-designer/phases/03-agent-design.md
Normal file
277
.claude/skills/codex-skill-designer/phases/03-agent-design.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 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
|
||||
|
||||
```javascript
|
||||
// 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:
|
||||
|
||||
```javascript
|
||||
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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
|
||||
```javascript
|
||||
// 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:
|
||||
|
||||
```javascript
|
||||
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:
|
||||
|
||||
```markdown
|
||||
# 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:
|
||||
|
||||
```javascript
|
||||
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](04-validation.md).
|
||||
254
.claude/skills/codex-skill-designer/phases/04-validation.md
Normal file
254
.claude/skills/codex-skill-designer/phases/04-validation.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Phase 4: Validation & Delivery
|
||||
|
||||
Validate the generated Codex skill package and deliver to target location.
|
||||
|
||||
## Objective
|
||||
|
||||
- Verify structural completeness of all generated files
|
||||
- Validate Codex pattern compliance (lifecycle, role loading, output format)
|
||||
- Score quality against standards
|
||||
- Deploy to target location with instructions
|
||||
|
||||
## Pre-Requisites
|
||||
|
||||
- Read `specs/quality-standards.md` for validation criteria
|
||||
- Access `generatedFiles` from previous phases
|
||||
- Access `codexSkillConfig` for expected structure
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 4.1: Structural Completeness Check
|
||||
|
||||
```javascript
|
||||
const structuralChecks = {
|
||||
// Orchestrator exists
|
||||
orchestrator: {
|
||||
exists: fileExists(generatedFiles.orchestrator),
|
||||
hasFrontmatter: checkFrontmatter(generatedFiles.orchestrator),
|
||||
hasArchitecture: checkSection(generatedFiles.orchestrator, "Architecture"),
|
||||
hasAgentRegistry: checkSection(generatedFiles.orchestrator, "Agent Registry"),
|
||||
hasPhaseExecution: checkSection(generatedFiles.orchestrator, "Phase"),
|
||||
hasLifecycleManagement: checkSection(generatedFiles.orchestrator, "Lifecycle"),
|
||||
hasTimeoutHandling: checkSection(generatedFiles.orchestrator, "Timeout"),
|
||||
passed: 0, total: 7
|
||||
},
|
||||
|
||||
// Agent files exist and are well-formed
|
||||
agents: codexSkillConfig.agents.map(agent => ({
|
||||
name: agent.name,
|
||||
exists: fileExists(agent.role_file) || fileExists(generatedFiles.agents.find(f => f.includes(agent.name))),
|
||||
hasFrontmatter: checkFrontmatter(agentFile),
|
||||
hasCapabilities: checkSection(agentFile, "Core Capabilities"),
|
||||
hasExecution: checkSection(agentFile, "Execution Process"),
|
||||
hasReminders: checkSection(agentFile, "Key Reminders"),
|
||||
passed: 0, total: 5
|
||||
})),
|
||||
|
||||
// Phase files (if structured mode)
|
||||
phases: generatedFiles.phases?.map(phasePath => ({
|
||||
path: phasePath,
|
||||
exists: fileExists(phasePath),
|
||||
hasAgentTable: checkSection(phasePath, "Agents Involved"),
|
||||
hasSpawnConfig: checkSection(phasePath, "spawn_agent"),
|
||||
hasWaitProcessing: checkSection(phasePath, "Wait"),
|
||||
passed: 0, total: 4
|
||||
})) || []
|
||||
}
|
||||
|
||||
// Count passes
|
||||
let totalPassed = 0, totalChecks = 0
|
||||
// ... count logic
|
||||
```
|
||||
|
||||
### Step 4.2: Codex Pattern Compliance
|
||||
|
||||
Verify all Codex-native patterns are correctly applied:
|
||||
|
||||
```javascript
|
||||
const patternChecks = {
|
||||
// Lifecycle: every spawn has a close
|
||||
lifecycle: {
|
||||
spawnCount: countPattern(orchestratorContent, /spawn_agent/g),
|
||||
closeCount: countPattern(orchestratorContent, /close_agent/g),
|
||||
balanced: spawnCount <= closeCount, // close >= spawn (batch close is OK)
|
||||
description: "Every spawn_agent must have matching close_agent"
|
||||
},
|
||||
|
||||
// Role loading: MANDATORY FIRST STEPS present
|
||||
roleLoading: {
|
||||
hasPattern: orchestratorContent.includes("MANDATORY FIRST STEPS"),
|
||||
allAgentsReferenced: codexSkillConfig.agents.every(a =>
|
||||
orchestratorContent.includes(a.role_file)
|
||||
),
|
||||
usesPathNotInline: !orchestratorContent.includes("## ROLE DEFINITION"),
|
||||
description: "Role files loaded via path reference, not inline content"
|
||||
},
|
||||
|
||||
// Wait pattern: uses wait() not close_agent for results
|
||||
waitPattern: {
|
||||
usesWaitForResults: countPattern(orchestratorContent, /wait\(\s*\{/) > 0,
|
||||
noCloseForResults: !hasPatternSequence(orchestratorContent, "close_agent", "result"),
|
||||
description: "Results obtained via wait(), not close_agent"
|
||||
},
|
||||
|
||||
// Batch wait: parallel agents use batch wait
|
||||
batchWait: {
|
||||
applicable: codexSkillConfig.parallelSplits?.length > 0,
|
||||
usesBatchIds: orchestratorContent.includes("ids: [") ||
|
||||
orchestratorContent.includes("ids: agentIds"),
|
||||
description: "Parallel agents use batch wait({ ids: [...] })"
|
||||
},
|
||||
|
||||
// Timeout handling: timeout_ms specified
|
||||
timeout: {
|
||||
hasTimeout: orchestratorContent.includes("timeout_ms"),
|
||||
hasTimeoutHandling: orchestratorContent.includes("timed_out"),
|
||||
description: "Timeout specified and timeout scenarios handled"
|
||||
},
|
||||
|
||||
// Structured output: agents produce uniform output
|
||||
structuredOutput: {
|
||||
hasSummary: agentContents.every(c => c.includes("Summary:")),
|
||||
hasDeliverables: agentContents.every(c => c.includes("Deliverables") || c.includes("Findings")),
|
||||
description: "All agents produce structured output template"
|
||||
},
|
||||
|
||||
// No Claude patterns: no Task(), no TaskOutput(), no resume
|
||||
noClaudePatterns: {
|
||||
noTask: !orchestratorContent.includes("Task("),
|
||||
noTaskOutput: !orchestratorContent.includes("TaskOutput("),
|
||||
noResume: !orchestratorContent.includes("resume:") && !orchestratorContent.includes("resume ="),
|
||||
description: "No Claude-specific patterns remain"
|
||||
}
|
||||
}
|
||||
|
||||
const patternScore = calculatePatternScore(patternChecks)
|
||||
```
|
||||
|
||||
### Step 4.3: Content Quality Check
|
||||
|
||||
```javascript
|
||||
const qualityChecks = {
|
||||
// Orchestrator quality
|
||||
orchestratorQuality: {
|
||||
hasDescription: orchestratorContent.length > 500,
|
||||
hasCodeBlocks: countPattern(orchestratorContent, /```/g) >= 4,
|
||||
hasErrorHandling: orchestratorContent.includes("Error") || orchestratorContent.includes("error"),
|
||||
noPlaceholders: !orchestratorContent.includes("{{") || !orchestratorContent.includes("TODO"),
|
||||
description: "Orchestrator is complete and production-ready"
|
||||
},
|
||||
|
||||
// Agent quality
|
||||
agentQuality: agentContents.map(content => ({
|
||||
hasSubstantiveContent: content.length > 300,
|
||||
hasActionableSteps: countPattern(content, /Step \d/g) >= 2,
|
||||
hasOutputFormat: content.includes("Output") || content.includes("Deliverables"),
|
||||
noPlaceholders: !content.includes("{{") || !content.includes("TODO")
|
||||
})),
|
||||
|
||||
// Conversion quality (if applicable)
|
||||
conversionQuality: codexSkillConfig.conversionSource ? {
|
||||
allTasksConverted: true, // verify all Claude Task() calls are mapped
|
||||
noLostFunctionality: true, // verify no features dropped
|
||||
interactionPreserved: true // verify resume → send_input mapping
|
||||
} : null
|
||||
}
|
||||
|
||||
const qualityScore = calculateQualityScore(qualityChecks)
|
||||
```
|
||||
|
||||
### Step 4.4: Quality Gate
|
||||
|
||||
```javascript
|
||||
const overallScore = (
|
||||
structuralScore * 0.30 +
|
||||
patternScore * 0.40 +
|
||||
qualityScore * 0.30
|
||||
)
|
||||
|
||||
const verdict = overallScore >= 80 ? "PASS" :
|
||||
overallScore >= 60 ? "REVIEW" : "FAIL"
|
||||
```
|
||||
|
||||
| Verdict | Score | Action |
|
||||
|---------|-------|--------|
|
||||
| **PASS** | >= 80% | Deliver to target location |
|
||||
| **REVIEW** | 60-79% | Report issues, ask user to proceed or fix |
|
||||
| **FAIL** | < 60% | Block delivery, list critical issues |
|
||||
|
||||
### Step 4.5: Validation Report
|
||||
|
||||
```javascript
|
||||
const validationReport = {
|
||||
skill: codexSkillConfig.name,
|
||||
outputMode: codexSkillConfig.outputMode,
|
||||
scores: {
|
||||
structural: structuralScore,
|
||||
pattern: patternScore,
|
||||
quality: qualityScore,
|
||||
overall: overallScore
|
||||
},
|
||||
verdict: verdict,
|
||||
issues: collectIssues(structuralChecks, patternChecks, qualityChecks),
|
||||
generatedFiles: generatedFiles,
|
||||
deploymentMap: deploymentMap
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4.6: Delivery
|
||||
|
||||
If verdict is PASS or user approves REVIEW:
|
||||
|
||||
```javascript
|
||||
// For structured mode — files already in .codex/skills/{name}/
|
||||
// Report deployment instructions for agent files
|
||||
|
||||
const deploymentInstructions = `
|
||||
## Deployment Instructions
|
||||
|
||||
### Generated Files
|
||||
${generatedFiles.orchestrator}
|
||||
${generatedFiles.agents.join('\n')}
|
||||
${generatedFiles.phases?.join('\n') || '(no phase files)'}
|
||||
|
||||
### Agent Deployment
|
||||
${deploymentMap.new.map(a =>
|
||||
`Copy: ${a.sourcePath} → ${a.targetPath}`
|
||||
).join('\n')}
|
||||
|
||||
### Existing Agents (no action needed)
|
||||
${deploymentMap.existing.map(a =>
|
||||
`✓ ${a.name}: ${a.path}`
|
||||
).join('\n')}
|
||||
|
||||
### Usage
|
||||
Invoke the generated orchestrator via Codex:
|
||||
- Read the orchestrator.md and follow its phase execution
|
||||
- Or register as a Codex prompt in ~/.codex/prompts/
|
||||
|
||||
### Validation Score
|
||||
Overall: ${overallScore}% (${verdict})
|
||||
- Structural: ${structuralScore}%
|
||||
- Pattern Compliance: ${patternScore}%
|
||||
- Content Quality: ${qualityScore}%
|
||||
`
|
||||
```
|
||||
|
||||
### Step 4.7: Final Summary to User
|
||||
|
||||
Present:
|
||||
1. Generated file list with paths
|
||||
2. Validation scores
|
||||
3. Deployment instructions
|
||||
4. Any issues or warnings
|
||||
5. Next steps (e.g., "test the skill by running the orchestrator")
|
||||
|
||||
## Output
|
||||
|
||||
- **Report**: Validation report with scores
|
||||
- **Deployment**: Instructions for agent file deployment
|
||||
- **TodoWrite**: Mark Phase 4 completed
|
||||
|
||||
## Completion
|
||||
|
||||
Skill package generation complete. All files written and validated.
|
||||
Reference in New Issue
Block a user