issue-flow

Issue Flow — AI 原生的 Issue 驱动开发

你正在编排一个从 GitHub Issue 到 PR 合并的完整开发周期。请严格遵循以下阶段。每项重大决策都需要获得人工确认。

开始时宣布：“我正在使用 issue-flow 技能来实现此 GitHub Issue。”

初始请求：$ARGUMENTS

---

Phase 0：预检

目标：验证环境并确定目标 Issue。

操作：

1. 环境检查：运行 gh auth status，确认 GitHub CLI 已通过身份验证。如果失败，告知用户运行 gh auth login，然后停止。

2. 解析参数：

   • #123 或仅 123 → 提取 Issue 编号，通过 gh repo view --json nameWithOwner 确定仓库
   • https://github.com/org/repo/issues/123 → 提取所有者、仓库和编号
   • 为空 → 运行 gh issue list --state open --limit 20，并使用 AskUserQuestion 让用户选择一个 Issue

3. 获取 Issue 详细信息：

   gh issue view <N> --json number,title,body,labels,comments,assignees,state
   

   保存：ISSUE_NUMBER、ISSUE_TITLE、ISSUE_BODY、ISSUE_LABELS。

4. 检查是否已有相关工作：

   • 使用 git branch -a --list '*issue/<N>*' 搜索分支 issue/<N>-*
   • 如果找到，使用 AskUserQuestion 询问：继续现有分支 / 重新开始 / 取消

5. 检测项目特性（供后续组建团队时使用）：

   • 是否有测试框架？（检查 jest.config*、vitest.config*、pytest.ini、*test* 目录）
   • 是否有 CI？（检查 .github/workflows/、.gitlab-ci.yml 等）
   • 是否有代码检查工具？（检查 .eslintrc*、biome.json、.prettierrc*）
   • 根据文件扩展名确定主要编程语言

---

Phase 1：工作树设置

目标：创建隔离的工作区。

操作：

1. 使用 EnterWorktree 工具，并以 issue-<N> 作为名称，创建隔离的工作树。
2. 创建并切换到分支 issue/<N>-<slugified-title>：
   • 生成 Slug：转为小写，将空格和特殊字符替换为 -，截断至 50 个字符
   • 示例：Issue #42“Add OAuth2 Login Support” → issue/42-add-oauth2-login-support
   • 运行：git checkout -b issue/<N>-<slug>

---

Phase 2：技术规划

目标：深入探索代码库 → 制定技术计划 → 获得用户批准。

步骤 2a：探索代码库

使用 Task 工具并行启动 2–3 个代码探索 Agent（subagent_type: code-explorer）。根据 Issue 调整每个 Agent 的关注重点：

• Agent 1：探索与 Issue 需求直接相关的现有实现和模式。返回 5–10 个关键文件的列表。
• Agent 2：分析受影响模块的架构、依赖和扩展点。返回 5–10 个关键文件的列表。
• Agent 3（复杂 Issue 可选）：调查测试模式、CI 配置和相关工具链。返回 5–10 个关键文件的列表。

Agent 返回结果后，阅读所有已识别的关键文件，深入了解代码库。

步骤 2b：制定技术计划

根据探索结果制定技术计划，包含：

1. 摘要：用 2–3 句话概述方案
2. 要修改/创建的文件：列出文件并简要说明变更
3. 实施步骤：有序、具体的步骤（每步对应一个逻辑工作单元）
4. 测试策略：测试内容和方法
5. 风险评估：潜在问题及缓解措施

根据 rules/plan-format.md 的格式编写计划。

步骤 2c：将计划发布到 Issue

使用 gh issue comment 将计划作为评论发布到 Issue：

gh issue comment <N> --body "$(cat <<'EOF'
<plan content formatted per rules/plan-format.md>
EOF
)"

在顶部使用 HTML 注释标记 ``，以便识别计划并以幂等方式更新。

步骤 2d：用户确认

使用 AskUserQuestion 提供以下选项：

• 批准 — 继续实施
• 修改 — 用户提供反馈，返回步骤 2b
• 取消 — 中止工作流

未经明确批准，不得继续。

---

Phase 3：团队执行

目标：实施计划 — 直接执行或借助 Agent 团队完成。

决策：直接实现还是团队执行

直接实现（不组建团队），需满足以下所有条件：

• 计划涉及 1-2 个文件
• 没有复杂的跨模块变更
• 不需要单独进行测试、审查或文档工作

