loop-it

name	loop-it
description	Automated issue loop with checkpoint/resume: fetch open GitHub issues → dependency-aware topological sort → implement each issue end-to-end → review with /review-it → document with /note-it → ship with /ship-it → repeat. Persists state to .loop-state.json for crash recovery. Triggers on: loop-it, loop issues, auto implement, 批量实现, 循环实现, 实现所有issue, 恢复循环, resume loop.
user-invocable	true
allowed-tools	["Bash(gh:*)","Bash(git:*)","Bash(cat:*)"]

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

Fetch all open GitHub issues, resolve dependency order, implement each through the full pipeline (内联实现 → /review-it → /note-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、/note-it、/ship-it 仍是真实 skill，经 Skill 工具调用。

---

Overview

前置检查 → 读取状态文件 → Fetch Issues → 构建依赖图 → 拓扑排序
                                                              |
    ┌───────────────────────────────────────────────────────────┘
    |
    v
┌──────────────── 单 Issue 循环 ────────────────┐
|                                               |
|  从检查点恢复？—— 跳过已完成/失败的             |
|                                               |
|  分支准备 (checkout main, pull, create branch) |
|        |                                      |
|  Skip/Blocked? ── 是 → 标记 skipped/blocked, 写检查点 |
|        |                                      |
|        否                                      |
|        |                                      |
|  内联实现 → 出错？→ 分类 → 恢复 → 重试        |
|        |              |                       |
|        |           失败 → 检查点, 下一个         |
|        |                                      |
|  /review-it → 有问题？→ 修复 → 重跑 review     |
|        |                                      |
|  /note-it (捕获实现笔记, best-effort)          |
|        |                                      |
|  /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 3h 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 3h 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. Document with /note-it

After review, before ship — capture implementation notes:

/note-it

This creates docs/issue#XXXX.html with design decisions, deviations, tradeoffs, and open questions.

On success:

📝 Issue #{number} notes captured

On failure (can't determine issue number, etc.) — print warning but do not block shipping:

⚠️  /note-it failed for Issue #{number}: {reason}. Continuing to ship.

Write checkpoint with phase: "note_done".

3f. 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 3h Branch Cleanup, proceed to next issue.

3g. Checkpoint

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

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

3h. 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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

错误分类与恢复

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

错误类别	检测信号	恢复策略	最大重试
build_failure	编译错误、undefined、类型错误	读错误，修代码，重新构建	3
test_failure	断言失败、test failed	读测试输出，修实现，重跑测试	3
lint_failure	lint 错误、格式问题	自动修复 (lint --fix)，重跑	2
merge_conflict	CONFLICT 标记	rebase origin/main，解决冲突，push	2
ci_failure	gh pr checks 失败	读 CI 日志，本地修复，push	2
auth_failure	403、401、认证错误	停止，告知用户重新认证	0
rate_limit	rate limit、secondary abuse	等待 60s，重试	3
issue_unclear	issue 无验收条件且无法推断需求	跳过，标记 failed	0
network_error	timeout、connection refused	等待 30s，重试	3
unknown	其他情况	记录完整错误，跳过	0

恢复协议：

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:

Emoji	Meaning
📋	Fetch / list
🔄	Processing issue
⏭️	Skip
🔒	Blocked (dependency not shipped)
✅	Success
❌	Failure
🔍	Review
📝	Notes (/note-it)
🚀	Ship
⚠️	Warning / retry
📊	Progress / summary

---

Safety Guards

• Never force-push to main/master — always use feature branches
• Never skip review — always run /review-it before /ship-it
• Never skip notes — always run /note-it before /ship-it（best-effort，不阻塞）
• 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

Scenario	Handling
No open issues	Print "nothing to do" and exit
All issues are questions	Skip all, report summary
gh not authenticated	Print error, suggest gh auth login, exit
Issue has no body	Use title only to decide skip/implement
Issue references PRD/SPEC	读取被引用的 PRD/SPEC 作为上下文，agent 内联实现
Multiple issues depend on each other	Topological sort; dependencies already shipped first
Git repo is dirty before starting	前置检查 Check 3: stash/abort/force
State file corrupted (invalid JSON)	警告用户，提供从头开始或中止选项。绝不自动覆盖
State file from different repo	检测 repo 字段不匹配，警告，提供从头开始选项
Issue in_progress from previous run	检查分支是否存在、是否有变更 → 恢复或重新开始
User aborts mid-loop	状态文件已包含最新检查点，下次运行可恢复
New issues created during loop	不重新获取。完成当前批次后运行新 /loop-it
Circular dependencies	打印警告，按编号顺序打破循环
/note-it can't find issue number	打印警告，跳过 /note-it，继续 /ship-it
.loop-state.json is git-tracked	警告用户添加到 .gitignore，继续
误以为需要外部 goal 命令	本环境无此命令；「实现 issue」由 agent 内联完成（读 issue → 写代码 → 测试），不要中止循环

---

Relationship to Other Skills

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

Part of the goal-workflow pipeline:

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