mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 12:13:51 +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,406 @@
|
||||
# Codex Agent Patterns
|
||||
|
||||
Core Codex subagent API patterns reference for skill generation.
|
||||
|
||||
## Purpose
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 0 | Read to understand available Codex patterns |
|
||||
| Phase 2 | Reference when generating orchestrator patterns |
|
||||
| Phase 3 | Reference when designing agent interactions |
|
||||
|
||||
---
|
||||
|
||||
## 1. API Reference
|
||||
|
||||
### 1.1 spawn_agent
|
||||
|
||||
Creates a new subagent with independent context.
|
||||
|
||||
```javascript
|
||||
const agentId = spawn_agent({
|
||||
message: "task message", // Required: task assignment
|
||||
agent_type: "type" // Optional: preset baseline
|
||||
})
|
||||
// Returns: agent_id (string)
|
||||
```
|
||||
|
||||
**Key Facts**:
|
||||
- Each agent has isolated context (no shared state)
|
||||
- `agent_type` selects preset behavior baseline
|
||||
- Role definition must be loaded via MANDATORY FIRST STEPS
|
||||
- Returns immediately — use `wait()` for results
|
||||
|
||||
### 1.2 wait
|
||||
|
||||
Retrieves results from one or more agents.
|
||||
|
||||
```javascript
|
||||
const result = wait({
|
||||
ids: [agentId1, agentId2], // Required: agent IDs to wait for
|
||||
timeout_ms: 300000 // Optional: max wait time (ms)
|
||||
})
|
||||
// Returns: { timed_out: boolean, status: { [id]: { completed: string } } }
|
||||
```
|
||||
|
||||
**Key Facts**:
|
||||
- Primary result retrieval method (NOT close_agent)
|
||||
- Supports batch wait for multiple agents
|
||||
- `timed_out: true` means some agents haven't finished — can re-wait
|
||||
- Can be called multiple times on same agent
|
||||
|
||||
### 1.3 send_input
|
||||
|
||||
Continues interaction with an active agent.
|
||||
|
||||
```javascript
|
||||
send_input({
|
||||
id: agentId, // Required: target agent
|
||||
message: "follow-up", // Required: continuation message
|
||||
interrupt: false // Optional: interrupt current processing
|
||||
})
|
||||
```
|
||||
|
||||
**Key Facts**:
|
||||
- Agent must NOT be closed
|
||||
- Preserves full conversation context
|
||||
- Use for: clarification answers, phase transitions, iterative refinement
|
||||
- `interrupt: true` — use with caution (stops current processing)
|
||||
|
||||
### 1.4 close_agent
|
||||
|
||||
Permanently terminates an agent.
|
||||
|
||||
```javascript
|
||||
close_agent({ id: agentId })
|
||||
```
|
||||
|
||||
**Key Facts**:
|
||||
- Irreversible — no further wait/send_input possible
|
||||
- Do NOT use to retrieve results (use wait instead)
|
||||
- Delay until certain no more interaction needed
|
||||
- Call for ALL agents at end of workflow (cleanup)
|
||||
|
||||
## 2. Interaction Patterns
|
||||
|
||||
### 2.1 Standard (Single Agent, Single Task)
|
||||
|
||||
```
|
||||
spawn_agent → wait → close_agent
|
||||
```
|
||||
|
||||
**Use When**: Simple, one-shot tasks with clear deliverables.
|
||||
|
||||
```javascript
|
||||
const agent = spawn_agent({ message: taskPrompt })
|
||||
const result = wait({ ids: [agent], timeout_ms: 300000 })
|
||||
close_agent({ id: agent })
|
||||
```
|
||||
|
||||
### 2.2 Parallel Fan-out (Multiple Independent Agents)
|
||||
|
||||
```
|
||||
spawn_agent × N → batch wait({ ids: [...] }) → close_agent × N
|
||||
```
|
||||
|
||||
**Use When**: Multiple independent tasks that can run concurrently.
|
||||
|
||||
```javascript
|
||||
const agents = tasks.map(t => spawn_agent({ message: buildPrompt(t) }))
|
||||
const results = wait({ ids: agents, timeout_ms: 600000 })
|
||||
// Aggregate results
|
||||
const merged = agents.map(id => results.status[id].completed)
|
||||
// Cleanup all
|
||||
agents.forEach(id => close_agent({ id }))
|
||||
```
|
||||
|
||||
**Split Strategies**:
|
||||
|
||||
| Strategy | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| By responsibility | Each agent has different role | Research / Plan / Test |
|
||||
| By module | Each agent handles different code area | auth / api / database |
|
||||
| By perspective | Each agent analyzes from different angle | security / performance / maintainability |
|
||||
|
||||
### 2.3 Deep Interaction (Multi-round with send_input)
|
||||
|
||||
```
|
||||
spawn_agent → wait (round 1) → send_input → wait (round 2) → ... → close_agent
|
||||
```
|
||||
|
||||
**Use When**: Tasks needing iterative refinement or multi-phase execution within single agent context.
|
||||
|
||||
```javascript
|
||||
const agent = spawn_agent({ message: initialPrompt })
|
||||
|
||||
// Round 1
|
||||
const r1 = wait({ ids: [agent], timeout_ms: 300000 })
|
||||
|
||||
// Round 2 (refine based on r1)
|
||||
send_input({ id: agent, message: refinementPrompt })
|
||||
const r2 = wait({ ids: [agent], timeout_ms: 300000 })
|
||||
|
||||
// Round 3 (finalize)
|
||||
send_input({ id: agent, message: finalizationPrompt })
|
||||
const r3 = wait({ ids: [agent], timeout_ms: 300000 })
|
||||
|
||||
close_agent({ id: agent })
|
||||
```
|
||||
|
||||
### 2.4 Two-Phase (Clarify → Execute)
|
||||
|
||||
```
|
||||
spawn_agent → wait (questions) → send_input (answers) → wait (solution) → close_agent
|
||||
```
|
||||
|
||||
**Use When**: Complex tasks where requirements need clarification before execution.
|
||||
|
||||
```javascript
|
||||
const agent = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
...
|
||||
### Phase A: Exploration & Clarification
|
||||
Output findings + Open Questions (CLARIFICATION_NEEDED format)
|
||||
|
||||
### Phase B: Full Solution (after receiving answers)
|
||||
Output complete deliverable
|
||||
`
|
||||
})
|
||||
|
||||
// Phase A
|
||||
const exploration = wait({ ids: [agent], timeout_ms: 600000 })
|
||||
|
||||
if (exploration.status[agent].completed.includes('CLARIFICATION_NEEDED')) {
|
||||
// Collect answers
|
||||
const answers = getUserAnswers(exploration)
|
||||
|
||||
// Phase B
|
||||
send_input({
|
||||
id: agent,
|
||||
message: `## CLARIFICATION ANSWERS\n${answers}\n\n## PROCEED\nGenerate full solution.`
|
||||
})
|
||||
const solution = wait({ ids: [agent], timeout_ms: 900000 })
|
||||
}
|
||||
|
||||
close_agent({ id: agent })
|
||||
```
|
||||
|
||||
### 2.5 Pipeline (Sequential Agent Chain)
|
||||
|
||||
```
|
||||
spawn(A) → wait(A) → close(A) → spawn(B, with A's output) → wait(B) → close(B)
|
||||
```
|
||||
|
||||
**Use When**: Tasks where each stage depends on the previous stage's output.
|
||||
|
||||
```javascript
|
||||
// Stage 1: Research
|
||||
const researcher = spawn_agent({ message: researchPrompt })
|
||||
const research = wait({ ids: [researcher] })
|
||||
close_agent({ id: researcher })
|
||||
|
||||
// Stage 2: Plan (uses research output)
|
||||
const planner = spawn_agent({
|
||||
message: `${planPrompt}\n\n## RESEARCH CONTEXT\n${research.status[researcher].completed}`
|
||||
})
|
||||
const plan = wait({ ids: [planner] })
|
||||
close_agent({ id: planner })
|
||||
|
||||
// Stage 3: Execute (uses plan output)
|
||||
const executor = spawn_agent({
|
||||
message: `${executePrompt}\n\n## PLAN\n${plan.status[planner].completed}`
|
||||
})
|
||||
const execution = wait({ ids: [executor] })
|
||||
close_agent({ id: executor })
|
||||
```
|
||||
|
||||
### 2.6 Merged Exploration (Explore + Clarify + Plan in Single Agent)
|
||||
|
||||
```
|
||||
spawn(dual-role) → wait(explore) → send_input(clarify) → wait(plan) → close
|
||||
```
|
||||
|
||||
**Use When**: Exploration and planning are tightly coupled and benefit from shared context.
|
||||
|
||||
**Advantages over Pipeline**:
|
||||
- 60-80% fewer agent creations
|
||||
- No context loss between phases
|
||||
- Higher result consistency
|
||||
|
||||
```javascript
|
||||
const agent = spawn_agent({
|
||||
message: `
|
||||
## DUAL ROLE ASSIGNMENT
|
||||
|
||||
### Role A: Explorer
|
||||
Explore codebase, identify patterns, generate questions
|
||||
|
||||
### Role B: Planner (activated after clarification)
|
||||
Generate implementation plan based on exploration + answers
|
||||
|
||||
### Phase 1: Explore
|
||||
Output: Findings + CLARIFICATION_NEEDED questions
|
||||
|
||||
### Phase 2: Plan (triggered by send_input)
|
||||
Output: plan.json
|
||||
`
|
||||
})
|
||||
|
||||
const explore = wait({ ids: [agent] })
|
||||
// ... handle clarification ...
|
||||
send_input({ id: agent, message: answers })
|
||||
const plan = wait({ ids: [agent] })
|
||||
close_agent({ id: agent })
|
||||
```
|
||||
|
||||
## 3. Message Design
|
||||
|
||||
### 3.1 TASK ASSIGNMENT Structure
|
||||
|
||||
```text
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
Goal: One-sentence objective
|
||||
|
||||
Scope:
|
||||
- Include: allowed operations
|
||||
- Exclude: forbidden operations
|
||||
- Directory: target paths
|
||||
- Dependencies: dependency constraints
|
||||
|
||||
Context:
|
||||
- Key paths: relevant file paths
|
||||
- Current state: system status
|
||||
- Constraints: must-follow rules
|
||||
|
||||
Deliverables:
|
||||
- Output structured following template
|
||||
|
||||
Quality bar:
|
||||
- Criterion 1
|
||||
- Criterion 2
|
||||
```
|
||||
|
||||
### 3.2 Structured Output Template
|
||||
|
||||
```text
|
||||
Summary:
|
||||
- One-sentence completion status
|
||||
|
||||
Findings:
|
||||
- Finding 1: description
|
||||
- Finding 2: description
|
||||
|
||||
Proposed changes:
|
||||
- File: path/to/file
|
||||
- Change: modification detail
|
||||
- Risk: impact assessment
|
||||
|
||||
Tests:
|
||||
- Test cases needed
|
||||
- Commands to run
|
||||
|
||||
Open questions:
|
||||
1. Unresolved question 1
|
||||
2. Unresolved question 2
|
||||
```
|
||||
|
||||
### 3.3 Clarification Format
|
||||
|
||||
```text
|
||||
CLARIFICATION_NEEDED:
|
||||
Q1: [question] | Options: [A, B, C] | Recommended: [A]
|
||||
Q2: [question] | Options: [A, B] | Recommended: [B]
|
||||
```
|
||||
|
||||
## 4. Error Handling
|
||||
|
||||
### 4.1 Timeout
|
||||
|
||||
```javascript
|
||||
const result = wait({ ids: [agent], timeout_ms: 30000 })
|
||||
if (result.timed_out) {
|
||||
// Option 1: Continue waiting
|
||||
const retry = wait({ ids: [agent], timeout_ms: 60000 })
|
||||
|
||||
// Option 2: Urge convergence
|
||||
send_input({ id: agent, message: "Please wrap up and output current findings." })
|
||||
const urged = wait({ ids: [agent], timeout_ms: 30000 })
|
||||
|
||||
// Option 3: Abort
|
||||
close_agent({ id: agent })
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Agent Recovery (post close_agent)
|
||||
|
||||
```javascript
|
||||
// Cannot recover closed agent — must recreate
|
||||
const newAgent = spawn_agent({
|
||||
message: `${originalPrompt}\n\n## PREVIOUS ATTEMPT OUTPUT\n${previousOutput}`
|
||||
})
|
||||
```
|
||||
|
||||
### 4.3 Partial Results (parallel fan-out)
|
||||
|
||||
```javascript
|
||||
const results = wait({ ids: agents, timeout_ms: 300000 })
|
||||
const completed = agents.filter(id => results.status[id]?.completed)
|
||||
const pending = agents.filter(id => !results.status[id]?.completed)
|
||||
|
||||
if (completed.length >= Math.ceil(agents.length * 0.7)) {
|
||||
// 70%+ complete — proceed with partial results
|
||||
pending.forEach(id => close_agent({ id }))
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Role Loading
|
||||
|
||||
### 5.1 Path Reference Pattern (Recommended)
|
||||
|
||||
```javascript
|
||||
spawn_agent({
|
||||
message: `
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/${agentType}.md (MUST read first)
|
||||
...
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Why**: Keeps message lean, agent loads its own role context.
|
||||
|
||||
### 5.2 Role Mapping
|
||||
|
||||
| Agent Type | Role File |
|
||||
|------------|-----------|
|
||||
| cli-explore-agent | ~/.codex/agents/cli-explore-agent.md |
|
||||
| cli-lite-planning-agent | ~/.codex/agents/cli-lite-planning-agent.md |
|
||||
| code-developer | ~/.codex/agents/code-developer.md |
|
||||
| context-search-agent | ~/.codex/agents/context-search-agent.md |
|
||||
| debug-explore-agent | ~/.codex/agents/debug-explore-agent.md |
|
||||
| doc-generator | ~/.codex/agents/doc-generator.md |
|
||||
| action-planning-agent | ~/.codex/agents/action-planning-agent.md |
|
||||
| test-fix-agent | ~/.codex/agents/test-fix-agent.md |
|
||||
| universal-executor | ~/.codex/agents/universal-executor.md |
|
||||
| tdd-developer | ~/.codex/agents/tdd-developer.md |
|
||||
| ui-design-agent | ~/.codex/agents/ui-design-agent.md |
|
||||
|
||||
## 6. Design Principles
|
||||
|
||||
1. **Delay close_agent**: Only close when certain no more interaction needed
|
||||
2. **Batch wait over sequential**: Use `wait({ ids: [...] })` for parallel agents
|
||||
3. **Merge phases when context-dependent**: Use send_input over new agents
|
||||
4. **Structured output always**: Enforce uniform output template
|
||||
5. **Minimal message size**: Pass role file paths, not inline content
|
||||
6. **Explicit lifecycle**: Every spawn must have a close (balanced)
|
||||
7. **Timeout handling**: Always specify timeout_ms, always handle timed_out
|
||||
228
.claude/skills/codex-skill-designer/specs/conversion-rules.md
Normal file
228
.claude/skills/codex-skill-designer/specs/conversion-rules.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Claude → Codex Conversion Rules
|
||||
|
||||
Comprehensive mapping rules for converting Claude Code skills to Codex-native skills.
|
||||
|
||||
## Purpose
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 1 | Reference when analyzing Claude source skill |
|
||||
| Phase 2 | Apply when generating Codex orchestrator |
|
||||
| Phase 3 | Apply when converting agent definitions |
|
||||
|
||||
---
|
||||
|
||||
## 1. API Mapping
|
||||
|
||||
### 1.1 Core API Conversion
|
||||
|
||||
| Claude Pattern | Codex Equivalent | Notes |
|
||||
|----------------|-----------------|-------|
|
||||
| `Task({ subagent_type, prompt })` | `spawn_agent({ message })` + `wait()` | Split create and result retrieval |
|
||||
| `Task({ run_in_background: false })` | `spawn_agent()` + immediate `wait()` | Synchronous equivalent |
|
||||
| `Task({ run_in_background: true })` | `spawn_agent()` (wait later) | Deferred wait |
|
||||
| `Task({ resume: agentId })` | `send_input({ id: agentId })` | Agent must not be closed |
|
||||
| `TaskOutput({ task_id, block: true })` | `wait({ ids: [id] })` | Blocking wait |
|
||||
| `TaskOutput({ task_id, block: false })` | `wait({ ids: [id], timeout_ms: 1000 })` | Polling with short timeout |
|
||||
| Agent auto-cleanup | `close_agent({ id })` | Must be explicit |
|
||||
|
||||
### 1.2 Parallel Task Conversion
|
||||
|
||||
**Claude**:
|
||||
```javascript
|
||||
// Multiple Task() calls in single message (parallel)
|
||||
const result1 = Task({ subagent_type: "agent-a", prompt: promptA })
|
||||
const result2 = Task({ subagent_type: "agent-b", prompt: promptB })
|
||||
const result3 = Task({ subagent_type: "agent-c", prompt: promptC })
|
||||
```
|
||||
|
||||
**Codex**:
|
||||
```javascript
|
||||
// Explicit parallel: spawn all, then batch wait
|
||||
const idA = spawn_agent({ message: promptA_with_role })
|
||||
const idB = spawn_agent({ message: promptB_with_role })
|
||||
const idC = spawn_agent({ message: promptC_with_role })
|
||||
|
||||
const results = wait({ ids: [idA, idB, idC], timeout_ms: 600000 })
|
||||
|
||||
// Process results
|
||||
const resultA = results.status[idA].completed
|
||||
const resultB = results.status[idB].completed
|
||||
const resultC = results.status[idC].completed
|
||||
|
||||
// Cleanup
|
||||
;[idA, idB, idC].forEach(id => close_agent({ id }))
|
||||
```
|
||||
|
||||
### 1.3 Resume/Continue Conversion
|
||||
|
||||
**Claude**:
|
||||
```javascript
|
||||
// Resume a previous agent
|
||||
Task({ subagent_type: "agent-a", resume: previousAgentId, prompt: "Continue..." })
|
||||
```
|
||||
|
||||
**Codex**:
|
||||
```javascript
|
||||
// send_input to continue (agent must still be alive)
|
||||
send_input({
|
||||
id: previousAgentId,
|
||||
message: "Continue..."
|
||||
})
|
||||
const continued = wait({ ids: [previousAgentId] })
|
||||
```
|
||||
|
||||
### 1.4 TaskOutput Polling Conversion
|
||||
|
||||
**Claude**:
|
||||
```javascript
|
||||
while (!done) {
|
||||
const output = TaskOutput({ task_id: id, block: false })
|
||||
if (output.status === 'completed') done = true
|
||||
sleep(1000)
|
||||
}
|
||||
```
|
||||
|
||||
**Codex**:
|
||||
```javascript
|
||||
let result = wait({ ids: [id], timeout_ms: 30000 })
|
||||
while (result.timed_out) {
|
||||
result = wait({ ids: [id], timeout_ms: 30000 })
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Role Loading Conversion
|
||||
|
||||
### 2.1 subagent_type → MANDATORY FIRST STEPS
|
||||
|
||||
**Claude**: Role automatically loaded via `subagent_type` parameter.
|
||||
|
||||
**Codex**: Role must be explicitly loaded by agent as first action.
|
||||
|
||||
**Conversion**:
|
||||
```javascript
|
||||
// Claude
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: "Explore the codebase for authentication patterns"
|
||||
})
|
||||
|
||||
// Codex
|
||||
spawn_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
|
||||
|
||||
---
|
||||
|
||||
Goal: Explore the codebase for authentication patterns
|
||||
Deliverables: Structured findings following output template
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### 2.2 Role Mapping Table
|
||||
|
||||
| Claude subagent_type | Codex Role Path |
|
||||
|----------------------|-----------------|
|
||||
| `Explore` | `~/.codex/agents/cli-explore-agent.md` |
|
||||
| `Plan` | `~/.codex/agents/cli-lite-planning-agent.md` |
|
||||
| `code-developer` | `~/.codex/agents/code-developer.md` |
|
||||
| `context-search-agent` | `~/.codex/agents/context-search-agent.md` |
|
||||
| `debug-explore-agent` | `~/.codex/agents/debug-explore-agent.md` |
|
||||
| `doc-generator` | `~/.codex/agents/doc-generator.md` |
|
||||
| `action-planning-agent` | `~/.codex/agents/action-planning-agent.md` |
|
||||
| `test-fix-agent` | `~/.codex/agents/test-fix-agent.md` |
|
||||
| `universal-executor` | `~/.codex/agents/universal-executor.md` |
|
||||
| `tdd-developer` | `~/.codex/agents/tdd-developer.md` |
|
||||
| `general-purpose` | `~/.codex/agents/universal-executor.md` |
|
||||
| `Bash` | Direct shell execution (no agent needed) |
|
||||
| `haiku` / `sonnet` / `opus` | Model selection via agent_type parameter |
|
||||
|
||||
## 3. Structural Conversion
|
||||
|
||||
### 3.1 SKILL.md → orchestrator.md
|
||||
|
||||
| Claude SKILL.md Section | Codex orchestrator.md Section |
|
||||
|--------------------------|-------------------------------|
|
||||
| Frontmatter (name, description, allowed-tools) | Frontmatter (name, description, agents, phases) |
|
||||
| Architecture Overview | Architecture Overview (spawn/wait/close flow) |
|
||||
| Execution Flow (Ref: markers) | Phase Execution (spawn_agent code blocks) |
|
||||
| Data Flow (variables, files) | Data Flow (wait results, context passing) |
|
||||
| TodoWrite Pattern | update_plan tracking (Codex convention) |
|
||||
| Interactive Preference Collection | User interaction via orchestrator prompts |
|
||||
| Error Handling | Timeout + Lifecycle error handling |
|
||||
| Phase Reference Documents table | Agent Registry + Phase detail files |
|
||||
|
||||
### 3.2 Phase Files → Phase Detail or Inline
|
||||
|
||||
**Simple phases** (single agent, no branching): Inline in orchestrator.md
|
||||
|
||||
**Complex phases** (multi-agent, conditional): Separate `phases/0N-{name}.md`
|
||||
|
||||
### 3.3 Pattern-Level Conversion
|
||||
|
||||
| Claude Pattern | Codex Pattern |
|
||||
|----------------|---------------|
|
||||
| Orchestrator + Progressive Loading | Orchestrator + Agent Registry + on-demand phase loading |
|
||||
| TodoWrite Attachment/Collapse | update_plan pending → in_progress → completed |
|
||||
| Inter-Phase Data Flow (variables) | wait() result passing between phases |
|
||||
| Conditional Phase Execution | if/else on wait() results |
|
||||
| Direct Phase Handoff (Read phase doc) | Inline execution or separate phase files |
|
||||
| AskUserQuestion | Direct user interaction in orchestrator |
|
||||
|
||||
## 4. Content Preservation Rules
|
||||
|
||||
When converting Claude skills:
|
||||
|
||||
1. **Agent prompts**: Preserve task descriptions, goals, scope, deliverables VERBATIM
|
||||
2. **Bash commands**: Preserve all shell commands unchanged
|
||||
3. **Code blocks**: Preserve implementation code unchanged
|
||||
4. **Validation logic**: Preserve quality checks and success criteria
|
||||
5. **Error handling**: Convert to Codex timeout/lifecycle patterns, preserve intent
|
||||
|
||||
**Transform** (structure changes):
|
||||
- `Task()` calls → `spawn_agent()` + `wait()` + `close_agent()`
|
||||
- `subagent_type` → MANDATORY FIRST STEPS role path
|
||||
- Synchronous returns → Explicit `wait()` calls
|
||||
- Auto-cleanup → Explicit `close_agent()` calls
|
||||
|
||||
**Preserve** (content unchanged):
|
||||
- Task descriptions and goals
|
||||
- Scope definitions
|
||||
- Quality criteria
|
||||
- File paths and patterns
|
||||
- Shell commands
|
||||
- Business logic
|
||||
|
||||
## 5. Anti-Patterns to Avoid
|
||||
|
||||
| Anti-Pattern | Why | Correct Pattern |
|
||||
|-------------|-----|-----------------|
|
||||
| Using close_agent for results | Returns are unreliable | Use wait() for results |
|
||||
| Inline role content in message | Bloats message, wastes tokens | Pass role file path in MANDATORY FIRST STEPS |
|
||||
| Early close_agent before potential follow-up | Cannot resume closed agent | Delay close until certain no more interaction |
|
||||
| Sequential wait for parallel agents | Wasted time | Batch wait({ ids: [...] }) |
|
||||
| No timeout_ms | Indefinite hang risk | Always specify timeout_ms |
|
||||
| No timed_out handling | Silent failures | Always check result.timed_out |
|
||||
| Claude Task() remaining in output | Runtime incompatibility | Convert all Task() to spawn_agent |
|
||||
| Claude resume: in output | Runtime incompatibility | Convert to send_input() |
|
||||
|
||||
## 6. Conversion Checklist
|
||||
|
||||
Before delivering converted skill:
|
||||
|
||||
- [ ] All `Task()` calls converted to `spawn_agent()` + `wait()` + `close_agent()`
|
||||
- [ ] All `subagent_type` mapped to MANDATORY FIRST STEPS role paths
|
||||
- [ ] All `resume` converted to `send_input()`
|
||||
- [ ] All `TaskOutput` polling converted to `wait()` with timeout
|
||||
- [ ] No Claude-specific patterns remain (Task, TaskOutput, resume, subagent_type)
|
||||
- [ ] Timeout handling added for all `wait()` calls
|
||||
- [ ] Lifecycle balanced (spawn count ≤ close count)
|
||||
- [ ] Structured output template enforced for all agents
|
||||
- [ ] Agent prompts/goals/scope preserved verbatim
|
||||
- [ ] Error handling converted to Codex patterns
|
||||
163
.claude/skills/codex-skill-designer/specs/quality-standards.md
Normal file
163
.claude/skills/codex-skill-designer/specs/quality-standards.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# Quality Standards
|
||||
|
||||
Quality criteria and validation gates for generated Codex skills.
|
||||
|
||||
## Purpose
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 3 | Reference during generation |
|
||||
| Phase 4 | Apply during validation |
|
||||
|
||||
---
|
||||
|
||||
## 1. Quality Dimensions
|
||||
|
||||
### 1.1 Structural Completeness (30%)
|
||||
|
||||
| Check | Weight | Criteria |
|
||||
|-------|--------|----------|
|
||||
| Orchestrator exists | 5 | File present at expected path |
|
||||
| Frontmatter valid | 3 | Contains name, description |
|
||||
| Architecture diagram | 3 | ASCII flow showing spawn/wait/close |
|
||||
| Agent Registry | 4 | Table with all agents, role paths, responsibilities |
|
||||
| Phase Execution blocks | 5 | Code blocks for each phase with spawn/wait/close |
|
||||
| Lifecycle Management | 5 | Timeout handling + cleanup protocol |
|
||||
| Agent files complete | 5 | All new agent roles have complete role files |
|
||||
|
||||
**Scoring**: Each check passes (full weight) or fails (0). Total = sum / max.
|
||||
|
||||
### 1.2 Pattern Compliance (40%)
|
||||
|
||||
| Check | Weight | Criteria |
|
||||
|-------|--------|----------|
|
||||
| Lifecycle balanced | 6 | Every spawn_agent has matching close_agent |
|
||||
| Role loading correct | 6 | MANDATORY FIRST STEPS pattern used (not inline content) |
|
||||
| Wait for results | 5 | wait() used for results (not close_agent) |
|
||||
| Batch wait for parallel | 5 | Parallel agents use wait({ ids: [...] }) |
|
||||
| Timeout specified | 4 | All wait() calls have timeout_ms |
|
||||
| Timeout handled | 4 | timed_out checked after every wait() |
|
||||
| Structured output | 5 | Agents produce Summary/Findings/Changes/Tests/Questions |
|
||||
| No Claude patterns | 5 | No Task(), TaskOutput(), resume: remaining |
|
||||
|
||||
**Scoring**: Each check passes (full weight) or fails (0). Total = sum / max.
|
||||
|
||||
### 1.3 Content Quality (30%)
|
||||
|
||||
| Check | Weight | Criteria |
|
||||
|-------|--------|----------|
|
||||
| Orchestrator substantive | 4 | Content > 500 chars, not boilerplate |
|
||||
| Code blocks present | 3 | >= 4 code blocks with executable patterns |
|
||||
| Error handling | 3 | Timeout + recovery + partial results handling |
|
||||
| No placeholders | 4 | No `{{...}}` or `TODO` remaining in output |
|
||||
| Agent roles substantive | 4 | Each agent role > 300 chars with actionable steps |
|
||||
| Output format defined | 3 | Structured output template in each agent |
|
||||
| Goals/scope clear | 4 | Every spawn_agent has Goal + Scope + Deliverables |
|
||||
| Conversion faithful | 5 | Source content preserved (if converting) |
|
||||
|
||||
**Scoring**: Each check passes (full weight) or fails (0). Total = sum / max.
|
||||
|
||||
## 2. Quality Gates
|
||||
|
||||
| Verdict | Score | Action |
|
||||
|---------|-------|--------|
|
||||
| **PASS** | >= 80% | Deliver to target location |
|
||||
| **REVIEW** | 60-79% | Report issues, user decides |
|
||||
| **FAIL** | < 60% | Block delivery, list critical issues |
|
||||
|
||||
### 2.1 Critical Failures (Auto-FAIL)
|
||||
|
||||
These issues force FAIL regardless of overall score:
|
||||
|
||||
1. **No orchestrator file** — skill has no entry point
|
||||
2. **Task() calls in output** — runtime incompatible with Codex
|
||||
3. **No agent registry** — agents cannot be identified
|
||||
4. **Missing close_agent** — resource leak risk
|
||||
5. **Inline role content** — violates Codex pattern (message bloat)
|
||||
|
||||
### 2.2 Warnings (Non-blocking)
|
||||
|
||||
1. **Missing timeout handling** — degraded reliability
|
||||
2. **No error handling section** — reduced robustness
|
||||
3. **Placeholder text remaining** — needs manual completion
|
||||
4. **Phase files missing** — acceptable for simple skills
|
||||
|
||||
## 3. Validation Process
|
||||
|
||||
### 3.1 Automated Checks
|
||||
|
||||
```javascript
|
||||
function validateSkill(generatedFiles, codexSkillConfig) {
|
||||
const checks = []
|
||||
|
||||
// Structural
|
||||
checks.push(checkFileExists(generatedFiles.orchestrator))
|
||||
checks.push(checkFrontmatter(generatedFiles.orchestrator))
|
||||
checks.push(checkSection(generatedFiles.orchestrator, "Architecture"))
|
||||
checks.push(checkSection(generatedFiles.orchestrator, "Agent Registry"))
|
||||
// ...
|
||||
|
||||
// Pattern compliance
|
||||
const content = Read(generatedFiles.orchestrator)
|
||||
checks.push(checkBalancedLifecycle(content))
|
||||
checks.push(checkRoleLoading(content))
|
||||
checks.push(checkWaitPattern(content))
|
||||
// ...
|
||||
|
||||
// Content quality
|
||||
checks.push(checkNoPlaceholders(content))
|
||||
checks.push(checkSubstantiveContent(content))
|
||||
// ...
|
||||
|
||||
// Critical failures
|
||||
const criticals = checkCriticalFailures(content, generatedFiles)
|
||||
if (criticals.length > 0) return { verdict: "FAIL", criticals }
|
||||
|
||||
// Score
|
||||
const score = calculateWeightedScore(checks)
|
||||
const verdict = score >= 80 ? "PASS" : score >= 60 ? "REVIEW" : "FAIL"
|
||||
|
||||
return { score, verdict, checks, issues: checks.filter(c => !c.passed) }
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Manual Review Points
|
||||
|
||||
For REVIEW verdict, highlight these for user attention:
|
||||
|
||||
1. Agent role completeness — are all capabilities covered?
|
||||
2. Interaction model appropriateness — right pattern for use case?
|
||||
3. Timeout values — appropriate for expected task duration?
|
||||
4. Scope definitions — clear boundaries for each agent?
|
||||
5. Output format — suitable for downstream consumers?
|
||||
|
||||
## 4. Scoring Formula
|
||||
|
||||
```
|
||||
Overall = Structural × 0.30 + PatternCompliance × 0.40 + ContentQuality × 0.30
|
||||
```
|
||||
|
||||
Pattern compliance weighted highest because Codex runtime correctness is critical.
|
||||
|
||||
## 5. Quality Improvement Guidance
|
||||
|
||||
### Low Structural Score
|
||||
|
||||
- Add missing sections to orchestrator
|
||||
- Create missing agent role files
|
||||
- Add frontmatter to all files
|
||||
|
||||
### Low Pattern Score
|
||||
|
||||
- Add MANDATORY FIRST STEPS to all spawn_agent messages
|
||||
- Replace inline role content with path references
|
||||
- Add close_agent for every spawn_agent
|
||||
- Add timeout_ms and timed_out handling to all wait calls
|
||||
- Remove any remaining Claude patterns
|
||||
|
||||
### Low Content Score
|
||||
|
||||
- Expand agent role definitions with more specific steps
|
||||
- Add concrete Goal/Scope/Deliverables to spawn messages
|
||||
- Replace placeholders with actual content
|
||||
- Add error handling for each phase
|
||||
Reference in New Issue
Block a user