✨ feat(state): add pre-worktree pending state

Author: crazygit

README.md

@@ -18,12 +18,13 @@ Issue-Flow ships two workflow state machines:
 
 ### `issue-flow`
 
-The issue-driven workflow has two parts: a pre-phase that produces a GitHub Issue number, and a persistent state machine that tracks delivery from that point on.
+The issue-driven workflow has two parts: a pre-worktree phase that produces a GitHub Issue number, and a persistent state machine that tracks delivery from that point on.
 
-**Pre-phase** (session-scoped, not persistable):
+**Pre-worktree phase** (short-lived pending state in the source repo):
 
 - `issue-brainstorm` turns a rough request into a design direction
 - `issue-create` turns the design spec into a GitHub Issue number
+- `.issue-flow/pending.json` can recover this short phase before a target worktree exists
 
 **Persistent state machine** (`.issue-flow/` created by `issue-pick`):
 
@@ -47,6 +48,8 @@ The top-level `issue-flow` skill is the orchestrator. It reads the current sessi
 
 The bugfix workflow is intentionally narrower. It is for cases where you already know there is a bug and want the agent to focus on reproducing, fixing, and verifying it before any commit or PR step.
 
+Bugfix work usually goes directly to `bugfix-pick`. If it must pause before a worktree exists, `.bugfix-flow/pending.json` can hold that short-lived pending state in the source repo.
+
 **Persistent state machine** (`.bugfix-flow/` created by `bugfix-pick`):
 
 ```text

docs/architecture.md

@@ -24,7 +24,7 @@ Everything else should remain delegated to focused skills or to `superpowers`.
 
 ### Orchestrator skill
 
-`skills/issue-flow/SKILL.md` is the entry point. It reads session state from `.issue-flow/`, determines the current phase, and hands control to the next workflow skill.
+`skills/issue-flow/SKILL.md` is the entry point. It reads formal session state from `.issue-flow/` in the target worktree, or pending pre-worktree state from the source repository when a worktree does not exist yet. It then determines the current phase and hands control to the next workflow skill.
 
 The orchestrator should stay small. It owns coordination, not execution details.
 
@@ -57,11 +57,13 @@ The `skills/issue-*` files implement each phase of the lifecycle:
 
 ## State Model
 
-Issue-Flow has two phases: a **pre-phase** and a **persistent state machine**.
+Issue-Flow has two phases: a **pre-worktree pending phase** and a **persistent state machine**.
 
-The pre-phase (`issue-brainstorm` + `issue-create`) runs before `.issue-flow/` exists. These stages are session-scoped and cannot be persisted or recovered. Mode is passed via `$ARGUMENTS --auto` since the mode file does not exist yet.
+The pre-worktree phase (`issue-brainstorm` + `issue-create`, and the setup immediately before `issue-pick`) runs before the target worktree exists. During this phase, the source repository root may contain `.issue-flow/pending.json`. That file is a short-lived handoff record, not a formal state-machine state. It lets the orchestrator recover from interruptions before the target worktree has been created. The same pattern is available to `bugfix-flow` as `.bugfix-flow/pending.json`, but only when bugfix pick needs to pause for clarification.
 
-The persistent state machine starts at `picked`, when `issue-pick` creates the `.issue-flow/` directory, worktree, and branch. From this point on, session state is persisted in `.issue-flow/` at the worktree root. Typical files include:
+Pending state is intentionally simple: one pending flow per repo root. If a new request finds an existing pending file in the same repo root, the orchestrator asks the user to recover, overwrite, or cancel instead of creating a multi-session registry.
+
+The persistent state machine starts at `picked`, when `issue-pick` creates the worktree, branch, and formal `.issue-flow/` directory. From this point on, session state is persisted in `.issue-flow/` at the worktree root. Typical files include:
 
 - `state` - current workflow phase
 - `mode` - manual or auto
@@ -70,7 +72,7 @@ The persistent state machine starts at `picked`, when `issue-pick` creates the `
 - `plan-path` - current implementation plan path
 - `verify-report.md` - verification output
 
-The source of truth for valid states and transitions is [../skills/issue-flow/references/state-schema.md](../skills/issue-flow/references/state-schema.md).
+The source of truth for valid states and transitions is [../skills/issue-flow/references/state-schema.md](../skills/issue-flow/references/state-schema.md). The bugfix equivalent is [../skills/bugfix-flow/references/state-schema.md](../skills/bugfix-flow/references/state-schema.md).
 
 ## Why Issue-Flow Depends On Superpowers
 

