issue-flow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Issue Flow — AI-Native Issue-Driven Development

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

You are orchestrating a complete development cycle from a GitHub Issue to a merged PR. Follow the phases below strictly. Every major decision requires human confirmation.

Announce at start: "I'm using the issue-flow skill to implement this GitHub Issue."

Initial request: $ARGUMENTS

你将编排从GitHub Issue到合并PR的完整开发周期。严格遵循以下阶段执行，所有重大决策都需要人工确认。

开始时需告知："我正在使用issue-flow技能来实现这个GitHub Issue。"

初始请求：$ARGUMENTS

Phase 0: Preflight

阶段0：预检

Goal: Validate environment and resolve the target Issue.

Actions:

Environment check: Run
```
gh auth status
```
to verify GitHub CLI is authenticated. If it fails, tell the user to run
```
gh auth login
```
and stop.
Parse arguments:
- ```
#123
```
  or just
```
123
```
  → extract issue number, detect repo from
```
gh repo view --json nameWithOwner
```
- ```
https://github.com/org/repo/issues/123
```
  → extract owner, repo, and number
- Empty → run
```
gh issue list --state open --limit 20
```
  and use AskUserQuestion to let the user pick an issue

Fetch Issue details:

bash

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

Store:

ISSUE_NUMBER

ISSUE_TITLE

ISSUE_BODY

ISSUE_LABELS

Check for existing work:
- Search for branch
```
issue/<N>-*
```
  via
```
git branch -a --list '*issue/<N>*'
```
- If found, AskUserQuestion: resume existing branch / start fresh / cancel
Detect project features (used later for team composition):
- Has test framework? (check for
```
jest.config*
```
  ,
```
vitest.config*
```
  ,
```
pytest.ini
```
  ,
```
*test*
```
  dirs)
- Has CI? (check
```
.github/workflows/
```
  ,
```
.gitlab-ci.yml
```
  , etc.)
- Has linter? (check
```
.eslintrc*
```
  ,
```
biome.json
```
  ,
```
.prettierrc*
```
  )
- Primary language(s) from file extensions

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

操作：

环境检查：运行
```
gh auth status
```
验证GitHub CLI已认证。如果失败，告知用户运行
```
gh auth login
```
并停止流程。
解析参数：
- ```
#123
```
  或仅
```
123
```
  → 提取Issue编号，通过
```
gh repo view --json nameWithOwner
```
  检测仓库
- ```
https://github.com/org/repo/issues/123
```
  → 提取所有者、仓库和编号
- 空值 → 运行
```
gh issue list --state open --limit 20
```
  ，并使用AskUserQuestion让用户选择一个Issue

获取Issue详情：

bash

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

存储：

ISSUE_NUMBER

、

ISSUE_TITLE

、

ISSUE_BODY

、

ISSUE_LABELS

。

检查现有工作：
- 通过
```
git branch -a --list '*issue/<N>*'
```
  搜索分支
```
issue/<N>-*
```
- 如果找到，使用AskUserQuestion询问：恢复现有分支 / 重新开始 / 取消
检测项目特性（后续用于团队组成）：
- 是否有测试框架？（检查
```
jest.config*
```
  、
```
vitest.config*
```
  、
```
pytest.ini
```
  、
```
*test*
```
  目录）
- 是否有CI？（检查
```
.github/workflows/
```
  、
```
.gitlab-ci.yml
```
  等）
- 是否有代码检查工具？（检查
```
.eslintrc*
```
  、
```
biome.json
```
  、
```
.prettierrc*
```
  ）
- 根据文件扩展名确定主要语言

Phase 1: Worktree Setup

阶段1：工作树设置

Goal: Create an isolated workspace.

Actions:

Use the
```
EnterWorktree
```
tool with name
```
issue-<N>
```
to create an isolated worktree.
Create and switch to branch
```
issue/<N>-<slugified-title>
```
:
- Slugify: lowercase, replace spaces/special chars with
```
-
```
  , truncate to 50 chars
- Example: Issue #42 "Add OAuth2 Login Support" →
```
issue/42-add-oauth2-login-support
```
- Run:
```
git checkout -b issue/<N>-<slug>
```

目标：创建独立的工作区。

操作：

