claude-dev-env 1.36.2 → 1.37.0

package/skills/bugteam/CONSTRAINTS.md

@@ -1,35 +1,26 @@
 # Bugteam — invariants and design rationale
 
-## Path A vs Path B
-
-**Path A** (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): the constraints below apply as written — `TeamCreate`, isolated teammate sessions, lead-only `TeamDelete`. **Path B** (Task harness): read [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) for harness-only steps; **agent types** (`code-quality-agent`, `clean-coder`), **models**, **one commit per fix**, **gate-before-AUDIT**, **10-loop cap**, and **outcome XML** remain identical to `SKILL.md`. Path B intentionally uses **`Task`** from the lead instead of teammate isolation — see that file **Clean-room note**.
-
 ## Constraints
 
-- **Path A — agent teams required, not parallel subagents from the lead without `TeamCreate`.** On Path A, the skill MUST use Claude Code's agent teams feature (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Spawning `code-quality-agent` and `clean-coder` as parallel **Agents** with `team_name` from the lead is the supported pattern. Spawning ad-hoc `generalPurpose` workers in place of those roles = fail. **Path B** does not use `TeamCreate`; it uses **`Task`** carrying the same Path A spawn contracts per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) (AUDIT/FIX spawn; when the host rejects `subagent_type="clean-coder"`, apply **Path B — Cursor `Task` registry**). Not a substitute for skipping `code-quality-agent` / `clean-coder` work.
-- **Path B — Cursor `Task` registry.** When the host `Task` tool rejects `subagent_type="clean-coder"`, Path B FIX MUST use `subagent_type: "generalPurpose"` plus the mandatory **Read** of `clean-coder.md` in the FIX prompt per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) (FIX spawn, Cursor host split). This is the documented shim, not an ad-hoc `generalPurpose` bypass of the clean-coder contract.
-- **Path A — orchestrator-only `TeamCreate`.** Only the lead session (this session, when `/bugteam` is invoked) calls `TeamCreate`. Teammates never call `TeamCreate` — if a teammate's spawn prompt instructs it to, that is a skill defect. When additional parallel work is needed (e.g., parallel auditors from loop 4 onward, supplementary audit of adjacent files), the lead spawns additional teammates into the EXISTING team by passing the current `team_name` to every `Agent(...)` call. Multiple teammate "sets" live inside one team under one orchestrator. The runtime enforces this: `TeamCreate` called while the session already leads a team returns the error `Already leading team "<name>". A leader can only manage one team at a time. Use TeamDelete to end the current team before creating a new one.` — direct quote from the runtime's response when this invariant is violated. The Step 2 lifecycle resolution in [Team lifecycle](SKILL.md#team-lifecycle-path-a-only) parses this exact error in `auto` mode to attach to the existing team rather than fail. **Path B:** no `TeamCreate`; parallel work uses parallel **`Task`** calls per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md).
-- **One team per invocation, multi-PR supported.** All PRs in a single /bugteam invocation share one team created by the orchestrator. Per-PR identity lives in the teammate name prefix (`bugfind-pr<N>-loop<L>` / `bugfix-pr<N>-loop<L>`) and the `<team_temp_dir>/pr-<N>/` subfolder containing that PR's git worktree, diff patches, and outcome XML files.
+- **One run per invocation, multi-PR supported.** All PRs in a single /bugteam invocation share one `run_temp_dir`. Per-PR identity lives in the subagent name prefix (`bugfind-pr<N>-loop<L>` / `bugfix-pr<N>-loop<L>`) and the `<run_temp_dir>/pr-<N>/` subfolder containing that PR's git worktree, diff patches, and outcome XML files.
 - **Grant before any spawn, revoke before any return.** Step 0 grants project `.claude/**` permissions; Step 5 revokes. Both are mandatory. Revoke runs on every exit path including error, cap-reached, and stuck.
-- **Fresh teammate per loop.** Both bugfind and bugfix are spawned new each loop and shut down after their action. Reusing a teammate across loops accumulates context inside that teammate's window — defeats clean-room.
+- **Fresh subagent per loop.** Both bugfind and bugfix are spawned new each loop. Reusing a subagent across loops accumulates context inside that subagent's window — defeats clean-room.
 - **One up-front confirmation = whole cycle.** The `/bugteam` invocation authorizes the entire cycle; every subsequent decision runs on that single authorization.
 - **10-loop hard cap.** Counted as **AUDIT** completions (increment in Step 3). Standards-fix passes before an audit do not advance `loop_count`. Worst case includes extra clean-coder spawns for the code-rules gate.
 - **Code rules gate before every AUDIT.** Run `_shared/pr-loop/scripts/code_rules_gate.py` (resolved via `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`) until exit **0** before spawning **bugfind**. Same `validate_content` logic as `hooks/blocking/code_rules_enforcer.py`.
-- **Clean-room audits, every loop.** Each bugfind teammate's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
-- **Targeted fixes.** Each fix teammate sees ONLY the most recent audit's findings. Prior loops are invisible to the fix teammate.
-- **Opus 4.7 at xhigh effort for both teammates.** Both `Agent(...)` spawns pass `model="opus"`, which resolves to Opus 4.7 on the Anthropic API. Opus 4.7's default effort level in Claude Code is `xhigh` (https://code.claude.com/docs/en/model-config — *"On Opus 4.7, the default effort is `xhigh` for all plans and providers."*), so no `effort` override is needed at spawn time. Effort is set per-subagent in YAML frontmatter, not via the `Agent` tool's parameters; `code-quality-agent` and `clean-coder` rely on the model default. The trade vs Sonnet is higher per-loop cost in exchange for deeper audit recall and stronger fix correctness on bug-hunting work, which the per-PR loop economics tolerate (10-loop hard cap bounds total spend).
-- **Fix teammate receives the latest audit as its input contract.** Passing the audit's findings to the fix teammate is the input contract — each loop's fix run operates on the current audit's output and only that.
+- **Clean-room audits, every loop.** Each bugfind subagent's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
+- **Targeted fixes.** Each fix subagent sees ONLY the most recent audit's findings. Prior loops are invisible to the fix subagent.
+- **Opus 4.7 at xhigh effort for both subagents.** Both `Agent(...)` spawns pass `model="opus"`, which resolves to Opus 4.7 on the Anthropic API. Opus 4.7's default effort level in Claude Code is `xhigh` (https://code.claude.com/docs/en/model-config — *"On Opus 4.7, the default effort is `xhigh` for all plans and providers."*), so no `effort` override is needed at spawn time. Effort is set per-subagent in YAML frontmatter, not via the `Agent` tool's parameters; `code-quality-agent` and `clean-coder` rely on the model default. The trade vs Sonnet is higher per-loop cost in exchange for deeper audit recall and stronger fix correctness on bug-hunting work, which the per-PR loop economics tolerate (10-loop hard cap bounds total spend).
+- **Fix subagent receives the latest audit as its input contract.** Passing the audit's findings to the fix subagent is the input contract — each loop's fix run operates on the current audit's output and only that.
 - **One commit per fix action.** Loops produce one commit per loop, not one per bug.
 - **Linear branch, fixed PR base.** Every loop appends one forward-only commit; existing commits and the PR base stay intact throughout the cycle.
-- **Lead-only cleanup, gated by `team_owned`.** Per the docs: *"Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state."* This session is the lead, and cleanup runs here only. Step 4 calls `TeamDelete` **only when `team_owned == true`** (this invocation called `TeamCreate` itself). When `team_owned == false` (lifecycle `attach`, or `auto` after the runtime's `Already leading team` fallback), the orchestrator that originally created the team owns teardown — see [Team lifecycle](SKILL.md#team-lifecycle-path-a-only).
-- **Orchestrators must use `attach` mode, not `owned`.** When `/bugteam` runs inside an orchestrator that is itself managing a long-lived team across PRs (`pr-converge` multi-PR mode, `monitor-open-prs`), the orchestrator passes `BUGTEAM_TEAM_LIFECYCLE=attach` and `BUGTEAM_TEAM_NAME=<existing>`. `owned` mode under such an orchestrator would either error out (the session already leads a team) or, worse, tear down the orchestrator's team mid-sweep on the first invocation's Step 4. `auto` is the safe default for ambiguous callers; `attach` is the explicit-orchestrator contract.
-- **Cleanup the per-team scoped temp directory on exit, gated by `team_owned`.** When `team_owned == true`, the resolved `<team_temp_dir>` is removed entirely so no loop patches leak between runs. When `team_owned == false`, only this invocation's per-PR subfolders (`<team_temp_dir>/pr-<N>/`) are removed; the orchestrator-owned parent stays so the next attached invocation can write its own per-PR subfolders without colliding.
-- **Cleanup all `.bugteam-*` files on exit.** `.bugteam-loop-*.patch`, `.bugteam-loop-*.outcomes.xml`, `.bugteam-final.diff`, `.bugteam-original-body.md`, `.bugteam-final-body.md`. Working directory ends clean.
-- **Audit/fix comment posting.** **Path A:** Bugfind posts ONE per-loop review (parent body + child finding comments in a single batched POST, with review-fallback to a top-level issue comment). Bugfix posts the fix replies after committing. All comment, review, and reply POSTs belong to the teammates; the lead's single PR-write action is the final description rewrite at Step 4.5. **Path B:** the **lead** performs the same POSTs after Task handoffs (`SKILL.md` Step 2.5 + [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) § Step 2.5).
+- **Lead-only cleanup.** Cleanup runs in the lead (this session) only. Step 4 removes the full `<run_temp_dir>` so no loop patches leak between runs.
+- **Cleanup all `.bugteam-*` files on exit.** The per-run `<run_temp_dir>` is removed entirely by Step 4, which covers `<run_temp_dir>/pr-<N>/loop-<L>.patch` and `<run_temp_dir>/pr-<N>/loop-<L>-{b,c}.outcomes.xml`. The per-loop outcomes XML at `<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml` is removed with the worktree. Step 4.5 deletes `.bugteam-final.diff`, `.bugteam-original-body.md`, and `.bugteam-final-body.md`. Working directory ends clean.
+- **Audit/fix comment posting.** The bugfind subagent posts ONE per-loop review (parent body + child finding comments in a single batched POST, with review-fallback to a top-level issue comment). The bugfix subagent posts the fix replies after committing. All comment, review, and reply POSTs belong to the subagents; the lead's single PR-write action is the final description rewrite at Step 4.5.
 - **Lead owns the final PR description rewrite only** (Step 4.5), and only via the `pr-description-writer` agent. The lead does not compose the description inline.
 - **One review per loop, findings as child comments of that review.** Each loop posts a single pull-request review whose body is the loop header and whose `comments[]` are the anchored findings. Each loop's review stands alone — one review created per loop, fully self-contained on the PR conversation.
 - **PR description rewrite on every exit.** Step 4.5 runs on `converged`, `cap reached`, and `stuck`. On `error`, the rewrite is best-effort; if it fails, surface the error in the final report and continue to revoke.
-- **Outcome XML, not JSON.** Both teammates write structured outcome data (findings or fix outcomes) to `.bugteam-loop-<N>.outcomes.xml`. The lead reads these files between actions. XML chosen for parser robustness against multi-line, special-character, and quoted reason fields.
+- **Outcome XML, not JSON.** Both subagents write structured outcome data (findings or fix outcomes) to `.bugteam-pr<N>-loop<L>.outcomes.xml`. The lead reads these files between actions. XML chosen for parser robustness against multi-line, special-character, and quoted reason fields.
 
 ## Why this design
 

package/skills/bugteam/PROMPTS.md

@@ -18,7 +18,7 @@ Keep the spawn prompt self-contained: reference only the PR scope, audit rubric,
 cd into `<worktree_path>` before any git, gh, or file operation.
 
 <scope>
-  <diff_path>Absolute path to the per-PR patch file: <team_temp_dir>/pr-<N>/loop-<L>.patch (same path as gh pr diff redirect in AUDIT)</diff_path>
+  <diff_path>Absolute path to the per-PR patch file: <run_temp_dir>/pr-<N>/loop-<L>.patch (same path as gh pr diff redirect in AUDIT)</diff_path>
   <scope_rule>Audit only lines added or modified in the diff. Pre-existing code on untouched lines is out of scope.</scope_rule>
 </scope>
 
@@ -76,8 +76,8 @@ cd into `<worktree_path>` before any git, gh, or file operation.
 </comment_posting>
 
 <output_format>
-  Write the outcome XML below to .bugteam-pr<N>-loop<L>.outcomes.xml inside
-  the PR's worktree directory (<worktree_path>). Return only that path on stdout. The schema:
+  For the primary (-a) auditor: write the outcome XML below to .bugteam-pr<N>-loop<L>.outcomes.xml inside
+  the PR's worktree directory (<worktree_path>). For sibling auditors (-b/-c): write to <run_temp_dir>/pr-<N>/loop-<L>-{b,c}.outcomes.xml (absolute path passed in prompt). Return only that path on stdout. The schema:
 </output_format>
 ```
 

package/skills/bugteam/SKILL.md

@@ -3,13 +3,9 @@ name: bugteam
 description: >-
   Open pull request audit–fix until convergence: CODE_RULES gate, clean-room
   audit (`code-quality-agent`, opus) and fix (`clean-coder`, opus), per-loop
-  GitHub reviews, 10-audit cap; grant then revoke `.claude/**`. **Path A** when
-  `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (orchestrated teams, `TeamCreate`).
-  **Path B** otherwise (Task harness — workflow in
-  `reference/workflow-path-b-task-harness.md`). **This `SKILL.md` holds only
-  shared steps**; per-path harness lives in `reference/workflow-path-*.md`.
-  Triggers: '/bugteam', 'run the bug team', 'auto-fix the PR until clean', 'loop
-  audit and fix'.
+  GitHub reviews, 10-audit cap; grant then revoke `.claude/**`. Spawns
+  background subagents (`Agent(..., run_in_background=true)`). Triggers: '/bugteam', 'run
+  the bug team', 'auto-fix the PR until clean', 'loop audit and fix'.
 ---
 
 # Bugteam
@@ -18,103 +14,22 @@ description: >-
 `code-quality-agent`, fresh context each loop. **Bugfix:** `clean-coder`. Hard
 cap: 10 audit loops. Grant `.claude/**` at start, revoke always at end.
 
-**Path routing** picks **Path A** (orchestrated teams) vs **Path B** (Task
-harness). Harness execution — `TeamCreate`, `Agent`/`Task` spawns,
-`SendMessage`, `TeamDelete`, who runs Step 2.5 `gh api` — lives only in
-[`reference/workflow-path-a-orchestrated-teams.md`][path-a] and
-[`reference/workflow-path-b-task-harness.md`][path-b]. Verbatim doc quotes and
-URLs: [`sources.md`](sources.md).
-
-## Path routing (mandatory first branch)
-
-At `/bugteam` entry, evaluate **once** (same rule as pr-converge §Team
-infrastructure detection):
-
-- **Path A** — `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` set and equals **`1`**
-  after trim → load and follow
-  [`reference/workflow-path-a-orchestrated-teams.md`][path-a] for every harness
-  step (with this `SKILL.md` for shared material).
-- **Path B** — otherwise → load and follow
-  [`reference/workflow-path-b-task-harness.md`][path-b] for every harness step
-  (with this `SKILL.md` for shared material).
-
-Shared material is **everything else in this file** plus
-[`PROMPTS.md`](PROMPTS.md), [`EXAMPLES.md`](EXAMPLES.md),
-[`CONSTRAINTS.md`](CONSTRAINTS.md) — agent types, models, XML, gates, cycle
-state machine, Step 2.5 payload shapes, shared teardown `rmtree`, revoke, final
-report.
-
-## Team lifecycle (Path A only)
-
-The `TeamCreate` / `TeamDelete` pair has historically been bound to a single
-`/bugteam` invocation. That coupling fails when an orchestrator (`pr-converge`
-multi-PR mode, `monitor-open-prs`) needs to call `/bugteam` repeatedly inside
-one parent session: only one team can be led at a time, and a missed Step 4
-leaks the team. To decouple, every Path A invocation reads
-`BUGTEAM_TEAM_LIFECYCLE` (defaults to `auto`) and may also read
-`BUGTEAM_TEAM_NAME`.
-
-**`owned`**
-
-- **Step 2:** `TeamCreate(<computed_team_name>)`. If the runtime returns
-  `Already leading team "<existing>". A leader can only manage one team at a
-  time.` → **error**: `Already leading team <existing>; rerun with
-  BUGTEAM_TEAM_LIFECYCLE=attach BUGTEAM_TEAM_NAME=<existing>`.
-- **Step 4:** `TeamDelete()` (lead-owned).
-- **Use case:** Pre-decoupling behavior. Use only when you know the session
-  leads no other team.
-
-**`attach`**
-
-- **Step 2:** Require `BUGTEAM_TEAM_NAME`. Treat that team as already-led; do
-  **not** call `TeamCreate`.
-- **Step 4:** **Skip** `TeamDelete` — the orchestrator owns teardown.
-- **Use case:** Orchestrators (pr-converge multi-PR, monitor-open-prs) that
-  explicitly created a team and will tear it down themselves.
-
-### `auto` (**default: `auto`**)
-
-- **Step 2:** Try `TeamCreate(<computed_team_name>)`. On `Already leading team
-  "<existing>"` → parse `<existing>`, attach (do **not** call `TeamCreate`
-  again), set `team_owned=false`. On success → set `team_owned=true`.
-- **Step 4:** If `team_owned=true` → `TeamDelete()`. Else → **skip**
-  `TeamDelete`.
-- **Use case:** All callers when in doubt. Solo invocations behave like `owned`;
-  nested or repeated invocations attach safely.
-
-**`team_owned` flag** — set in Step 2 by all three modes
-(`owned` always `true`; `attach` always `false`; `auto` reflects the
-`TeamCreate` outcome). Read in Step
-4 to decide whether to call `TeamDelete`. The same flag also gates
-`<team_temp_dir>` `rmtree`: when `team_owned=false`, only the per-PR subfolders
-this invocation created (`<team_temp_dir>/pr-<N>/`) are removed; the
-orchestrator's parent directory survives.
-
-**Path B note:** Path B does not use `TeamCreate` / `TeamDelete`, so
-`BUGTEAM_TEAM_LIFECYCLE` is read but only its `team_temp_dir` cleanup behavior
-applies. `team_owned` is treated as `true` by default in Path B; orchestrators
-driving Path B that share a temp directory should set
-`BUGTEAM_TEAM_LIFECYCLE=attach` so the per-PR subfolder cleanup rule applies.
+Both audit and fix roles run as background subagents
+(`Agent(..., run_in_background=true)`). Verbatim doc quotes and URLs:
+[`sources.md`](sources.md).
 
 ## Contents
 
 Orchestration lives here; companion files hold prompts, invariants, examples,
 citations, and domain reference notes. Scan this list before a partial read.
 
-- [Path routing](#path-routing-mandatory-first-branch) — Path A vs Path B
-- [Team lifecycle](#team-lifecycle-path-a-only) — `owned` / `attach` / `auto`
-  modes; orchestrator-owned teams
-- [`reference/workflow-path-a-orchestrated-teams.md`][path-a] — Path A harness
-  (orchestrated teams)
-- [`reference/workflow-path-b-task-harness.md`][path-b] — Path B harness (Task
-  harness)
 - When this skill applies — refusal cases and trigger conditions
 - Utility scripts — pre-flight (`scripts/`, executed not inlined)
 - Pre-audit gate — `validate_content` before each AUDIT
 - The Process — checklist + Steps 0–6
   - Step 0 — Grant project permissions
   - Step 1 — Resolve PR scope
-  - Step 2 — Path harness + loop state
+  - Step 2 — Loop state
   - Step 2.5 — PR comment lifecycle (per-loop review + fix replies)
   - Step 3 — Cycle (AUDIT ↔ FIX, exits)
   - Step 4 — Teardown + clean tree
@@ -140,12 +55,6 @@ Refusals — first match wins; respond with the quoted line exactly and stop:
 - **Missing subagents.** Before Step 0, confirm `code-quality-agent` and
   `clean-coder` exist. Else: `Required subagent type <name> not installed.
   /bugteam needs both code-quality-agent and clean-coder available.`
-- **Lead role must be held by the orchestrator.** Run /bugteam in the session
-  that received the user's command. **Path A:** lead calls `TeamCreate` per
-  [`reference/workflow-path-a-orchestrated-teams.md`][path-a]; runtime may
-  return `Already leading team "<name>". A leader can only manage one team at a
-  time.` **Path B:** lead runs the Task harness per
-  [`reference/workflow-path-b-task-harness.md`][path-b]; no `TeamCreate`.
 
 ## Utility scripts
 
@@ -189,9 +98,9 @@ the auto-remediation only applies to the `core.hooksPath` failure mode.
 ```
 [ ] Step 0: project permissions granted
 [ ] Step 1: PR scope resolved
-[ ] Step 2: loop state set + path harness applied
+[ ] Step 2: loop state set
 [ ] Step 3: cycle complete (converged | cap reached | stuck | error)
-[ ] Step 4: team torn down + working tree clean
+[ ] Step 4: working tree clean
 [ ] Step 4.5: PR description rewritten (or skip warning logged)
 [ ] Step 5: project permissions revoked
 [ ] Step 6: final report printed
@@ -200,9 +109,9 @@ the auto-remediation only applies to the `core.hooksPath` failure mode.
 ### Step 0: Grant project permissions (once, first)
 
 ```bash
-python
-"${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/grant_project_claude_permis \
-sions.py"
+python \
+"${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/"\
+"grant_project_claude_permissions.py"
 ```
 
 `${CLAUDE_SKILL_DIR}` is host-substituted before the shell runs (unlike normal
@@ -219,62 +128,59 @@ follows the same downstream rules.
 
 Keep: owner/repo, branches, PR number, URL — for all loops.
 
+**`<run_temp_dir>`:** `Path(tempfile.gettempdir()) / run_name` where
+`run_name = "bugteam-pr-<number>-<YYYYMMDDHHMMSS>"` for a single-PR invocation
+or `"bugteam-<YYYYMMDDHHMMSS>"` for multi-PR. Lead resolves once to an absolute
+path; every shell gets that literal string.
+
 #### Per-PR workspace
 
 For each PR in all_prs:
 
-1. Create `<team_temp_dir>/pr-<N>/`.
-2. Run `git worktree add "<team_temp_dir>/pr-<N>/worktree" origin/<headRef>`.
+1. Create `<run_temp_dir>/pr-<N>/`.
+2. Run `git worktree add "<run_temp_dir>/pr-<N>/worktree" origin/<headRef>`.
 3. Record the absolute worktree path alongside the PR's other fields.
 
-Teammates or Task workers for a PR operate inside that PR's worktree. Step 4
-teardown runs `git worktree remove "<team_temp_dir>/pr-<N>/worktree"` for each
-PR, then path-specific harness teardown per
-[`reference/workflow-path-a-orchestrated-teams.md`][path-a] or
-[`reference/workflow-path-b-task-harness.md`][path-b] § Step 4.
-
-### Step 2: Path harness + loop state
-
-Apply the path you chose in [Path
-routing](#path-routing-mandatory-first-branch): **Path A** —
-[`reference/workflow-path-a-orchestrated-teams.md`][path-a] § Step 2
-(`TeamCreate`, team name, `team_temp_dir`, roles, optional Groq FIX,
-`--bugbot-retrigger`). **Path B** —
-[`reference/workflow-path-b-task-harness.md`][path-b] § Step 2 (no `TeamCreate`
-/ `TeamDelete`; same worktrees and variables).
+Background subagents for a PR operate inside that PR's worktree. Step 4
+teardown runs `git worktree remove "<run_temp_dir>/pr-<N>/worktree"` for each
+PR before the shared `rmtree`.
 
-Path A also resolves the team lifecycle here per [Team
-lifecycle](#team-lifecycle-path-a-only): pick the mode (`owned` / `attach` /
-`auto`) from `BUGTEAM_TEAM_LIFECYCLE`, set `team_name` (computed for
-`owned`/`auto` create paths; required `BUGTEAM_TEAM_NAME` for `attach` and
-`auto`'s attach branch), and set `team_owned` (`true` when `TeamCreate`
-succeeded in this invocation; `false` when attaching to an existing team). Step
-4 reads `team_owned` to decide whether to call `TeamDelete`.
+### Step 2: Loop state
 
-**Loop state (lead; not a single script):**
+**Loop state (lead; not a single script; per-PR):** The variables
+below are tracked independently for each PR in `all_prs`. Each PR has its
+own cycle, state, and exit reason.
 
 ```bash
 loop_count=0
 last_action="fresh"
 last_findings='{"total": 0}'
 audit_log=""
-starting_sha="$(git rev-parse HEAD)"
-team_name="bugteam-pr-<number>-<YYYYMMDDHHMMSS>"
-team_temp_dir="<absolute-path>/<team_name>"
-team_owned="true" # set by Step 2 lifecycle resolution; see Team lifecycle table
+run_temp_dir="<absolute-path>/<run_name>"
+starting_sha="$(git -C "<run_temp_dir>/pr-<N>/worktree" rev-parse HEAD)"
 loop_comment_index=""
 ```
 
+**Optional Groq-backed FIX (explicit opt-in only):** when the user explicitly
+sets `BUGTEAM_FIX_IMPLEMENTER=groq-coder` before invocation, spawn the FIX
+subagent with `subagent_type="groq-coder"`. Requires `GROQ_API_KEY` in the
+environment (load from `packages/claude-dev-env/.env` when that file exists;
+prompt the user to create it from `.env.example` if still unset). Any other
+`BUGTEAM_FIX_IMPLEMENTER` value (or unset) uses `clean-coder`.
+
+**`--bugbot-retrigger` flag:** when present, the FIX subagent posts a `bugbot
+run` issue comment via the Step 2.5 issue-comments fallback endpoint after
+every successful FIX push, to re-trigger Cursor's bugbot on the new commit.
+
 **`loop_comment_index`:** reset each AUDIT start; filled during AUDIT; FIX
 consumes for replies; cleared after FIX. Entries: `{loop, finding_id,
 finding_comment_id, finding_comment_url, used_fallback, fix_status}`.
 
 ### Step 2.5: PR comments (one review per loop)
 
-**Who posts:** Path A vs Path B —
-[`reference/workflow-path-a-orchestrated-teams.md`][path-a] § Step 2.5 and
-[`reference/workflow-path-b-task-harness.md`][path-b] § Step 2.5. Payloads and
-endpoints below are identical for both paths.
+**Who posts:** the AUDIT subagent posts one `POST .../pulls/<n>/reviews` per
+loop. The FIX subagent posts `.../comments/<id>/replies` after push. The lead's
+only PR write before Step 4.5 is the final description rewrite.
 
 Order: audit → buffer → validate anchors vs diff → single review POST.
 Review body states counts; zero findings → still one review, `comments: []`,
@@ -316,7 +222,7 @@ POST --input -`
 <tmp_fallback.md | gh api repos/<owner>/<repo>/issues/<number>/comments -X POST
 --input -`
 
-`<head_sha_at_post_time>`: `git rev-parse HEAD` in teammate cwd immediately
+`<head_sha_at_post_time>`: `git rev-parse HEAD` in subagent cwd immediately
 before POST.
 
 **Review body template (`<tmp_review_body.md>`):**
@@ -342,8 +248,7 @@ before POST.
 
 ### Step 3: The cycle
 
-Run the AUDIT-FIX cycle for each PR in all_prs, reusing the same team across
-PRs. The 10-loop cap applies per PR. Exit reasons (converged, cap reached,
+Run the AUDIT-FIX cycle for each PR in all_prs. The 10-loop cap applies per PR. Exit reasons (converged, cap reached,
 stuck, error) are tracked per PR; the final report lists one outcome line per
 PR.
 
@@ -360,9 +265,8 @@ dirty so the AUDIT runs against the latest diff with that signal in mind:
 
 ```bash
 dirty_review_count=0
-gh api "repos/<owner>/<repo>/pulls/<number>/reviews" \
---jq '[.[] | select(.body | startswith("## /bugteam loop "))] |
-sort_by(.submitted_at) | reverse'
+gh api "repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100" --paginate --slurp \
+  | jq '[.[][] | select((.body // "") | startswith("## /bugteam loop "))] | sort_by(.submitted_at) | reverse'
 ```
 
 Iterate from index 0 (most recent) toward older entries:
@@ -432,85 +336,84 @@ before the next AUDIT.
 ### AUDIT action
 
 ```bash
-mkdir -p "<team_temp_dir>/pr-<N>"
-gh pr diff <N> -R <owner>/<repo> > "<team_temp_dir>/pr-<N>/loop-<L>.patch"
+mkdir -p "<run_temp_dir>/pr-<N>"
+gh pr diff <N> -R <owner>/<repo> > "<run_temp_dir>/pr-<N>/loop-<L>.patch"
 ```
 
-**Spawn and shutdown:** Path A —
-[`reference/workflow-path-a-orchestrated-teams.md`][path-a] § AUDIT. Path B —
-[`reference/workflow-path-b-task-harness.md`][path-b] § AUDIT. Same
-`prompt="<audit XML; see PROMPTS.md>"` and outcome files.
+**Spawn:**
 
-Fresh spawn each loop; Path A teammate context excludes lead history
-([`sources.md`](sources.md) § Teammate context isolation). Path B: fresh Task
-per loop for the same clean-room intent. [`PROMPTS.md`](PROMPTS.md): XML +
-outcome schema. Lead reads `.bugteam-pr<N>-loop<L>.outcomes.xml`, fills
-`loop_comment_index`.
+```
+Agent(
+  subagent_type="code-quality-agent",
+  name="bugfind-pr<N>-loop<L>",
+  model="opus",
+  run_in_background=true,
+  description="Bugfind audit PR <N> loop <L>",
+  prompt="<audit XML; see PROMPTS.md>"
+)
+```
+
+Fresh spawn each loop for clean-room isolation. Lead awaits the
+background-completion notification, then reads
+`.bugteam-pr<N>-loop<L>.outcomes.xml` from the worktree directory, fills
+`loop_comment_index`. [`PROMPTS.md`](PROMPTS.md): XML + outcome schema.
 
 `last_action = "audited"`; append audit line to `audit_log`.
 
 **Parallel auditors (`loop_count >= 4`):** gate passes immediately before;
-after three full audit/fix rounds without convergence, issue three spawns in
-one assistant message (parallel): Path A — three `Agent` calls; Path B —
-three `Task` calls — full rules in the workflow files § parallel auditors.
-`-a` posts
-the review and merges outcomes from `-b`/`-c` (read
+after three full audit/fix rounds without convergence, issue three `Agent`
+calls in one assistant message (`run_in_background=true`): `-a` posts the
+review and merges outcomes from `-b`/`-c` (read
 `.bugteam-pr<N>-loop<L>.outcomes.xml` plus
-`<team_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml` and `...-c...`); merge key
+`<run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml` and `...-c...`); merge key
 `(file, line, category_letter)`; re-id `loopN-K`. `-b`/`-c` write sibling XML
-only; prompts must pass literal absolute sibling paths. Shutdown order: Path A
-workflow § parallel auditors; Path B: await all three Tasks.
+only; prompts must pass literal absolute sibling paths. Output path
+contract: `-b`/`-c` write to `<run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml`
+and `<run_temp_dir>/pr-<N>/loop-<L>-c.outcomes.xml`; `-a` writes to
+`<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml`.
+Lead awaits all three background-completion notifications before merging
+outcomes.
 
 ### FIX action
 
-**Spawn and shutdown:** Path A —
-[`reference/workflow-path-a-orchestrated-teams.md`][path-a] § FIX. Path B —
-[`reference/workflow-path-b-task-harness.md`][path-b] § FIX.
+**Spawn:**
 
-Pass finding comment URLs/ids from `loop_comment_index` in XML. Replies: `Fixed
-in <sha>` or `Could not address this loop: <reason>`.
+```
+Agent(
+  subagent_type="clean-coder",
+  name="bugfix-pr<N>-loop<L>",
+  model="opus",
+  run_in_background=true,
+  description="Bugfix PR <N> loop <L>",
+  prompt="<fix XML; see PROMPTS.md>"
+)
+```
 
-[`PROMPTS.md`](PROMPTS.md): fix XML + schema. Verify: `git rev-parse HEAD`
-advanced; `git fetch origin <branch> && git rev-parse origin/<branch>` matches
+Pass finding comment URLs/ids from `loop_comment_index` in XML. Lead awaits the
+background-completion notification. Replies: `Fixed in <sha>` or `Could not
+address this loop: <reason>`.
+
+[`PROMPTS.md`](PROMPTS.md): fix XML + schema. Verify from worktree: `git -C "<run_temp_dir>/pr-<N>/worktree" rev-parse HEAD`
+advanced; `git -C "<run_temp_dir>/pr-<N>/worktree" fetch origin <branch> && git -C "<run_temp_dir>/pr-<N>/worktree" rev-parse origin/<branch>` matches
 `HEAD`. Unchanged HEAD →
-`stuck — bugfix teammate could not address findings`.
+`stuck — bugfix subagent could not address findings`.
 
 ### Step 4: Teardown
 
 1. For each PR in `all_prs`: `git worktree remove
-   "<team_temp_dir>/pr-<N>/worktree"` (from Step 1) before tearing down the team
-   harness — tolerate already-removed worktrees.
-
-2. Path-specific harness —
-   [`reference/workflow-path-a-orchestrated-teams.md`][path-a] § Step 4
-   (teammate `SendMessage`, `TeamDelete` **only when `team_owned=true`**) or
-   [`reference/workflow-path-b-task-harness.md`][path-b] § Step 4 (omit those).
-
-3. **Windows-safe `rmtree` — gated by `team_owned` from [Team
-   lifecycle](#team-lifecycle-path-a-only).** The Windows-safe handler strips
-   the Windows ReadOnly attribute and retries the failing syscall (see
-   `~/.claude/rules/windows-filesystem-safe.md`).
+   "<run_temp_dir>/pr-<N>/worktree"` (from Step 1) — tolerate already-removed
+   worktrees.
 
-   - `team_owned=true` → remove the full `<team_temp_dir>`:
+2. **Windows-safe `rmtree`** — strips the Windows ReadOnly attribute and retries
+   the failing syscall (see `~/.claude/rules/windows-filesystem-safe.md`).
+   Remove the full `<run_temp_dir>`:
 
-     ```bash
+   ```bash
 python -c "import os, shutil, stat, sys; \
 h = lambda f, p, *_: (os.chmod(p, stat.S_IWRITE), f(p)); \
-shutil.rmtree(r'<team_temp_dir>', **({'onexc': h} if sys.version_info >= (3, 12)
+shutil.rmtree(r'<run_temp_dir>', **({'onexc': h} if sys.version_info >= (3, 12)
 else {'onerror': h}))"
-     ```
-
-   - `team_owned=false` (attach mode) → for each PR in `all_prs`, remove only
-     that PR's `<team_temp_dir>/pr-<N>/` subfolder. The orchestrator-owned
-     parent `<team_temp_dir>` survives so the next attached invocation can write
-     its own per-PR subfolders without colliding.
-
-     ```bash
-python -c "import os, shutil, stat, sys; \
-h = lambda f, p, *_: (os.chmod(p, stat.S_IWRITE), f(p)); \
-shutil.rmtree(r'<team_temp_dir>/pr-<N>', **({'onexc': h} if sys.version_info >=
-(3, 12) else {'onerror': h}))"
-     ```
+   ```
 
 ### Step 4.5: PR description
 
@@ -532,9 +435,9 @@ On failure: log in final report; continue to Step 5.
 ### Step 5: Revoke permissions (always)
 
 ```bash
-python
-"${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/revoke_project_claude_permi \
-ssions.py"
+python \
+"${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/"\
+"revoke_project_claude_permissions.py"
 ```
 
 Removes Step 0 grant — run even if Step 4 partially failed (log separately).
@@ -572,7 +475,5 @@ See [`reference/README.md`](reference/README.md).
 
 See [`sources.md`](sources.md).
 
-[path-a]: reference/workflow-path-a-orchestrated-teams.md
-[path-b]: reference/workflow-path-b-task-harness.md
 [path-code-rules]: ../../_shared/pr-loop/code-rules-gate.md
 [path-scripts-readme]: ../../_shared/pr-loop/scripts/README.md