claude-code-workflow 6.3.49 → 6.3.51

package/.codex/skills/codex-issue-plan-execute/SKILL.md

@@ -0,0 +1,239 @@
+---
+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 (强制前置条件)
+
+> **⛔ 禁止跳过**: 在执行任何操作之前，**必须**阅读以下两份P0规范文档。未理解规范直接执行将导致输出质量不符合标准。
+
+| Document | Purpose | When |
+|----------|---------|------|
+| [specs/issue-handling.md](specs/issue-handling.md) | Issue 处理规范和数据结构 | **执行前必读** |
+| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案数据结构和验证规则 | **执行前必读** |
+
+---
+
+## Execution Flow
+
+### Phase 1: Initialize Persistent Agents
+→ **查阅**: [phases/orchestrator.md](phases/orchestrator.md) - 理解编排逻辑
+→ 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
+→ **查阅**: [phases/actions/action-plan.md](phases/actions/action-plan.md), [specs/subagent-roles.md](specs/subagent-roles.md)
+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
+→ **查阅**: [phases/actions/action-execute.md](phases/actions/action-execute.md), [specs/quality-standards.md](specs/quality-standards.md)
+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
+→ **查阅**: [phases/actions/action-complete.md](phases/actions/action-complete.md)
+→ 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 by Phase
+
+### 🔧 Setup & Understanding (初始化阶段)
+用于理解整个系统架构和执行流程
+
+| Document | Purpose | Key Topics |
+|----------|---------|-----------|
+| [phases/orchestrator.md](phases/orchestrator.md) | 编排器核心逻辑 | 如何管理agents、pipeline流程、状态转换 |
+| [phases/state-schema.md](phases/state-schema.md) | 状态结构定义 | 完整状态模型、验证规则、持久化 |
+| [specs/subagent-roles.md](specs/subagent-roles.md) | Subagent角色定义 | Planning Agent & Execution Agent职责 |
+
+### 📋 Planning Phase (规划阶段)
+执行Phase 2时查阅 - Planning逻辑和Issue处理
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/actions/action-plan.md](phases/actions/action-plan.md) | Planning流程详解 | 理解issue→solution转换逻辑 |
+| [phases/actions/action-list.md](phases/actions/action-list.md) | Issue列表处理 | 学习issue加载和列举逻辑 |
+| [specs/issue-handling.md](specs/issue-handling.md) | Issue数据规范 | 理解issue结构和验证规则 ✅ **必读** |
+| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案数据结构 | 了解solution JSON格式 ✅ **必读** |
+
+### ⚙️ Execution Phase (执行阶段)
+执行Phase 3时查阅 - 实现和验证逻辑
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/actions/action-execute.md](phases/actions/action-execute.md) | Execution流程详解 | 理解solution→implementation逻辑 |
+| [specs/quality-standards.md](specs/quality-standards.md) | 质量标准和验收条件 | 检查implementation是否达标 |
+
+### 🏁 Completion Phase (完成阶段)
+执行Phase 4时查阅 - 收尾和报告逻辑
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/actions/action-complete.md](phases/actions/action-complete.md) | 完成流程 | 生成最终报告、统计信息 |
+
+### 🔍 Debugging & Troubleshooting (问题排查)
+遇到问题时查阅 - 快速定位和解决
+
+| Issue | Solution Document |
+|-------|------------------|
+| 执行过程中状态异常 | [phases/state-schema.md](phases/state-schema.md) - 验证状态结构 |
+| Planning Agent输出不符合预期 | [phases/actions/action-plan.md](phases/actions/action-plan.md) + [specs/solution-schema.md](specs/solution-schema.md) |
+| Execution Agent实现失败 | [phases/actions/action-execute.md](phases/actions/action-execute.md) + [specs/quality-standards.md](specs/quality-standards.md) |
+| Issue数据格式错误 | [specs/issue-handling.md](specs/issue-handling.md) |
+
+### 📚 Reference & Background (深度学习)
+用于理解原始实现和设计决策
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [../issue-plan.md](../../.codex/prompts/issue-plan.md) | Codex Issue Plan 原始实现 | Planning Agent system prompt原型 |
+| [../issue-execute.md](../../.codex/prompts/issue-execute.md) | Codex Issue Execute 原始实现 | Execution Agent system prompt原型 |
+| [../codex SUBAGENT 策略补充.md](../../workflow/.scratchpad/codex%20SUBAGENT%20策略补充.md) | Subagent使用指南 | Agent交互最佳实践 |
+
+---
+
+## 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*

package/.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}`

package/.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 阶段
+- 有失败项：用户选择是否重试
+- 全部完成：生成最终报告