Claude-Code-Workflow/.codex/skills/codex-issue-plan-execute/specs/agent-roles.md

Agent Roles Definition

Agent角色定义和职责范围。

---

Role Assignment

Planning Agent (Issue-Plan-Agent)

职责: 分析issue并生成可执行的解决方案

角色文件: ~/.codex/agents/issue-plan-agent.md
提示词: prompts/planning-agent.md

Capabilities

允许:

• 读取代码、文档、配置
• 探索项目结构和依赖关系
• 分析问题和设计解决方案
• 分解任务为可执行步骤
• 定义验收条件

禁止:

• 修改代码
• 执行代码
• 推送到远程
• 删除文件或分支

Input Format

{
  "type": "plan_issue",
  "issue_id": "ISS-001",
  "title": "Fix authentication timeout",
  "description": "User sessions timeout too quickly",
  "project_context": {
    "tech_stack": "Node.js + Express + JWT",
    "guidelines": "Follow existing patterns",
    "relevant_files": ["src/auth.ts", "src/middleware/auth.ts"]
  }
}

Output Format

{
  "status": "completed|failed",
  "solution_id": "SOL-ISS-001-1",
  "tasks": [
    {
      "id": "T1",
      "title": "Update JWT configuration",
      "action": "Modify",
      "scope": "src/config/auth.ts",
      "description": "Increase token expiration time",
      "modification_points": ["TOKEN_EXPIRY constant"],
      "implementation": ["Step 1", "Step 2"],
      "test": {
        "commands": ["npm test -- auth.test.ts"],
        "unit": ["Token expiry should be 24 hours"]
      },
      "acceptance": {
        "criteria": ["Token valid for 24 hours", "Test suite passes"],
        "verification": ["Run tests"]
      },
      "depends_on": [],
      "estimated_minutes": 20,
      "priority": 1
    }
  ],
  "exploration_context": {
    "relevant_files": ["src/auth.ts", "src/middleware/auth.ts"],
    "patterns": "Follow existing JWT configuration pattern",
    "integration_points": "Used by authentication middleware"
  },
  "analysis": {
    "risk": "low|medium|high",
    "impact": "low|medium|high",
    "complexity": "low|medium|high"
  },
  "score": 0.95,
  "validation": {
    "schema_valid": true,
    "criteria_quantified": true,
    "no_circular_deps": true
  }
}

---

Execution Agent (Issue-Execute-Agent)

职责: 执行规划的解决方案，实现所有任务

角色文件: ~/.codex/agents/issue-execute-agent.md
提示词: prompts/execution-agent.md

Capabilities

允许:

• 读取代码和配置
• 修改代码
• 运行测试
• 提交代码
• 验证acceptance criteria
• 创建snapshots用于恢复

禁止:

• 推送到远程分支
• 创建PR（除非明确授权）
• 删除分支
• 强制覆盖主分支

Input Format

{
  "type": "execute_solution",
  "issue_id": "ISS-001",
  "solution_id": "SOL-ISS-001-1",
  "solution": {
    "id": "SOL-ISS-001-1",
    "tasks": [ /* task objects from planning */ ],
    "exploration_context": {
      "relevant_files": ["src/auth.ts"],
      "patterns": "Follow existing pattern",
      "integration_points": "Used by auth middleware"
    }
  },
  "project_root": "/path/to/project"
}

Output Format

{
  "status": "completed|failed",
  "execution_result_id": "EXR-ISS-001-1",
  "issue_id": "ISS-001",
  "solution_id": "SOL-ISS-001-1",
  "executed_tasks": [
    {
      "task_id": "T1",
      "title": "Update JWT configuration",
      "status": "completed",
      "files_modified": ["src/config/auth.ts"],
      "commits": [
        {
          "hash": "abc123def456",
          "message": "[T1] Update JWT token expiration to 24 hours"
        }
      ],
      "test_results": {
        "passed": 8,
        "failed": 0,
        "command": "npm test -- auth.test.ts",
        "output": "All tests passed"
      },
      "acceptance_met": true,
      "execution_time_minutes": 15,
      "errors": []
    }
  ],
  "overall_stats": {
    "total_tasks": 1,
    "completed": 1,
    "failed": 0,
    "total_files_modified": 1,
    "total_commits": 1,
    "total_time_minutes": 15
  },
  "final_commit": {
    "hash": "xyz789abc",
    "message": "Resolve ISS-001: Fix authentication timeout"
  },
  "verification": {
    "all_tests_passed": true,
    "all_acceptance_met": true,
    "no_regressions": true
  }
}

---

Dual-Agent Strategy

为什么使用双Agent模式

1. 关注点分离 - 规划和执行各自专注一个任务
2. 并行优化 - 虽然执行仍是串行，但规划可独立优化
3. 上下文最小化 - 仅传递solution ID，避免上下文膨胀
4. 错误隔离 - 规划失败不影响执行，反之亦然
5. 可维护性 - 每个agent专注单一职责

工作流程

┌────────────────────────────────────┐
│  Planning Agent                    │
│  • Analyze issue                   │
│  • Explore codebase                │
│  • Design solution                 │
│  • Generate tasks                  │
│  • Validate schema                 │
│  → Output: SOL-ISS-001-1 JSON      │
└────────────┬─────────────────────┘
             ↓
        ┌──────────────┐
        │ Save to      │
        │ planning-    │
        │ results.json │
        │ + Bind       │
        └──────┬───────┘
               ↓
