loop-it — 带检查点恢复的自动化 Issue 实现循环

Fetch all open GitHub issues, resolve dependency order, implement each through the full pipeline (内联实现 → /review-it → /ship-it), persist progress to state file, and resume from checkpoint on crash.

⚠️ 关键前提：实现步骤由 agent 内联自主完成，不依赖任何外部 /goal 命令。 本环境中不存在可调用的 goal 命令或 skill。因此「实现 issue」这一步必须由 agent 内联完成：直接读取该 issue 的标题与正文（含其引用的 PRD/SPEC 与验收条件），自主完成"理解需求 → 写/改代码 → 跑测试与 lint → 满足全部验收条件"的闭环，持续工作直到该 issue 的验收条件全部满足且测试/构建通过。不要尝试用 Skill 工具调用 goal（会报 goal is a UI command, not a skill），也不要因为找不到 /goal 而中止循环。/review-it、/ship-it 仍是真实 skill，经 Skill 工具调用。loop-it 循环中不调用 /note-it。

Overview

前置检查 → 读取状态文件 → Fetch Issues → 构建依赖图 → 拓扑排序
                                                              |
    ┌───────────────────────────────────────────────────────────┘
    |
    v
┌──────────────── 单 Issue 循环 ────────────────┐
|                                               |
|  从检查点恢复？—— 跳过已完成/失败的             |
|                                               |
|  分支准备 (checkout main, pull, create branch) |
|        |                                      |
|  Skip/Blocked? ── 是 → 标记 skipped/blocked, 写检查点 |
|        |                                      |
|        否                                      |
|        |                                      |
|  内联实现 → 出错？→ 分类 → 恢复 → 重试        |
|        |              |                       |
|        |           失败 → 检查点, 下一个         |
|        |                                      |
|  /review-it → 有问题？→ 修复 → 重跑 review     |
|        |                                      |
|  /ship-it → 出错？→ 分类 → 恢复                |
|        |                                      |
|  分支清理 (checkout main, pull, delete branch) |
|        |                                      |
|  检查点 (标记 shipped)                         |
|        |                                      |
└────────┴──────────────────────────────────────┘
         |
         v
    全部完成 → 最终 Summary

前置检查

开始循环前，按顺序验证所有前提条件。任何检查失败则停止并打印错误。

Check 1: gh CLI 认证

gh auth status

失败 → 打印 ❌ gh CLI 未认证。运行: gh auth login，退出。

Check 2: Git 仓库

git rev-parse --is-inside-work-tree

失败 → 打印 ❌ 不在 git 仓库中，退出。

Check 3: Git 工作树清洁度

git status --porcelain

有输出（dirty）→ 打印 ⚠️ 工作树有未提交的更改，提供选项：

• A. git stash 暂存后继续
• B. 中止，让用户自行处理
• C. 强制继续（不推荐）

默认 B。

Check 4: 在默认分支上

git branch --show-current

不在 main/master → 打印 ⚠️ 当前在 {branch} 分支，提供选项：

• A. git checkout main && git pull 切换
• B. 继续在当前分支

Check 5: 远程可达

git ls-remote --heads origin

失败 → 打印 ❌ 无法访问远程仓库。检查网络和权限，退出。

Check 6: 状态文件存在？

cat .loop-state.json

存在 → 打印进度摘要，提供选项：

• A. 从检查点恢复
• B. 从头开始（删除状态文件）
• C. 中止

状态文件

位置

.loop-state.json，放在 repo 根目录。必须添加到 .gitignore。如果文件被 git 跟踪，打印警告并建议用户添加到 .gitignore。

格式

{
  "version": 1,
  "started_at": "2025-06-09T10:00:00Z",
  "updated_at": "2025-06-09T10:30:00Z",
  "repo": "owner/repo-name",
  "total_issues": 8,
  "issues": {
    "3": {
      "status": "shipped",
      "branch": "feat/issue-3-add-priority",
      "started_at": "2025-06-09T10:00:00Z",
      "completed_at": "2025-06-09T10:15:00Z",
      "attempts": 1
    },
    "4": {
      "status": "failed",
      "phase": "goal",
      "error_class": "build_failure",
      "branch": "feat/issue-4-filter-tasks",
      "started_at": "2025-06-09T10:15:00Z",
      "updated_at": "2025-06-09T10:30:00Z",
      "attempts": 3,
      "last_error": "test TestFilterPriority failed: expected 3, got 0"
    },
    "7": {
      "status": "pending"
    }
  }
}

