issue-loop

name	issue-loop
description	Autonomous GitHub issue fixer. For each open issue: Session 1 writes a spec + runs /deep-verify-plan (≥95/100), Session 2 uses /writing-plans to produce a TDD task list, Session 3 implements with TDD + /verification-before-completion then commits and pushes. Quality gates validate each artifact. Loops until no open issues remain. All orchestration events are visible inline in the CC terminal.

Issue Loop

Autonomous GitHub issue fixer running entirely in the CC terminal. Every event — issue selection, session start, gate result, label change — is visible inline as it happens.

Usage: /issue-loop [START_ISSUE=N] [START_SESSION=N]

Examples:

• /issue-loop — process all open issues from the beginning
• /issue-loop START_ISSUE=6 — skip issues #1–#5, start at #6
• /issue-loop START_ISSUE=6 START_SESSION=3 — resume issue #6 at Session 3

---

Step 0: Argument Parsing

Parse $ARGUMENTS. Extract:

• START_ISSUE — default 1. Skip all issues with number < this value.
• START_SESSION — default 1. For the first issue processed, skip sessions before this number. After the first issue completes (or fails), reset START_SESSION to 1 for all subsequent issues.

Example: START_ISSUE=6 START_SESSION=3 → for issue #6 start at Session 3; all later issues start at Session 1.

---

Step 1: Setup

Run all of the following via Bash before the main loop.

1a. Hard dependency check

command -v jq      &>/dev/null || { echo "ERROR: 'jq' not found. Install jq and re-run."; exit 1; }
command -v gh      &>/dev/null || { echo "ERROR: 'gh' not found. Install GitHub CLI and re-run."; exit 1; }
command -v python3 &>/dev/null || { echo "ERROR: 'python3' not found. Install Python 3 and re-run."; exit 1; }

1b. Auto-detect project path and repo slug

PROJECT_PATH="$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "ERROR: Not inside a git repo."; exit 1; }
REPO_SLUG="$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null)" || { echo "ERROR: gh not configured or no remote."; exit 1; }
echo "Project : $PROJECT_PATH"
echo "Repo    : $REPO_SLUG"

1c. Ensure labels exist

for label in "in-progress" "implemented" "needs-review"; do
  gh label create "$label" --force 2>/dev/null || true
done

1d. Create directories

mkdir -p "$PROJECT_PATH/.a5c/plans" "$PROJECT_PATH/.a5c/logs"

1e. Soft dependency warnings

Check these paths and warn (do not fail) if missing:

