Loop It

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".