| name | bugfix-flow |
| description | 轻量 bug 修复编排器。通过 .bugfix-flow/ 状态机管理从问题接手到验证完成的修复流程， 支持 manual 和 auto 两种模式，默认在验证通过后暂停等待人工决定是否提交或创建 PR。 |
| argument-hint | [<bug 描述> | #<Issue编号> | --auto ...] |
| disable-model-invocation | false |
| allowed-tools | ["Read","Write","Glob","Grep","AskUserQuestion","Bash(git remote -v)","Bash(git rev-parse --is-inside-work-tree)","Bash(git status *)","Bash(git branch *)","Bash(git worktree *)","Bash(gh auth status *)","Bash(gh repo view *)","Bash(gh issue view *)","Bash(mkdir *)","Bash(cat *)","Bash(date)","Bash(rm -f .bugfix-flow/pending.json)","Bash(rm -r .bugfix-flow)","Skill(bugfix-pick)","Skill(bugfix-implement)","Skill(bugfix-verify)","Skill(bugfix-finish)","Skill(superpowers:using-git-worktrees)","Skill(superpowers:finishing-a-development-branch)"] |
Bugfix Development（编排器）
bugfix-flow 是面向 bug 修复的轻量状态机编排器。它只负责：
- 判断当前处于哪个修复阶段
- 调用对应子 skill 完成该阶段工作
- 根据验证结果推进或回退状态
它不承载 brainstorm、issue-create、plan、commit、pr 的完整交付流程；目标是尽快把 bug 修好并验证完成。
入口模式
/bugfix-flow <bug 描述> → 模式 A（manual）/bugfix-flow --auto <bug 描述> 或 /bugfix-flow auto <bug 描述> → 模式 A（auto）/bugfix-flow #123 → 模式 B（manual）/bugfix-flow auto #123 → 模式 B（auto）/bugfix-flow → 模式 C（恢复已有会话）
状态持久化
Bugfix-Flow 有两个状态位置：
- pre-worktree pending state：默认不创建；仅在 pick 前需要澄清或暂停时，保存在启动命令所在仓库根目录的
.bugfix-flow/pending.json
- 正式状态机 state：目标 worktree 创建后，状态保存在目标 worktree 根目录的
.bugfix-flow/
正式开发会话状态保存在 worktree 根目录的 .bugfix-flow/ 中：
.bugfix-flow/
state # 当前阶段
mode # auto | manual
context.json # bug 上下文（Issue 或 adhoc）
verify-report.md # 验证报告
.bugfix-flow/pending.json 不是正式状态机 state，只用于 pick 前的短期恢复。同一 repo root 只允许一个 pending 流程；若已存在 pending，新请求必须提示恢复、覆盖或取消。
持久化状态机（.bugfix-flow/ 在 bugfix-pick 时创建）：
picked → implementing → ready → finished
↑__________↓
verify 失败
执行流程
前置检查（所有模式）
git rev-parse --is-inside-work-tree — 失败则停止，提示当前目录不是 git 仓库git remote -v — 失败则停止，提示仓库缺少 remote- 若参数是
#N，额外执行 gh auth status 和 gh issue view
- superpowers 可用性检查 — 必须确认以下运行时 skill 可发现：
using-git-worktrees、finishing-a-development-branch
- Claude Code：优先检查
~/.claude/plugins/superpowers/skills/ 下对应 SKILL.md
- Codex：优先检查已安装的
superpowers 插件；优先假设其来自 OpenAI Curated
- 若缺失任一必需 skill，则立即停止，且不要创建或修改
.bugfix-flow/
模式 A：从 bug 描述开始
bug 描述
→ 1. bugfix-flow 在调用 `bugfix-pick` 前预检查输入是否包含最小复现线索、预期行为和验证目标
→ 2. 如需澄清或暂停，bugfix-flow 写入 `.bugfix-flow/pending.json` 后再 AskUserQuestion
→ 3. bugfix-pick（创建 worktree + 分支 + 正式 .bugfix-flow/）
→ 4. bugfix-flow 删除源仓库的 `.bugfix-flow/pending.json`
→ [进入状态机循环]
模式 B：基于已有 Issue 修复
Issue #N
→ 1. bugfix-pick（读取 Issue + 创建 worktree + 分支 + 正式 .bugfix-flow/）
→ 2. bugfix-flow 删除源仓库的 `.bugfix-flow/pending.json`（如果存在）
→ [进入状态机循环]
模式 C：恢复会话
- 查找当前目录或父目录中的
.bugfix-flow/state
- 若找到正式 state，读取
state 和 mode，按状态调用对应子 skill
- 若未找到正式 state，查找当前 git 仓库根目录的
.bugfix-flow/pending.json
- 若找到 pending，则恢复 pick 前澄清流程；同一 repo root 只允许一个 pending 流程
- 若都未找到，视为新会话，进入模式 A 或 B
状态机循环
| 当前 state | 调用子 skill | 成功后 state |
|---|
picked | bugfix-implement | implementing |
implementing | bugfix-verify | ready（失败则保持 implementing） |
ready | bugfix-implement | implementing |
finished | bugfix-finish | 删除 .bugfix-flow/ |
Manual 模式行为
每调用完一个子 skill 并更新 state 后：
- 输出当前进展摘要
- 告知用户当前 state 和下一步建议
- 停止，等待用户下一次输入
/bugfix-flow
Auto 模式行为
bugfix-flow 连续自动调用子 skill，直到：
state 变为 ready- 某个子 skill 返回失败/阻塞
- 遇到需要人工介入的不可恢复错误
状态查找规则
- 从当前目录开始，检查是否存在
.bugfix-flow/state
- 若不存在，向父目录逐级递归查找（最多到 git 仓库根目录）
- 若找到，以该目录为 worktree 根目录读取正式
.bugfix-flow/ 下所有文件
- 若未找到正式 state，检查当前 git 仓库根目录的
.bugfix-flow/pending.json
- 若找到 pending，恢复 pick 前澄清流程
- 若都未找到，视为新会话，进入模式 A 或 B
Mode 判定与写入
解析 $ARGUMENTS：
- 如果以
--auto 或 auto 开头 → mode=auto
- 否则 →
mode=manual
若参数为 finish / --finish：
- 仅在当前
state=ready 时有效
bugfix-flow 先将 .bugfix-flow/state 写为 finished- 然后调用
bugfix-finish
新建会话时（模式 A/B），不得在源仓库根目录预先创建正式 .bugfix-flow/state。
仅在 pick 前需要澄清或暂停时，bugfix-flow 在源仓库根目录创建 .bugfix-flow/pending.json。
同一 repo root 已存在 pending 时，不自动覆盖；必须提示用户恢复、覆盖或取消。
调用 bugfix-pick 前，bugfix-flow 必须先检查 bug 描述是否包含最小复现线索、预期行为和至少一条验证目标：
- 信息充足 → 调用
bugfix-pick
- manual 模式信息不足 → 先写入
.bugfix-flow/pending.json 后再 AskUserQuestion
- auto 模式信息不足 → 停止并说明缺失项，不调用
bugfix-pick
bugfix-pick 创建目标 worktree 后，必须在目标 worktree 根目录创建正式 .bugfix-flow/ 并写入：
mode: manual | auto
state: picked
正式状态写入成功后，bugfix-flow 删除源仓库的 .bugfix-flow/pending.json（如果存在），完成 handoff。
pending 生命周期由 bugfix-flow 编排器统一维护：
bugfix-flow 负责创建、更新和删除源仓库 .bugfix-flow/pending.jsonbugfix-pick 只负责在目标 worktree 创建正式 .bugfix-flow/- 删除 pending 必须在源仓库根目录执行
rm -f .bugfix-flow/pending.json
状态更新规则
bugfix-flow 统一负责更新 .bugfix-flow/state：
- 子 skill 返回成功 → 按状态流转表写入下一个 state
- 仅在 pick 前需要澄清或暂停时写入
.bugfix-flow/pending.json
bugfix-pick 成功写入正式状态后，bugfix-flow 回到源仓库根目录删除 .bugfix-flow/pending.jsonbugfix-verify 失败 → 保持 implementingbugfix-finish 只在用户显式要求收尾时触发，不因验证通过自动触发
核心治理规则
- bugfix-flow 允许没有 GitHub Issue 的 adhoc 修复
- 若存在 Issue，则只作为上下文与后续 PR 关联依据；不强制在流程中提交或开 PR
.bugfix-flow/ 不应提交到仓库，必要时提醒用户添加到 .gitignore- 验证通过后默认进入
ready，等待人工决定是否提交、开 PR 或继续补改
ready 阶段允许重新进入 bugfix-implement 处理新发现的问题
错误处理
gh 未安装或未认证且用户输入 #N → 停止，提示修复- Issue 不存在或无权限 → 停止，让用户确认
- bug 描述不足以形成可验证修复目标 → manual 模式下澄清；auto 模式下停止并说明缺失项
- 子 skill 执行失败 → 保留
.bugfix-flow/ 和 worktree，输出失败详情，提示用户修复后继续
- 找不到
.bugfix-flow/ 但用户意图是恢复 → 提示用户先执行 /bugfix-flow <bug 描述> 或 /bugfix-flow #<编号>
- 找到
.bugfix-flow/pending.json 但找不到正式 state → 恢复 pick 前澄清流程，不把 pending 当成正式 state
- 用户要求
finish 但当前不在 ready → 停止，提示先完成验证
