mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
Add execution and planning agent prompts, specifications, and quality standards
- Created execution agent prompt for issue execution with detailed deliverables and validation criteria. - Developed planning agent prompt to analyze issues and generate structured solution plans. - Introduced issue handling specifications outlining the workflow and issue structure. - Established quality standards for evaluating completeness, consistency, correctness, and clarity of solutions. - Defined solution schema specification detailing the required structure and validation rules for solutions. - Documented subagent roles and responsibilities, emphasizing the dual-agent strategy for improved workflow efficiency.
This commit is contained in:
catlog22
255
.codex/skills/codex-issue-plan-execute/README.md
Normal file
255
.codex/skills/codex-issue-plan-execute/README.md
Normal file
@@ -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"
|
||||
```
|
||||
206
.codex/skills/codex-issue-plan-execute/SKILL.md
Normal file
206
.codex/skills/codex-issue-plan-execute/SKILL.md
Normal file
@@ -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*
|
||||
@@ -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}`
|
||||
@@ -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 阶段
|
||||
- 有失败项：用户选择是否重试
|
||||
- 全部完成：生成最终报告
|
||||
@@ -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
|
||||
- 失败：中止工作流
|
||||
@@ -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
|
||||
- 用户取消：中止
|
||||
@@ -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 重新选择
|
||||
210
.codex/skills/codex-issue-plan-execute/phases/orchestrator.md
Normal file
210
.codex/skills/codex-issue-plan-execute/phases/orchestrator.md
Normal file
@@ -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 间的数据传递 |
|
||||
| **可维护性** | 流水线结构清晰，易于调试 |
|
||||
136
.codex/skills/codex-issue-plan-execute/phases/state-schema.md
Normal file
136
.codex/skills/codex-issue-plan-execute/phases/state-schema.md
Normal file
@@ -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));
|
||||
}
|
||||
```
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
122
.codex/skills/codex-issue-plan-execute/prompts/planning-agent.md
Normal file
122
.codex/skills/codex-issue-plan-execute/prompts/planning-agent.md
Normal file
@@ -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
|
||||
187
.codex/skills/codex-issue-plan-execute/specs/issue-handling.md
Normal file
187
.codex/skills/codex-issue-plan-execute/specs/issue-handling.md
Normal file
@@ -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 | 超时、网络延迟 | 日志记录 |
|
||||
@@ -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)
|
||||
```
|
||||
270
.codex/skills/codex-issue-plan-execute/specs/solution-schema.md
Normal file
270
.codex/skills/codex-issue-plan-execute/specs/solution-schema.md
Normal file
@@ -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
|
||||
268
.codex/skills/codex-issue-plan-execute/specs/subagent-roles.md
Normal file
268
.codex/skills/codex-issue-plan-execute/specs/subagent-roles.md
Normal file
@@ -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. 提交一次包含所有更改
|
||||
```
|
||||
Reference in New Issue
Block a user