work-on-issues

处理 Issue

获取 GitHub/GitLab issue，进行分类并逐个实现（一次处理一个主 issue），运行 find-mismatch 审查，然后关闭 issue。

1. Tracker 设置

通过 git remote -v 检测托管平台。将 $TRACKER 设置为 gh 或 glab。 术语：

• GitHub：pr / comment
• GitLab：mr / note

---

2. 阶段 1：获取与分类

1. 列出未关闭的 issue：使用 gh issue list --state open --json number,title,labels 或 glab issue list -O json。
2. 筛选：仅保留主 issue（标题以 PRD: 或 feat: 开头）。在自动/批处理运行中跳过其他 issue（但用户明确指定时可以处理）。
3. 选择：用户选择 issue 编号或选择从当前项开始的模式。
4. 预检查：
   • 确认 issue 处于未关闭状态（若已关闭则跳过）。
   • 通过标签 PRD 或标题前缀 PRD: 检测 PRD/Epic。跳过实现，并将其添加到 $PRD_TRACKER，以便自动检查是否可关闭。
5. 读取详情：获取 issue 完整内容和评论（gh issue view --comments / glab issue view --comments）。
6. 指派与添加标签：标记为进行中，并移除 needs-triage。

---

3. 依赖项与关联

解析 issue 正文中的 ## Blocked by（匹配 #42 或完整 issue URL），以构建 DEPS[issue] = [blockers]。 如果可行，创建原生 tracker 关联（例如，使用 GitLab API /links 和 is_blocked_by，或使用带有 blocked_by=true 的 GitHub 子 issue API）。若无法创建，则改用文本引用。

---

4. 阶段 2：实现（一次处理一个主 issue）

1. 创建 Worktree：

   git worktree add .claude/worktrees/issue-<number> -b work-on-issue-<number>
   

2. 复制 .env 文件：将 .env 和 .env.* 文件复制到 worktree 目录。
3. 分派子 Agent（在 .claude/worktrees/issue-<number> 中使用 subagent_type: "full-stack-engineer"）： 提示词规范：

   Implement issue #<number>: <title>.
   Acceptance Criteria: <AC>
   Branch/Worktree: work-on-issue-<number> in .claude/worktrees/issue-<number>
   API/best-practices: Search via `context7` or web.
   Compile/Lint errors: If 3+ consecutive failures, check Reference Directories (<RefDirs>) to align configurations.
   Parallel subtasks: Decompose & dispatch sub-agents if tasks are independent (no shared files/dirs).
   Post-implementation: Run `find-mismatch` skill on modified files only. Auto-apply confirmed fixes without prompting. Re-run tests.
   Output: Summary, find-mismatch fixes, tests run, and commit hash.
   Commit format: `fix: resolve #<number> — <short description>`
   

4. 验证：检查输出和差异，并运行测试。
5. 提交：确保在 worktree 中提交更改（fix: resolve #<number> — <desc>）。

---

5. 阶段 3：提交与关闭

1. 创建 PR/MR：使用 “Closes #” 关联 issue。
2. 自动合并：立即合并（压缩提交并删除分支）。
3. 评论：发布实现摘要。
4. 关闭：移除分类/进度标签，添加 ai-agent-closed，并关闭 issue。
5. 传播 .env 文件：移除 worktree 前，将修改过的 env 文件复制回主工作目录：

   WT=.claude/worktrees/issue-<number>
   for wtf in "$WT"/.env "$WT"/.env.*; do
     [ -f "$wtf" ] || continue
     base=$(basename "$wtf")
     if [ ! -f "$base" ] || ! cmp -s "$base" "$wtf"; then
       cp "$wtf" "$base" && echo "Propagated $base back"
     fi
   done
   

6. 清理：

   git worktree remove .claude/worktrees/issue-<number>
   git branch -d work-on-issue-<number>
   

---

6. PRD 自动关闭

关闭子 issue 后，检查 PRD_TRACKER 中的所有 PRD。读取 PRD 描述/链接。如果所有引用的子 issue（如 #42）都已关闭，则关闭该 PRD，并将其从 PRD_TRACKER 中移除。

---

7. 子任务并行化

符合以下条件时，将主 issue 拆分为子任务：

• 涉及互不重叠的文件/文件夹。
• 产出相互独立（不存在顺序依赖）。 如果子任务共用文件、存在严格的流程依赖，或需要先完成配置，则按顺序执行。

子任务提示词规范：

Implement subtask for issue #<number>: <title>.
Subtask: <details>
Working Directory: .claude/worktrees/issue-<number>
Scope: Modify <MAY_MODIFY>, DO NOT modify <MUST_NOT_MODIFY>.
Compile/Lint errors: If 3+ consecutive failures, check Reference Directories (<RefDirs>).
Post-implementation: Run `find-mismatch` on modified files, auto-fix.
Verification: Run relevant tests. Return summary, modified files, test results.

---

8. 执行模式

批处理与后续模式

1. 获取所有未关闭的 issue，筛选主 issue（PRD:、feat:）。
2. 从 issue 正文解析 DEPS 映射，并设置正式关联。
3. 显示进度表：| Issue | Title | Type | Blocked By | Agent | Status | PR/MR |
4. 循环：
   • 选择下一个未解决阻塞项数量为 0 的 issue。跳过已关闭或 PRD issue。
   • 分派子 Agent 到 worktree。
   • 运行验证 -> 合并 PR/MR -> 关闭 issue -> 传播 env 文件 -> 清理 -> 检查 PRD。
   • 重新评估依赖项。重复上述步骤。
5. 完成后重新获取所有未关闭的 issue（外层循环），以发现新增的主 issue。仅当不存在未关闭的主 issue 或用户中断时退出。

单个 Issue 模式

单独处理所选 issue。跳过依赖关系图处理。

---

9. 标签与辅助项

标签	含义	颜色
PRD	父级跟踪 issue	#0075CA
in-progress	正在处理	#E4E669
ready-for-agent	已准备好交由 Agent 处理	#0E8A16
ai-agent-closed	已由 AI 关闭	#5319E7

添加标签时，先尝试直接更新。如果找不到，则先创建标签（例如，为 in-progress 创建颜色为 #E4E669 的标签），然后重试。

---

10. 边缘情况

• 没有 CLI：直接使用 API，或让用户安装 gh/glab。
• 冲突/循环：报告循环依赖，并跳过受影响的问题。
• 外部阻塞项：将未关闭的外部问题视为未解决的阻塞项。
• API 链接失败：回退为文本引用。
• 没有主要问题：告知用户，并询问是否要处理非主要问题。
• 环境文件被 gitignore 忽略：移除工作树前，必须将环境文件传回，以便在后续运行中保留。不要提交密钥。