状态值

pending | in_progress | skipped | shipped | failed | blocked

写入规则

• 每次状态转换后立即写入（pending → in_progress、in_progress → shipped/failed/skipped 等）
• 写入使用 cat > .loop-state.json << 'LOOPSTATE'\n{json}\nLOOPSTATE
• 如果状态文件已存在但内容损坏（非法 JSON），打印警告，提供从头开始或中止的选项。绝不自动覆盖损坏文件
• 循环完成后保留状态文件（作为记录），用户可手动删除

Step 1: Fetch Issues & Build Dependency Graph

Fetch all open issues:

gh issue list --state open --json number,title,labels,body --limit 100

Parse Dependencies

Read each issue body, look for patterns:

• Dependencies: #3, #5 or Depends on: #3
• depends on #3 or requires #3 (in body text)

Build a dependency graph. Sort using topological order:

1. Issues with no dependencies first (sorted by number ascending)
2. Issues whose dependencies are all shipped/closed next
3. Blocked issues (depend on other open issues) last
4. Circular dependencies → print warning ⚠️ 循环依赖检测到: #A ↔ #B，按编号顺序处理，break cycle by number order

If no dependency patterns found in any issue body, fall back to number-ascending sort.

Print ordered list:

📋 Found N open issues (topological sort):
  #1: Add priority field (无依赖)
  #3: Display indicator (依赖 #1)
  #5: Add selector (依赖 #1)
  #7: Filter view (依赖 #1, #3)

If no open issues → print ✅ No open issues found. Nothing to do. and exit.

Step 2: Resume or Initialize

If .loop-state.json exists (from 前置检查 Check 6)

1. Read the file
2. Print progress summary:

📊 从检查点恢复 (上次更新: {updated_at})
   ✅ Shipped:  #1, #3
   ⏭️  Skipped:   #2 (question)
   ❌ Failed:    #4 (build_failure — 3 attempts)
   📋 Remaining: #5, #7

3. For each failed issue: ask user — retry or skip?
4. For in_progress issues: check if branch exists, changes exist → decide resume from current state or restart
5. Skip all shipped/skipped issues
6. Continue from first pending/retryable issue

If no state file

1. Initialize new state file with all fetched issues as pending
2. Start from first issue in topological order

Step 3: Process Single Issue

For each issue, print a banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 Processing Issue #{number}: {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3a. Branch Prep

Prepare a clean git environment for this issue:

# 确认在 main 上
git checkout main
git pull

# 创建功能分支
git checkout -b feat/issue-{N}-{short-desc}

Branch naming: feat/issue-N-short-desc or fix/issue-N-short-desc（与 /ship-it 保持一致）

3b. Skip or Implement

Read the issue title and body. Decide if it needs code implementation:

Skip if the issue is:

• A question / discussion / clarification
• Documentation-only (typos, wording)
• Already implemented (check codebase)
• A duplicate of another issue
• Clearly labeled wontfix, question, discussion, or invalid
• Not actionable (no clear acceptance criteria and cannot infer any)

Skip (blocked) if the issue has unresolved dependencies:

• Check the dependency graph from Step 1
• If any dependency issue is not shipped (still pending, failed, blocked, or not in state file) → skip as blocked
• The dependency issue itself may have failed or been skipped — in either case, this issue cannot proceed safely

When skipping:

⏭️  Skipping Issue #{number}: {title}
   Reason: {why}

When blocked:

🔒 Blocking Issue #{number}: {title}
   Reason: dependency #{dep_number} not shipped ({status})

Update state: pending → skipped or pending → blocked, write checkpoint, run 3g Branch Cleanup, proceed to next issue.

3c. Implement (内联自主实现)

Update state: pending → in_progress, phase: "implement", write checkpoint.

由 agent 内联完成实现（本环境无 goal 命令/skill 可调用，必须自己干）：

1. 读取该 issue 的标题与正文，提取需求与全部验收条件（Acceptance Criteria）；若正文引用了 PRD/SPEC 文件（如 tasks/prd-*.md），一并读取作为上下文
2. 阅读相关现有代码，遵循项目既有风格、命名与依赖约定
3. 实现/修改代码以满足全部验收条件
4. 跑项目的构建、测试与 lint（如 go build ./...、go vet ./...、go test ./...）
5. 持续工作直到该 issue 的验收条件全部满足且测试/构建/lint 通过

不要尝试用 Skill 工具调用 goal（会报 goal is a UI command, not a skill），也不要因找不到 /goal 而中止——实现就是你自己内联完成的工作。