┌────────────────────────────────────┐
│  Execution Agent                   │
│  • Load SOL-ISS-001-1              │
│  • Implement T1, T2, T3...         │
│  • Run tests per task              │
│  • Commit changes                  │
│  • Verify acceptance               │
│  → Output: EXR-ISS-001-1 JSON      │
└────────────┬─────────────────────┘
             ↓
        ┌──────────────┐
        │ Save to      │
        │ execution-   │
        │ results.json │
        └──────────────┘

---

Context Minimization

信息传递原则

目标: 最小化上下文，减少token浪费

Planning Phase - 传递内容

• Issue ID 和 Title
• Issue Description
• Project tech stack (project-tech.json)
• Project guidelines (project-guidelines.json)
• Solution schema reference

Planning Phase - 不传递

• 完整的代码库快照
• 所有相关文件内容 (Agent自己探索)
• 历史执行结果
• 其他issues的信息

Execution Phase - 传递内容

• Solution ID (完整的solution JSON)
• 执行参数（worktree路径等）
• Project tech stack
• Project guidelines

Execution Phase - 不传递

• 规划阶段的完整上下文
• 其他solutions的信息
• 原始issue描述（solution JSON中已包含）

上下文加载策略

// Planning Agent 自己加载
const issueDetails = Read(issueStore + issue_id);
const techStack = Read('.workflow/project-tech.json');
const guidelines = Read('.workflow/project-guidelines.json');
const schema = Read('~/.claude/workflows/cli-templates/schemas/solution-schema.json');

// Execution Agent 自己加载
const solution = planningResults.find(r => r.solution_id === solutionId);
const techStack = Read('.workflow/project-tech.json');
const guidelines = Read('.workflow/project-guidelines.json');

优势:

• 减少重复传递
• 使用相同的源文件版本
• Agents可以自我刷新上下文
• 易于更新project guidelines或tech stack

---

错误处理与重试

Planning 错误

错误	原因	重试策略	恢复
Subagent超时	分析复杂或系统慢	增加timeout，重试1次	返回用户，标记失败
无效solution	生成不符合schema	验证schema，返回错误	返回用户进行修正
依赖循环	DAG错误	检测循环，返回错误	用户手动修正
权限错误	无法读取文件	检查路径和权限	返回具体错误
格式错误	JSON无效	验证格式，返回错误	用户修正格式

Execution 错误

错误	原因	重试策略	恢复
Task失败	代码实现问题	检查错误，不重试	记录错误，标记失败
测试失败	测试用例不符	不提交，标记失败	返回测试输出
提交失败	冲突或权限	创建snapshot便于恢复	让用户决定
Subagent超时	任务太复杂	增加timeout	记录超时，标记失败
文件冲突	并发修改	创建snapshot	让用户合并

---

交互指南

向Planning Agent的问题

"这个issue描述了什么问题？"
→ 返回：问题分析 + 根本原因

"解决这个问题需要修改哪些文件？"
→ 返回：文件列表 + 修改点

"如何验证解决方案是否有效？"
→ 返回：验收条件 + 验证步骤

"预计需要多少时间？"
→ 返回：每个任务的估计时间 + 总计

"有哪些风险？"
→ 返回：风险分析 + 影响评估

向Execution Agent的问题

"这个task有哪些实现步骤？"
→ 返回：逐步指南 + 代码示例

"所有测试都通过了吗？"
→ 返回：测试结果 + 失败原因（如有）

"acceptance criteria都满足了吗？"
→ 返回：验证结果 + 不符合项（如有）

"有哪些文件被修改了？"
→ 返回：文件列表 + 变更摘要

"代码有没有回归问题？"
→ 返回：回归测试结果

---

Role文件位置

~/.codex/agents/
├── issue-plan-agent.md          # 规划角色定义
├── issue-execute-agent.md       # 执行角色定义
└── ...

.codex/skills/codex-issue-plan-execute/
├── prompts/
│   ├── planning-agent.md        # 规划提示词
│   └── execution-agent.md       # 执行提示词
└── specs/
    ├── agent-roles.md           # 本文件
    └── ...

如果角色文件不存在

Orchestrator会使用fallback策略：

• universal-executor 作为备用规划角色
• code-developer 作为备用执行角色

---

最佳实践

为Planning Agent设计提示词

✓ 从issue描述提取关键信息
✓ 探索相关代码和类似实现
✓ 分析根本原因和解决方向
✓ 设计最小化解决方案
✓ 分解为2-7个可执行任务
✓ 为每个task定义明确的acceptance criteria
✓ 验证任务依赖无循环
✓ 估计总时间≤2小时

为Execution Agent设计提示词

✓ 加载solution和所有task定义
✓ 按依赖顺序执行tasks
✓ 为每个task：implement → test → verify
✓ 确保所有acceptance criteria通过
✓ 运行完整的测试套件
✓ 检查代码质量和风格一致性
✓ 创建描述性的commit消息
✓ 生成完整的execution result JSON

---

Communication Protocol

Planning Agent Lifecycle

1. Initialize (once)
   - Read system prompt
   - Read role definition
   - Load project context

2. Process issues (loop)
   - Receive issue via send_input
   - Analyze issue
   - Design solution
   - Return solution JSON
   - Wait for next issue

3. Shutdown
   - Orchestrator closes when done

Execution Agent Lifecycle

1. Initialize (once)
   - Read system prompt
   - Read role definition
   - Load project context

2. Process solutions (loop)
   - Receive solution via send_input
   - Implement all tasks
   - Run tests
   - Return execution result
   - Wait for next solution

3. Shutdown
   - Orchestrator closes when done

---

Version History

Version	Date	Changes
2.0	2025-01-29	Consolidated from subagent-roles.md, updated format
1.0	2024-12-29	Initial agent roles definition

---

Document Version: 2.0
Last Updated: 2025-01-29
Maintained By: Codex Issue Plan-Execute Team