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 认证

bash

gh auth status

失败 → 打印

❌ gh CLI 未认证。运行: gh auth login

，退出。

Check 2: Git 仓库

bash

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

失败 → 打印

❌ 不在 git 仓库中

，退出。

Check 3: Git 工作树清洁度

bash

git status --porcelain

有输出（dirty）→ 打印

⚠️ 工作树有未提交的更改

，提供选项：

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

默认 B。

Check 4: 在默认分支上

bash

git branch --show-current

不在 main/master → 打印

⚠️ 当前在 {branch} 分支

，提供选项：

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

Check 5: 远程可达

bash

git ls-remote --heads origin

失败 → 打印

❌ 无法访问远程仓库。检查网络和权限

，退出。

Check 6: 状态文件存在？

bash

cat .loop-state.json

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

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

状态文件

位置

.loop-state.json

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

.gitignore

。

格式

json

{
  "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:

bash

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:

Issues with no dependencies first (sorted by number ascending)
Issues whose dependencies are all shipped/closed next
Blocked issues (depend on other open issues) last
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

.loop-state.json

exists (from 前置检查 Check 6)

Read the file
Print progress summary:

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

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

If no state file

Initialize new state file with all fetched issues as
```
pending
```
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:

bash

# 确认在 main 上
git checkout main
git pull

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

Branch naming:

feat/issue-N-short-desc

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

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 可调用，必须自己干）：

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

bash

# 切回 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

恢复协议：

匹配错误类别
匹配成功 → 应用恢复策略，重试最多 N 次
重试全部失败 → 标记
```
failed
```
，写检查点，继续下一个 issue
无法匹配 → 标记
```
failed
```
（error_class:
```
unknown
```
），继续
绝不无限重试。绝不未经确认 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
🚀	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
```
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	打印警告，按编号顺序打破循环
`.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）
  └── /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

loop-it

NPX Install

Tags

SKILL.md Content

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

Overview

前置检查

Check 1: gh CLI 认证

Check 2: Git 仓库

Check 3: Git 工作树清洁度

Check 4: 在默认分支上

Check 5: 远程可达

Check 6: 状态文件存在？

状态文件

位置

格式

状态值

写入规则

Step 1: Fetch Issues & Build Dependency Graph

Parse Dependencies

Step 2: Resume or Initialize

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

If no state file

Step 3: Process Single Issue

3a. Branch Prep

3b. Skip or Implement

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

3d. Review with /review-it

3e. Ship with /ship-it

3f. Checkpoint

3g. Branch Cleanup

Next Issue

错误分类与恢复

进度可观测性

Logging Rules

Safety Guards

Edge Cases

Relationship to Other Skills

loop-it

NPX Install

Tags

SKILL.md Content

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

Overview

前置检查

Check 1: gh CLI 认证

Check 2: Git 仓库

Check 3: Git 工作树清洁度

Check 4: 在默认分支上

Check 5: 远程可达

Check 6: 状态文件存在？

状态文件

位置

格式

状态值

写入规则

Step 1: Fetch Issues & Build Dependency Graph

Parse Dependencies

Step 2: Resume or Initialize

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

If no state file

Step 3: Process Single Issue

3a. Branch Prep

3b. Skip or Implement

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

3d. Review with /review-it

3e. Ship with /ship-it

3f. Checkpoint

3g. Branch Cleanup

Next Issue

错误分类与恢复

进度可观测性

Logging Rules

Safety Guards

Edge Cases

Relationship to Other Skills

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