hooks/state-transition-guard

@@ -67,8 +67,8 @@ declare -A TRANSITIONS
 
 # issue-flow transitions
 TRANSITIONS[issue-brainstorm]="none"
-TRANSITIONS[issue-create]="brainstorm none"
-TRANSITIONS[issue-pick]="brainstorm none"
+TRANSITIONS[issue-create]="none"
+TRANSITIONS[issue-pick]="none"
 TRANSITIONS[issue-plan]="researching"
 TRANSITIONS[issue-research]="picked"
 TRANSITIONS[issue-implement]="planned reviewing"

skills/bugfix-finish/SKILL.md

@@ -31,7 +31,17 @@ allowed-tools:
 - `auto` → **auto 模式**
 - 其他/不存在 → **manual 模式**
 
-### 3. 分支收尾
+同时读取并暂存最终报告需要的 bug 摘要、当前分支名、worktree 路径和未提交变更摘要。
+
+### 3. 清理 `.bugfix-flow`
+
+在任何可能移除 worktree 的操作之前，删除当前 worktree 根目录下的 `.bugfix-flow/`：
+
+```bash
+rm -rf .bugfix-flow
+```
+
+### 4. 分支收尾
 
 #### Manual 模式
 
@@ -50,14 +60,6 @@ bugfix-flow 默认不要求在此阶段创建 PR。
 2. 清理 worktree
 3. 不自动 merge
 
-### 4. 清理 `.bugfix-flow`
-
-无论 manual 还是 auto，在收尾完成后删除 `.bugfix-flow/` 目录：
-
-```bash
-rm -rf .bugfix-flow
-```
-
 ### 5. 输出
 
 输出最终报告：
@@ -71,5 +73,5 @@ rm -rf .bugfix-flow
 
 - 不自动 merge PR
 - 不自动删除远端 branch
-- `.bugfix-flow/` 在 `finished` 后必须清理
+- `.bugfix-flow/` 在 `finished` 后必须清理，并且必须先于 worktree 移除执行
 - 删除时仅清理当前 worktree 根目录下的 `.bugfix-flow/`

skills/bugfix-flow/SKILL.md

@@ -21,6 +21,8 @@ allowed-tools:
   - 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)
@@ -50,7 +52,12 @@ allowed-tools:
 
 ## 状态持久化
 
-开发会话状态保存在 worktree 根目录的 `.bugfix-flow/` 中：
+Bugfix-Flow 有两个状态位置：
+
+1. **pre-worktree pending state**：默认不创建；仅在 pick 前需要澄清或暂停时，保存在启动命令所在仓库根目录的 `.bugfix-flow/pending.json`
+2. **正式状态机 state**：目标 worktree 创建后，状态保存在目标 worktree 根目录的 `.bugfix-flow/`
+
+正式开发会话状态保存在 worktree 根目录的 `.bugfix-flow/` 中：
 
 ```text
 .bugfix-flow/
@@ -60,6 +67,8 @@ allowed-tools:
   verify-report.md # 验证报告
 ```
 
+`.bugfix-flow/pending.json` 不是正式状态机 state，只用于 pick 前的短期恢复。同一 repo root 只允许一个 pending 流程；若已存在 pending，新请求必须提示恢复、覆盖或取消。
+
 持久化状态机（`.bugfix-flow/` 在 `bugfix-pick` 时创建）：
 
 ```text
@@ -84,24 +93,29 @@ picked → implementing → ready → finished
 
 ```text
 bug 描述
-  → 1. bugfix-pick（创建 worktree + 分支 + .bugfix-flow/context.json）
+  → 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 修复
 
 ```text
 Issue #N
-  → 1. bugfix-pick（读取 Issue + 创建 worktree + 分支）
+  → 1. bugfix-pick（读取 Issue + 创建 worktree + 分支 + 正式 .bugfix-flow/）
+  → 2. bugfix-flow 删除源仓库的 `.bugfix-flow/pending.json`（如果存在）
   → [进入状态机循环]
 ```
 
 ### 模式 C：恢复会话
 
 1. 查找当前目录或父目录中的 `.bugfix-flow/state`