• ~/.claude/skills/deep-verify-plan/SKILL.md
• Superpowers writing-plans skill (look in ~/.claude/plugins/cache/claude-plugins-official/superpowers/*/skills/writing-plans/SKILL.md)
• Superpowers verification-before-completion skill

Warn format: ⚠ Soft dep missing: <name> — sessions will run but skill may not load

---

Step 2: Main Loop

Repeat the following until no open issues remain. Track TOTAL_FIXED=0, TOTAL_FAILED=0, ITERATION=0.

2a. Get next issue

Run via Bash. Increment ITERATION. Print a separator:

════════════════════════════════════════════
  Iteration N — fetching next issue...
════════════════════════════════════════════

Fetch the next issue (sorted by number ascending, skip those labeled in-progress or needs-review, skip those with number < START_ISSUE):

ISSUE_JSON=$(gh issue list \
  --state open \
  --limit 50 \
  --json number,title,body,labels \
  --jq "[.[] | select(
          (.labels | map(.name) | (contains([\"in-progress\"]) or contains([\"needs-review\"])) | not)
          and (.number >= $START_ISSUE)
        )] | sort_by(.number) | .[0]")

If the result is empty or null: print ✓ No more open issues. All done! with the summary, then exit.

Set from the result: ISSUE_NUM, ISSUE_TITLE (parse from $ISSUE_JSON).

Set file paths:

BRIEF_FILE = $PROJECT_PATH/.a5c/plans/issue-N-brief.md
SPEC_FILE  = $PROJECT_PATH/.a5c/plans/issue-N-spec.md
PLAN_FILE  = $PROJECT_PATH/.a5c/plans/issue-N-plan.md

Print:

  Issue #N: <title>
  Brief : $BRIEF_FILE
  Spec  : $SPEC_FILE
  Plan  : $PLAN_FILE

2b. Write brief file

Use Bash to write the issue brief:

{
  printf "# Issue #%s: %s\n\n## Body\n\n%s\n" \
    "$ISSUE_NUM" \
    "$(echo "$ISSUE_JSON" | jq -r '.title')" \
    "$(echo "$ISSUE_JSON" | jq -r '.body // "(no body)"')"
} > "$BRIEF_FILE"

2c. Label in-progress + record start SHA

gh issue edit "$ISSUE_NUM" --add-label "in-progress" 2>/dev/null || true
IMPL_START_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")

2d. Determine effective start session

For this issue only: if ISSUE_NUM == START_ISSUE and START_SESSION > 1, set EFFECTIVE_START_SESSION = START_SESSION. Otherwise EFFECTIVE_START_SESSION = 1.

Create a TaskCreate task: Issue #N — Session 1: Spec + Deep-Verify.

---

Session 1: Spec + Deep-Verify

Skip if EFFECTIVE_START_SESSION > 1. In that case, validate the existing spec at SPEC_FILE using Gate 1 and skip to Session 2 if valid; if invalid, label needs-review, remove in-progress, increment TOTAL_FAILED, continue to next issue.

Otherwise, dispatch via Agent tool:

Agent(
  subagent_type: "general-purpose",
  description: "Issue #N — Session 1: Spec + Deep-Verify",
  prompt: <SESSION 1 PROMPT — see Session Prompts section below>
)

After the agent completes:

• Run Gate 1 on SPEC_FILE.
• Gate 1 FAIL or agent returned indicating rate-limit exhaustion → check output for rate limit signals (you've hit your usage limit, rate limit, quota exceeded). If rate-limited: remove in-progress label (do NOT add needs-review), skip to next issue. Otherwise (genuine failure): label needs-review, remove in-progress, increment TOTAL_FAILED, continue to next issue.
• Gate 1 PASS → proceed to Session 2.

Update task to completed.

---

Session 2: Writing Plans

Create a TaskCreate task: Issue #N — Session 2: Writing Plans.

Skip if EFFECTIVE_START_SESSION > 2. In that case, validate the existing plan at PLAN_FILE using Gate 2; if invalid, label needs-review, remove in-progress, increment TOTAL_FAILED, continue.

Otherwise, dispatch via Agent tool:

Agent(
  subagent_type: "general-purpose",
  description: "Issue #N — Session 2: Writing Plans",
  prompt: <SESSION 2 PROMPT — see Session Prompts section below>
)

After the agent completes:

• Run Gate 2 on PLAN_FILE (with SPEC_FILE for drift check).
• Gate 2 FAIL: label needs-review, remove in-progress, increment TOTAL_FAILED, continue to next issue.
• Gate 2 PASS → proceed to Session 3.

Update task to completed.

After processing the resume issue, reset START_SESSION = 1 for all subsequent issues.

---

Session 3: TDD Implementation

Create a TaskCreate task: Issue #N — Session 3: TDD Implementation.

Dispatch via Agent tool:

Agent(
  subagent_type: "general-purpose",
  description: "Issue #N — Session 3: TDD Implementation",
  prompt: <SESSION 3 PROMPT — see Session Prompts section below>
)

After the agent completes:

• Run Gate 3 with IMPL_START_SHA.
• Gate 3 PASS:

  gh issue close "$ISSUE_NUM" \
    --comment "Automatically fixed via 3-session issue-loop skill. Spec: \`.a5c/plans/issue-N-spec.md\` | Plan: \`.a5c/plans/issue-N-plan.md\`." \
    2>/dev/null || true
  gh issue edit "$ISSUE_NUM" --add-label "implemented" --remove-label "in-progress" 2>/dev/null || true
  

  Print: ✓ Issue #N FIXED. Increment TOTAL_FIXED.
• Gate 3 FAIL: label needs-review, remove in-progress, increment TOTAL_FAILED. Print: ✗ Issue #N failed — needs-review.

Update task to completed.

---

Step 3: Loop End / Summary

When get_next_issue returns nothing, print:

════════════════════════════════════════════
  Fixed  : N  |  Failed : N  |  Iterations: N
════════════════════════════════════════════

---

Session Prompts

Substitute {ISSUE_NUM}, {REPO_SLUG}, {BRIEF_FILE}, {SPEC_FILE}, {PLAN_FILE}, {PROJECT_PATH} before dispatching.

Session 1 Prompt

You are writing a verified spec for GitHub issue #{ISSUE_NUM} from repo {REPO_SLUG}. The issue brief is at {BRIEF_FILE}.

Your tasks:
(1) Read {BRIEF_FILE} and the full issue with: gh issue view {ISSUE_NUM}
(2) Thoroughly explore the codebase to understand context and root cause.
(3) Write a comprehensive spec to {SPEC_FILE}. The spec must include:
    ## Problem (root cause analysis with exact file:line references)
    ## Acceptance Criteria (numbered, testable)
    ## Proposed Solution (architecture and approach)
    ## Edge Cases & Out of Scope
    ## Test Strategy (what to test and how)
(4) Run babysitter to deeply verify the spec using the deep-verify-plan skill. Invoke it like this:
    /babysitter:yolo Run the deep-plan-verification process via the /deep-verify-plan skill.
      Process file: ~/.a5c/processes/deep-plan-verification.js
      Inputs: planFile={SPEC_FILE}, projectRoot={PROJECT_PATH}, requireApproval=false,
              taskDescription=Deep spec verification for issue #{ISSUE_NUM} — improve quality to 95/100 across 8 dimensions
    Wait for babysitter to complete (it will iterate automatically until score >= 95).
    Save the final verified spec back to {SPEC_FILE}.

Do NOT write any implementation code — this session is spec-only.

Session 2 Prompt

You are writing an implementation plan for GitHub issue #{ISSUE_NUM} from repo {REPO_SLUG}. The issue brief is at {BRIEF_FILE}. The verified spec is at {SPEC_FILE}.

Your tasks:
(1) Read {BRIEF_FILE} and {SPEC_FILE} carefully.
(2) Run babysitter to write the implementation plan using the writing-plans skill:
    /babysitter:yolo Run the writing-plans skill to produce a TDD implementation plan.
      Invoke Skill("superpowers:writing-plans") with specFile={SPEC_FILE}, outputFile={PLAN_FILE}
      Wait for babysitter to complete. The skill will write the plan directly to {PLAN_FILE}.

The plan must:
- Use checkbox (- [ ]) syntax for every step
- Include exact file paths
- Include real code for every code step (no placeholders)
- Specify exact test commands with expected output
- Include commit steps after each passing test group

Quality bar: minimum 5 task blocks, no TBD/TODO/FIXME anywhere.

Do NOT write any implementation code — plan only.

Session 3 Prompt

You are implementing the fix for GitHub issue #{ISSUE_NUM} from repo {REPO_SLUG}.
- Issue brief : {BRIEF_FILE}
- Verified spec: {SPEC_FILE}
- Implementation plan: {PLAN_FILE}

Your tasks:
(1) Read {BRIEF_FILE}, {SPEC_FILE}, and {PLAN_FILE} carefully. Also run: gh issue view {ISSUE_NUM}
(2) Before writing any code, invoke the coding standards skill: Invoke Skill("superpowers:coding-standards") — all code you write MUST comply with those standards.
(3) Execute the plan using strict TDD: for each task, write a failing test first, then implement the minimum code to make it pass.
(4) TESTING STRATEGY — detect whether the issue touches frontend (any .tsx/.ts React files, UI components, pages, hooks):
    - If YES: write Playwright CLI tests using 'npx playwright test' (write test files under frontend/tests/ or e2e/, run with 'npx playwright test').
    - If backend only: use pytest.
    - If both: use both.
(5) Commit after each passing test group with a clear message referencing issue #{ISSUE_NUM}.
(6) Push after every commit.
(7) Maintain code quality: no regressions, no skipped tests, all edge cases from the spec handled.
(8) Run the full test suite before finishing.
(9) Run babysitter to run the final QA gate using the verification-before-completion skill:
    /babysitter:yolo Run the verification-before-completion skill as the final QA gate.
      Invoke Skill("superpowers:verification-before-completion")
      Wait for babysitter to complete. Fix every issue it raises before continuing.
(10) All changes must be production-ready with no regressions.

Do NOT close the issue yourself — the runner closes it on success.

---

Quality Gates

Gate 1 — Spec Validation

Run via Bash after Session 1:

# Hard fail: file missing or empty
[ -s "$SPEC_FILE" ] || { echo "✗ Gate 1 FAIL: spec file missing or empty"; exit 1; }

# Hard fail: too short
char_count=$(wc -c < "$SPEC_FILE")
[ "$char_count" -lt 800 ] && { echo "✗ Gate 1 FAIL: spec too short (${char_count} chars < 800)"; exit 1; }

# Warnings: expected section headings
missing=()
grep -qi "## .*problem\|## .*root cause\|## .*issue" "$SPEC_FILE" || missing+=("Problem/Root Cause")
grep -qi "## .*accept\|## .*criteria\|## .*done\|## .*goal" "$SPEC_FILE" || missing+=("Acceptance Criteria/Goal")
grep -qi "## .*edge\|## .*corner\|## .*scope\|## .*out.of" "$SPEC_FILE" || missing+=("Edge Cases/Scope")
[ ${#missing[@]} -gt 0 ] && echo "⚠ Gate 1 WARNING: possible missing sections: ${missing[*]} (continuing — babysitter may use different headings)"

echo "✓ Gate 1 PASS: spec looks valid (${char_count} chars)"

Gate 2 — Plan Validation

Run via Bash after Session 2. Inline Python for placeholder check:

# Hard fail: file missing
[ -s "$PLAN_FILE" ] || { echo "✗ Gate 2 FAIL: plan file missing or empty"; exit 1; }

# Hard fail: too few task items
task_count=$(grep -cE '^\s*-\s*\[[ x]\]' "$PLAN_FILE" 2>/dev/null || echo 0)
list_count=$(grep -cE '^\s*-\s+\S'       "$PLAN_FILE" 2>/dev/null || echo 0)
if [ "$task_count" -lt 3 ] && [ "$list_count" -lt 5 ]; then
  echo "✗ Gate 2 FAIL: plan has only ${task_count} checkbox / ${list_count} list items"
  exit 1
fi

# Placeholder check via Python (strips code fences; ignores negation context)
py_out=$(python3 - "$PLAN_FILE" 2>&1 <<'PYEOF'
import sys, re
content = open(sys.argv[1], encoding='utf-8', errors='replace').read()
content = re.sub(r'```[\s\S]*?```', '', content)
bad = []
for line in content.split('\n'):
    if re.match(r'^\s*-\s*\[[ x]\]', line):
        continue
    if re.search(r'\b(no|zero|without|not found|none|absence of|free of)\b.{0,60}\b(TBD|TODO|FIXME)\b', line, re.IGNORECASE):
        continue
    if re.search(r'\b(TBD|TODO|FIXME)\b.{0,60}\b(not found|none found|free|clean|absent|zero|0)\b', line, re.IGNORECASE):
        continue
    if re.search(r'\b(TBD|TODO|FIXME)\b|implement later|fill in', line, re.IGNORECASE):
        print(f'  placeholder: {line.strip()[:120]}', file=sys.stderr)
        bad.append(line)
if bad:
    sys.exit(1)
PYEOF
)
if [ $? -ne 0 ]; then
  echo "✗ Gate 2 FAIL: plan contains placeholder text (TBD/TODO/FIXME)"
  [ -n "$py_out" ] && echo "$py_out"
  exit 1
fi

# Drift check: spec file paths vs plan (warning only)
if [ -s "$SPEC_FILE" ]; then
  matched=0 total=0
  while IFS= read -r f; do
    [ -z "$f" ] && continue
    total=$((total + 1))
    grep -qF "$f" "$PLAN_FILE" 2>/dev/null && matched=$((matched + 1))
  done < <(grep -oE '[a-zA-Z0-9_/-]+\.[a-zA-Z]{2,4}' "$SPEC_FILE" 2>/dev/null | grep -vE '^\.' | sort -u | head -20)
  if [ "$total" -gt 0 ] && [ "$matched" -eq 0 ]; then
    echo "⚠ Gate 2 WARNING: plan references none of the ${total} file paths mentioned in spec — possible drift"
  elif [ "$total" -gt 0 ]; then
    echo "✓ Gate 2: plan covers ${matched}/${total} file paths from spec"
  fi
fi

echo "✓ Gate 2 PASS: plan looks valid (${task_count} task items)"

Gate 3 — Implementation Validation

Run via Bash after Session 3:

# Hard fail: no new commits
current_sha=$(git rev-parse HEAD 2>/dev/null || echo "")
if [ -z "$current_sha" ] || [ "$current_sha" = "$IMPL_START_SHA" ]; then
  echo "✗ Gate 3 FAIL: no new commits since session start"
  exit 1
fi
new_commits=$(git log --oneline "${IMPL_START_SHA}..HEAD" 2>/dev/null | wc -l || echo 0)
echo "✓ Gate 3 PASS: ${new_commits} new commit(s)"

# Push any unpushed commits
if git rev-parse -q --verify "@{u}" >/dev/null 2>&1; then
  unpushed=$(git log --oneline "@{u}..HEAD" 2>/dev/null | wc -l || echo 0)
else
  unpushed=$(git log --oneline "origin/HEAD..HEAD" 2>/dev/null | wc -l || echo 0)
fi
if [ "$unpushed" -gt 0 ]; then
  echo "↑ Pushing ${unpushed} unpushed commit(s)..."
  git push 2>/dev/null && echo "✓ Push successful" || echo "⚠ Push failed — may need manual push"
fi

---

Failure Handling

Scenario	Behavior
Gate 1 fail	Label needs-review, remove in-progress, TOTAL_FAILED++, continue to next issue
Gate 2 fail	Label needs-review, remove in-progress, TOTAL_FAILED++, continue to next issue
Gate 3 fail	Label needs-review, remove in-progress, TOTAL_FAILED++, continue to next issue
Agent output contains rate-limit signal	Remove in-progress, do NOT label needs-review, skip issue and continue
No open issues	Exit cleanly with summary

Rate-limit detection in agent output: look for any of these patterns in the agent's response:

• you've hit your usage limit / you've hit your session limit
• rate limit / rate-limited
• usage limit reached / quota exceeded
• limit.*reset

If detected, the issue is skipped without the needs-review label (it will be retried next time you run /issue-loop).

---

Notes

• The skill auto-detects repo root and slug — works in any git repo with a GitHub remote.
• All orchestration (issue selection, session start, gate result, label changes) is printed inline in the CC terminal."
• Babysitter sessions handle quality convergence internally (score ≥ 95) using the babysitter:yolo process.
• START_SESSION only applies to the first issue processed; all subsequent issues always start at Session 1.