On success:

✅ Issue #{number} implementation complete

Write checkpoint with phase: "implement_done".

On failure — classify error (see 错误分类与恢复), apply recovery strategy, retry up to max attempts. If all retries exhausted:

⚠️  Issue #{number} failed: {error_class} after {N} attempts
   Manual intervention required.

Update state: in_progress → failed, write checkpoint, run 3g Branch Cleanup, proceed to next issue.

3d. Review with /review-it

Write checkpoint with phase: "review".

/review-it

If review finds actionable issues:

🔍 Review found N issue(s) for #{number}. Fixing...

Fix each accepted finding, re-run /review-it. Repeat until clean or max 2 review rounds.

If review is clean:

✅ Review clean for Issue #{number}

Write checkpoint with phase: "review_done".

3e. Ship with /ship-it

/ship-it

This commits, pushes, creates PR, merges, and closes the issue.

On success:

🚀 Issue #{number} shipped successfully!

On failure — classify error (see 错误分类与恢复), apply recovery. If unresolvable:

⚠️  Issue #{number} ship failed: {error}. Manual merge required.

Update state: in_progress → failed, phase: "ship", write checkpoint, run 3g Branch Cleanup, proceed to next issue.

3f. Checkpoint

After successful ship, update state: in_progress → shipped, set completed_at, write checkpoint.

Print progress (see 进度可观测性).

3g. Branch Cleanup

After each issue (shipped, skipped, or failed):

# 切回 main
git checkout main
git pull

# 删除本地功能分支（仅当 shipped 时）
git branch -d feat/issue-{N}-{short-desc}

For failed issues: do NOT delete the branch. Keep it for investigation.

Next Issue

Return to Step 3 for the next issue in topological order.

When all issues processed, print final summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Loop Complete — Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Shipped:   N issues  (#1, #3, ...)
  ⏭️  Skipped:   N issues  (#2 — reason, #5 — reason, ...)
  🔒 Blocked:   N issues  (#7 — depends on #4, ...)
  ❌ Failed:    N issues  (#4 — error, ...)
  📋 Total:     N issues
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

错误分类与恢复

当错误发生时，先分类，再按策略恢复。

恢复协议：

1. 匹配错误类别
2. 匹配成功 → 应用恢复策略，重试最多 N 次
3. 重试全部失败 → 标记 failed，写检查点，继续下一个 issue
4. 无法匹配 → 标记 failed（error_class: unknown），继续
5. 绝不无限重试。绝不未经确认 force-push。

进度可观测性

每完成一个 issue 后，打印结构化进度：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Progress: 3/8 issues (37%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Shipped:  #1, #3
  ⏭️  Skipped:   #2 (question), #6 (duplicate)
  🔒 Blocked:   #7 (depends on #4 — failed)
  ❌ Failed:    #4 (build_failure — 3 attempts)
  📋 Remaining: #5, #8
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Logging Rules

Every key step MUST print a log line with emoji prefix:

Safety Guards

• Never force-push to main/master — always use feature branches
• Never skip review — always run /review-it before /ship-it
• Max retries per error class — 参见错误分类与恢复表，不无限重试
• Max 2 review rounds — don't over-polish
• Pause on CI failure — log and continue, don't auto-override branch protection
• Preserve issue labels — only close issues that were actually shipped
• Never auto-delete failed branches — 保留供调查
• Checkpoint at every transition — 每次状态变更写检查点，不仅仅在 ship 时
• State file integrity — 损坏时警告用户，绝不自动覆盖
• State file in .gitignore — 提醒用户添加 .loop-state.json
• Strictly sequential — 一次只处理一个 issue（实现会修改工作树，不能并行）
• Skip dependency-blocked issues — 依赖的 issue 未 shipped 时标记 blocked
• 实现由 agent 内联完成 — 本环境无 goal 命令/skill 可调用；「实现 issue」必须由 agent 自己读 issue、写代码、跑测试完成。报 goal is a UI command, not a skill 时不要中止，直接内联实现

Edge Cases

Relationship to Other Skills

/loop-it
  ├── 内联实现   ← implement each issue（agent 自主读 issue、写代码、测试；非外部命令）
  ├── /review-it  ← review code before shipping（skill）
  └── /ship-it    ← commit, PR, merge, close（skill）

Part of the goal-workflow pipeline:

/prd → /prd-to-spec → /to-issues → /loop-it (→ 内联实现 → /review-it → /ship-it)×N