-2. 读取 `state` 和 `mode`
-3. 按状态调用对应子 skill
-4. 更新状态后，根据 mode 决定是继续还是暂停
+2. 若找到正式 state，读取 `state` 和 `mode`，按状态调用对应子 skill
+3. 若未找到正式 state，查找当前 git 仓库根目录的 `.bugfix-flow/pending.json`
+4. 若找到 pending，则恢复 pick 前澄清流程；同一 repo root 只允许一个 pending 流程
+5. 若都未找到，视为新会话，进入模式 A 或 B
 
 ### 状态机循环
 
@@ -132,8 +146,10 @@ Issue #N
 
 1. 从当前目录开始，检查是否存在 `.bugfix-flow/state`
 2. 若不存在，向父目录逐级递归查找（最多到 git 仓库根目录）
-3. 若找到，以该目录为 worktree 根目录读取 `.bugfix-flow/` 下所有文件
-4. 若未找到，视为新会话，进入模式 A 或 B
+3. 若找到，以该目录为 worktree 根目录读取正式 `.bugfix-flow/` 下所有文件
+4. 若未找到正式 state，检查当前 git 仓库根目录的 `.bugfix-flow/pending.json`
+5. 若找到 pending，恢复 pick 前澄清流程
+6. 若都未找到，视为新会话，进入模式 A 或 B
 
 ## Mode 判定与写入
 
@@ -148,13 +164,36 @@ Issue #N
 - `bugfix-flow` 先将 `.bugfix-flow/state` 写为 `finished`
 - 然后调用 `bugfix-finish`
 
-新建会话时（模式 A/B），在调用 `bugfix-pick` 前创建 `.bugfix-flow/mode`。
+新建会话时（模式 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/` 并写入：
+
+```text
+mode: manual | auto
+state: picked
+```
+
+正式状态写入成功后，`bugfix-flow` 删除源仓库的 `.bugfix-flow/pending.json`（如果存在），完成 handoff。
+
+pending 生命周期由 `bugfix-flow` 编排器统一维护：
+- `bugfix-flow` 负责创建、更新和删除源仓库 `.bugfix-flow/pending.json`
+- `bugfix-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.json`
 - `bugfix-verify` 失败 → 保持 `implementing`
 - `bugfix-finish` 只在用户显式要求收尾时触发，不因验证通过自动触发
 
@@ -173,4 +212,5 @@ Issue #N
 - bug 描述不足以形成可验证修复目标 → manual 模式下澄清；auto 模式下停止并说明缺失项
 - 子 skill 执行失败 → 保留 `.bugfix-flow/` 和 worktree，输出失败详情，提示用户修复后继续
 - 找不到 `.bugfix-flow/` 但用户意图是恢复 → 提示用户先执行 `/bugfix-flow <bug 描述>` 或 `/bugfix-flow #<编号>`
+- 找到 `.bugfix-flow/pending.json` 但找不到正式 state → 恢复 pick 前澄清流程，不把 pending 当成正式 state
 - 用户要求 `finish` 但当前不在 `ready` → 停止，提示先完成验证

skills/bugfix-flow/references/state-machine.md

@@ -1,5 +1,11 @@
 # Bugfix-Flow 状态机
 
+## 预阶段（可选 pending）
+
+Bugfix-Flow 通常直接从输入进入 `bugfix-pick`。只有在 pick 前需要澄清或暂停时，才在源仓库根目录写入 `.bugfix-flow/pending.json`。
+
+`pending.json` 不是正式状态机 state；正式状态机仍从目标 worktree 的 `picked` 开始。
+
 ## 持久化状态机（`.bugfix-flow/` 在 `bugfix-pick` 时创建）
 
 ```text

skills/bugfix-flow/references/state-schema.md

@@ -4,7 +4,12 @@
 
 ## 目录结构
 
-每个被 `bugfix-flow` 接管的开发会话，在 **worktree 根目录**下创建 `.bugfix-flow/`：
+Bugfix-Flow 有两个状态位置：
+
+- pre-worktree 阶段：默认不创建；仅在 pick 前需要澄清或暂停时，在启动命令所在仓库根目录使用 `.bugfix-flow/pending.json`
+- 正式状态机阶段：在目标 **worktree 根目录**下创建 `.bugfix-flow/`
+
+每个被 `bugfix-flow` 接管的正式开发会话，在 **worktree 根目录**下创建 `.bugfix-flow/`：
 
 ```text
 .bugfix-flow/
@@ -18,6 +23,29 @@
 
 ## 文件格式
 
