diff --git a/.codex/skills/codex-issue-plan-execute/README.md b/.codex/skills/codex-issue-plan-execute/README.md new file mode 100644 index 00000000..9ad53887 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/README.md @@ -0,0 +1,255 @@ +# Codex Issue Plan-Execute Skill + +简化的 Codex issue 规划-执行工作流 Skill。 + +## 快速开始 + +### 安装 + +该 Skill 已经在 `~/.claude/skills/codex-issue-plan-execute/` 中生成。 + +### 使用方式 + +#### 方式 1:执行单个 issue + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute --issue ISS-001" +``` + +#### 方式 2:批量执行多个 issues + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute --issues ISS-001,ISS-002,ISS-003" +``` + +#### 方式 3:交互式选择 + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute" +# 系统会显示 issues 列表,你可以交互式选择 +``` + +#### 方式 4:恢复之前的执行 + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute --resume .workflow/.scratchpad/codex-issue-20250129-120000" +``` + +## 工作流程 + +``` +Initialize + ↓ +List Issues (显示所有 pending/planned issues) + ↓ +Plan Solutions (为选中的 issues 生成解决方案) + ↓ +Execute Solutions (按顺序执行解决方案) + ↓ +Complete (生成报告并完成) +``` + +### 每个阶段做什么 + +**Phase 1: Initialize** +- 创建工作目录 +- 初始化状态 JSON +- 准备执行环境 + +**Phase 2: List Issues** +- 从 ccw issue 加载 issues +- 显示当前状态矩阵 +- 收集用户的规划/执行选择 + +**Phase 3: Plan Solutions** +- 为每个 issue 生成规划 subagent +- 分析代码并设计解决方案 +- 绑定 solution 到 issue +- 更新 issue 状态 → "planned" + +**Phase 4: Execute Solutions** +- 加载已规划的解决方案 +- 执行所有 tasks(implement → test → verify) +- 一次性提交所有更改 +- 更新 solution 状态 → "completed" + +**Phase 5: Complete** +- 生成执行报告 +- 保存最终状态和统计信息 +- 输出完成摘要 + +## 目录结构 + +``` +codex-issue-plan-execute/ +├── SKILL.md # 入口文件(你已读) +├── phases/ +│ ├── orchestrator.md # Orchestrator 编排逻辑 +│ ├── state-schema.md # 状态结构定义 +│ └── actions/ +│ ├── action-init.md # 初始化 +│ ├── action-list.md # 列表显示 +│ ├── action-plan.md # 规划 +│ ├── action-execute.md # 执行 +│ └── action-complete.md # 完成 +├── specs/ +│ ├── issue-handling.md # Issue 处理规范 +│ ├── solution-schema.md # Solution 数据结构 +│ ├── quality-standards.md # 质量标准 +│ └── subagent-roles.md # Subagent 角色定义 +└── templates/ + └── (可选的 prompt 模板) +``` + +## 配置选项 + +### 命令行参数 + +| 参数 | 值 | 说明 | +|------|-----|------| +| `--issue` | ISS-ID | 执行单个 issue | +| `--issues` | ID1,ID2,ID3 | 执行多个 issues | +| `--resume` | path | 从快照恢复 | +| `--skip-plan` | - | 跳过规划阶段,直接执行 | +| `--skip-execute` | - | 仅规划,不执行 | + +## 关键特性 + +### ✓ 已实现 + +- [x] Autonomous 状态驱动编排 +- [x] 双 Agent 规划-执行分离 +- [x] 最小化队列(仅保留待执行项) +- [x] 批量 issue 处理 +- [x] 完整状态持久化 +- [x] 快照恢复能力 +- [x] 详细执行报告 + +### ⌛ 可选增强 + +- [ ] 并行规划(当前串行) +- [ ] 冲突检测和优先级排序 +- [ ] 自动重试失败项 +- [ ] WebUI 显示进度 +- [ ] Slack 通知 + +## 输出文件 + +执行完成后会在 `.workflow/.scratchpad/codex-issue-{timestamp}/` 生成: + +``` +state.json # 最终状态快照 +state-history.json # 状态变更历史 +queue.json # 执行队列 +execution-results.json # 执行结果汇总 +final-report.md # 最终报告 +solutions/ + ├── ISS-001-plan.json + ├── ISS-001-execution.json + ├── ISS-002-plan.json + └── ... +snapshots/ + ├── snapshot-before-plan.json + ├── snapshot-before-execute.json + └── ... +``` + +## 故障排除 + +### Issue 无法加载 + +```bash +# 检查 issues 是否存在 +ccw issue list --status registered + +# 手动创建 issue +ccw issue init ISS-001 --title "My Issue" +``` + +### 规划失败 + +- 检查 `~/.codex/agents/issue-plan-agent.md` 是否存在 +- 查看错误日志中的具体原因 +- 从快照恢复后重试 + +### 执行失败 + +- 检查测试是否通过:`npm test` +- 查看 acceptance criteria 是否满足 +- 从快照恢复:`codex ... --resume {snapshot_path}` + +### 状态不一致 + +- 删除旧的 state.json 重新开始 +- 或从最后一个有效快照恢复 + +## 性能指标 + +| 指标 | 预期值 | +|------|--------| +| 初始化 | < 1s | +| 列表加载 | < 2s | +| 单 issue 规划 | 30-60s | +| 单 issue 执行 | 1-5 min | +| 总处理时间(3 issues) | 5-20 min | + +## 系统要求 + +- Codex CLI >= 2.0 +- Node.js >= 14 +- Git 仓库已初始化 +- ccw issue 命令可用 + +## 贡献指南 + +### 修改 Action + +编辑 `phases/actions/action-*.md` 文件 + +### 修改规范 + +编辑 `specs/*.md` 文件 + +### 测试 Skill + +```bash +# 测试单个 issue +ccw codex issue:plan-execute --issue ISS-001 + +# 测试批量处理 +ccw codex issue:plan-execute --issues ISS-001,ISS-002 + +# 检查输出 +cat .workflow/.scratchpad/codex-issue-*/final-report.md +``` + +## 版本历史 + +- **v1.0** (2025-01-29) + - 初始发布 + - Autonomous 编排模式 + - 双 Agent 规划-执行分离 + - 简化队列管理 + +## 许可证 + +与 Claude Code 相同 + +## 支持 + +遇到问题? + +1. 查看 [SKILL.md](SKILL.md) 了解架构 +2. 查看 `specs/` 下的规范文档 +3. 检查执行日志和快照 +4. 查看最终报告 `final-report.md` + +--- + +**Ready to use!** 🚀 + +开始你的第一个 issue 规划-执行工作流: + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute" +``` diff --git a/.codex/skills/codex-issue-plan-execute/SKILL.md b/.codex/skills/codex-issue-plan-execute/SKILL.md new file mode 100644 index 00000000..ee03cff9 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/SKILL.md @@ -0,0 +1,206 @@ +--- +name: codex-issue-plan-execute +description: Autonomous issue planning and execution workflow for Codex. Supports batch issue processing with integrated planning, queuing, and execution stages. Triggers on "codex-issue", "plan execute issue", "issue workflow". +allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep +--- + +# Codex Issue Plan-Execute Workflow + +Streamlined autonomous workflow for Codex that integrates issue planning, queue management, and solution execution in a single stateful Skill. Supports batch processing with minimal queue overhead and dual-agent execution strategy. + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Main Orchestrator (Claude Code Entry Point) │ +│ • Loads issues │ +│ • Spawns persistent agents │ +│ • Manages pipeline flow │ +└──────┬──────────────────────────────────────┬──────────────────────┘ + │ spawn_agent(planning-system-prompt) │ spawn_agent(execution-system-prompt) + │ (创建一次) │ (创建一次) + ▼ ▼ +┌─────────────────────────────┐ ┌────────────────────────────────┐ +│ Planning Agent │ │ Execution Agent │ +│ (持久化 - 不关闭) │ │ (持久化 - 不关闭) │ +│ │ │ │ +│ Loop: receive issue → │ │ Loop: receive solution → │ +│ analyze & design │ │ implement & test │ +│ return solution │ │ return results │ +└────────┬────────────────────┘ └────────┬─────────────────────┘ + │ send_input(issue) │ send_input(solution) + │ wait for response │ wait for response + │ (逐个 issue) │ (逐个 solution) + ▼ ▼ + Planning Results Execution Results + (unified JSON) (unified JSON) +``` + + +## Key Design Principles + +1. **Persistent Agent Architecture**: Two long-running agents (Planning + Execution) that never close until all work completes +2. **Pipeline Flow**: Main orchestrator feeds issues sequentially to Planning Agent via `send_input`, then feeds solutions to Execution Agent via `send_input` +3. **Unified Results Storage**: Single JSON files (`planning-results.json`, `execution-results.json`) accumulate all results instead of per-issue files +4. **Context Preservation**: Agents maintain context across multiple tasks without being recreated +5. **Efficient Communication**: Uses `send_input()` mechanism to communicate with agents without spawn/close overhead + +--- + +## ⚠️ Mandatory Prerequisites (强制前置条件) + +> **⛔ 禁止跳过**: 在执行任何操作之前,**必须**完整阅读以下文档。未阅读规范直接执行将导致输出不符合质量标准。 + +### 规范文档 (必读) + +| Document | Purpose | Priority | +|----------|---------|----------| +| [specs/issue-handling.md](specs/issue-handling.md) | Issue 处理规范和数据结构 | **P0 - 最高** | +| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案数据结构和验证规则 | **P0 - 最高** | +| [specs/quality-standards.md](specs/quality-standards.md) | 质量标准和验收条件 | P1 | + +### 参考文档 (背景知识) + +| Document | Purpose | +|----------|---------| +| [../issue-plan.md](../../.codex/prompts/issue-plan.md) | Codex Issue Plan 原始实现 | +| [../issue-execute.md](../../.codex/prompts/issue-execute.md) | Codex Issue Execute 原始实现 | +| [../codex SUBAGENT 策略补充.md](../../workflow/.scratchpad/codex%20SUBAGENT%20策略补充.md) | Codex Subagent 使用指南 | + +--- + +## Execution Flow + +### Phase 1: Initialize Persistent Agents +→ Spawn Planning Agent with `planning-agent-system.md` prompt (stays alive) +→ Spawn Execution Agent with `execution-agent-system.md` prompt (stays alive) + +### Phase 2: Planning Pipeline +For each issue sequentially: +1. Send issue to Planning Agent via `send_input()` with planning request +2. Wait for Planning Agent to return solution JSON +3. Store result in unified `planning-results.json` array +4. Continue to next issue (agent stays alive) + +### Phase 3: Execution Pipeline +For each successful planning result sequentially: +1. Send solution to Execution Agent via `send_input()` with execution request +2. Wait for Execution Agent to complete implementation and testing +3. Store result in unified `execution-results.json` array +4. Continue to next solution (agent stays alive) + +### Phase 4: Finalize +→ Close Planning Agent (after all issues planned) +→ Close Execution Agent (after all solutions executed) +→ Generate final report with statistics + +### State Schema + +```json +{ + "status": "pending|running|completed", + "phase": "init|listing|planning|executing|complete", + "issues": { + "{issue_id}": { + "id": "ISS-xxx", + "status": "registered|planning|planned|executing|completed", + "solution_id": "SOL-xxx-1", + "planned_at": "ISO-8601", + "executed_at": "ISO-8601" + } + }, + "queue": [ + { + "item_id": "S-1", + "issue_id": "ISS-xxx", + "solution_id": "SOL-xxx-1", + "status": "pending|executing|completed" + } + ], + "context": { + "work_dir": ".workflow/.scratchpad/...", + "total_issues": 0, + "completed_count": 0, + "failed_count": 0 + }, + "errors": [] +} +``` + +--- + +## Directory Setup + +```javascript +const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, ''); +const workDir = `.workflow/.scratchpad/codex-issue-${timestamp}`; + +Bash(`mkdir -p "${workDir}"`); +Bash(`mkdir -p "${workDir}/solutions"`); +Bash(`mkdir -p "${workDir}/snapshots"`); +``` + +## Output Structure + +``` +.workflow/.scratchpad/codex-issue-{timestamp}/ +├── planning-results.json # All planning results in single file +│ ├── phase: "planning" +│ ├── created_at: "ISO-8601" +│ └── results: [ +│ { issue_id, solution_id, status, solution, planned_at } +│ ] +├── execution-results.json # All execution results in single file +│ ├── phase: "execution" +│ ├── created_at: "ISO-8601" +│ └── results: [ +│ { issue_id, solution_id, status, commit_hash, files_modified, executed_at } +│ ] +└── final-report.md # Summary statistics and report +``` + +--- + +## Reference Documents + +| Document | Purpose | +|----------|---------| +| [phases/orchestrator.md](phases/orchestrator.md) | Orchestrator 编排器逻辑 | +| [phases/actions/action-list.md](phases/actions/action-list.md) | List Issues 动作 | +| [phases/actions/action-plan.md](phases/actions/action-plan.md) | Plan Solutions 动作 | +| [phases/actions/action-execute.md](phases/actions/action-execute.md) | Execute Solutions 动作 | +| [phases/actions/action-complete.md](phases/actions/action-complete.md) | Complete 动作 | +| [phases/state-schema.md](phases/state-schema.md) | 状态结构定义和验证 | +| [specs/issue-handling.md](specs/issue-handling.md) | Issue 处理规范 | +| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案数据结构 | +| [specs/quality-standards.md](specs/quality-standards.md) | 质量标准 | +| [specs/subagent-roles.md](specs/subagent-roles.md) | Subagent 角色定义 | + +--- + +## Usage Examples + +### Batch Process Specific Issues + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute ISS-001,ISS-002,ISS-003" +``` + +### Interactive Selection + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute" +# Then select issues from the list +``` + +### Resume from Snapshot + +```bash +codex -p "@.codex/prompts/codex-issue-plan-execute --resume snapshot-path" +``` + +--- + +*Skill Version: 1.0* +*Execution Mode: Autonomous* +*Status: Ready for Customization* diff --git a/.codex/skills/codex-issue-plan-execute/phases/actions/action-complete.md b/.codex/skills/codex-issue-plan-execute/phases/actions/action-complete.md new file mode 100644 index 00000000..105c47d0 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/phases/actions/action-complete.md @@ -0,0 +1,173 @@ +# Action: Complete + +完成工作流并生成最终报告。 + +## Purpose + +序列化最终状态,生成执行摘要,清理临时文件。 + +## Preconditions + +- [ ] `state.status === "running"` +- [ ] 所有 issues 已处理或错误限制达到 + +## Execution + +```javascript +async function execute(state) { + const workDir = state.work_dir; + const issues = state.issues || {}; + + console.log("\n=== Finalizing Workflow ==="); + + // 1. 生成统计信息 + const totalIssues = Object.keys(issues).length; + const completedCount = Object.values(issues).filter(i => i.status === "completed").length; + const failedCount = Object.values(issues).filter(i => i.status === "failed").length; + const pendingCount = totalIssues - completedCount - failedCount; + + const stats = { + total_issues: totalIssues, + completed: completedCount, + failed: failedCount, + pending: pendingCount, + success_rate: totalIssues > 0 ? ((completedCount / totalIssues) * 100).toFixed(1) : 0, + duration_ms: new Date() - new Date(state.created_at) + }; + + console.log("\n=== Summary ==="); + console.log(`Total Issues: ${stats.total_issues}`); + console.log(`✓ Completed: ${stats.completed}`); + console.log(`✗ Failed: ${stats.failed}`); + console.log(`○ Pending: ${stats.pending}`); + console.log(`Success Rate: ${stats.success_rate}%`); + console.log(`Duration: ${(stats.duration_ms / 1000).toFixed(1)}s`); + + // 2. 生成详细报告 + const reportLines = [ + "# Execution Report", + "", + `## Summary`, + `- Total Issues: ${stats.total_issues}`, + `- Completed: ${stats.completed}`, + `- Failed: ${stats.failed}`, + `- Pending: ${stats.pending}`, + `- Success Rate: ${stats.success_rate}%`, + `- Duration: ${(stats.duration_ms / 1000).toFixed(1)}s`, + "", + "## Results by Issue" + ]; + + Object.values(issues).forEach((issue, index) => { + const status = issue.status === "completed" ? "✓" : issue.status === "failed" ? "✗" : "○"; + reportLines.push(`### ${status} [${index + 1}] ${issue.id}: ${issue.title}`); + reportLines.push(`- Status: ${issue.status}`); + if (issue.solution_id) { + reportLines.push(`- Solution: ${issue.solution_id}`); + } + if (issue.planned_at) { + reportLines.push(`- Planned: ${issue.planned_at}`); + } + if (issue.executed_at) { + reportLines.push(`- Executed: ${issue.executed_at}`); + } + if (issue.error) { + reportLines.push(`- Error: ${issue.error}`); + } + reportLines.push(""); + }); + + if (state.errors && state.errors.length > 0) { + reportLines.push("## Errors"); + state.errors.forEach(error => { + reportLines.push(`- [${error.timestamp}] ${error.action}: ${error.message}`); + }); + reportLines.push(""); + } + + reportLines.push("## Files Generated"); + reportLines.push(`- Work Directory: ${workDir}`); + reportLines.push(`- State File: ${workDir}/state.json`); + reportLines.push(`- Execution Results: ${workDir}/execution-results.json`); + reportLines.push(`- Solutions: ${workDir}/solutions/`); + reportLines.push(`- Snapshots: ${workDir}/snapshots/`); + + // 3. 保存报告 + const reportPath = `${workDir}/final-report.md`; + Write(reportPath, reportLines.join("\n")); + + // 4. 保存最终状态 + const finalState = { + ...state, + status: "completed", + phase: "completed", + completed_at: new Date().toISOString(), + completed_actions: [...state.completed_actions, "action-complete"], + context: { + ...state.context, + ...stats + } + }; + + Write(`${workDir}/state.json`, JSON.stringify(finalState, null, 2)); + + // 5. 保存汇总 JSON + Write(`${workDir}/summary.json`, JSON.stringify({ + status: "completed", + stats: stats, + report_file: reportPath, + work_dir: workDir, + completed_at: new Date().toISOString() + }, null, 2)); + + // 6. 输出完成消息 + console.log(`\n✓ Workflow completed`); + console.log(`📄 Report: ${reportPath}`); + console.log(`📁 Working directory: ${workDir}`); + + return { + stateUpdates: { + status: "completed", + phase: "completed", + completed_at: new Date().toISOString(), + completed_actions: [...state.completed_actions, "action-complete"], + context: finalState.context + } + }; +} +``` + +## State Updates + +```javascript +return { + stateUpdates: { + status: "completed", + phase: "completed", + completed_at: timestamp, + completed_actions: [...state.completed_actions, "action-complete"], + context: { + total_issues: stats.total_issues, + completed_count: stats.completed, + failed_count: stats.failed, + success_rate: stats.success_rate + } + } +}; +``` + +## Error Handling + +| Error Type | Recovery | +|------------|----------| +| 报告生成失败 | 输出文本摘要到控制台 | +| 文件写入失败 | 继续完成,允许手动保存 | +| 权限错误 | 使用替代目录 | + +## Next Actions (Hints) + +- 无(终止状态) +- 用户可选择: + - 查看报告:`cat {report_path}` + - 恢复并重试失败的 issues:`codex issue:plan-execute --resume {work_dir}` + - 清理临时文件:`rm -rf {work_dir}` diff --git a/.codex/skills/codex-issue-plan-execute/phases/actions/action-execute.md b/.codex/skills/codex-issue-plan-execute/phases/actions/action-execute.md new file mode 100644 index 00000000..3efd498b --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/phases/actions/action-execute.md @@ -0,0 +1,220 @@ +# Action: Execute Solutions + +按队列顺序执行已规划的解决方案。 + +## Purpose + +加载计划的解决方案并使用 subagent 执行所有任务、提交更改。 + +## Preconditions + +- [ ] `state.status === "running"` +- [ ] `issues with solution_id` exist (来自规划阶段) + +## Execution + +```javascript +async function execute(state) { + const workDir = state.work_dir; + const issues = state.issues || {}; + const queue = state.queue || []; + + // 1. 构建执行队列(来自已规划的 issues) + const plannedIssues = Object.values(issues).filter(i => i.status === "planned"); + + if (plannedIssues.length === 0) { + console.log("No planned solutions to execute"); + return { stateUpdates: { queue } }; + } + + console.log(`\n=== Executing ${plannedIssues.length} Solutions ===`); + + // 2. 序列化执行每个解决方案 + const executionResults = []; + + for (let i = 0; i < plannedIssues.length; i++) { + const issue = plannedIssues[i]; + const solutionId = issue.solution_id; + + console.log(`\n[${i + 1}/${plannedIssues.length}] Executing: ${solutionId}`); + + try { + // 创建快照(便于恢复) + const beforeSnapshot = { + timestamp: new Date().toISOString(), + phase: "before-execute", + issue_id: issue.id, + solution_id: solutionId, + state: { ...state } + }; + Write(`${workDir}/snapshots/snapshot-before-execute-${i}.json`, JSON.stringify(beforeSnapshot, null, 2)); + + // 执行 subagent + const executionPrompt = ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/issue-execute-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +--- + +Goal: Execute solution "${solutionId}" for issue "${issue.id}" + +Scope: +- CAN DO: Implement tasks, run tests, commit code +- CANNOT DO: Push to remote or create PRs without approval +- Directory: ${process.cwd()} + +Solution ID: ${solutionId} + +Load solution details: +- Read: ${workDir}/solutions/${issue.id}-plan.json + +Execution steps: +1. Parse all tasks from solution +2. Execute each task: implement → test → verify +3. Commit once for all tasks with formatted summary +4. Report completion + +Quality bar: +- All acceptance criteria verified +- Tests passing +- Commit message follows conventions + +Return: JSON with files_modified[], commit_hash, status +`; + + const result = await Task({ + subagent_type: "universal-executor", + run_in_background: false, + description: `Execute solution ${solutionId}`, + prompt: executionPrompt + }); + + // 解析执行结果 + let execResult; + try { + execResult = typeof result === "string" ? JSON.parse(result) : result; + } catch { + execResult = { status: "executed", commit_hash: "unknown" }; + } + + // 保存执行结果 + Write(`${workDir}/solutions/${issue.id}-execution.json`, JSON.stringify({ + solution_id: solutionId, + issue_id: issue.id, + status: "completed", + executed_at: new Date().toISOString(), + execution_result: execResult + }, null, 2)); + + // 更新 issue 状态 + issues[issue.id].status = "completed"; + issues[issue.id].executed_at = new Date().toISOString(); + + // 更新队列项 + const queueIndex = queue.findIndex(q => q.solution_id === solutionId); + if (queueIndex >= 0) { + queue[queueIndex].status = "completed"; + } + + // 更新 ccw + try { + Bash(`ccw issue update ${issue.id} --status completed`); + } catch (error) { + console.log(`Note: Could not update ccw status (${error.message})`); + } + + console.log(`✓ ${solutionId} completed`); + executionResults.push({ + issue_id: issue.id, + solution_id: solutionId, + status: "completed", + commit: execResult.commit_hash + }); + + state.context.completed_count++; + + } catch (error) { + console.error(`✗ Execution failed for ${solutionId}: ${error.message}`); + + // 更新失败状态 + issues[issue.id].status = "failed"; + issues[issue.id].error = error.message; + + state.context.failed_count++; + + executionResults.push({ + issue_id: issue.id, + solution_id: solutionId, + status: "failed", + error: error.message + }); + } + } + + // 3. 保存执行结果摘要 + Write(`${workDir}/execution-results.json`, JSON.stringify({ + total: plannedIssues.length, + completed: state.context.completed_count, + failed: state.context.failed_count, + results: executionResults, + timestamp: new Date().toISOString() + }, null, 2)); + + return { + stateUpdates: { + issues: issues, + queue: queue, + context: state.context, + completed_actions: [...state.completed_actions, "action-execute"] + } + }; +} +``` + +## State Updates + +```javascript +return { + stateUpdates: { + issues: { + [issue.id]: { + ...issue, + status: "completed|failed", + executed_at: timestamp, + error: errorMessage + } + }, + queue: [ + ...queue.map(item => + item.solution_id === solutionId + ? { ...item, status: "completed|failed" } + : item + ) + ], + context: { + ...state.context, + completed_count: newCompletedCount, + failed_count: newFailedCount + } + } +}; +``` + +## Error Handling + +| Error Type | Recovery | +|------------|----------| +| 任务执行失败 | 标记为失败,继续下一个 | +| 测试失败 | 不提交,标记为失败 | +| 提交失败 | 保存快照便于恢复 | +| Subagent 超时 | 记录超时,继续 | + +## Next Actions (Hints) + +- 执行完成:转入 action-complete 阶段 +- 有失败项:用户选择是否重试 +- 全部完成:生成最终报告 diff --git a/.codex/skills/codex-issue-plan-execute/phases/actions/action-init.md b/.codex/skills/codex-issue-plan-execute/phases/actions/action-init.md new file mode 100644 index 00000000..eeb74e21 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/phases/actions/action-init.md @@ -0,0 +1,86 @@ +# Action: Initialize + +初始化 Skill 执行状态和工作目录。 + +## Purpose + +设置初始状态,创建工作目录,准备执行环境。 + +## Preconditions + +- [ ] `state.status === "pending"` + +## Execution + +```javascript +async function execute(state) { + // 创建工作目录 + const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, ''); + const workDir = `.workflow/.scratchpad/codex-issue-${timestamp}`; + + Bash(`mkdir -p "${workDir}/solutions" "${workDir}/snapshots"`); + + // 初始化状态 + const initialState = { + status: "running", + phase: "initialized", + work_dir: workDir, + issues: {}, + queue: [], + completed_actions: ["action-init"], + context: { + total_issues: 0, + completed_count: 0, + failed_count: 0 + }, + errors: [], + created_at: new Date().toISOString(), + updated_at: new Date().toISOString() + }; + + // 保存初始状态 + Write(`${workDir}/state.json`, JSON.stringify(initialState, null, 2)); + Write(`${workDir}/state-history.json`, JSON.stringify([{ + timestamp: initialState.created_at, + phase: "init", + completed_actions: 1, + issues_count: 0 + }], null, 2)); + + console.log(`✓ Initialized: ${workDir}`); + + return { + stateUpdates: { + status: "running", + phase: "initialized", + work_dir: workDir, + completed_actions: ["action-init"] + } + }; +} +``` + +## State Updates + +```javascript +return { + stateUpdates: { + status: "running", + phase: "initialized", + work_dir: workDir, + completed_actions: ["action-init"] + } +}; +``` + +## Error Handling + +| Error Type | Recovery | +|------------|----------| +| 目录创建失败 | 检查权限,使用临时目录 | +| 文件写入失败 | 重试或切换存储位置 | + +## Next Actions (Hints) + +- 成功:进入 listing phase,执行 action-list +- 失败:中止工作流 diff --git a/.codex/skills/codex-issue-plan-execute/phases/actions/action-list.md b/.codex/skills/codex-issue-plan-execute/phases/actions/action-list.md new file mode 100644 index 00000000..bf2d48f1 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/phases/actions/action-list.md @@ -0,0 +1,165 @@ +# Action: List Issues + +列出 issues 并支持用户交互选择。 + +## Purpose + +展示当前所有 issues 的状态,收集用户的规划/执行意图。 + +## Preconditions + +- [ ] `state.status === "running"` + +## Execution + +```javascript +async function execute(state) { + // 1. 加载或初始化 issues + let issues = state.issues || {}; + + // 2. 从 ccw issue list 或提供的参数加载 issues + // 这取决于用户是否在命令行提供了 issue IDs + // 示例:ccw codex issue:plan-execute ISS-001,ISS-002 + + // 对于本次演示,我们假设从 issues.jsonl 加载 + try { + const issuesListOutput = Bash("ccw issue list --status registered,planned --json").output; + const issuesList = JSON.parse(issuesListOutput); + + issuesList.forEach(issue => { + if (!issues[issue.id]) { + issues[issue.id] = { + id: issue.id, + title: issue.title, + status: "registered", + solution_id: null, + planned_at: null, + executed_at: null, + error: null + }; + } + }); + } catch (error) { + console.log("Note: Could not load issues from ccw issue list"); + // 使用来自参数的 issues,或者空列表 + } + + // 3. 显示当前状态 + const totalIssues = Object.keys(issues).length; + const registeredCount = Object.values(issues).filter(i => i.status === "registered").length; + const plannedCount = Object.values(issues).filter(i => i.status === "planned").length; + const completedCount = Object.values(issues).filter(i => i.status === "completed").length; + + console.log("\n=== Issue Status ==="); + console.log(`Total: ${totalIssues} | Registered: ${registeredCount} | Planned: ${plannedCount} | Completed: ${completedCount}`); + + if (totalIssues === 0) { + console.log("\nNo issues found. Please create issues first using 'ccw issue init'"); + return { + stateUpdates: { + context: { + ...state.context, + total_issues: 0 + } + } + }; + } + + // 4. 显示详细列表 + console.log("\n=== Issue Details ==="); + Object.values(issues).forEach((issue, index) => { + const status = issue.status === "completed" ? "✓" : issue.status === "planned" ? "→" : "○"; + console.log(`${status} [${index + 1}] ${issue.id}: ${issue.title} (${issue.status})`); + }); + + // 5. 询问用户下一步 + const issueIds = Object.keys(issues); + const pendingIds = issueIds.filter(id => issues[id].status === "registered"); + + if (pendingIds.length === 0) { + console.log("\nNo unplanned issues. Ready to execute planned solutions."); + return { + stateUpdates: { + context: { + ...state.context, + total_issues: totalIssues + } + } + }; + } + + // 6. 显示选项 + console.log("\nNext action:"); + console.log("- Enter 'p' to PLAN selected issues"); + console.log("- Enter 'x' to EXECUTE planned solutions"); + console.log("- Enter 'a' to plan ALL pending issues"); + console.log("- Enter 'q' to QUIT"); + + const response = await AskUserQuestion({ + questions: [{ + question: "Select issues to plan (comma-separated numbers, or 'all'):", + header: "Selection", + multiSelect: false, + options: pendingIds.slice(0, 4).map(id => ({ + label: `${issues[id].id}: ${issues[id].title}`, + description: `Current status: ${issues[id].status}` + })) + }] + }); + + // 7. 更新 issues 状态为 "planning" + const selectedIds = []; + if (response.Selection === "all") { + selectedIds.push(...pendingIds); + } else { + // 解析用户选择 + selectedIds.push(response.Selection); + } + + selectedIds.forEach(issueId => { + if (issues[issueId]) { + issues[issueId].status = "planning"; + } + }); + + return { + stateUpdates: { + issues: issues, + context: { + ...state.context, + total_issues: totalIssues + } + } + }; +} +``` + +## State Updates + +```javascript +return { + stateUpdates: { + issues: issues, + context: { + total_issues: Object.keys(issues).length, + registered_count: registeredCount, + planned_count: plannedCount, + completed_count: completedCount + } + } +}; +``` + +## Error Handling + +| Error Type | Recovery | +|------------|----------| +| Issues 加载失败 | 使用空列表继续 | +| 用户输入无效 | 要求重新选择 | +| 列表显示异常 | 使用 JSON 格式输出 | + +## Next Actions (Hints) + +- 有 "planning" issues:执行 action-plan +- 无 pending issues:执行 action-execute +- 用户取消:中止 diff --git a/.codex/skills/codex-issue-plan-execute/phases/actions/action-plan.md b/.codex/skills/codex-issue-plan-execute/phases/actions/action-plan.md new file mode 100644 index 00000000..c05b1a50 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/phases/actions/action-plan.md @@ -0,0 +1,170 @@ +# Action: Plan Solutions + +为选中的 issues 生成执行方案。 + +## Purpose + +使用 subagent 分析 issues 并生成解决方案,支持多解决方案选择和自动绑定。 + +## Preconditions + +- [ ] `state.status === "running"` +- [ ] `issues with status === "planning"` exist + +## Execution + +```javascript +async function execute(state) { + const workDir = state.work_dir; + const issues = state.issues || {}; + + // 1. 识别需要规划的 issues + const planningIssues = Object.values(issues).filter(i => i.status === "planning"); + + if (planningIssues.length === 0) { + console.log("No issues to plan"); + return { stateUpdates: { issues } }; + } + + console.log(`\n=== Planning ${planningIssues.length} Issues ===`); + + // 2. 为每个 issue 生成规划 subagent + const planningAgents = planningIssues.map(issue => ({ + issue_id: issue.id, + issue_title: issue.title, + prompt: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json +4. Read schema: ~/.claude/workflows/cli-templates/schemas/solution-schema.json + +--- + +Goal: Plan solution for issue "${issue.id}: ${issue.title}" + +Scope: +- CAN DO: Explore codebase, design solutions, create tasks +- CANNOT DO: Execute solutions, modify production code +- Directory: ${process.cwd()} + +Task Description: +${issue.title} + +Deliverables: +- Create ONE primary solution +- Write to: ${workDir}/solutions/${issue.id}-plan.json +- Format: JSON following solution-schema.json + +Quality bar: +- Tasks have quantified acceptance.criteria +- Each task includes test.commands +- Solution follows schema exactly + +Return: JSON with solution_id, task_count, status +` + })); + + // 3. 执行规划(串行执行避免竞争) + for (const agent of planningAgents) { + console.log(`\n→ Planning: ${agent.issue_id}`); + + try { + // 对于 Codex,这里应该使用 spawn_agent + // 对于 Claude Code Task,使用 Task() + + // 模拟 Task 调用 (实际应该是 spawn_agent 对于 Codex) + const result = await Task({ + subagent_type: "universal-executor", + run_in_background: false, + description: `Plan solution for ${agent.issue_id}`, + prompt: agent.prompt + }); + + // 解析结果 + let planResult; + try { + planResult = typeof result === "string" ? JSON.parse(result) : result; + } catch { + planResult = { status: "executed", solution_id: `SOL-${agent.issue_id}-1` }; + } + + // 更新 issue 状态 + issues[agent.issue_id].status = "planned"; + issues[agent.issue_id].solution_id = planResult.solution_id || `SOL-${agent.issue_id}-1`; + issues[agent.issue_id].planned_at = new Date().toISOString(); + + console.log(`✓ ${agent.issue_id} → ${issues[agent.issue_id].solution_id}`); + + // 绑定解决方案 + try { + Bash(`ccw issue bind ${agent.issue_id} ${issues[agent.issue_id].solution_id}`); + } catch (error) { + console.log(`Note: Could not bind solution (${error.message})`); + } + + } catch (error) { + console.error(`✗ Planning failed for ${agent.issue_id}: ${error.message}`); + issues[agent.issue_id].status = "registered"; // 回退 + issues[agent.issue_id].error = error.message; + } + } + + // 4. 更新 issue 状态到 ccw + try { + Bash(`ccw issue update --from-planning`); + } catch { + console.log("Note: Could not update issue status"); + } + + return { + stateUpdates: { + issues: issues, + completed_actions: [...state.completed_actions, "action-plan"] + } + }; +} +``` + +## State Updates + +```javascript +return { + stateUpdates: { + issues: { + [issue.id]: { + ...issue, + status: "planned", + solution_id: solutionId, + planned_at: timestamp + } + }, + queue: [ + ...state.queue, + { + item_id: `S-${index}`, + issue_id: issue.id, + solution_id: solutionId, + status: "pending" + } + ] + } +}; +``` + +## Error Handling + +| Error Type | Recovery | +|------------|----------| +| Subagent 超时 | 标记为失败,继续下一个 | +| 无效解决方案 | 回退到 registered 状态 | +| 绑定失败 | 记录警告,但继续 | +| 文件写入失败 | 重试 3 次 | + +## Next Actions (Hints) + +- 所有 issues 规划完成:执行 action-execute +- 部分失败:用户选择是否继续或重试 +- 全部失败:返回 action-list 重新选择 diff --git a/.codex/skills/codex-issue-plan-execute/phases/orchestrator.md b/.codex/skills/codex-issue-plan-execute/phases/orchestrator.md new file mode 100644 index 00000000..db23f8ac --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/phases/orchestrator.md @@ -0,0 +1,210 @@ +# Orchestrator - Dual-Agent Pipeline Architecture + +主流程编排器:创建两个持久化 agent(规划和执行),流水线式处理所有 issue。 + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────┐ +│ Main Orchestrator (Claude Code) │ +│ 流水线式分配任务给两个持久化 agent │ +└──────┬────────────────────────────────────────┬────────┘ + │ send_input │ send_input + │ (逐个 issue) │ (逐个 solution) + ▼ ▼ +┌──────────────────┐ ┌──────────────────┐ +│ Planning Agent │ │ Execution Agent │ +│ (持久化) │ │ (持久化) │ +│ │ │ │ +│ • 接收 issue │ │ • 接收 solution │ +│ • 设计方案 │ │ • 执行 tasks │ +│ • 返回 solution │ │ • 返回执行结果 │ +└──────────────────┘ └──────────────────┘ + ▲ ▲ + └────────────────┬─────────────────────┘ + wait for completion +``` + +## Main Orchestrator Pseudocode + +```javascript +async function mainOrchestrator(workDir, issues) { + const planningResults = { results: [] }; // 统一存储 + const executionResults = { results: [] }; // 统一存储 + + // 1. Create persistent agents (never close until done) + const planningAgentId = spawn_agent({ + message: Read('prompts/planning-agent-system.md') + }); + + const executionAgentId = spawn_agent({ + message: Read('prompts/execution-agent-system.md') + }); + + try { + // Phase 1: Planning Pipeline + for (const issue of issues) { + // Send issue to planning agent (不新建 agent,用 send_input) + send_input({ + id: planningAgentId, + message: buildPlanningRequest(issue) + }); + + // Wait for solution + const result = wait({ ids: [planningAgentId], timeout_ms: 300000 }); + const solution = parseResponse(result); + + // Store in unified results + planningResults.results.push({ + issue_id: issue.id, + solution: solution, + status: solution ? "completed" : "failed" + }); + } + + // Save planning results once + Write(`${workDir}/planning-results.json`, JSON.stringify(planningResults, null, 2)); + + // Phase 2: Execution Pipeline + for (const planning of planningResults.results) { + if (planning.status !== "completed") continue; + + // Send solution to execution agent (不新建 agent,用 send_input) + send_input({ + id: executionAgentId, + message: buildExecutionRequest(planning.solution) + }); + + // Wait for execution result + const result = wait({ ids: [executionAgentId], timeout_ms: 600000 }); + const execResult = parseResponse(result); + + // Store in unified results + executionResults.results.push({ + issue_id: planning.issue_id, + status: execResult?.status || "failed", + commit_hash: execResult?.commit_hash + }); + } + + // Save execution results once + Write(`${workDir}/execution-results.json`, JSON.stringify(executionResults, null, 2)); + + } finally { + // Close agents after ALL issues processed + close_agent({ id: planningAgentId }); + close_agent({ id: executionAgentId }); + } + + generateFinalReport(workDir, planningResults, executionResults); +} +``` + +## Key Design Principles + +### 1. Agent Persistence + +- **Creating**: Each agent created once at the beginning +- **Running**: Agents continue running, receiving multiple `send_input` calls +- **Closing**: Agents closed only after all issues processed +- **Benefit**: Agent maintains context across multiple issues + +### 2. Unified Results Storage + +```json +// planning-results.json +{ + "phase": "planning", + "created_at": "2025-01-29T12:00:00Z", + "results": [ + { + "issue_id": "ISS-001", + "solution_id": "SOL-ISS-001-1", + "status": "completed", + "solution": { "id": "...", "tasks": [...] }, + "planned_at": "2025-01-29T12:05:00Z" + }, + { + "issue_id": "ISS-002", + "solution_id": "SOL-ISS-002-1", + "status": "completed", + "solution": { "id": "...", "tasks": [...] }, + "planned_at": "2025-01-29T12:10:00Z" + } + ] +} + +// execution-results.json +{ + "phase": "execution", + "created_at": "2025-01-29T12:15:00Z", + "results": [ + { + "issue_id": "ISS-001", + "solution_id": "SOL-ISS-001-1", + "status": "completed", + "commit_hash": "abc123def", + "files_modified": ["src/auth.ts"], + "executed_at": "2025-01-29T12:20:00Z" + } + ] +} +``` + +**优点**: +- 单一 JSON 文件,易于查询和分析 +- 完整的处理历史 +- 减少文件 I/O 次数 + +### 3. Pipeline Flow + +``` +Issue 1 → Planning Agent → Wait → Solution 1 (save) +Issue 2 → Planning Agent → Wait → Solution 2 (save) +Issue 3 → Planning Agent → Wait → Solution 3 (save) +[All saved to planning-results.json] + +Solution 1 → Execution Agent → Wait → Result 1 (save) +Solution 2 → Execution Agent → Wait → Result 2 (save) +Solution 3 → Execution Agent → Wait → Result 3 (save) +[All saved to execution-results.json] +``` + +### 4. Agent Communication via send_input + +Instead of creating new agents, reuse persistent ones: + +```javascript +// ❌ OLD: Create new agent per issue +for (const issue of issues) { + const agentId = spawn_agent({ message: prompt }); + const result = wait({ ids: [agentId] }); + close_agent({ id: agentId }); // ← Expensive! +} + +// ✅ NEW: Persistent agent with send_input +const agentId = spawn_agent({ message: initialPrompt }); +for (const issue of issues) { + send_input({ id: agentId, message: taskPrompt }); // ← Reuse! + const result = wait({ ids: [agentId] }); +} +close_agent({ id: agentId }); // ← Single cleanup +``` + +### 5. Path Resolution for Global Installation + +When this skill is installed globally: +- **Skill-internal paths**: Use relative paths from skill root (e.g., `prompts/planning-agent-system.md`) +- **Project paths**: Use project-relative paths starting with `.` (e.g., `.workflow/project-tech.json`) +- **User-home paths**: Use `~` prefix (e.g., `~/.codex/agents/...`) +- **Working directory**: Always relative to the project root when skill executes + +## Benefits of This Architecture + +| 方面 | 优势 | +|------|------| +| **性能** | Agent 创建/销毁开销仅一次(而非 N 次) | +| **上下文** | Agent 在多个任务间保持上下文 | +| **存储** | 统一的 JSON 文件,易于追踪和查询 | +| **通信** | 通过 send_input 实现 agent 间的数据传递 | +| **可维护性** | 流水线结构清晰,易于调试 | diff --git a/.codex/skills/codex-issue-plan-execute/phases/state-schema.md b/.codex/skills/codex-issue-plan-execute/phases/state-schema.md new file mode 100644 index 00000000..ee5a686b --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/phases/state-schema.md @@ -0,0 +1,136 @@ +# State Schema Definition + +状态结构定义和验证规则。 + +## 初始状态 + +```json +{ + "status": "pending", + "phase": "init", + "work_dir": "", + "issues": {}, + "queue": [], + "completed_actions": [], + "context": { + "total_issues": 0, + "completed_count": 0, + "failed_count": 0 + }, + "errors": [], + "created_at": "ISO-8601", + "updated_at": "ISO-8601" +} +``` + +## 状态转移 + +``` +pending + ↓ +init (Action-Init) + ↓ +running + ├→ list (Action-List) → Display issues + ├→ plan (Action-Plan) → Plan issues + ├→ execute (Action-Execute) → Execute solutions + ├→ back to list/plan/execute loop + │ + └→ complete (Action-Complete) → Finalize + ↓ +completed +``` + +## 字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `status` | string | "pending"\|"running"\|"completed" - 全局状态 | +| `phase` | string | "init"\|"listing"\|"planning"\|"executing"\|"complete" - 当前阶段 | +| `work_dir` | string | 工作目录路径 | +| `issues` | object | Issue 状态映射 `{issue_id: IssueState}` | +| `queue` | array | 待执行队列 | +| `completed_actions` | array | 已执行动作 ID 列表 | +| `context` | object | 执行上下文信息 | +| `errors` | array | 错误日志 | + +## Issue 状态 + +```json +{ + "id": "ISS-xxx", + "title": "Issue title", + "status": "registered|planning|planned|executing|completed|failed", + "solution_id": "SOL-xxx-1", + "planned_at": "ISO-8601", + "executed_at": "ISO-8601", + "error": null +} +``` + +## Queue Item + +```json +{ + "item_id": "S-1", + "issue_id": "ISS-xxx", + "solution_id": "SOL-xxx-1", + "status": "pending|executing|completed|failed" +} +``` + +## 验证函数 + +```javascript +function validateState(state) { + // Required fields + if (!state.status) throw new Error("Missing: status"); + if (!state.phase) throw new Error("Missing: phase"); + if (!state.work_dir) throw new Error("Missing: work_dir"); + + // Valid status values + const validStatus = ["pending", "running", "completed"]; + if (!validStatus.includes(state.status)) { + throw new Error(`Invalid status: ${state.status}`); + } + + // Issues structure + if (typeof state.issues !== "object") { + throw new Error("issues must be object"); + } + + // Queue is array + if (!Array.isArray(state.queue)) { + throw new Error("queue must be array"); + } + + return true; +} +``` + +## 状态持久化 + +```javascript +// 保存状态 +function saveState(state) { + const statePath = `${state.work_dir}/state.json`; + Write(statePath, JSON.stringify(state, null, 2)); + + // 保存历史 + const historyPath = `${state.work_dir}/state-history.json`; + const history = Read(historyPath).then(JSON.parse).catch(() => []); + history.push({ + timestamp: new Date().toISOString(), + phase: state.phase, + completed_actions: state.completed_actions.length, + issues_count: Object.keys(state.issues).length + }); + Write(historyPath, JSON.stringify(history, null, 2)); +} + +// 加载状态 +function loadState(workDir) { + const statePath = `${workDir}/state.json`; + return JSON.parse(Read(statePath)); +} +``` diff --git a/.codex/skills/codex-issue-plan-execute/prompts/execution-agent-system.md b/.codex/skills/codex-issue-plan-execute/prompts/execution-agent-system.md new file mode 100644 index 00000000..090ce603 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/prompts/execution-agent-system.md @@ -0,0 +1,136 @@ +# Execution Agent System Prompt + +You are the **Execution Agent** for the Codex issue planning and execution workflow. + +## Your Role + +You are responsible for implementing planned solutions and verifying they work correctly. You will: + +1. **Receive solutions** one at a time via `send_input` messages from the main orchestrator +2. **Implement each solution** by executing the planned tasks in order +3. **Verify acceptance criteria** are met through testing +4. **Create commits** for each completed task +5. **Return execution results** with details on what was implemented +6. **Maintain context** across multiple solutions without closing + +## How to Operate + +### Input Format + +You will receive `send_input` messages with this structure: + +```json +{ + "type": "execute_solution", + "issue_id": "ISS-001", + "solution_id": "SOL-ISS-001-1", + "solution": { + "id": "SOL-ISS-001-1", + "tasks": [ /* task objects */ ], + /* full solution JSON */ + }, + "project_root": "/path/to/project" +} +``` + +### Your Workflow for Each Solution + +1. **Read the mandatory files** (only on first run): + - Role definition from ~/.codex/agents/issue-execute-agent.md + - Project tech stack from .workflow/project-tech.json + - Project guidelines from .workflow/project-guidelines.json + - Execution result schema + +2. **Prepare for execution**: + - Review all planned tasks and dependencies + - Ensure task ordering respects dependencies + - Identify files that need modification + - Plan code structure and implementation + +3. **Execute each task in order**: + - Read existing code and understand context + - Implement modifications according to specs + - Run tests immediately after changes + - Verify acceptance criteria are met + - Create commit with descriptive message + +4. **Handle task dependencies**: + - Execute tasks in dependency order + - Stop immediately if a dependency fails + - Report which task failed and why + - Include error details in result + +5. **Verify all acceptance criteria**: + - Run test commands specified in task + - Ensure all acceptance criteria are met + - Check for regressions in existing tests + - Document test results + +6. **Generate execution result JSON**: + - Track each task's status (completed/failed) + - Record all files modified + - Record all commits created + - Include test results and verification status + - Return final commit hash + +7. **Return structured response**: + ```json + { + "status": "completed|failed", + "execution_result_id": "EXR-ISS-001-1", + "issue_id": "ISS-001", + "solution_id": "SOL-ISS-001-1", + "tasks_completed": 3, + "files_modified": 5, + "commits": 3, + "final_commit_hash": "xyz789abc", + "verification": { + "all_tests_passed": true, + "all_acceptance_met": true, + "no_regressions": true + } + } + ``` + +### Quality Requirements + +- **Completeness**: All tasks must be executed +- **Correctness**: All acceptance criteria must be verified +- **Traceability**: Each change must be tracked with commits +- **Safety**: All tests must pass before finalizing + +### Context Preservation + +You will receive multiple solutions sequentially. Do NOT close after each solution. Instead: +- Process each solution independently +- Maintain awareness of the codebase state after modifications +- Use consistent coding style with the project +- Reference patterns established in previous solutions + +### Error Handling + +If you cannot execute a solution: +1. Clearly state what went wrong +2. Specify which task failed and why +3. Include the error message or test output +4. Return status: "failed" +5. Continue waiting for the next solution + +## Communication Protocol + +After processing each solution, you will: +1. Return the result JSON +2. Wait for the next `send_input` with a new solution +3. Continue this cycle until instructed to close + +**IMPORTANT**: Do NOT attempt to close yourself. The orchestrator will close you when all execution is complete. + +## Key Principles + +- **Follow the plan exactly** - implement what was designed, don't deviate +- **Test thoroughly** - run all specified tests before committing +- **Communicate changes** - create commits with descriptive messages +- **Verify acceptance** - ensure every criterion is met before marking complete +- **Maintain code quality** - follow existing project patterns and style +- **Handle failures gracefully** - stop immediately if something fails, report clearly +- **Preserve state** - remember what you've done across multiple solutions diff --git a/.codex/skills/codex-issue-plan-execute/prompts/execution-agent.md b/.codex/skills/codex-issue-plan-execute/prompts/execution-agent.md new file mode 100644 index 00000000..3769a32f --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/prompts/execution-agent.md @@ -0,0 +1,135 @@ +# Execution Agent Prompt + +执行 agent 的提示词模板。 + +## MANDATORY FIRST STEPS (Agent Execute) + +1. **Read role definition**: ~/.codex/agents/issue-execute-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json +4. Read schema: ~/.claude/workflows/cli-templates/schemas/execution-result-schema.json + +--- + +## Goal + +Execute solution for issue "{ISSUE_ID}: {ISSUE_TITLE}" + +## Scope + +- **CAN DO**: + - Read and understand planned solution + - Implement code changes + - Execute tests and validation + - Create commits + - Handle errors and rollback + +- **CANNOT DO**: + - Modify solution design + - Skip acceptance criteria + - Bypass test requirements + - Deploy to production + +- **Directory**: {PROJECT_ROOT} + +## Task Description + +Planned Solution: {SOLUTION_JSON} + +## Deliverables + +### Primary Output: Execution Result JSON + +```json +{ + "id": "EXR-{ISSUE_ID}-1", + "issue_id": "{ISSUE_ID}", + "solution_id": "SOL-{ISSUE_ID}-1", + "status": "completed|failed", + "executed_tasks": [ + { + "task_id": "T1", + "title": "Task title", + "status": "completed|failed", + "files_modified": ["src/auth.ts", "src/auth.test.ts"], + "commits": [ + { + "hash": "abc123def", + "message": "Implement authentication" + } + ], + "test_results": { + "passed": 15, + "failed": 0, + "command": "npm test -- auth.test.ts" + }, + "acceptance_met": true, + "execution_time_minutes": 25, + "errors": [] + } + ], + "overall_stats": { + "total_tasks": 3, + "completed": 3, + "failed": 0, + "total_files_modified": 5, + "total_commits": 3, + "total_time_minutes": 75 + }, + "final_commit": { + "hash": "xyz789abc", + "message": "Resolve issue ISS-001: Feature implementation" + }, + "verification": { + "all_tests_passed": true, + "all_acceptance_met": true, + "no_regressions": true + } +} +``` + +### Validation + +Ensure: +- [ ] All planned tasks executed +- [ ] All acceptance criteria verified +- [ ] Tests pass without failures +- [ ] All commits created with descriptive messages +- [ ] Execution result follows schema exactly +- [ ] No breaking changes introduced + +### Return JSON + +```json +{ + "status": "completed|failed", + "execution_result_id": "EXR-{ISSUE_ID}-1", + "issue_id": "{ISSUE_ID}", + "tasks_completed": 3, + "files_modified": 5, + "commits": 3, + "verification": { + "all_tests_passed": true, + "all_acceptance_met": true, + "no_regressions": true + }, + "final_commit_hash": "xyz789abc", + "errors": [] +} +``` + +## Quality Standards + +- **Completeness**: All tasks executed, all acceptance criteria met +- **Correctness**: Tests pass, no regressions, code quality maintained +- **Traceability**: Each change tracked with commits and test results +- **Safety**: Changes verified before final commit + +## Success Criteria + +✓ All planned tasks completed +✓ All acceptance criteria verified and met +✓ Unit tests pass with 100% success rate +✓ No regressions in existing functionality +✓ Final commit created with descriptive message +✓ Execution result JSON is valid and complete diff --git a/.codex/skills/codex-issue-plan-execute/prompts/planning-agent-system.md b/.codex/skills/codex-issue-plan-execute/prompts/planning-agent-system.md new file mode 100644 index 00000000..6edf35d8 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/prompts/planning-agent-system.md @@ -0,0 +1,107 @@ +# Planning Agent System Prompt + +You are the **Planning Agent** for the Codex issue planning and execution workflow. + +## Your Role + +You are responsible for analyzing issues and creating detailed, executable solution plans. You will: + +1. **Receive issues** one at a time via `send_input` messages from the main orchestrator +2. **Analyze each issue** by exploring the codebase, understanding requirements, and identifying the solution approach +3. **Design a comprehensive solution** with task breakdown, acceptance criteria, and implementation steps +4. **Return a structured solution JSON** that the Execution Agent will implement +5. **Maintain context** across multiple issues without closing + +## How to Operate + +### Input Format + +You will receive `send_input` messages with this structure: + +```json +{ + "type": "plan_issue", + "issue_id": "ISS-001", + "issue_title": "Add user authentication", + "issue_description": "Implement JWT-based authentication for API endpoints", + "project_root": "/path/to/project" +} +``` + +### Your Workflow for Each Issue + +1. **Read the mandatory files** (only on first run): + - Role definition from ~/.codex/agents/issue-plan-agent.md + - Project tech stack from .workflow/project-tech.json + - Project guidelines from .workflow/project-guidelines.json + - Solution schema from ~/.claude/workflows/cli-templates/schemas/solution-schema.json + +2. **Analyze the issue**: + - Understand the problem and requirements + - Explore relevant code files + - Identify integration points + - Check for existing patterns + +3. **Design the solution**: + - Break down into concrete tasks + - Define file modifications needed + - Create implementation steps + - Define test commands and acceptance criteria + - Identify task dependencies + +4. **Generate solution JSON**: + - Follow the solution schema exactly + - Include all required fields + - Set realistic time estimates + - Assign appropriate priorities + +5. **Return structured response**: + ```json + { + "status": "completed|failed", + "solution_id": "SOL-ISS-001-1", + "task_count": 3, + "score": 0.95, + "solution": { /* full solution object */ } + } + ``` + +### Quality Requirements + +- **Completeness**: All required fields must be present +- **Clarity**: Each task must have specific, measurable acceptance criteria +- **Correctness**: No circular dependencies in task ordering +- **Pragmatism**: Solution must be minimal and focused on the issue + +### Context Preservation + +You will receive multiple issues sequentially. Do NOT close after each issue. Instead: +- Process each issue independently +- Maintain awareness of the workflow context +- Use consistent naming conventions across solutions +- Reference previous patterns if applicable + +### Error Handling + +If you cannot complete planning for an issue: +1. Clearly state what went wrong +2. Provide the reason (missing context, unclear requirements, etc.) +3. Return status: "failed" +4. Continue waiting for the next issue + +## Communication Protocol + +After processing each issue, you will: +1. Return the response JSON +2. Wait for the next `send_input` with a new issue +3. Continue this cycle until instructed to close + +**IMPORTANT**: Do NOT attempt to close yourself. The orchestrator will close you when all planning is complete. + +## Key Principles + +- **Focus on analysis and design** - leave implementation to the Execution Agent +- **Be thorough** - explore code and understand patterns before proposing solutions +- **Be pragmatic** - solutions should be achievable within 1-2 hours +- **Follow schema** - every solution JSON must validate against the solution schema +- **Maintain context** - remember project context across multiple issues diff --git a/.codex/skills/codex-issue-plan-execute/prompts/planning-agent.md b/.codex/skills/codex-issue-plan-execute/prompts/planning-agent.md new file mode 100644 index 00000000..747671f5 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/prompts/planning-agent.md @@ -0,0 +1,122 @@ +# Planning Agent Prompt + +规划 agent 的提示词模板。 + +## MANDATORY FIRST STEPS (Agent Execute) + +1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json +4. Read schema: ~/.claude/workflows/cli-templates/schemas/solution-schema.json + +--- + +## Goal + +Plan solution for issue "{ISSUE_ID}: {ISSUE_TITLE}" + +## Scope + +- **CAN DO**: + - Explore codebase + - Analyze issue and design solutions + - Create executable task breakdown + - Define acceptance criteria + +- **CANNOT DO**: + - Execute solutions + - Modify production code + - Make commits + +- **Directory**: {PROJECT_ROOT} + +## Task Description + +{ISSUE_DESCRIPTION} + +## Deliverables + +### Primary Output: Solution JSON + +```json +{ + "id": "SOL-{ISSUE_ID}-1", + "issue_id": "{ISSUE_ID}", + "description": "Brief description of solution", + "tasks": [ + { + "id": "T1", + "title": "Task title", + "action": "Create|Modify|Fix|Refactor", + "scope": "file path or directory", + "description": "What to do", + "modification_points": [...], + "implementation": ["Step 1", "Step 2"], + "test": { + "commands": ["npm test -- file.test.ts"], + "unit": ["Requirement 1"] + }, + "acceptance": { + "criteria": ["Criterion 1: Must pass"], + "verification": ["Run tests"] + }, + "depends_on": [], + "estimated_minutes": 30, + "priority": 1 + } + ], + "exploration_context": { + "relevant_files": ["path/to/file.ts"], + "patterns": "Follow existing pattern", + "integration_points": "Used by service X" + }, + "analysis": { + "risk": "low|medium|high", + "impact": "low|medium|high", + "complexity": "low|medium|high" + }, + "score": 0.95, + "is_bound": true +} +``` + +### Validation + +Ensure: +- [ ] All required fields present +- [ ] No circular dependencies in task.depends_on +- [ ] Each task has quantified acceptance.criteria +- [ ] Solution follows solution-schema.json exactly +- [ ] Score reflects quality (0.8+ for approval) + +### Return JSON + +```json +{ + "status": "completed|failed", + "solution_id": "SOL-{ISSUE_ID}-1", + "task_count": 3, + "score": 0.95, + "validation": { + "schema_valid": true, + "criteria_quantified": true, + "no_circular_deps": true + }, + "errors": [] +} +``` + +## Quality Standards + +- **Completeness**: All required fields, no missing sections +- **Clarity**: Acceptance criteria must be specific and measurable +- **Correctness**: No circular dependencies, valid schema +- **Pragmatism**: Solution is minimal and focused + +## Success Criteria + +✓ Solution JSON is valid and follows schema +✓ All tasks have acceptance.criteria +✓ No circular dependencies detected +✓ Score >= 0.8 +✓ Estimated total time <= 2 hours diff --git a/.codex/skills/codex-issue-plan-execute/specs/issue-handling.md b/.codex/skills/codex-issue-plan-execute/specs/issue-handling.md new file mode 100644 index 00000000..4e8b4c20 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/specs/issue-handling.md @@ -0,0 +1,187 @@ +# Issue Handling Specification + +Issue 处理的核心规范和约定。 + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| Phase: action-list | Issue 列表展示 | Issue Status & Display | +| Phase: action-plan | Issue 规划 | Solution Planning | +| Phase: action-execute | Issue 执行 | Solution Execution | + +--- + +## Issue Structure + +### 基本字段 + +```json +{ + "id": "ISS-20250129-001", + "title": "Fix authentication token expiration bug", + "description": "Tokens expire too quickly in production", + "status": "registered", + "priority": "high", + "tags": ["auth", "bugfix"], + "created_at": "2025-01-29T10:00:00Z", + "updated_at": "2025-01-29T10:00:00Z" +} +``` + +### 工作流状态 + +| Status | Phase | 说明 | +|--------|-------|------| +| `registered` | Initial | Issue 已创建,待规划 | +| `planning` | List → Plan | 正在规划中 | +| `planned` | Plan → Execute | 规划完成,解决方案已绑定 | +| `executing` | Execute | 正在执行 | +| `completed` | Execute → Complete | 执行完成 | +| `failed` | Any | 执行失败 | + +### 工作流字段 + +```json +{ + "id": "ISS-xxx", + "status": "registered|planning|planned|executing|completed|failed", + "solution_id": "SOL-xxx-1", + "planned_at": "2025-01-29T11:00:00Z", + "executed_at": "2025-01-29T12:00:00Z", + "error": null +} +``` + +## Issue 列表显示 + +### 格式规范 + +``` +Status Matrix: +Total: 5 | Registered: 2 | Planned: 2 | Completed: 1 + +Issue Details: +○ [1] ISS-001: Fix login bug (registered) +→ [2] ISS-002: Add MFA support (planning) +✓ [3] ISS-003: Refactor auth (completed) +✗ [4] ISS-004: Update password policy (failed) +``` + +### 显示字段 + +- ID: 唯一标识 +- Title: 简短描述 +- Status: 当前状态 +- Solution ID: 绑定的解决方案(如有) + +## Solution Planning + +### 规划输入 + +- Issue ID 和 Title +- Issue 描述和上下文 +- 项目技术栈和指南 + +### 规划输出 + +- Solution ID:`SOL-{issue-id}-{sequence}` +- Tasks 数组:可执行的任务列表 +- Acceptance Criteria:验收标准 +- 估计时间 + +### Planning Subagent 职责 + +1. 分析 issue 描述 +2. 探索相关代码路径 +3. 设计解决方案 +4. 分解为可执行任务 +5. 定义验收条件 + +### 多解决方案处理 + +- 如果生成多个方案,需要用户选择 +- 选择后绑定主方案到 issue +- 备选方案保存但不自动执行 + +## Solution Execution + +### 执行顺序 + +1. 加载已规划的解决方案 +2. 逐个执行每个 solution 中的所有 tasks +3. 每个 task:implement → test → verify +4. 完成后提交一次 + +### Execution Subagent 职责 + +1. 加载 solution JSON +2. 实现所有任务 +3. 运行测试 +4. 验收条件检查 +5. 提交代码并返回结果 + +### 错误恢复 + +- Task 失败:不提交,标记 solution 为失败 +- 提交失败:创建快照便于恢复 +- Subagent 超时:记录并继续下一个 + +## 批量处理约定 + +### 输入格式 + +```bash +# 单个 issue +codex issue:plan-execute ISS-001 + +# 多个 issues +codex issue:plan-execute ISS-001,ISS-002,ISS-003 + +# 交互式 +codex issue:plan-execute +``` + +### 处理策略 + +- 规划:可并行,但为保持一致性这里采用串行 +- 执行:必须串行(避免冲突提交) +- 队列:FIFO,无优先级排序 + +## 状态持久化 + +### 保存位置 + +``` +.workflow/.scratchpad/codex-issue-{timestamp}/ +├── state.json # 当前状态快照 +├── state-history.json # 状态变更历史 +├── queue.json # 执行队列 +├── solutions/ # 解决方案文件 +├── snapshots/ # 流程快照 +└── final-report.md # 最终报告 +``` + +### 快照用途 + +- 流程恢复:允许从中断点恢复 +- 调试:记录每个阶段的状态变化 +- 审计:跟踪完整的执行过程 + +## 质量保证 + +### 验收清单 + +- [ ] Issue 规范明确 +- [ ] Solution 遵循 schema +- [ ] All tasks 有 acceptance criteria +- [ ] 执行成功率 >= 80% +- [ ] 报告生成完整 + +### 错误分类 + +| 级别 | 类型 | 处理 | +|------|------|------| +| Critical | 规划失败、提交失败 | 中止该 issue | +| Warning | 测试失败、条件未满足 | 记录但继续 | +| Info | 超时、网络延迟 | 日志记录 | diff --git a/.codex/skills/codex-issue-plan-execute/specs/quality-standards.md b/.codex/skills/codex-issue-plan-execute/specs/quality-standards.md new file mode 100644 index 00000000..45371b7e --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/specs/quality-standards.md @@ -0,0 +1,231 @@ +# Quality Standards + +质量评估标准和验收条件。 + +## Quality Dimensions + +### 1. Completeness (完整性) - 25% + +**定义**:所有必需的结构和字段都存在 + +- [ ] 所有 issues 都有规划或执行结果 +- [ ] 每个 solution 都有完整的 task 列表 +- [ ] 每个 task 都有 acceptance criteria +- [ ] 状态日志完整记录 + +**评分**: +- 90-100%:全部完整,可能有可选字段缺失 +- 70-89%:主要字段完整,部分可选字段缺失 +- 50-69%:核心字段完整,重要字段缺失 +- <50%:结构不完整 + +### 2. Consistency (一致性) - 25% + +**定义**:整个工作流中的术语、格式、风格统一 + +- [ ] Issue ID/Solution ID 格式统一 +- [ ] Status 值遵循规范 +- [ ] Task 结构一致 +- [ ] 时间戳格式一致(ISO-8601) + +**评分**: +- 90-100%:完全一致,无格式混乱 +- 70-89%:大部分一致,偶有格式变化 +- 50-69%:半数一致,混乱明显 +- <50%:严重不一致 + +### 3. Correctness (正确性) - 25% + +**定义**:执行过程中没有错误,验收条件都通过 + +- [ ] 无 DAG 循环依赖 +- [ ] 所有测试通过 +- [ ] 所有 acceptance criteria 验证通过 +- [ ] 无代码冲突 + +**评分**: +- 90-100%:完全正确,无错误 +- 70-89%:基本正确,<10% 错误率 +- 50-69%:有明显错误,10-30% 错误率 +- <50%:错误过多,>30% 错误率 + +### 4. Clarity (清晰度) - 25% + +**定义**:文档清晰易读,逻辑清晰 + +- [ ] Task 描述明确可操作 +- [ ] Acceptance criteria 具体明确 +- [ ] 报告结构清晰,易理解 +- [ ] 错误信息详细有帮助 + +**评分**: +- 90-100%:非常清晰,一目了然 +- 70-89%:大部分清晰,有基本可读性 +- 50-69%:部分清晰,理解有难度 +- <50%:极不清晰,难以理解 + +## Quality Gates + +### Pass (通过) + +**条件**:总分 >= 80% + +**结果**:工作流正常完成,可进入下一阶段 + +**检查清单**: +- [ ] 所有 issues 已规划或执行 +- [ ] 成功率 >= 80% +- [ ] 无关键错误 +- [ ] 报告完整 + +### Review (需审查) + +**条件**:总分 60-79% + +**结果**:工作流部分完成,有可改进项 + +**常见问题**: +- 部分 task 失败 +- 某些验收条件未满足 +- 文档不够完整 + +**改进方式**: +- 检查失败的 task +- 添加缺失的文档 +- 优化工作流配置 + +### Fail (失败) + +**条件**:总分 < 60% + +**结果**:工作流失败,需重做 + +**常见原因**: +- 关键 task 失败 +- 规划过程中断 +- 系统错误过多 +- 无法生成有效报告 + +**恢复方式**: +- 从快照恢复 +- 修复根本问题 +- 重新规划和执行 + +## Issue Classification + +### Errors (必须修复) + +| 错误 | 影响 | 处理 | +|------|------|------| +| DAG 循环依赖 | Critical | 中止规划 | +| 任务无 acceptance | High | 补充条件 | +| 提交失败 | High | 调查并重试 | +| 规划 subagent 超时 | Medium | 重试或跳过 | +| 无效的 solution ID | Medium | 重新生成 | + +### Warnings (应该修复) + +| 警告 | 影响 | 处理 | +|------|------|------| +| Task 执行时间过长 | Medium | 考虑拆分 | +| 测试覆盖率低 | Medium | 补充测试 | +| 多个解决方案 | Low | 明确选择 | +| Criteria 不具体 | Low | 改进措辞 | + +### Info (可选改进) + +| 信息 | 说明 | +|------|------| +| 建议任务数 | 2-7 个任务为最优 | +| 时间建议 | 总耗时 <= 2 小时为佳 | +| 代码风格 | 检查是否遵循项目规范 | + +## 执行检查清单 + +### 规划阶段 + +- [ ] Issue 描述清晰 +- [ ] 生成了有效的 solution +- [ ] 所有 task 有 acceptance criteria +- [ ] 依赖关系正确 + +### 执行阶段 + +- [ ] 每个 task 实现完整 +- [ ] 所有测试通过 +- [ ] 所有 acceptance criteria 验证通过 +- [ ] 提交信息规范 + +### 完成阶段 + +- [ ] 生成了最终报告 +- [ ] 统计信息准确 +- [ ] 状态持久化完整 +- [ ] 快照保存无误 + +## 自动化验证函数 + +```javascript +function runQualityChecks(workDir) { + const state = JSON.parse(Read(`${workDir}/state.json`)); + const issues = state.issues || {}; + + const scores = { + completeness: checkCompleteness(issues), + consistency: checkConsistency(state), + correctness: checkCorrectness(issues), + clarity: checkClarity(state) + }; + + const overall = Object.values(scores).reduce((a, b) => a + b) / 4; + + return { + scores: scores, + overall: overall.toFixed(1), + gate: overall >= 80 ? 'pass' : overall >= 60 ? 'review' : 'fail', + details: { + issues_total: Object.keys(issues).length, + completed: Object.values(issues).filter(i => i.status === 'completed').length, + failed: Object.values(issues).filter(i => i.status === 'failed').length + } + }; +} +``` + +## 报告模板 + +```markdown +# Quality Report + +## Scores + +| Dimension | Score | Status | +|-----------|-------|--------| +| Completeness | 90% | ✓ | +| Consistency | 85% | ✓ | +| Correctness | 92% | ✓ | +| Clarity | 88% | ✓ | +| **Overall** | **89%** | **PASS** | + +## Issues Summary + +- Total: 10 +- Completed: 8 (80%) +- Failed: 2 (20%) +- Pending: 0 (0%) + +## Recommendations + +1. ... +2. ... + +## Errors & Warnings + +### Errors (0) + +None + +### Warnings (1) + +- Task T4 in ISS-003 took 45 minutes (expected 30) +``` diff --git a/.codex/skills/codex-issue-plan-execute/specs/solution-schema.md b/.codex/skills/codex-issue-plan-execute/specs/solution-schema.md new file mode 100644 index 00000000..368925c2 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/specs/solution-schema.md @@ -0,0 +1,270 @@ +# Solution Schema Specification + +解决方案数据结构和验证规则。 + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| Phase: action-plan | Solution 生成 | Solution Structure | +| Phase: action-execute | Task 解析 | Task Definition | + +--- + +## Solution Structure + +### 完整 Schema + +```json +{ + "id": "SOL-ISS-001-1", + "issue_id": "ISS-001", + "description": "Fix authentication token expiration by extending TTL", + "strategy_type": "bugfix", + "created_at": "2025-01-29T11:00:00Z", + "tasks": [ + { + "id": "T1", + "title": "Update token TTL configuration", + "action": "Modify", + "scope": "src/config/auth.ts", + "description": "Increase JWT token expiration from 1h to 24h", + "modification_points": [ + { + "file": "src/config/auth.ts", + "target": "JWT_EXPIRY", + "change": "Change value from 3600 to 86400" + } + ], + "implementation": [ + "Open src/config/auth.ts", + "Locate JWT_EXPIRY constant", + "Update value: 3600 → 86400", + "Add comment explaining change" + ], + "test": { + "commands": ["npm test -- auth.config.test.ts"], + "unit": ["Token expiration should be 24h"], + "integration": [] + }, + "acceptance": { + "criteria": [ + "Unit tests pass", + "Token TTL is correctly set", + "No breaking changes to API" + ], + "verification": [ + "Run: npm test", + "Manual: Verify token in console" + ] + }, + "depends_on": [], + "estimated_minutes": 15, + "priority": 1 + } + ], + "exploration_context": { + "relevant_files": [ + "src/config/auth.ts", + "src/services/auth.service.ts", + "tests/auth.test.ts" + ], + "patterns": "Follow existing config pattern in .env", + "integration_points": "Used by AuthService in middleware" + }, + "analysis": { + "risk": "low", + "impact": "medium", + "complexity": "low" + }, + "score": 0.95, + "is_bound": true +} +``` + +## 字段说明 + +### 基础字段 + +| 字段 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `id` | string | ✓ | 唯一 ID:SOL-{issue-id}-{seq} | +| `issue_id` | string | ✓ | 关联的 Issue ID | +| `description` | string | ✓ | 解决方案描述 | +| `strategy_type` | string | | 策略类型:bugfix/feature/refactor | +| `tasks` | array | ✓ | 任务列表,至少 1 个 | + +### Task 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | string | 任务 ID:T1, T2, ... | +| `title` | string | 任务标题 | +| `action` | string | 动作类型:Create/Modify/Fix/Refactor | +| `scope` | string | 作用范围:文件或目录 | +| `modification_points` | array | 具体修改点列表 | +| `implementation` | array | 实现步骤 | +| `test` | object | 测试命令和用例 | +| `acceptance` | object | 验收条件和验证步骤 | +| `depends_on` | array | 任务依赖:[T1, T2] | +| `estimated_minutes` | number | 预计耗时(分钟) | + +### 验收条件 + +```json +{ + "acceptance": { + "criteria": [ + "Unit tests pass", + "Function returns correct result", + "No performance regression" + ], + "verification": [ + "Run: npm test -- module.test.ts", + "Manual: Call function and verify output" + ] + } +} +``` + +## 验证规则 + +### 必需字段检查 + +```javascript +function validateSolution(solution) { + if (!solution.id) throw new Error("Missing: id"); + if (!solution.issue_id) throw new Error("Missing: issue_id"); + if (!solution.description) throw new Error("Missing: description"); + if (!Array.isArray(solution.tasks)) throw new Error("tasks must be array"); + if (solution.tasks.length === 0) throw new Error("tasks cannot be empty"); + return true; +} + +function validateTask(task) { + if (!task.id) throw new Error("Missing: task.id"); + if (!task.title) throw new Error("Missing: task.title"); + if (!task.action) throw new Error("Missing: task.action"); + if (!Array.isArray(task.implementation)) throw new Error("implementation must be array"); + if (!task.acceptance) throw new Error("Missing: task.acceptance"); + if (!Array.isArray(task.acceptance.criteria)) throw new Error("acceptance.criteria must be array"); + if (task.acceptance.criteria.length === 0) throw new Error("acceptance.criteria cannot be empty"); + return true; +} +``` + +### 格式验证 + +- ID 格式:`SOL-ISS-\d+-\d+` +- Action 值:Create | Modify | Fix | Refactor | Add | Remove +- Risk/Impact/Complexity 值:low | medium | high +- Score 范围:0.0 - 1.0 + +## 任务依赖 + +### 表示方法 + +```json +{ + "tasks": [ + { + "id": "T1", + "title": "Create auth module", + "depends_on": [] + }, + { + "id": "T2", + "title": "Add authentication logic", + "depends_on": ["T1"] + }, + { + "id": "T3", + "title": "Add tests", + "depends_on": ["T1", "T2"] + } + ] +} +``` + +### DAG 验证 + +```javascript +function validateDAG(tasks) { + const visited = new Set(); + const recursionStack = new Set(); + + function hasCycle(taskId) { + visited.add(taskId); + recursionStack.add(taskId); + + const task = tasks.find(t => t.id === taskId); + if (!task || !task.depends_on) return false; + + for (const dep of task.depends_on) { + if (!visited.has(dep)) { + if (hasCycle(dep)) return true; + } else if (recursionStack.has(dep)) { + return true; // 发现循环 + } + } + + recursionStack.delete(taskId); + return false; + } + + for (const task of tasks) { + if (!visited.has(task.id) && hasCycle(task.id)) { + throw new Error(`Circular dependency detected: ${task.id}`); + } + } + return true; +} +``` + +## 文件保存 + +### 位置 + +``` +.workflow/.scratchpad/codex-issue-{timestamp}/solutions/ +├── ISS-001-plan.json # 规划结果 +├── ISS-001-execution.json # 执行结果 +├── ISS-002-plan.json +└── ISS-002-execution.json +``` + +### 文件内容 + +**规划结果**:包含 solution 完整定义 +**执行结果**:包含执行状态和提交信息 + +```json +{ + "solution_id": "SOL-ISS-001-1", + "status": "completed|failed", + "executed_at": "ISO-8601", + "execution_result": { + "files_modified": ["src/auth.ts"], + "commit_hash": "abc123...", + "tests_passed": true + } +} +``` + +## 质量门控 + +### Solution 评分标准 + +| 指标 | 权重 | 评分方法 | +|------|------|----------| +| 任务完整性 | 30% | 无空任务,每个任务有 acceptance | +| 依赖合法性 | 20% | 无循环依赖,依赖链清晰 | +| 验收可测 | 30% | Criteria 明确可测,有验证步骤 | +| 复杂度评估 | 20% | Risk/Impact/Complexity 合理评估 | + +### 通过条件 + +- 所有必需字段存在 +- 无格式错误 +- 无循环依赖 +- Score >= 0.8 diff --git a/.codex/skills/codex-issue-plan-execute/specs/subagent-roles.md b/.codex/skills/codex-issue-plan-execute/specs/subagent-roles.md new file mode 100644 index 00000000..d4f40a84 --- /dev/null +++ b/.codex/skills/codex-issue-plan-execute/specs/subagent-roles.md @@ -0,0 +1,268 @@ +# Subagent Roles Definition + +Subagent 的角色定义和职责范围。 + +## Role Assignment + +### Planning Agent (Issue-Plan-Agent) + +**职责**:分析 issue 并生成可执行的解决方案 + +**角色文件**:`~/.codex/agents/issue-plan-agent.md` + +#### Capabilities + +- **允许**: + - 读取代码、文档、配置 + - 探索项目结构和依赖关系 + - 分析问题和设计解决方案 + - 分解任务为可执行步骤 + - 定义验收条件 + +- **禁止**: + - 修改代码 + - 执行代码 + - 推送到远程 + +#### 输入 + +```json +{ + "issue_id": "ISS-001", + "title": "Fix authentication timeout", + "description": "User sessions timeout too quickly", + "project_context": { + "tech_stack": "Node.js + Express + JWT", + "guidelines": "..." + } +} +``` + +#### 输出 + +```json +{ + "solution_id": "SOL-ISS-001-1", + "tasks": [ + { + "id": "T1", + "title": "Update JWT configuration", + "...": "..." + } + ], + "acceptance": { + "criteria": [...], + "verification": [...] + }, + "score": 0.95 +} +``` + +### Execution Agent (Issue-Execute-Agent) + +**职责**:执行规划的解决方案,实现所有任务 + +**角色文件**:`~/.codex/agents/issue-execute-agent.md` + +#### Capabilities + +- **允许**: + - 读取代码和配置 + - 修改代码 + - 运行测试 + - 提交代码 + - 验证 acceptance criteria + +- **禁止**: + - 推送到远程分支 + - 创建 PR(除非明确授权) + - 删除分支或文件 + +#### 输入 + +```json +{ + "solution_id": "SOL-ISS-001-1", + "issue_id": "ISS-001", + "solution": { + "tasks": [...], + "exploration_context": {...} + } +} +``` + +#### 输出 + +```json +{ + "status": "completed|failed", + "files_modified": ["src/auth.ts", "src/config.ts"], + "commit_hash": "abc123def456", + "tests_passed": true, + "acceptance_verified": true, + "errors": [] +} +``` + +## Dual-Agent Strategy + +### 为什么使用双 Agent 模式 + +1. **关注点分离**:规划和执行各自专注一个任务 +2. **并行优化**:虽然执行依然串行,但规划可独立优化 +3. **上下文最小化**:仅传递 solution ID,避免上下文膨胀 +4. **错误隔离**:规划失败不影响执行,反之亦然 + +### 工作流程 + +``` +┌────────────────────────┐ +│ Planning Agent │ +│ • Analyze issue │ +│ • Design solution │ +│ • Generate tasks │ +│ → Output: SOL-xxx-1 │ +└────────┬───────────────┘ + ↓ + ┌──────────────┐ + │ Bind solution│ + │ Update state │ + └──────┬───────┘ + ↓ +┌─────────────────────────┐ +│ Execution Agent │ +│ • Load SOL-xxx-1 │ +│ • Execute all tasks │ +│ • Run tests │ +│ • Commit changes │ +│ → Output: commit hash │ +└─────────────────────────┘ + ↓ + ┌──────────────┐ + │ Save results │ + │ Update state │ + └──────────────┘ +``` + +## Context Minimization + +### 信息传递原则 + +**目标**:最小化上下文,减少 token 浪费 + +#### Planning Phase + +**传递内容**: +- Issue ID 和 Title +- Issue Description +- Project tech stack +- Project guidelines + +**不传递**: +- 完整的代码库快照 +- 所有相关文件内容 +- 历史执行结果 + +#### Execution Phase + +**传递内容**: +- Solution ID(仅 ID,不传递完整 solution) +- 执行参数(worktree 路径等) + +**不传递**: +- 规划阶段的完整上下文 +- 其他 issues 的信息 + +### 上下文加载策略 + +```javascript +// Planning Agent 自己加载 +const issueDetails = ReadFromIssueStore(issueId); +const techStack = Read('.workflow/project-tech.json'); +const guidelines = Read('.workflow/project-guidelines.json'); + +// Execution Agent 自己加载 +const solution = ReadFromSolutionStore(solutionId); +const project = Read('.workflow/project-guidelines.json'); +``` + +## 错误处理与重试 + +### Planning 错误 + +| 错误 | 原因 | 重试策略 | +|------|------|----------| +| Subagent 超时 | 分析复杂 | 增加 timeout,重试 1 次 | +| 无效 solution | 生成不符合 schema | 返回用户,标记失败 | +| 依赖循环 | DAG 错误 | 返回用户进行修正 | + +### Execution 错误 + +| 错误 | 原因 | 重试策略 | +|------|------|----------| +| Task 失败 | 代码有问题 | 记录错误,标记 solution 失败 | +| 测试失败 | 测试用例不符 | 不提交,标记失败 | +| 提交失败 | 冲突或权限 | 创建快照,让用户决定 | + +## 交互指南 + +### 向 Planning Agent 的问题 + +``` +这个 issue 描述了什么问题? +→ 返回:问题分析 + 根本原因 + +解决这个问题需要修改哪些文件? +→ 返回:文件列表 + 修改点 + +如何验证解决方案是否有效? +→ 返回:验收条件 + 验证步骤 +``` + +### 向 Execution Agent 的问题 + +``` +这个 task 有哪些实现步骤? +→ 返回:逐步指南 + 代码示例 + +所有测试都通过了吗? +→ 返回:测试结果 + 失败原因(如有) + +acceptance criteria 都满足了吗? +→ 返回:验证结果 + 不符合项(如有) +``` + +## Role 文件位置 + +``` +~/.codex/agents/ +├── issue-plan-agent.md # 规划角色 +├── issue-execute-agent.md # 执行角色 +└── ... +``` + +### 如果角色文件不存在 + +Orchestrator 会使用 `universal-executor` 或 `code-developer` 作为备用角色。 + +## 最佳实践 + +### 为 Planning Agent 设计提示词 + +```markdown +1. 从 issue 描述提取关键信息 +2. 探索相关代码和类似实现 +3. 设计最小化解决方案 +4. 分解为 2-7 个可执行任务 +5. 为每个 task 定义明确的 acceptance criteria +``` + +### 为 Execution Agent 设计提示词 + +```markdown +1. 加载 solution 和所有 task 定义 +2. 按依赖顺序执行 tasks +3. 为每个 task:implement → test → verify +4. 确保所有 acceptance criteria 通过 +5. 提交一次包含所有更改 +``` diff --git a/package.json b/package.json index 5a03c9ab..be0cb0c3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflow", - "version": "6.3.49", + "version": "6.3.50", "description": "JSON-driven multi-agent development framework with intelligent CLI orchestration (Gemini/Qwen/Codex), context-first architecture, and automated workflow execution", "type": "module", "main": "ccw/src/index.js",