SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsloop-it

loop-it

General & other

View repository

Updated 10-16 00:02

About this skill

loop-it — automated Issue implementation loop with checkpoint recovery

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

⚠️ Key prerequisite: the implementation step is completed inline and autonomously by the agent, without relying on any external /goal command. In this environment there is no callable goal command or skill. Therefore the "implement issue" stepmust be completed inline by the agent: directly read the issue's title and body (including the PRD/SPEC and acceptance criteria it references), autonomously complete the closed loop of "understand requirements → write/modify code → run tests and lint → satisfy all acceptance criteria", and keep working until all acceptance criteria for that issue are satisfied and the tests/build pass.Do notattempt to use the Skill tool to call goal(it will report goal is a UI command, not a skill), and alsodo notbecause you cannot find /goal abort the loop./review-it、/ship-it is still a real skill, invoked via the Skill tool.In the loop-it loop, do not call /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

Pre-checks

Before starting the loop, verify all prerequisites in order. If any check fails, stop and print the error.

Check 1: gh CLI authentication

gh auth status

Failure → print ❌ gh CLI 未认证。运行: gh auth login, exit.

Check 2: Git repository

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

Failure → print ❌ 不在 git 仓库中, exit.

Check 3: Git working tree cleanliness

git status --porcelain

Has output (dirty) → print ⚠️ 工作树有未提交的更改, provide options:

  • A. git stash Stage and continue
  • B. Abort, let the user handle it themselves
  • C. Force continue (not recommended)

Default B.

Check 4: On the default branch

git branch --show-current

Not on main/master → print ⚠️ 当前在 {branch} 分支, provide options:

  • A. git checkout main && git pull Switch
  • B. Continue on the current branch

Check 5: Remote reachable

git ls-remote --heads origin

Failure → print ❌ 无法访问远程仓库。检查网络和权限, exit.

Check 6: Does the state file exist?

cat .loop-state.json

Exists → print a progress summary, provide options:

  • A. Resume from checkpoint
  • B. Start from scratch (delete the state file)
  • C. Abort

State file

Location

.loop-state.json, placed in the repo root directory.Must be added to .gitignore. If the file is tracked by git, print a warning and suggest the user add it to .gitignore。

Format

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

State values

pending | in_progress | skipped | shipped | failed | blocked

Write rules

  • Write immediately after each state transition (pending → in_progress、in_progress → shipped/failed/skipped , etc.)
  • Write using cat > .loop-state.json << 'LOOPSTATE'\n{json}\nLOOPSTATE
  • If the state file already exists but its contents are corrupted (invalid JSON), print a warning and provide the option to start from scratch or abort.Never automatically overwrite a corrupted file
  • After the loop completes, keep the state file (as a record); the user can delete it manually

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 Pre-checks 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
  1. For each failed issue: ask user — retry or skip?
  2. For in_progress issues: check if branch exists, changes exist → decide resume from current state or restart
  3. Skip all shipped/skipped issues
  4. 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(consistent with /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 (inline autonomous implementation)

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

The implementation is completed inline by the agent(in this environment there is no goal command/skill to call, you must do it yourself):

  1. Read the issue's title and body, extract the requirements and all acceptance criteria; if the body references a PRD/SPEC file (e.g. tasks/prd-*.md), also read it as context
  2. Read the relevant existing code, follow the project's existing style, naming, and dependency conventions
  3. Implement/modify code to satisfy all acceptance criteria
  4. Run the project's build, tests, and lint (e.g. go build ./...、go vet ./...、go test ./...）
  5. Keep working until the issue's acceptance criteria areall satisfiedand tests/build/lint pass

Do not try to invoke goalwith the Skill tool (it will report goal is a UI command, not a skill), and do not stop because you cannot find /goal — the implementation is work you complete inline yourself.

On success:

✅ Issue #{number} implementation complete

Write checkpoint with phase: "implement_done".

On failure — classify error (see Error Classification and Recovery), 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 Error Classification and Recovery), 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 Progress Observability).

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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Error Classification and Recovery

When an error occurs, first classify it, then recover according to the strategy.

Error Category Detection Signal Recovery Strategy Max Retries
build_failure Compile errors, undefined, type errors Read the error, fix the code, rebuild 3
test_failure Assertion failures, test failed Read the test output, fix the implementation, rerun the tests 3
lint_failure Lint errors, formatting issues Auto-fix (lint --fix), rerun 2
merge_conflict CONFLICT markers rebase origin/main, resolve conflicts, push 2
ci_failure gh pr checks failed Read the CI logs, fix locally, push 2
auth_failure 403, 401, authentication errors Stop, tell the user to re-authenticate 0
rate_limit rate limit、secondary abuse Wait 60s, retry 3
issue_unclear Issue has no acceptance criteria and requirements cannot be inferred Skip, mark failed 0
network_error timeout、connection refused Wait 30s, retry 3
unknown Other cases Log the full error, skip 0

Recovery protocol:

  1. Match the error category
  2. Match succeeded → apply recovery strategy, retry up to N times
  3. All retries failed → mark failed, write a checkpoint, continue to the next issue
  4. No match → mark failed（error_class: unknown), continue
  5. Never retry infinitely. Never force-push without confirmation.

Progress Observability

After completing each issue, print structured progress:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 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 — see the Error Classification and Recovery table, do not retry infinitely
  • 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 — keep for investigation
  • Checkpoint at every transition — write a checkpoint on every status change, not just on ship
  • State file integrity — warn the user when corrupted, never overwrite automatically
  • State file in .gitignore — remind the user to add .loop-state.json
  • Strictly sequential — handle only one issue at a time (implementation modifies the working tree, cannot be parallelized)
  • Skip dependency-blocked issues — when a depended-on issue is not shipped, mark blocked
  • Implementation is completed inline by the agent — this environment has no goal command/skill can be invoked; "implement issue" must be completed by the agent itself reading the issue, writing code, and running tests. When reporting goal is a UI command, not a skill , do not abort, directly implement inline

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 Read the referenced PRD/SPEC as context, agent implements inline
Multiple issues depend on each other Topological sort; dependencies already shipped first
Git repo is dirty before starting Pre-check Check 3: stash/abort/force
State file corrupted (invalid JSON) Warn the user, provide options to start over or abort. Never overwrite automatically
State file from different repo Detect repo field mismatch, warn, provide option to start over
Issue in_progress from previous run Check whether the branch exists and whether there are changes → resume or start over
User aborts mid-loop The state file already contains the latest checkpoint, the next run can resume
New issues created during loop Do not re-fetch. After completing the current batch, run the new /loop-it
Circular dependencies Print a warning, break the loop in numbered order
.loop-state.json is git-tracked Warn the user to add to .gitignore, continue
Mistakenly believe an external goal command is needed This environment does not have this command; "implement issue" is completed inline by the agent (read issue → write code → test), do not abort the loop

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