+### `pending.json`
+
+`.bugfix-flow/pending.json` 是 pre-worktree 暂存文件，不是正式状态机 state。它只用于 pick 前澄清或暂停时的短期恢复。
+
+建议格式：
+
+```json
+{
+  "flow": "bugfix-flow",
+  "mode": "manual",
+  "phase": "clarifying",
+  "summary": "空配置文件会导致服务启动 panic",
+  "created_at": "2026-04-30T12:00:00Z",
+  "updated_at": "2026-04-30T12:05:00Z"
+}
+```
+
+约束：
+
+- `phase` 取值：`clarifying`, `picking`
+- 同一 repo root 只允许一个 pending 流程；如已存在，编排器必须提示用户恢复、覆盖或取消
+- `pending.json` 不参与 `state-transition-guard` 的正式 state 校验
+
 ### `state`
 
 合法值（按流转顺序）：
@@ -77,12 +105,28 @@ picked → implementing → ready → finished
 1. 当前目录是否存在 `.bugfix-flow/state`
 2. 若不存在，向父目录逐级递归查找
 3. 若找到，以找到 `.bugfix-flow/` 的目录为基准读取其他文件
-4. 若未找到，视为不在 bugfix-flow 会话中
+4. 若未找到正式 state，编排器可以读取当前 git 仓库根目录的 `.bugfix-flow/pending.json` 恢复 pick 前澄清流程
+5. 若正式 state 和 pending 都未找到，视为不在 bugfix-flow 会话中
 
 ## 子 skill 行为约定
 
 - **读取**：子 skill 可以读取 `.bugfix-flow/` 中的文件获取上下文
 - **写入**：子 skill 可以写入 `context.json`、`verify-report.md` 等业务文件
 - 写入 `.bugfix-flow/` 状态文件时，优先使用 `Write`，不要依赖 shell 重定向
-- **状态更新**：`.bugfix-flow/state` 由 `bugfix-flow` 编排器统一维护，子 skill 不应直接修改
-- **mode 适配**：子 skill 优先读取 `.bugfix-flow/mode`，若不存在则默认 `manual`
+- **初始状态**：`bugfix-pick` 是唯一允许创建正式 `.bugfix-flow/state` 初始值的子 skill，初始 state 为 `picked`
+- **状态更新**：初始创建之后，`.bugfix-flow/state` 由 `bugfix-flow` 编排器统一维护，其他子 skill 不应直接修改
+- **mode 适配**：子 skill 在执行门控操作前，应按以下优先级检测运行模式：
+  1. 检查 `$ARGUMENTS` 是否包含 `--auto`
+  2. 读取 `.bugfix-flow/pending.json` 的 `mode`（用于 pick 前恢复阶段）
+  3. 读取 `.bugfix-flow/mode`（用于持久化状态机阶段）
+  4. 默认 `manual` 模式
+
+## 新会话初始化顺序
+
+新建会话时，编排器不得在源仓库预先创建正式 `.bugfix-flow/state`。仅当 pick 前需要澄清或暂停时，写入 `.bugfix-flow/pending.json`。正确顺序是：
+
+1. 如需澄清或暂停，`bugfix-flow` 在源仓库根目录写入或更新 `.bugfix-flow/pending.json`
+2. `bugfix-pick` 创建目标 worktree 和分支
+3. `bugfix-pick` 在目标 worktree 根目录写入 `.bugfix-flow/mode`、`.bugfix-flow/state` 和 `.bugfix-flow/context.json`
+4. `bugfix-flow` 回到源仓库根目录并删除 `.bugfix-flow/pending.json`（如果存在）
+5. 正式状态机从 `picked` 开始恢复和推进

skills/bugfix-implement/SKILL.md

@@ -7,6 +7,8 @@ disable-model-invocation: false
 allowed-tools:
   - Read
   - Write
+  - Edit
+  - MultiEdit
   - Glob
   - Grep
   - Bash(cat *)
@@ -46,6 +48,7 @@ allowed-tools:
 - 优先做最小可行修复，不扩大范围
 - 如需要补测试，测试内容应直接覆盖 `verification_targets`
 - 若当前 `state=ready` 且用户重新进入本阶段，视为处理验证中暴露的新缺口
+- 优先使用 `Edit` / `MultiEdit` 做局部修改；只有创建新文件或整体生成文件时才使用 `Write`
 
 ### 4. 输出