claude-code-workflow 6.3.53 → 7.0.0

package/.codex/skills/codex-issue-plan-execute/specs/agent-roles.md

@@ -1,468 +0,0 @@
-# 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
-
-```json
-{
-  "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
-
-```json
-{
-  "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
-
-```json
-{
-  "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
-
-```json
-{
-  "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中已包含）
-
-### 上下文加载策略
-
-```javascript
-// 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

package/.codex/skills/codex-issue-plan-execute/specs/issue-handling.md

@@ -1,187 +0,0 @@
-# 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 | 超时、网络延迟 | 日志记录 |