catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor: team-planex dual-version optimization with v5 architecture

Browse Source 
Claude version: add coordinator role with Spawn-and-Stop beat model,
replace role-routed planner/executor with team-worker agents using
lightweight role-specs (~80-110 lines each).

Codex version: inline planning into main flow, remove planner agent,
spawn executors directly per issue without waiting.

Both versions preserve 3 input types (Issue IDs / --text / --plan).
This commit is contained in:
catlog22
2026-02-28 15:31:03 +08:00
parent d14a710797
commit 3788ba1268
11 changed files with 925 additions and 1330 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
.codex/skills/team-planex/SKILL.md
View File

@@ -1,34 +1,37 @@
---
name: team-planex
description: |
Beat pipeline: planner decomposes requirements issue-by-issue, orchestrator spawns
Codex executor per issue immediately. All execution via Codex CLI only.
Inline planning + delegated execution pipeline. Main flow does planning directly,
spawns Codex executor per issue immediately. All execution via Codex CLI only.
---
# Team PlanEx (Codex)
逐 Issue 节拍流水线。Planner 每完成一个 issue 的 solution 立即输出 `ISSUE_READY` 信号，Orchestrator 即刻 spawn 独立 Codex executor 并行实现，无需等待 planner 完成全部规划。
主流程内联规划 + 委托执行。SKILL.md 自身完成规划（不再 spawn planner agent），每完成一个 issue 的 solution 后立即 spawn executor agent 并行实现，无需等待所有规划完成。
## Architecture
```
Input (Issue IDs / --text / --plan)
→ Orchestrator: parse input → init session → spawn planner
→ Beat loop:
wait(planner) → ISSUE_READY:{issueId} → spawn_agent(executor)
→ send_input(planner, "Continue")
→ ALL_PLANNED:{count} → close_agent(planner)
→ wait(all executors) → report
┌────────────────────────────────────────┐
│ SKILL.md (主流程 = 规划 + 节拍控制) │
│ │
│ Phase 1: 解析输入 + 初始化 session │
│ Phase 2: 逐 issue 规划循环 (内联) │
│ ├── issue-plan → 写 solution artifact │
│ ├── spawn executor agent ────────────┼──> [executor] 实现
│ └── continue (不等 executor) │
│ Phase 3: 等待所有 executors │
│ Phase 4: 汇总报告 │
└────────────────────────────────────────┘
```
## Agent Registry
| Agent | Role File | Responsibility |
|-------|-----------|----------------|
| `planner` | `~/.codex/agents/planex-planner.md` | Issue decomp → solution design → ISSUE_READY signals |
| `executor` | `~/.codex/agents/planex-executor.md` | Codex CLI implementation per issue |
> Both agents must be deployed to `~/.codex/agents/` before use.
> Executor agent must be deployed to `~/.codex/agents/` before use.
> Source: `.codex/skills/team-planex/agents/`
---
@@ -39,18 +42,29 @@ Supported input types (parse from `$ARGUMENTS`):
| Type | Detection | Handler |
|------|-----------|---------|
| Issue IDs | `ISS-\d{8}-\d{6}` regex | Pass directly to planner |
| Text | `--text '...'` flag | Planner creates issue(s) first |
| Plan file | `--plan <path>` flag | Planner reads file, batch creates issues |
| Issue IDs | `ISS-\d{8}-\d{6}` regex | Use directly for planning |
| Text | `--text '...'` flag | Create issue(s) first via CLI |
| Plan file | `--plan <path>` flag | Read file, parse phases, batch create issues |
### Issue Creation (when needed)
For `--text` input:
```bash
ccw issue create --data '{"title":"<title>","description":"<description>"}' --json
```
For `--plan` input:
- Match `## Phase N: Title`, `## Step N: Title`, or `### N. Title`
- Each match → one issue (title + description from section content)
- Fallback: no structure found → entire file as single issue
---
## Session Setup
Before spawning agents, initialize session directory:
Before processing issues, initialize session directory:
```javascript
// Generate session slug from input description (max 20 chars, kebab-case)
const slug = toSlug(inputDescription).slice(0, 20)
const date = new Date().toISOString().slice(0, 10).replace(/-/g, '')
const sessionDir = `.workflow/.team/PEX-${slug}-${date}`
@@ -58,7 +72,6 @@ const artifactsDir = `${sessionDir}/artifacts/solutions`
Bash(`mkdir -p "${artifactsDir}"`)
// Write initial session state
Write({
file_path: `${sessionDir}/team-session.json`,
content: JSON.stringify({
@@ -74,128 +87,101 @@ Write({
---
## Phase 1: Spawn Planner
## Phase 1: Parse Input + Initialize
1. Parse `$ARGUMENTS` to determine input type
2. Create issues if needed (--text / --plan)
3. Collect all issue IDs
4. Initialize session directory
---
## Phase 2: Inline Planning Loop
For each issue, execute planning inline (no planner agent):
### 2a. Generate Solution via issue-plan-agent
```javascript
const plannerAgent = spawn_agent({
const planAgent = spawn_agent({
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/planex-planner.md (MUST read first)
2. Run: `ccw spec load --category "planning execution"`
1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first)
---
## Session
Session directory: ${sessionDir}
Artifacts directory: ${artifactsDir}
issue_ids: ["${issueId}"]
project_root: "${projectRoot}"
## Input
${inputType === 'issues' ? `Issue IDs: ${issueIds.join(' ')}` : ''}
${inputType === 'text' ? `Requirement: ${requirementText}` : ''}
${inputType === 'plan' ? `Plan file: ${planPath}` : ''}
## Beat Protocol (CRITICAL)
Process issues one at a time. After completing each issue's solution:
1. Write solution JSON to: ${artifactsDir}/{issueId}.json
2. Output EXACTLY this line: ISSUE_READY:{issueId}
3. STOP and wait — do NOT continue until you receive "Continue"
When ALL issues are processed:
1. Output EXACTLY: ALL_PLANNED:{totalCount}
## Requirements
- Generate solution for this issue
- Auto-bind single solution
- Output solution JSON when complete
`
})
const result = wait({ ids: [planAgent], timeout_ms: 600000 })
close_agent({ id: planAgent })
```
### 2b. Write Solution Artifact
```javascript
const solution = parseSolution(result)
Write({
file_path: `${artifactsDir}/${issueId}.json`,
content: JSON.stringify({
session_id: sessionId,
issue_id: issueId,
solution: solution,
planned_at: new Date().toISOString()
}, null, 2)
})
```
---
## Phase 2: Beat Loop
Orchestrator coordinates the planner-executor pipeline:
### 2c. Spawn Executor Immediately
```javascript
const executorIds = []
const executorIssueMap = {}
while (true) {
// Wait for planner beat signal (up to 10 min per issue)
const plannerOut = wait({ ids: [plannerAgent], timeout_ms: 600000 })
// Handle timeout: urge convergence and retry
if (plannerOut.timed_out) {
send_input({
id: plannerAgent,
message: "Please output ISSUE_READY:{issueId} for current issue or ALL_PLANNED if done."
})
continue
}
const output = plannerOut.status[plannerAgent].completed
// Detect ALL_PLANNED — pipeline complete
if (output.includes('ALL_PLANNED')) {
const match = output.match(/ALL_PLANNED:(\d+)/)
const total = match ? parseInt(match[1]) : executorIds.length
close_agent({ id: plannerAgent })
break
}
// Detect ISSUE_READY — spawn executor immediately
const issueMatch = output.match(/ISSUE_READY:(ISS-\d{8}-\d{6}|[A-Z0-9-]+)/)
if (issueMatch) {
const issueId = issueMatch[1]
const solutionFile = `${artifactsDir}/${issueId}.json`
const executorId = spawn_agent({
message: `
const executorId = spawn_agent({
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/planex-executor.md (MUST read first)
2. Run: `ccw spec load --category "planning execution"`
---
## Issue
Issue ID: ${issueId}
Solution file: ${solutionFile}
Solution file: ${artifactsDir}/${issueId}.json
Session: ${sessionDir}
## Execution
Load solution from file → implement via Codex CLI → verify tests → commit → report.
`
})
})
executorIds.push(executorId)
executorIssueMap[executorId] = issueId
// Signal planner to continue to next issue
send_input({ id: plannerAgent, message: "Continue with next issue." })
continue
}
// Unexpected output: urge convergence
send_input({
id: plannerAgent,
message: "Output ISSUE_READY:{issueId} when solution is ready, or ALL_PLANNED when all done."
})
}
executorIds.push(executorId)
executorIssueMap[executorId] = issueId
```
### 2d. Continue to Next Issue
Do NOT wait for executor. Proceed to next issue immediately.
---
## Phase 3: Wait All Executors
```javascript
if (executorIds.length > 0) {
// Extended timeout: Codex CLI execution per issue (~10-20 min each)
const execResults = wait({ ids: executorIds, timeout_ms: 1800000 })
if (execResults.timed_out) {
const completed = executorIds.filter(id => execResults.status[id]?.completed)
const pending = executorIds.filter(id => !execResults.status[id]?.completed)
// Log pending issues for manual follow-up
const pending = executorIds.filter(id => !execResults.status[id]?.completed)
if (pending.length > 0) {
const pendingIssues = pending.map(id => executorIssueMap[id])
Write({
@@ -216,12 +202,29 @@ if (executorIds.length > 0) {
executorIds.forEach(id => {
try { close_agent({ id }) } catch { /* already closed */ }
})
}
```
// Final report
const completed = summaries.filter(s => s.status === 'completed').length
const failed = summaries.filter(s => s.status === 'timeout').length
---
return `
## Phase 4: Report
```javascript
const completed = summaries.filter(s => s.status === 'completed').length
const failed = summaries.filter(s => s.status === 'timeout').length
// Update session
Write({
file_path: `${sessionDir}/team-session.json`,
content: JSON.stringify({
...session,
status: "completed",
completed_at: new Date().toISOString(),
results: { total: executorIds.length, completed, failed }
}, null, 2)
})
return `
## Pipeline Complete
**Total issues**: ${executorIds.length}
@@ -232,7 +235,6 @@ ${summaries.map(s => `- ${s.issue_id}: ${s.status}`).join('\n')}
Session: ${sessionDir}
`
}
```
---
@@ -244,29 +246,7 @@ During execution, the user may issue:
| Command | Action |
|---------|--------|
| `check` / `status` | Show executor progress summary |
| `resume` / `continue` | Urge stalled planner or executor |
| `add <issue-ids>` | `send_input` to planner with new issue IDs |
| `add --text '...'` | `send_input` to planner to create and plan new issue |
| `add --plan <path>` | `send_input` to planner to parse and batch create from plan file |
**`add` handler** (inject mid-execution):
```javascript
// Get current planner agent ID from session state
const session = JSON.parse(Read(`${sessionDir}/team-session.json`))
const plannerAgentId = session.planner_agent_id // saved during Phase 1
send_input({
id: plannerAgentId,
message: `
## NEW ISSUES INJECTED
${newInput}
Process these after current issue (or immediately if idle).
Follow beat protocol: ISSUE_READY → wait for Continue → next issue.
`
})
```
| `resume` / `continue` | Urge stalled executor |
---
@@ -274,9 +254,8 @@ Follow beat protocol: ISSUE_READY → wait for Continue → next issue.
| Scenario | Resolution |
|----------|------------|
| Planner timeout (>10 min per issue) | `send_input` urge convergence, re-enter loop |
| Planner never outputs ISSUE_READY | After 3 retries, `close_agent` + report stall |
| issue-plan-agent timeout (>10 min) | Skip issue, log error, continue to next |
| issue-plan-agent failure | Retry once, then skip with error log |
| Solution file not written | Executor reports error, logs to `${sessionDir}/errors.json` |
| Executor (Codex CLI) failure | Executor handles resume; logs CLI resume command |
| ALL_PLANNED never received | After 60 min total, close planner, wait remaining executors |
| No issues to process | AskUserQuestion for clarification |
| No issues to process | Report error: no issues found |

43
.codex/skills/team-planex/agents/executor.md
View File

@@ -23,13 +23,13 @@ completion report.
| Action | Allowed |
|--------|---------|
| Read solution artifact from disk | ✅ |
| Implement via Codex CLI | ✅ |
| Run tests for verification | ✅ |
| git commit completed work | ✅ |
| Create or modify issues | ❌ |
| Spawn subagents | ❌ |
| Interact with user (AskUserQuestion) | ❌ |
| Read solution artifact from disk | Yes |
| Implement via Codex CLI | Yes |
| Run tests for verification | Yes |
| git commit completed work | Yes |
| Create or modify issues | No |
| Spawn subagents | No |
| Interact with user (AskUserQuestion) | No |
---
@@ -38,7 +38,6 @@ completion report.
### Step 1: Load Context
After reading role definition:
- Run: `ccw spec load --category execution`
- Extract issue ID, solution file path, session dir from task message
### Step 2: Load Solution
@@ -52,7 +51,7 @@ const solution = solutionData.solution
If file not found or invalid:
- Log error: `[executor] ERROR: Solution file not found: ${solutionFile}`
- Output: `EXEC_FAILED:{issueId}:solution_file_missing`
- Output: `EXEC_FAILED:${issueId}:solution_file_missing`
- Stop execution
Verify solution has required fields:
@@ -81,10 +80,9 @@ ${JSON.stringify(solution.bound, null, 2)}
## Implementation Requirements
1. Follow the solution plan tasks in order
2. Write clean, minimal code following existing patterns
3. Read .workflow/specs/*.md for project conventions
4. Run tests after each significant change
5. Ensure all existing tests still pass
6. Do NOT over-engineer - implement exactly what the solution specifies
3. Run tests after each significant change
4. Ensure all existing tests still pass
5. Do NOT over-engineer - implement exactly what the solution specifies
## Quality Checklist
- [ ] All solution tasks implemented
@@ -92,9 +90,6 @@ ${JSON.stringify(solution.bound, null, 2)}
- [ ] Existing tests pass
- [ ] New tests added where specified in solution
- [ ] No security vulnerabilities introduced
## Project Guidelines
@.workflow/specs/*.md
PROMPT_EOF
)" --tool codex --mode write --id planex-${issueId}
```
@@ -120,7 +115,6 @@ if (testCmd) {
const testResult = Bash(`${testCmd} 2>&1 || echo TEST_FAILED`)
if (testResult.includes('TEST_FAILED') || testResult.includes('FAIL')) {
// Report failure with resume command
const resumeCmd = `ccw cli -p "Fix failing tests" --resume planex-${issueId} --tool codex --mode write`
Write({
@@ -179,7 +173,6 @@ EXEC_DONE:${issueId}
If Codex CLI execution fails or times out:
```bash
# Resume with same session ID
ccw cli -p "Continue implementation from where stopped" \
--resume planex-${issueId} \
--tool codex --mode write \
@@ -194,19 +187,19 @@ Resume command is always logged to `${sessionDir}/errors.json` on any failure.
| Scenario | Resolution |
|----------|------------|
| Solution file missing | Output `EXEC_FAILED:{id}:solution_file_missing`, stop |
| Solution JSON malformed | Output `EXEC_FAILED:{id}:solution_invalid`, stop |
| Solution file missing | Output `EXEC_FAILED:<id>:solution_file_missing`, stop |
| Solution JSON malformed | Output `EXEC_FAILED:<id>:solution_invalid`, stop |
| Issue status update fails | Log warning, continue |
| Codex CLI failure | Log resume command to errors.json, output `EXEC_FAILED:{id}:codex_failed` |
| Tests failing | Log test output + resume command, output `EXEC_FAILED:{id}:tests_failing` |
| Commit fails | Log warning, still output `EXEC_DONE:{id}` (implementation complete) |
| Codex CLI failure | Log resume command to errors.json, output `EXEC_FAILED:<id>:codex_failed` |
| Tests failing | Log test output + resume command, output `EXEC_FAILED:<id>:tests_failing` |
| Commit fails | Log warning, still output `EXEC_DONE:<id>` (implementation complete) |
| No test command found | Skip test step, proceed to commit |
## Key Reminders
**ALWAYS**:
- Output `EXEC_DONE:{issueId}` on its own line when implementation succeeds
- Output `EXEC_FAILED:{issueId}:{reason}` on its own line when implementation fails
- Output `EXEC_DONE:<issueId>` on its own line when implementation succeeds
- Output `EXEC_FAILED:<issueId>:<reason>` on its own line when implementation fails
- Log resume command to errors.json on any failure
- Use `[executor]` prefix in all status messages

183
.codex/skills/team-planex/agents/planner.md
View File

@@ -1,183 +0,0 @@
---
name: planex-planner
description: |
PlanEx planner agent. Issue decomposition + solution design with beat protocol.
Outputs ISSUE_READY:{id} after each solution, waits for "Continue" signal.
Deploy to: ~/.codex/agents/planex-planner.md
color: blue
---
# PlanEx Planner
Requirement decomposition → issue creation → solution design, one issue at a time.
Outputs `ISSUE_READY:{issueId}` after each solution and waits for orchestrator to signal
"Continue". Only outputs `ALL_PLANNED:{count}` when all issues are processed.
## Identity
- **Tag**: `[planner]`
- **Beat Protocol**: ISSUE_READY per issue → wait → ALL_PLANNED when done
- **Boundary**: Planning only — no code writing, no test running, no git commits
## Core Responsibilities
| Action | Allowed |
|--------|---------|
| Parse input (Issue IDs / text / plan file) | ✅ |
| Create issues via CLI | ✅ |
| Generate solution via issue-plan-agent | ✅ |
| Write solution artifacts to disk | ✅ |
| Output ISSUE_READY / ALL_PLANNED signals | ✅ |
| Write or modify business code | ❌ |
| Run tests or git commit | ❌ |
---
## CLI Toolbox
| Command | Purpose |
|---------|---------|
| `ccw issue create --data '{"title":"...","description":"..."}' --json` | Create issue |
| `ccw issue status <id> --json` | Check issue status |
| `ccw issue plan <id>` | Plan single issue (generates solution) |
---
## Execution Flow
### Step 1: Load Context
After reading role definition, load project context:
- Run: `ccw spec load --category planning`
- Extract session directory and artifacts directory from task message
### Step 2: Parse Input
Determine input type from task message:
| Detection | Condition | Action |
|-----------|-----------|--------|
| Issue IDs | `ISS-\d{8}-\d{6}` pattern | Use directly for planning |
| `--text '...'` | Flag in message | Create issue(s) first via CLI |
| `--plan <path>` | Flag in message | Read file, parse phases, batch create issues |
**Plan file parsing rules** (when `--plan` is used):
- Match `## Phase N: Title`, `## Step N: Title`, or `### N. Title`
- Each match → one issue (title + description from section content)
- Fallback: no structure found → entire file as single issue
### Step 3: Issue Processing Loop (Beat Protocol)
For each issue, execute in sequence:
#### 3a. Generate Solution
Use `issue-plan-agent` subagent to generate and bind solution:
```
spawn_agent({
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first)
2. Run: `ccw spec load --category planning`
---
issue_ids: ["${issueId}"]
project_root: "${projectRoot}"
## Requirements
- Generate solution for this issue
- Auto-bind single solution
- Output solution JSON when complete
`
})
const result = wait({ ids: [agent], timeout_ms: 600000 })
close_agent({ id: agent })
```
#### 3b. Write Solution Artifact
```javascript
// Extract solution from issue-plan-agent result
const solution = parseSolution(result)
Write({
file_path: `${artifactsDir}/${issueId}.json`,
content: JSON.stringify({
session_id: sessionId,
issue_id: issueId,
solution: solution,
planned_at: new Date().toISOString()
}, null, 2)
})
```
#### 3c. Output Beat Signal
Output EXACTLY (no surrounding text on this line):
```
ISSUE_READY:{issueId}
```
Then STOP. Do not process next issue. Wait for "Continue" message from orchestrator.
### Step 4: After All Issues
When every issue has been processed and confirmed with "Continue":
Output EXACTLY:
```
ALL_PLANNED:{totalCount}
```
Where `{totalCount}` is the integer count of issues planned.
---
## Issue Creation (when needed)
For `--text` input:
```bash
ccw issue create --data '{"title":"<title>","description":"<description>"}' --json
```
Parse returned JSON for `id` field → use as issue ID.
For `--plan` input, create issues one at a time:
```bash
# For each parsed phase/step:
ccw issue create --data '{"title":"<phase-title>","description":"<phase-content>"}' --json
```
Collect all created issue IDs before proceeding to Step 3.
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Issue creation failure | Retry once with simplified text, then report error |
| `issue-plan-agent` failure | Retry once, then skip issue with `ISSUE_SKIP:{issueId}:reason` signal |
| Plan file not found | Output error immediately, do not proceed |
| Artifact write failure | Log warning inline, still output ISSUE_READY (executor will handle missing file) |
| "Continue" not received after 5 min | Re-output `ISSUE_READY:{issueId}` once as reminder |
## Key Reminders
**ALWAYS**:
- Output `ISSUE_READY:{issueId}` on its own line with no surrounding text
- Wait after each ISSUE_READY — do NOT auto-continue
- Write solution file before outputting ISSUE_READY
- Use `[planner]` prefix in all status messages
**NEVER**:
- Output multiple ISSUE_READY signals before waiting for "Continue"
- Proceed to next issue without receiving "Continue"
- Write or modify any business logic files
- Run tests or execute git commands