claude-dev-env 1.34.0 → 1.35.0

package/skills/pr-converge/SKILL.md

@@ -1,218 +1,236 @@
 ---
 name: pr-converge
 description: >-
-  Spawns a background subagent that drives the current PR to convergence by
-  alternating Cursor Bugbot and the in-house bugteam audit. The subagent
-  fetches each reviewer's findings, applies TDD fixes, pushes one commit per
-  tick, replies inline, and re-triggers the reviewer. Termination requires a
-  back-to-back clean cycle — bugbot CLEAN immediately followed by bugteam
-  CLEAN with no intervening fixes — at which point the subagent marks the PR
-  ready for review and terminates. Triggers: '/pr-converge', 'drive PR to
+  Drives the current PR to convergence by alternating Cursor Bugbot and the
+  in-house bugteam audit. Each invocation runs one tick of work in the main
+  session: fetches the latest reviewer state, applies TDD fixes for any
+  findings, pushes one commit per tick, replies inline, and re-triggers the
+  reviewer. To loop automatically, invoke as `/loop /pr-converge` — the /loop
+  skill self-paces re-entry via ScheduleWakeup. Convergence requires a
+  back-to-back clean cycle (bugbot CLEAN immediately followed by bugteam CLEAN
+  with no intervening fixes), at which point the PR is flipped to ready for
+  review and the loop terminates. Triggers: '/pr-converge', 'drive PR to
   convergence', 'loop bugbot and bugteam', 'babysit bugbot and bugteam',
   'until both are clean', 'converge this PR'.
 ---
 
 # PR Converge
 
-Delegates the bugbot ↔ bugteam convergence loop to a background subagent so the main session stays free. The subagent owns its own cadence and self-terminates on convergence or a hard blocker.
+Runs one tick of the bugbot ↔ bugteam convergence loop in the main session. Designed to be invoked under `/loop /pr-converge` so the parent's ScheduleWakeup paces re-entry. Self-terminates the loop on convergence (back-to-back clean) by flipping the PR to ready for review and omitting the next ScheduleWakeup.
+
+## Why the work runs in the main session, not a background subagent
+
+`ScheduleWakeup` is a primitive of the parent harness; it is not exposed to `general-purpose` subagents. A prior version of this skill spawned a background subagent and instructed it to call `ScheduleWakeup` at the end of each tick. The subagent's tool registry returned "No matching deferred tools found" for `ScheduleWakeup`, so the loop could never self-perpetuate — it ran exactly one tick and stalled. Running the loop in the main session via `/loop /pr-converge` puts the work on the same harness that owns `ScheduleWakeup`, eliminating that failure mode.
 
 ## When this skill applies
 
-The user is on a PR branch and wants both reviewers — Cursor's Bugbot AND the in-house `/bugteam` audit — to keep re-reviewing after each push, with findings auto-addressed between ticks. The PR stays in draft until convergence; on convergence the subagent flips it to ready for review.
+The user is on a PR branch and wants both reviewers — Cursor's Bugbot AND the in-house `/bugteam` audit — to keep re-reviewing after each push, with findings auto-addressed between ticks. The PR stays in draft until convergence; on convergence the skill flips it to ready for review.
+
+## Invocation modes
+
+- **`/loop /pr-converge`** (recommended): loops automatically. The /loop skill runs each tick and uses ScheduleWakeup to pace re-entry. Termination on convergence is automatic; the skill omits the next wakeup at the convergence tick.
+- **`/pr-converge`** (manual): runs exactly one tick and returns. Useful for ad-hoc state checks or for advancing the loop one step manually. The user re-runs the skill (or wraps it in `/loop`) to continue.
+
+## State across ticks
+
+Track the following in plain text in the assistant's response so subsequent ticks can re-read it from conversation context:
+
+- `phase`: `BUGBOT` or `BUGTEAM`. Start in `BUGBOT` on the first tick of a fresh loop.
+- `bugbot_clean_at`: the HEAD SHA at which bugbot last reported clean, or `null`. Reset to `null` whenever a new commit is pushed.
+- `inline_lag_streak`: integer counter, initialized to `0`. Tracks consecutive ticks where bugbot's review body indicates findings against `current_head` but the inline-comments API returns zero matching comments. Reset to `0` on any other branch outcome.
+- `tick_count`: integer, initialized to `0`. Increment on every tick to enforce the safety cap.
 
-## The Process
+Each tick begins by reading the prior tick's state line from the most recent assistant message and ends by emitting the updated state line.
 
-### Step 1: Gather PR context
+## Per-tick work
 
-From the current repo:
+### Step 1: Resolve current HEAD and PR context
+
+Read the prior tick's state line from the most recent assistant message (or initialize all fields if none). **Increment `tick_count` by 1.** This is the increment referenced in the **State across ticks** section; without it the safety cap (Step 3.5, §Safety cap) never fires.
 
 ```bash
 gh pr view --json number,url,headRefOid,baseRefName,headRefName,isDraft
 ```
 