团队执行，满足以下任一条件：

• 计划涉及多个模块中的 3 个或更多文件
• 需要编写或更新测试
• 涉及安全敏感的变更
• 需要更新文档
• 同时涉及前端和后端变更

路径 A：直接实现

1. 按照计划逐步实现变更
2. 如果有现成测试，则运行测试
3. 跳转到阶段 4

路径 B：团队执行

1. 创建团队：使用 TeamCreate，名称为 issue-<N>。

2. 决定团队组成：根据问题的特点，从 rules/team-roles.md 中定义的候选池选择角色。考虑以下因素：

   • 问题标签（例如 frontend、security、docs）
   • 计划涉及的文件类型（.tsx → 前端，.sql → 后端等）
   • 是否有需要更新的测试
   • 变更的风险等级

3. 启动队友：针对每个角色使用 Task 工具，并传入 team_name 参数。向每位队友提供：

   • 技术计划
   • 其具体任务
   • 第 2 阶段中发现的代码库模式相关背景

4. 创建任务：根据计划中的每个实现步骤使用 TaskCreate 创建任务。对于有依赖关系的步骤，使用 addBlockedBy 设置依赖项。

5. 分配并协调：通过 TaskUpdate 将任务分配给队友。监控进度、解决阻碍，并协调队友之间的工作。

6. 迭代次数上限：每项任务最多进行 2 次修复迭代。如果任务经过 2 轮后仍然失败：

   • 记录问题
   • 使用 AskUserQuestion 询问：手动修复 / 跳过 / 中止

7. 关闭团队：所有任务完成后，向每位队友发送 shutdown_request，然后使用 TeamDelete。

---

阶段 4：PR 和 CI

目标：提交、推送、创建 PR 并处理 CI。

步骤 4a：提交并推送

1. 暂存所有变更：通过 git status 和 git diff 进行检查
2. 提交时使用描述性消息并引用问题：

   feat: <summary from plan> (#<N>)
   

3. 推送分支：

   git push -u origin issue/<N>-<slug>
   

步骤 4b：创建 PR

使用 rules/pr-template.md 中的模板，通过 gh pr create 创建 PR：

gh pr create --title "<title>" --body "$(cat <<'EOF'
<PR body per rules/pr-template.md, includes Closes #N>
EOF
)"

步骤 4c：向问题发布实现摘要

向问题添加评论，总结已实现的内容：

gh issue comment <N> --body "$(cat <<'EOF'

## Implementation Complete

- PR: #<PR_NUMBER>
- <brief summary of changes>
EOF
)"

步骤 4d：CI 检查

1. 稍作等待，然后检查 CI 状态：

   gh pr checks <PR_NUMBER> --watch --fail-fast
   

2. 如果 CI 失败：使用 AskUserQuestion 提供以下选项：

   • 自动修复 — 尝试诊断并修复 CI 失败（最多 2 次迭代）
   • 手动 — 用户将手动修复
   • 中止 — 关闭 PR

3. 如果 CI 通过（或未配置 CI）：使用 AskUserQuestion 提供以下选项：

   • 合并 — 立即合并 PR
   • 保持开放 — 保持 PR 开放，以供人工审查
   • 请求审查 — 通过 gh pr edit --add-reviewer 指定审查者

---

阶段 5：清理

目标：合并后清理资源。

操作（仅当 PR 已合并时）：

1. 检查问题状态：确认 Closes #N 是否已自动关闭问题。如果没有：

   gh issue close <N> --comment "Closed via PR #<PR_NUMBER>"
   

2. 报告：输出完成摘要：

   ## Issue Flow Complete
   
   - Issue: #<N> <title>
   - Branch: issue/<N>-<slug>
   - PR: #<PR_NUMBER> (merged)
   - Files changed: <count>
   - Implementation: <1-2 sentence summary>
   

---

错误恢复

如果工作流在任何时候中断，用户可以重新运行 /issue-flow #<N> 以继续。详细的恢复场景请参阅 references/recovery-guide.md。

核心原则

• 人在回路中：每项重大决策（计划审批、合并、CI 失败处理）都需要用户明确确认
• 幂等评论：问题评论使用 HTML 标记（、），因此重新运行时会更新评论，而不是重复添加
• 隔离：所有工作都在工作树中进行 — 直到合并前都不会触碰主分支
• 按需响应：简单变更无需承担团队协作的额外开销；复杂变更则进行全面的团队协调