使用
```
EnterWorktree
```
工具，命名为
```
issue-<N>
```
以创建独立工作树。
创建并切换到分支
```
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: Technical Planning

阶段2：技术规划

Goal: Deep codebase exploration → technical plan → user approval.

目标：深度探索代码库 → 制定技术方案 → 获得用户批准。

Step 2a: Codebase Exploration

步骤2a：代码库探索

Launch 2-3 code-explorer agents in parallel using the Task tool (subagent_type:

code-explorer

). Tailor each agent's focus to the Issue:

Agent 1: Explore existing implementations and patterns directly related to the Issue's requirements. Return a list of 5-10 key files.
Agent 2: Analyze architecture, dependencies, and extension points of affected modules. Return a list of 5-10 key files.
Agent 3 (optional, for complex issues): Investigate test patterns, CI configuration, and related toolchain. Return a list of 5-10 key files.

After agents return, read all key files they identified to build deep understanding.

使用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返回结果后，阅读所有他们识别的关键文件以建立深度理解。

Step 2b: Design Technical Plan

步骤2b：设计技术方案

Based on the exploration, design a technical plan with:

Summary: 2-3 sentence overview of the approach
Files to modify/create: List with brief description of changes
Implementation steps: Ordered, concrete steps (each step = one logical unit of work)
Test strategy: What to test, how to test
Risk assessment: Potential issues and mitigations

Format the plan according to

rules/plan-format.md

基于探索结果，设计包含以下内容的技术方案：

概述：2-3句话的方法概述
需修改/创建的文件：带变更简要说明的列表
实施步骤：有序、具体的步骤（每个步骤=一个逻辑工作单元）
测试策略：测试内容和测试方式
风险评估：潜在问题及缓解措施

按照

rules/plan-format.md

格式化方案。

Step 2c: Publish Plan to Issue

步骤2c：将方案发布到Issue

Post the plan as a comment on the Issue using

gh issue comment

bash

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

Use the HTML comment marker

<!-- issue-flow-plan -->

at the top so the plan can be identified and updated idempotently.

使用

gh issue comment

将方案作为评论发布到Issue：

bash

gh issue comment <N> --body "$(cat <<'EOF'
<按照rules/plan-format.md格式化的方案内容>
EOF
)"

在顶部使用HTML注释标记

<!-- issue-flow-plan -->

，以便方案可被识别并实现幂等更新。

Step 2d: User Confirmation

步骤2d：用户确认

Use AskUserQuestion with options:

Approve — proceed with implementation
Modify — user provides feedback, return to Step 2b
Cancel — abort the workflow

Do NOT proceed without explicit approval.

使用AskUserQuestion提供选项：

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

未获得明确批准前不得继续。

Phase 3: Team Execution

阶段3：团队执行

Goal: Implement the plan — either directly or with an agent team.

目标：实施方案 — 直接执行或通过Agent团队执行。

Decision: Direct vs Team

决策：直接执行 vs 团队执行

Direct implementation (no team) when ALL of these are true:

Plan involves 1-2 files
No complex cross-module changes
No separate test/review/docs work needed

Team execution when ANY of these are true:

Plan involves 3+ files across multiple modules
Tests need to be written or updated
Security-sensitive changes
Documentation updates required
Frontend + backend changes together

直接执行（无需团队）需满足以下所有条件：

方案涉及1-2个文件
无复杂跨模块变更
无需单独的测试/评审/文档工作

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

方案涉及3个及以上跨模块文件
需要编写或更新测试
安全敏感型变更
需要更新文档
同时涉及前端+后端变更

Path A: Direct Implementation

路径A：直接执行

Implement changes following the plan step by step
Run existing tests if available
Skip to Phase 4

按照方案步骤逐步实施变更
如果有现有测试则运行
跳至阶段4

Path B: Team Execution

路径B：团队执行

Create team: Use
```
TeamCreate
```
with name
```
issue-<N>
```
.
Decide team composition: Based on Issue characteristics, select roles from the candidate pool defined in
```
rules/team-roles.md
```
. Consider:
- Issue labels (e.g.,
```
frontend
```
  ,
```
security
```
  ,
```
docs
```
  )
- File types in the plan (
```
.tsx
```
  → frontend,
```
.sql
```
  → backend, etc.)
- Whether tests exist and need updating
- Risk level of the changes
Spawn teammates: Use the Task tool with
```
team_name
```
parameter for each role. Give each teammate:
- The technical plan
- Their specific tasks
- Context about the codebase patterns discovered in Phase 2
Create tasks: Use
```
TaskCreate
```
for each implementation step from the plan. Set up dependencies with
```
addBlockedBy
```
where steps depend on each other.
Assign and coordinate: Assign tasks to teammates via
```
TaskUpdate
```
. Monitor progress, resolve blockers, and coordinate between teammates.
Iteration limit: Each task gets at most 2 fix iterations. If a task still fails after 2 rounds:
- Log the issue
- AskUserQuestion: fix manually / skip / abort
Shutdown team: After all tasks complete, send
```
shutdown_request
```
to each teammate, then
```
TeamDelete
```
.

创建团队：使用
```
TeamCreate
```
命名为
```
issue-<N>
```
。
确定团队组成：根据Issue特性，从
```
rules/team-roles.md
```
定义的候选池中选择角色。考虑：
- Issue标签（如
```
frontend
```
  、
```
security
```
  、
```
docs
```
  ）
- 方案中的文件类型（
```
.tsx
```
  → 前端，
```
.sql
```
  → 后端等）
- 是否存在测试且需要更新
- 变更的风险等级
生成团队成员：使用带
```
team_name
```
参数的Task工具为每个角色生成成员。为每个成员提供：
- 技术方案
- 他们的具体任务
- 阶段2中发现的代码库模式相关上下文
创建任务：为方案中的每个实施步骤使用
```
TaskCreate
```
。在步骤存在依赖关系时，使用
```
addBlockedBy
```
设置依赖。
分配与协调：通过
```
TaskUpdate
```
将任务分配给团队成员。监控进度、解决阻塞问题并协调成员间工作。
迭代限制：每个任务最多允许2次修复迭代。如果经过2轮后任务仍失败：
- 记录问题
- 使用AskUserQuestion询问：手动修复 / 跳过 / 终止
解散团队：所有任务完成后，向每个成员发送
```
shutdown_request
```
，然后执行
```
TeamDelete
```
。

Phase 4: PR & CI

阶段4：PR与CI

Goal: Commit, push, create PR, handle CI.

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

Step 4a: Commit & Push

步骤4a：提交与推送

Stage all changes: review with
```
git status
```
and
```
git diff
```
Commit with a descriptive message referencing the Issue:
```
feat: <summary from plan> (#<N>)
```
Push the branch:
bash
```
git push -u origin issue/<N>-<slug>
```

暂存所有变更：通过
```
git status
```
和
```
git diff
```
检查
使用引用Issue的描述性消息提交：
```
feat: <方案中的概述> (#<N>)
```
推送分支：
bash
```
git push -u origin issue/<N>-<slug>
```

Step 4b: Create PR

步骤4b：创建PR

Create PR using

gh pr create

with the template from

rules/pr-template.md

bash

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

使用

gh pr create

和

rules/pr-template.md

中的模板创建PR：

bash

gh pr create --title "<标题>" --body "$(cat <<'EOF'
<按照rules/pr-template.md编写的PR正文，包含Closes #N>
EOF
)"

Step 4c: Post Implementation Summary to Issue

步骤4c：向Issue发布实施摘要

Add a comment to the Issue summarizing what was implemented:

bash

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

向Issue添加评论总结已实施内容：

bash

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

Implementation Complete

实施完成

PR: #<PR_NUMBER>
<brief summary of changes>

EOF )"

undefined

PR: #<PR_NUMBER>
<变更简要总结> EOF )"

undefined

Step 4d: CI Check

步骤4d：CI检查

Wait briefly, then check CI status:

bash

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

If CI fails: AskUserQuestion with options:
- Auto-fix — attempt to diagnose and fix CI failures (max 2 iterations)
- Manual — user will fix manually
- Abort — close the PR
If CI passes (or no CI configured): AskUserQuestion with options:
- Merge — merge the PR now
- Keep open — leave PR open for human review
- Request review — assign reviewer via
```
gh pr edit --add-reviewer
```

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

bash

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

如果CI 失败：使用AskUserQuestion提供选项：
- 自动修复 — 尝试诊断并修复CI失败（最多2次迭代）
- 手动修复 — 用户将手动修复
- 终止 — 关闭PR
如果CI 通过（或未配置CI）：使用AskUserQuestion提供选项：
- 合并 — 立即合并PR
- 保持开启 — 保留PR供人工评审
- 请求评审 — 通过
```
gh pr edit --add-reviewer
```
  分配评审人

Phase 5: Cleanup

阶段5：清理

Goal: Clean up resources after merge.

Actions (only if PR was merged):

Check Issue status: Verify if

Closes #N

auto-closed the Issue. If not:

bash

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

Report: Output a completion summary:

## Issue Flow Complete

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

目标：合并后清理资源。

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

检查Issue状态：验证
```
Closes #N
```
是否自动关闭了Issue。如果未关闭：
bash
```
gh issue close <N> --comment "Closed via PR #<PR_NUMBER>"
```

报告：输出完成摘要：

## Issue Flow 完成

- Issue: #<N> <标题>
- 分支: issue/<N>-<slug>
- PR: #<PR_NUMBER> (已合并)
- 变更文件数: <数量>
- 实施内容: <1-2句话的总结>

Error Recovery

错误恢复

If the workflow is interrupted at any point, the user can re-run

/issue-flow #<N>

to resume. See

references/recovery-guide.md

for detailed recovery scenarios.

如果工作流在任何阶段中断，用户可以重新运行

/issue-flow #<N>

以恢复。详细恢复场景请参考

references/recovery-guide.md

。

Key Principles

核心原则

Human-in-the-loop: Every major decision (plan approval, merge, CI failure handling) requires explicit user confirmation
Idempotent comments: Issue comments use HTML markers (
```

```
,
```

```
) so re-runs update rather than duplicate
Isolation: All work happens in a worktree — the main branch is never touched until merge
Proportional response: Simple changes skip the team overhead; complex changes get full team coordination

人工参与：所有重大决策（方案批准、合并、CI失败处理）都需要明确的用户确认
幂等评论：Issue评论使用HTML标记（
```

```
、
```

```
），以便重新运行时更新而非重复添加
隔离性：所有工作都在工作树中进行 — 主分支在合并前绝不会被触碰
响应适配：简单变更跳过团队开销；复杂变更使用完整团队协调