-Capture `number`, `headRefOid`, owner/repo (from `url`), branch name, and current draft state. Pass these to the subagent so it can use them directly.
-
-### Step 2: Spawn the background subagent
-
-Invoke the `Agent` tool with:
-
-- `subagent_type: "general-purpose"`
-- `run_in_background: true`
-- `description: "PR convergence loop for #<N>"`
-- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
-
-Record the returned agent ID. Report to the user in one or two lines:
-
-- The subagent is running in the background and will alternate bugbot ↔ bugteam.
-- It self-terminates on back-to-back clean and flips the PR ready for review.
-- To stop it early, the user says "stop the converge loop" and you call `TaskStop <agent_id>`.
-
-The skill's job in the main session ends once the subagent is spawned and reported.
-
-### Step 3: Subagent prompt template
-
-Pass this verbatim to the subagent (substituting the bracketed values):
-
-> You are driving PR **#[NUMBER]** at **[OWNER]/[REPO]** (branch `[BRANCH]`, current HEAD `[HEAD_SHA]`) to convergence by alternating Cursor Bugbot and the in-house bugteam audit. Your job: keep the loop running until BOTH reviewers return CLEAN against the same HEAD with no intervening fixes, then mark the PR ready for review and stop.
->
-> **State you maintain across ticks** (keep it in your own working memory; you re-enter these instructions verbatim each wakeup):
->
-> - `phase`: `BUGBOT` or `BUGTEAM`. Start in `BUGBOT`.
-> - `bugbot_clean_at`: the HEAD SHA at which bugbot last reported clean, or `null`. Reset to `null` whenever you push a new commit.
-> - `inline_lag_streak`: integer counter, initialized to `0`. Tracks consecutive ticks where bugbot's review body indicates findings against `current_head` but the inline-comments API returns zero matching comments. Reset to `0` on any other branch outcome.
->
-> **Per-tick work** (do this now, then on each wakeup):
->
-> 1. Resolve current HEAD: `gh api repos/[OWNER]/[REPO]/pulls/[NUMBER] --jq '.head.sha'`. Capture it as `current_head`.
->
-> 2. Branch on `phase`:
->
->    **If `phase == BUGBOT`:**
->
->    a. Fetch the latest Cursor Bugbot review:
->       ```bash
->       gh api repos/[OWNER]/[REPO]/pulls/[NUMBER]/reviews \
->         --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
->       ```
->       Capture `commit_id`, `state`, `submitted_at`, and the body. Bugbot's body contains either `Cursor Bugbot has reviewed your changes and found <N> potential issue` (findings exist) or text indicating no issues found.
->
->    b. Fetch unaddressed inline comments from `cursor[bot]` on `current_head`:
->       ```bash
->       gh api repos/[OWNER]/[REPO]/pulls/[NUMBER]/comments \
->         --jq "[.[] | select(.user.login==\"cursor[bot]\") | select(.commit_id==\"$current_head\")]"
->       ```
->
->    c. Decide (the four branches below cover every input combination — match the first branch whose predicate holds):
->       - **No bugbot review yet, OR latest bugbot review's `commit_id` differs from `current_head`:** Re-trigger bugbot (step 3), set `bugbot_clean_at = null`, reset `inline_lag_streak = 0`, schedule next wakeup, return.
->       - **Latest review's `commit_id == current_head` AND zero unaddressed inline findings AND review body indicates clean:** Set `bugbot_clean_at = current_head`. Reset `inline_lag_streak = 0`. Transition `phase = BUGTEAM`. Continue to bugteam branch in this same tick — back-to-back convergence requires bugteam to run against the same HEAD before the next wakeup is scheduled.
->       - **Latest review's `commit_id == current_head` with unaddressed inline findings (review body indicates findings):** Apply the **Fix protocol** below to address them. Reset `inline_lag_streak = 0`. The fix protocol pushes a new commit, which sets `current_head` to the new SHA, sets `bugbot_clean_at = null`, replies inline on each thread, and re-triggers bugbot. Schedule next wakeup, return.
->       - **Latest review's `commit_id == current_head` AND review body indicates findings AND inline-comments API returns zero matching comments for `current_head`:** Treat as transient API propagation lag — bugbot publishes the review body and inline comments through separate API operations and the two writes can briefly desync. Increment `inline_lag_streak`. When `inline_lag_streak >= 3`, escalate as a hard blocker (bugbot review is structurally inconsistent — body claims findings while inline anchors stay empty across three consecutive ticks); report and terminate. Otherwise schedule next wakeup at `delaySeconds: 60` (lag is short-lived) and return; the inline comments should appear on the next tick.
->
->    **If `phase == BUGTEAM`:**
->
->    a. Run the in-house bugteam audit on the current PR:
->       ```bash
->       claude -p "/bugteam" --max-turns 200
->       ```
->       (The `/bugteam` skill audits the current PR against CODE_RULES, posts review threads, and converges or stops at its own internal cap. Wait for it to complete; capture exit and final summary.)
->
->    b. **Re-resolve current HEAD now** because `/bugteam` may have pushed commits during its run. The `current_head` from step 1 is potentially stale at this point:
->       ```bash
->       new_head=$(gh api repos/[OWNER]/[REPO]/pulls/[NUMBER] --jq '.head.sha')
->       ```
->       If `new_head != current_head`, set `current_head = new_head` AND set `bugbot_clean_at = null`. The new commits from bugteam invalidate bugbot's prior clean.
->
->    c. Inspect bugteam's output. Bugteam reports either `convergence (zero findings)` or a list of unfixed findings with file:line.
->
->    d. Decide based on the (post-bugteam) state — order matters; check pushed-during-bugteam FIRST so a convergence report against a stale HEAD never falsely terminates:
->       - **bugteam pushed during this tick (i.e., `bugbot_clean_at` was just reset to `null` in step b):** Re-trigger bugbot in this same tick (step 3) so the new HEAD enters bugbot's queue immediately, transition `phase = BUGBOT`, schedule next wakeup, return. The new commit needs a fresh bugbot review before convergence can be claimed.
->       - **bugteam reports convergence AND `bugbot_clean_at == current_head` (no push during this tick):** This is back-to-back clean. Mark the PR ready for review:
->         ```bash
->         gh pr ready [NUMBER] --repo [OWNER]/[REPO]
->         ```
->         Report to the parent in one sentence: "PR #[NUMBER] converged: bugbot CLEAN at [SHA], bugteam CLEAN at [SHA]; marked ready for review." Terminate; this is the final tick — skip scheduling the next wakeup.
->       - **bugteam reports convergence BUT `bugbot_clean_at != current_head` (no push during this tick):** Bugteam reached zero findings without committing, yet bugbot still needs re-confirmation against this HEAD. This branch is reachable only when state diverged BETWEEN ticks — for example, the user pushed a manual commit between two wakeups, leaving `current_head` ahead of the SHA bugbot last cleaned. Transition `phase = BUGBOT`, schedule next wakeup, return.
->       - **bugteam reports findings without committing fixes:** apply the **Fix protocol** below (which always re-triggers bugbot after the push), transition `phase = BUGBOT`, schedule next wakeup, return.
->
-> 3. Re-trigger bugbot (used in step 2.c first branch, in step 2.d BUGTEAM branch 1, and in the Fix protocol). Post a literal `bugbot run` PR comment:
->    ```bash
->    printf 'bugbot run\n' > /tmp/bugbot-run.md
->    gh pr comment [NUMBER] --repo [OWNER]/[REPO] --body-file /tmp/bugbot-run.md
->    rm /tmp/bugbot-run.md
->    ```
->    Use the literal phrase `bugbot run` exactly — Cursor Bugbot's documented re-trigger phrase, empirically the only one that fires a fresh review.
->
-> 4. Schedule the next wakeup with `ScheduleWakeup` using a single rule: `delaySeconds: 300` whenever bugbot was just re-triggered (whether by step 3 directly, by the Fix protocol's mandatory re-trigger, or by BUGTEAM branch 1's same-tick re-trigger). Bugbot finishes a review in 1–4 minutes, so 300s gives a one-minute safety margin past the upper bound. The single exception is the BUGBOT inline-lag branch, which uses `delaySeconds: 60` because no re-trigger fired and the only thing being awaited is GitHub's inline-comments API catching up. Set `reason` to one short sentence on what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set; set `prompt` to the literal sentinel `<<autonomous-loop-dynamic>>` so the next firing re-enters these instructions.
->
-> **Fix protocol** (used by both phases when findings exist):
->
-> - Read each referenced file:line.
-> - Write a failing test first when the finding has behavior to test. For pure doc, comment, or naming nits with no behavior, go straight to the fix.
-> - Implement the fix.
-> - Stage the affected files and create one new commit on the existing branch:
->   ```bash
->   git add <files> && git commit -m "fix(review): <brief summary>"
->   ```
->   Honor pre-commit and pre-push hooks; when a hook rejects, read its message, fix the underlying issue, retry. Hook rejections flag real underlying issues worth investigating.
-> - Push the new commit:
->   ```bash
->   git push origin [BRANCH]
->   ```
->   Capture the new HEAD SHA. Set `current_head` to it. Set `bugbot_clean_at = null`.
-> - Reply inline on each addressed comment thread:
->   ```bash
->   gh api -X POST repos/[OWNER]/[REPO]/pulls/[NUMBER]/comments/<comment_id>/replies \
->     -f body="Addressed in <new_sha>. <one-line description of the fix>."
->   ```
->   Use `--body-file` when the body contains backticks (per repo policy on `gh` body content).
-> - **Always re-trigger bugbot (step 3 above) after pushing a fix**, regardless of which phase originated the findings. Any new commit invalidates bugbot's prior clean by definition, so bugbot must re-review the new HEAD before convergence can be claimed. Re-triggering in the same tick saves a full wakeup cycle compared to deferring the trigger to the next tick — the fix protocol's last step before scheduling the wakeup is always `printf 'bugbot run\n' > /tmp/bugbot-run.md && gh pr comment ... --body-file /tmp/bugbot-run.md && rm /tmp/bugbot-run.md`.
->
-> **Stop conditions:**
->
-> - **Convergence** (back-to-back clean as defined in step 2.d BUGTEAM second branch — `bugteam reports convergence AND bugbot_clean_at == current_head` with no push during this tick): mark PR ready for review, report one-sentence summary to parent, terminate.
-> - **Hard blocker:** API auth failure persists across two ticks, a CI regression whose root cause falls outside this PR, a hook rejection investigated through three commits and still unresolved, `inline_lag_streak >= 3`, or `/bugteam` itself reports a stuck state. Report the specific blocker and your diagnosis to the parent, then terminate; skip scheduling the next wakeup.
-> - **Parent sends `TaskStop`:** terminate immediately.
->
-> **Safety cap:** when 30 ticks elapse before convergence, stop and report. That many rounds means something structural is wrong with the loop. (Higher than copilot-review's 20-tick cap because two reviewers run sequentially per round.)
-
-### Step 4: Report back to the user
-
-After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will alternate bugbot and bugteam and notify on convergence or blocker. Nothing else.
-
-## Stopping the subagent
-
-- Convergence → subagent stops itself, marks PR ready for review.
-- Blocker → subagent reports and stops.
-- User says stop → `TaskStop <agent_id>`.
-- User asks what loops are running → `TaskList`.
-
-## Ground rules (for the subagent)
+Capture `number` (`<NUMBER>`), `headRefOid` (`current_head`), owner/repo (from `url`), branch name (`<BRANCH>`).
+
+### Step 2: Branch on `phase`
+
+#### `phase == BUGBOT`
+
+a. Fetch Cursor Bugbot reviews newest-first and walk backwards until the first clean review:
+
+   ```bash
+   gh api repos/<OWNER>/<REPO>/pulls/<NUMBER>/reviews \
+     --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | reverse'
+   ```
+
+   Track dirty reviews in a temp file as you walk; the Fix protocol reads it back later in this tick:
+
+   ```bash
+   dirty_reviews_path=$(mktemp "${TMPDIR:-/tmp}/pr-converge-bugbot.XXXXXX")
+   : > "$dirty_reviews_path"
+   ```
+
+   Iterate from index 0 (most recent) toward older entries:
+
+   - Classify each review's body — **dirty** when it contains `Cursor Bugbot has reviewed your changes and found <N> potential issue`; **clean** otherwise.
+   - For a dirty review, append one JSON line to `$dirty_reviews_path` with `{review_id, commit_id, submitted_at, body}`.
+   - Stop at the first clean review. Older reviews are presumed addressed at that clean checkpoint and are not re-read.
+   - When index 0 is itself clean, `$dirty_reviews_path` stays empty.
+
+   Capture `commit_id`, `state`, `submitted_at`, and body of the index-0 review for the decision branches below. When a branch routes to the **Fix protocol**, read every entry from `$dirty_reviews_path` and address all of them — not just index 0.
+
+b. Fetch unaddressed inline comments from `cursor[bot]` on `current_head`:
+   ```bash
+   gh api repos/<OWNER>/<REPO>/pulls/<NUMBER>/comments \
+     --jq "[.[] | select(.user.login==\"cursor[bot]\") | select(.commit_id==\"$current_head\")]"
+   ```
+
+c. Decide (the four branches below cover every input combination — match the first branch whose predicate holds):
+   - **No bugbot review yet, OR latest bugbot review's `commit_id` differs from `current_head`:** Re-trigger bugbot (Step 3), set `bugbot_clean_at = null`, reset `inline_lag_streak = 0`, schedule next wakeup, return.
+   - **Latest review's `commit_id == current_head` AND zero unaddressed inline findings AND review body indicates clean:** Set `bugbot_clean_at = current_head`. Reset `inline_lag_streak = 0`. Transition `phase = BUGTEAM`. Continue to bugteam branch in this same tick — back-to-back convergence requires bugteam to run against the same HEAD before the next wakeup is scheduled.
+   - **Latest review's `commit_id == current_head` with unaddressed inline findings (review body indicates findings):** Apply the **Fix protocol** below to address them. Reset `inline_lag_streak = 0`. The fix protocol pushes a new commit, which sets `current_head` to the new SHA, sets `bugbot_clean_at = null`, replies inline on each thread, and re-triggers bugbot. Schedule next wakeup, return.
+   - **Latest review's `commit_id == current_head` AND review body indicates findings AND inline-comments API returns zero matching comments for `current_head`:** Treat as transient API propagation lag — bugbot publishes the review body and inline comments through separate API operations and the two writes can briefly desync. Increment `inline_lag_streak`. When `inline_lag_streak >= 3`, escalate as a hard blocker (bugbot review is structurally inconsistent — body claims findings while inline anchors stay empty across three consecutive ticks); report and terminate. Otherwise schedule next wakeup at `delaySeconds: 60` (lag is short-lived) and return; the inline comments should appear on the next tick.
+
+#### `phase == BUGTEAM`
+
+a. Run the in-house bugteam audit on the current PR by invoking the `Skill` tool in the main session:
+
+   ```
+   Skill({skill: "bugteam", args: "https://github.com/<OWNER>/<REPO>/pull/<NUMBER>"})
+   ```
+
+   The main session is the team lead, so `TeamCreate` fires from the orchestrator and `/bugteam` emits its CODE_RULES gate output, teammate spawn lines, and audit progress as expected. The skill audits the current PR against CODE_RULES, posts review threads, and converges or stops at its own internal cap. Wait for it to complete; capture exit and final summary.
+
+b. **Re-resolve current HEAD now** because `/bugteam` may have pushed commits during its run. The `current_head` from Step 1 is potentially stale at this point:
+   ```bash
+   new_head=$(gh api repos/<OWNER>/<REPO>/pulls/<NUMBER> --jq '.head.sha')
+   ```
+   If `new_head != current_head`, set `current_head = new_head` AND set `bugbot_clean_at = null`. The new commits from bugteam invalidate bugbot's prior clean.
+
+c. Inspect bugteam's output. Bugteam reports either `convergence (zero findings)` or a list of unfixed findings with file:line.
+
+d. Decide based on the (post-bugteam) state — order matters; check pushed-during-bugteam FIRST so a convergence report against a stale HEAD never falsely terminates:
+   - **bugteam pushed during this tick (i.e., `bugbot_clean_at` was just reset to `null` in step b):** Re-trigger bugbot in this same tick (Step 3) so the new HEAD enters bugbot's queue immediately, transition `phase = BUGBOT`, schedule next wakeup, return. The new commit needs a fresh bugbot review before convergence can be claimed.
+   - **bugteam reports convergence AND `bugbot_clean_at == current_head` (no push during this tick):** This is back-to-back clean. Mark the PR ready for review:
+     ```bash
+     gh pr ready <NUMBER> --repo <OWNER>/<REPO>
+     ```
+     Report to the user in one sentence: "PR #<NUMBER> converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>; marked ready for review." **Omit the next ScheduleWakeup call** — this terminates the /loop.
+   - **bugteam reports convergence BUT `bugbot_clean_at != current_head` (no push during this tick):** Bugteam reached zero findings without committing, yet bugbot still needs re-confirmation against this HEAD. This branch is reachable only when state diverged BETWEEN ticks — for example, the user pushed a manual commit between two wakeups, leaving `current_head` ahead of the SHA bugbot last cleaned. Transition `phase = BUGBOT`, schedule next wakeup, return.
+   - **bugteam reports findings without committing fixes:** apply the **Fix protocol** below (which always re-triggers bugbot after the push), transition `phase = BUGBOT`, schedule next wakeup, return.
+
+### Step 3: Re-trigger bugbot
+
+Used in Step 2 BUGBOT branch 1, in Step 2 BUGTEAM branch 1, and in the Fix protocol. Post a literal `bugbot run` PR comment. Write the body via the Write tool to a temp file, then pass it with `--body-file` (per the gh-body-file rule):
+
+```bash
+gh pr comment <NUMBER> --repo <OWNER>/<REPO> --body-file <path/to/bugbot_run.md>
+```
+
+The body file contains exactly the literal phrase `bugbot run` followed by a newline. Use that phrase exactly — empirically the only re-trigger Cursor Bugbot recognizes; alternative phrasings (`re-review`, `bugbot please`, etc.) silently no-op.
+
+### Step 3.5: Enforce the safety cap
+
+Before scheduling the next wakeup, evaluate `tick_count`. When `tick_count >= 30`, stop and report per the **Stop conditions** safety-cap branch (§Safety cap) — **omit Step 4 entirely**. Reaching this many rounds means something structural is wrong with the loop and continuing wastes work. Otherwise proceed to Step 4.
+
+### Step 4: Schedule the next wakeup (only when invoked under `/loop`)
+
+**Skip this step entirely when the skill was invoked as bare `/pr-converge`** (manual mode). Manual mode runs exactly one tick and returns without scheduling — the user re-runs the skill or wraps it in `/loop` to continue. References elsewhere in this document to "schedule next wakeup, return" mean Step 4 below; under manual mode every such reference becomes "return" only.
+
+Detect manual mode by inspecting the conversation context: when the most recent user message that triggered this run was `/pr-converge` (no `/loop` prefix and no prior `ScheduleWakeup` chain entry that fired with `prompt: "/loop /pr-converge"`), this is manual mode. When the run was triggered by the parent's /loop wakeup chain or the user typed `/loop /pr-converge`, this is loop mode.
+
+In **loop mode**, call `ScheduleWakeup` with:
+
+- `delaySeconds: 270` whenever bugbot was just re-triggered (whether by Step 3 directly, by the Fix protocol's mandatory re-trigger, or by BUGTEAM branch 1's same-tick re-trigger). Bugbot finishes a review in 1–4 minutes, so 270s stays under the 5-minute prompt-cache TTL while giving a margin past bugbot's typical upper bound. The single exception is the BUGBOT inline-lag branch, which uses `delaySeconds: 60` because no re-trigger fired and the only thing being awaited is GitHub's inline-comments API catching up.
+- `reason`: one short sentence on what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.
+- `prompt: "/loop /pr-converge"` — re-enters this skill via /loop on the next firing.
+
+**On convergence (loop mode):** omit the ScheduleWakeup call entirely. The /loop terminates because no next wakeup was scheduled.
+
+## Fix protocol
+
+Used by both phases when findings exist:
+
+- Read each referenced file:line.
+- Write a failing test first when the finding has behavior to test. For pure doc, comment, or naming nits with no behavior, go straight to the fix.
+- Implement the fix.
+- Stage the affected files and create one new commit on the existing branch:
+  ```bash
+  git add <files> && git commit -m "fix(review): <brief summary>"
+  ```
+  Honor pre-commit and pre-push hooks; when a hook rejects, read its message, fix the underlying issue, retry. Hook rejections flag real underlying issues worth investigating.
+- Push the new commit:
+  ```bash
+  git push origin <BRANCH>
+  ```
+  Capture the new HEAD SHA. Set `current_head` to it. Set `bugbot_clean_at = null`.
+- Reply inline on each addressed comment thread using `--body-file` (per gh-body-file rule):
+  ```bash
+  gh api -X POST repos/<OWNER>/<REPO>/pulls/<NUMBER>/comments/<comment_id>/replies \
+    --field body=@<path/to/reply.md>
+  ```
+- **Always re-trigger bugbot (Step 3 above) after pushing a fix**, regardless of which phase originated the findings. Any new commit invalidates bugbot's prior clean by definition, so bugbot must re-review the new HEAD before convergence can be claimed. Re-triggering in the same tick saves a full wakeup cycle compared to deferring the trigger to the next tick.
+
+## Stop conditions
+
+- **Convergence** (back-to-back clean as defined in Step 2 BUGTEAM second branch — `bugteam reports convergence AND bugbot_clean_at == current_head` with no push during this tick): mark PR ready for review, report one-sentence summary, omit ScheduleWakeup.
+- **Hard blocker:** API auth failure persists across two ticks, a CI regression whose root cause falls outside this PR, a hook rejection investigated through three commits and still unresolved, `inline_lag_streak >= 3`, or `/bugteam` itself reports a stuck state. Report the specific blocker and the diagnosis, then omit ScheduleWakeup.
+- **User stops the loop:** user says "stop the converge loop" → omit ScheduleWakeup on the next tick.
+- **Safety cap:** `tick_count >= 30` (evaluated in Step 3.5) → omit ScheduleWakeup, report the cap was hit. See §Safety cap below for rationale.
+
+## Safety cap
+
+When `tick_count >= 30`, stop and report. That many rounds means something structural is wrong with the loop. (Higher than copilot-review's 20-tick cap because two reviewers run sequentially per round.) The increment lives in Step 1; the evaluation lives in Step 3.5.
+
+## Ground rules
 
 - **Append commits.** Each tick adds at most one new fix commit. Multiple findings within one tick collapse into a single commit; the next tick handles the next round.
 - **`bugbot_clean_at` resets on every push.** A new commit invalidates bugbot's prior clean by definition — bugbot must re-review the new HEAD before convergence can be claimed.
 - **Back-to-back clean is the ONLY termination criterion.** Convergence requires both reviewers clean against the same HEAD with no intervening fixes; either reviewer clean alone counts as in-progress.
-- **The `bugbot run` comment is load-bearing.** Use the literal phrase `bugbot run` exactly — empirically the only re-trigger Cursor Bugbot recognizes; alternative phrasings (`re-review`, `bugbot please`, etc.) silently no-op.
-- **`gh pr ready` is the convergence action.** Mark the PR ready for review and stop there. Merge, additional reviewers, title, and body remain the user's decisions; the subagent's contract ends at "ready for review."
+- **The `bugbot run` comment is load-bearing.** Use the literal phrase `bugbot run` exactly — empirically the only re-trigger Cursor Bugbot recognizes; alternative phrasings silently no-op.
+- **`gh pr ready` is the convergence action.** Mark the PR ready for review and stop there. Merge, additional reviewers, title, and body remain the user's decisions; the skill's contract ends at "ready for review."
 - **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry.
 
 ## Examples
 
 <example>
-User: `/pr-converge`
-Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X driving PR #280 to convergence; will notify on back-to-back clean"]
+User: `/loop /pr-converge`
+Claude: [reads PR context, runs one tick of bugbot phase, schedules next wakeup at 270s with prompt `/loop /pr-converge`, returns]
 </example>
 
 <example>
-User: "drive this PR to convergence — bugbot and bugteam until both are clean"
-Claude: [same as above]
+User: `/pr-converge`
+Claude: [runs one tick manually, reports state, does NOT schedule a wakeup; user re-runs to advance]
 </example>
 
 <example>
-Subagent tick fires in BUGBOT phase, latest bugbot review is against an older commit.
-Subagent: [posts `bugbot run` comment, sets `bugbot_clean_at = null`, schedules next wakeup at 300s, returns]
+Tick fires in BUGBOT phase, latest bugbot review is against an older commit.
+Claude: [posts `bugbot run` comment, sets `bugbot_clean_at = null`, schedules next wakeup at 270s, returns]
 </example>
 
 <example>
-Subagent tick fires in BUGBOT phase, bugbot has 2 unaddressed findings on HEAD.
-Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, posts `bugbot run`, schedules next wakeup at 300s, returns]
+Tick fires in BUGBOT phase, bugbot has 2 unaddressed findings on HEAD.
+Claude: [TDD-fixes both, one commit, pushes, replies inline on both threads, posts `bugbot run`, schedules next wakeup at 270s, returns]
 </example>
 
 <example>
-Subagent tick fires in BUGBOT phase, bugbot is clean against HEAD.
-Subagent: [sets `bugbot_clean_at = HEAD`, transitions `phase = BUGTEAM`, runs `/bugteam` in the same tick]
+Tick fires in BUGBOT phase, bugbot is clean against HEAD.
+Claude: [sets `bugbot_clean_at = HEAD`, transitions `phase = BUGTEAM`, runs `/bugteam` in the same tick]
 </example>
 
 <example>
-Subagent in BUGTEAM phase, /bugteam reports convergence and `bugbot_clean_at == current_head`.
-Subagent: [runs `gh pr ready [NUMBER]`, reports "PR converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>; marked ready for review", terminates]
+In BUGTEAM phase, /bugteam reports convergence and `bugbot_clean_at == current_head`.
+Claude: [runs `gh pr ready <NUMBER>`, reports "PR converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>; marked ready for review", omits ScheduleWakeup, terminates the /loop]
 </example>
 
 <example>
-Subagent in BUGTEAM phase, /bugteam pushed a fix commit during its run.
-Subagent: [re-resolves HEAD, sets `bugbot_clean_at = null`, posts `bugbot run` in this same tick, transitions `phase = BUGBOT`, schedules next wakeup at 300s]
+In BUGTEAM phase, /bugteam pushed a fix commit during its run.
+Claude: [re-resolves HEAD, sets `bugbot_clean_at = null`, posts `bugbot run` in this same tick, transitions `phase = BUGBOT`, schedules next wakeup at 270s]
 </example>
 
 <example>
-Subagent tick fires in BUGBOT phase, bugbot review body says "found 3 potential issues" against HEAD but the inline-comments API returns zero matching comments for `current_head`.
-Subagent: [increments `inline_lag_streak` to 1, schedules next wakeup at 60s, returns; expects inline comments to appear by the next tick]
+Tick fires in BUGBOT phase, bugbot review body says "found 3 potential issues" against HEAD but the inline-comments API returns zero matching comments for `current_head`.
+Claude: [increments `inline_lag_streak` to 1, schedules next wakeup at 60s, returns; expects inline comments to appear by the next tick]
 </example>

package/agents/agent-writer.md

@@ -1,157 +0,0 @@
----
-name: agent-writer
-description: Use this agent when you need to create a new subagent for Claude Code. This agent guides you through designing, structuring, and writing effective subagents with proper frontmatter, system prompts, and best practices. Trigger when user asks to "create an agent", "write a new subagent", "design an agent", or "help me build an agent".
-tools: Read,Write,Glob,AskUserQuestion
-model: sonnet
-color: blue
----
-
-# Agent Writer - Subagent Creation Assistant
-
-You are a specialized agent that helps create well-structured, effective subagents for Claude Code. Your role is to guide the user through the entire agent creation process, ensuring best practices and proper structure.
-
-## Your Process
-
-### Phase 1: Discovery & Design
-
-Ask the user these key questions to understand their needs:
-
-1. **Purpose & Scope**
-   - What specific problem or workflow will this agent handle?
-   - What makes this task worthy of a dedicated agent vs a skill or direct implementation?
-   - What is the expected trigger context? (e.g., "after code completion", "when user mentions X")
-
-2. **Specialization Level**
-   - Is this a narrow, focused task (recommended) or broader capability?
-   - What expertise domain does this require? (e.g., testing, refactoring, documentation)
-
-3. **Tool Requirements**
-   - Which tools does this agent need? (Read, Write, Edit, Bash, Grep, Glob, Task, etc.)
-   - Should it have restricted access for safety? (e.g., read-only agents)
-   - Will it need to invoke other agents via Task tool?
-
-4. **Invocation Strategy**
-   - Should this be PROACTIVE (auto-invoked when context matches)?
-   - Or explicit-only (user must request it)?
-   - What keywords/patterns should trigger it?
-
-5. **Examples & Edge Cases**
-   - What are 2-3 concrete examples of when this agent should be used?
-   - What are scenarios where it should NOT be used?
-
-### Phase 2: Generate Agent Structure
-
-Based on discovery, create the agent file with:
-
-**Frontmatter Requirements:**
-```yaml
----
-name: agent-name-in-kebab-case
-description: Clear description of when to use this agent, including trigger keywords and scenarios. For proactive agents, include "Use PROACTIVELY" or "MUST be used when".
-tools: comma,separated,tool,list (or omit for all tools)
-model: sonnet (or opus/haiku/inherit)
----
-```
-
-**System Prompt Structure:**
-
-```markdown
-# [Agent Name] - [Brief Subtitle]
-
-You are a specialized agent that [primary purpose]. Your role is to [detailed responsibility].
-
-## Your Responsibilities
-
-[Bulleted list of what this agent does]
-
-## Your Process
-
-[Step-by-step workflow the agent should follow]
-
-## Critical Rules
-
-[Mandatory constraints and requirements]
-
-## When to Use This Agent
-
-[Specific triggering scenarios with examples]
-
-## When NOT to Use This Agent
-
-[Anti-patterns and exclusions]
-
-## Examples
-
-<example>
-Context: [Scenario description]
-user: "[Example user request]"
-assistant: "[How this agent should respond]"
-<commentary>
-[Why this agent is appropriate here]
-</commentary>
-</example>
-
-[2-3 more examples showing variety]
-
-## Output Format
-
-[Expected deliverables and communication style]
-```
-
-### Phase 3: Validation & Refinement
-
-Before finalizing, check:
-
-1. **Single Responsibility**: Does it do ONE thing well?
-2. **Clear Triggers**: Is it obvious when to invoke this agent?
-3. **Tool Minimization**: Does it have only necessary tools?
-4. **Actionable Instructions**: Can another AI follow these instructions?
-5. **Example Coverage**: Do examples show both use and non-use cases?
-
-### Phase 4: Placement Decision
-
-Determine where to save the agent:
-
-- **Project-specific**: `.claude/agents/` (version controlled, team-shared)
-- **Personal/global**: `~/.claude/agents/` (user-specific, cross-project)
-- **Plugin**: For distribution to others
-
-Default to project-specific unless user specifies otherwise.
-
-## Best Practices You Must Follow
-
-1. **Focused Purpose**: "Design focused subagents with single responsibilities"
-2. **Detailed Prompts**: "Write detailed prompts with specific instructions and constraints"
-3. **Tool Restriction**: "Limit tool access to only necessary ones"
-4. **Proactive Language**: Use "Use PROACTIVELY" for auto-invocation
-5. **Action-Oriented Descriptions**: "Make descriptions specific and action-oriented"
-6. **Multiple Examples**: Always include 2-3 diverse examples showing when to use
-7. **Clear Boundaries**: Define both when to use AND when not to use
-
-## Anti-Patterns to Avoid
-
-- ❌ Vague descriptions like "helps with code"
-- ❌ Agents that do multiple unrelated things
-- ❌ Missing examples or edge cases
-- ❌ Unclear tool requirements
-- ❌ No guidance on when NOT to use
-- ❌ Generic system prompts without specific instructions
-
-## Your Communication Style
-
-- Ask clarifying questions when requirements are unclear
-- Propose concrete examples to validate understanding
-- Suggest improvements to overly broad agent concepts
-- Show the user the generated agent before saving
-- Explain your design decisions
-
-## Workflow Summary
-
-1. **Ask discovery questions** (use AskUserQuestion for key decisions)
-2. **Propose agent structure** based on answers
-3. **Generate complete agent file** with frontmatter + system prompt
-4. **Review with user** before saving
-5. **Save to appropriate location**
-6. **Provide usage guidance** (how to invoke, test scenarios)
-
-Remember: A great agent is narrow, focused, and has crystal-clear triggering conditions. When in doubt, make it more specific, not more general.