claude-dev-env 1.35.0 → 1.36.1

package/skills/bugteam/SKILL_EVALS.md

@@ -14,23 +14,23 @@ Evals are split into two layers. Both layers run against the same trace but carr
 
 ## Ironclad invariants (Layer A, apply to every eval)
 
-Each invariant cites the normative section or companion file it derives from.
+Each invariant cites the normative section or companion file it derives from. **Path A vs Path B:** `SKILL.md` **Path routing** splits harnesses. Invariants **I-1, I-3, I-4, I-7, I-9, I-11 (teammate shutdown → `TeamDelete` prefix), I-13** apply to **Path A only**. **Path B** substitutes per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md): no `TeamCreate` / `TeamDelete`; parallel auditors use parallel **`Task`** calls; **I-12 Path B** — the **lead** runs Step 2.5 `gh api` posts. **I-2, I-5, I-6, I-8, I-10** apply to **both** paths (revoke once; fresh spawn per loop; `model="opus"` on audit/fix workers; cap; read outcome XML).
 
 | # | Invariant | Citation |
 |---|---|---|
-| I-1 | `Bash` invoking `scripts/grant_project_claude_permissions.py` precedes every `TeamCreate`. | `SKILL.md` § Step 0 |
-| I-2 | `Bash` invoking `scripts/revoke_project_claude_permissions.py` runs exactly once per invocation, after the last `TeamDelete`, on every exit path (converged, stuck, cap reached, error). | `SKILL.md` § Step 5 |
-| I-3 | Exactly one `TeamCreate` and exactly one `TeamDelete` per invocation. | `SKILL.md` § Step 2; § Step 4 |
-| I-4 | Before `TeamDelete`, no teammate remains active without cleanup: either the teammate self-terminated after `Agent` returned, or the lead sent a matching `SendMessage(..., shutdown_request)` (including parallel-auditor shutdowns). No orphaned teammates when `TeamDelete` runs. | `SKILL.md` § AUDIT action (**Shutdown**); § FIX action (**Shutdown**); § Step 4 |
-| I-5 | `Agent` calls are fresh per loop — the same `name` is never reused across loops without an intervening shutdown. | `CONSTRAINTS.md` — **Fresh teammate per loop** |
-| I-6 | Both audit and fix `Agent` calls pass `model="opus"` (resolves to Opus 4.7 via the Anthropic API alias; effort remains the Claude Code/model-config default `xhigh`). | `SKILL.md` § Step 2 (**Roles**); `CONSTRAINTS.md` — **Opus 4.7 at xhigh effort for both teammates** |
-| I-7 | `TeamDelete()` is called with no arguments. | TeamDelete schema: no required params, no properties |
+| I-1 | **Path A:** `Bash` invoking `scripts/grant_project_claude_permissions.py` precedes every `TeamCreate`. **Path B:** grant precedes first audit **`Task`**. | `SKILL.md` § Step 0; § Path routing |
+| I-2 | `Bash` invoking `scripts/revoke_project_claude_permissions.py` runs exactly once per invocation on every exit path, **after** teardown that applies to that path (`TeamDelete` only on Path A). | `SKILL.md` § Step 5 |
+| I-3 | **Path A:** Exactly one `TeamCreate` and exactly one `TeamDelete` per invocation. **Path B:** zero `TeamCreate` / `TeamDelete`. | `SKILL.md` § Step 2; § Step 4 |
+| I-4 | **Path A:** Before `TeamDelete`, no teammate remains active without cleanup (self-terminated `Agent` or `SendMessage` shutdown). | `SKILL.md` § AUDIT/FIX shutdown; § Step 4 |
+| I-5 | **Path A:** `Agent` calls are fresh per loop. **Path B:** `Task` calls for audit/fix are fresh per loop (same `name` discipline where the host exposes naming). | `CONSTRAINTS.md` — **Fresh teammate per loop**; deltas **Clean-room note** |
+| I-6 | Both paths: audit and fix worker spawns pass `model="opus"` on `Agent` **or** `Task` as documented in `SKILL.md` § AUDIT/FIX. | `SKILL.md` § Step 2 (**Roles**); `CONSTRAINTS.md` — **Opus 4.7 at xhigh effort for both teammates** |
+| I-7 | **Path A:** `TeamDelete()` is called with no arguments. **Path B:** omit. | `SKILL.md` § Step 4 |
 | I-8 | Loop count ≤ 10 audits. 11th audit never fires. | `SKILL.md` YAML `description` (10-loop cap); § Step 3 (**Pre-audit** / **FIX** increment rules) |
-| I-9 | From loop 4 onward without convergence, the audit phase emits three parallel `Agent` calls in a single assistant message with names `bugfind-loop-<N>-a/b/c`. | `SKILL.md` § AUDIT action (**Parallel auditors**); `reference/audit-and-teammates.md` § **Parallel auditors** |
+| I-9 | **Path A:** From loop 4 onward without convergence, three parallel `Agent` calls in one message. **Path B:** three parallel **`Task`** calls. | `SKILL.md` § AUDIT action (**Parallel auditors**); `reference/workflow-path-b-task-harness.md` |
 | I-10 | Lead reads `.bugteam-loop-<N>.outcomes.xml` with the `Read` tool after each audit, before the next action. | `SKILL.md` § AUDIT action |
-| I-11 | On exit of any kind, ordering is: teammate shutdowns → `TeamDelete` → temp-dir cleanup → Step 4.5 PR rewrite → revoke. | `SKILL.md` § Step 4; § Step 4.5; § Step 5; `reference/teardown-publish-permissions.md` § **Step 4** / **Step 4.5** / **Step 5** |
-| I-12 | Lead never posts PR review comments, finding comments, or fix replies. The only lead-side PR mutation is the final `gh pr edit --body-file` in Step 4.5. | `CONSTRAINTS.md` — **Teammates own audit/fix comment posting**; **Lead owns the final PR description rewrite only** |
-| I-13 | Only the orchestrator (lead session) invokes `TeamCreate`. Every teammate `Agent(...)` call passes `team_name=<lead_team_name>`. No teammate ever calls `TeamCreate`. When supplementary work arises mid-cycle (parallel auditors, adjacent-file audits, infrastructure fixes), the lead spawns additional teammates into the existing team rather than creating a second team. | `CONSTRAINTS.md` — **Orchestrator-only `TeamCreate`** (runtime error quoted there) |
+| I-11 | **Path A:** `git worktree remove` each PR → teammate shutdowns → `TeamDelete` → `rmtree` `<team_temp_dir>` → Step 4.5 → revoke. **Path B:** `git worktree remove` each PR → (omit shutdown / `TeamDelete`) → `rmtree` → Step 4.5 → revoke. | `SKILL.md` § Step 4; § Step 4.5; § Step 5; `reference/workflow-path-a-orchestrated-teams.md` § Step 4; `reference/workflow-path-b-task-harness.md` § Step 4 |
+| I-12 | **Path A:** Lead never posts PR review / finding / fix replies except Step 4.5 body. **Path B:** Lead performs Step 2.5 posts per deltas; Step 4.5 unchanged. | `CONSTRAINTS.md` — **Audit/fix comment posting** |
+| I-13 | **Path A:** Only the lead invokes `TeamCreate`; every teammate `Agent(..., team_name=...)`. **Path B:** no `TeamCreate`; `Task` spawns omit `team_name`. | `CONSTRAINTS.md` — **Path A — orchestrator-only `TeamCreate`**; `reference/workflow-path-b-task-harness.md` |
 
 Any eval failing one or more Layer A invariants fails the run.
 
@@ -46,23 +46,25 @@ The harness does not yet exist; this document defines its contract.
 
 ---
 
-## Eval 1 — Refusal: agent teams not enabled
+## Eval 1 — Path B: agent teams env unset (Task harness, not a refusal)
 
 **Scenario.** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is unset in both `claude config` and `~/.claude/settings.json`.
 
 **Trigger.** `/bugteam`
 
-**Layer A invariants.** None fire downstream — this is a pre-cycle refusal.
+**Layer A invariants.** Path B subset (I-2, I-5, I-6, I-8, I-10; I-1/I-3/I-4/I-7/I-9/I-11/I-13 N/A or Path-B-shaped).
 
-**Layer B predicted trace.**
+**Layer B predicted trace (Path B smoke).**
 1. `Bash("claude config get env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS")` → empty.
-2. `Read("~/.claude/settings.json")` → settings without the env var.
-3. No grant script, no `TeamCreate`, no `Agent`.
+2. `Bash("python .../grant_project_claude_permissions.py")` runs (Step 0).
+3. **No** `TeamCreate`.
+4. At least one `Task(subagent_type="code-quality-agent", ...)` or host-equivalent for AUDIT; FIX rounds use the host-appropriate FIX `Task` from `workflow-path-b-task-harness.md` § **FIX spawn** (`clean-coder` subtype on Claude Code when accepted; `generalPurpose` + clean-coder **Read** preamble on Cursor when the enum rejects `clean-coder`).
+5. `Bash("python .../revoke_project_claude_permissions.py")` on exit.
 
 **Pass criteria.**
-- Final assistant message contains the exact string `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 not set. /bugteam requires the agent teams feature.`.
-- Zero `TeamCreate`, `Agent`, `SendMessage`, `TeamDelete` calls.
-- Zero invocations of the grant or revoke scripts.
+- **No** refusal string about missing agent teams.
+- Zero `TeamCreate`, zero `TeamDelete`, zero teammate `SendMessage` shutdowns.
+- Non-zero `Task` (or `Agent` without `team_name` only if the host maps Path B that way) carrying **`code-quality-agent`** / **fix worker under the clean-coder contract** (subtype `clean-coder` where accepted, else `generalPurpose` + `clean-coder.md` Read per `workflow-path-b-task-harness.md`).
 
 ---
 
@@ -95,11 +97,11 @@ The harness does not yet exist; this document defines its contract.
 
 ---
 
-## Eval 5 — Happy path: converges in 2 loops
+## Eval 5 — Happy path: converges in 2 loops (Path A fixture)
 
-**Scenario.** PR #42 contains three P1 bugs all addressable by the mock fix teammate. Loop 1 audit returns 3 findings; loop 1 fix commits cleanly; loop 2 audit returns zero findings.
+**Scenario.** PR #42 contains three P1 bugs all addressable by the mock fix teammate. Loop 1 audit returns 3 findings; loop 1 fix commits cleanly; loop 2 audit returns zero findings. **`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`** (Path A — `TeamCreate` + teammate `Agent`).
 
-**Layer A invariants.** I-1, I-2, I-3, I-4, I-5, I-6, I-7, I-10, I-11, I-12.
+**Layer A invariants.** Path A: I-1, I-2, I-3, I-4, I-5, I-6, I-7, I-10, I-11, I-12, I-13.
 
 **Layer B predicted trace.**
 

package/skills/bugteam/reference/README.md

@@ -4,6 +4,8 @@ Expanded material that used to live inline in `SKILL.md`. Load a file when the o
 
 | File | Domain |
 |------|--------|
+| [`workflow-path-a-orchestrated-teams.md`](workflow-path-a-orchestrated-teams.md) | **Path A only** — `TeamCreate`, `Agent` + `team_name`, `SendMessage`, `TeamDelete`, who posts Step 2.5 |
+| [`workflow-path-b-task-harness.md`](workflow-path-b-task-harness.md) | **Path B only** — `Task` harness (no `TeamCreate` / `TeamDelete`, lead Step 2.5 `gh api`, Step 4 omissions) |
 | [`design-rationale.md`](design-rationale.md) | Why agent teams (clean-room), table-of-contents habit, when `/bugteam` applies, refusal reasons |
 | [`team-setup.md`](team-setup.md) | Permissions grant (`CLAUDE_SKILL_DIR`), PR scope, `TeamCreate`, team name / sanitization / temp dir / roles / loop state |
 | [`github-pr-reviews.md`](github-pr-reviews.md) | Per-loop reviews, `jq` + `gh api` payloads, anchors, fallbacks, REST endpoints |

package/skills/bugteam/reference/audit-and-teammates.md

@@ -16,10 +16,10 @@ Repeat until an exit condition fires.
    1. From the repository root, run the gate script (align `--base` with the PR base branch from Step 1, e.g. `origin/main` or `origin/develop`):
 
       ```bash
-      python "${CLAUDE_SKILL_DIR}/scripts/bugteam_code_rules_gate.py" --base origin/<baseRefName>
+      python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py" --base origin/<baseRefName>
       ```
 
-      `git merge-base` + `git diff --name-only` live inside the script; see [`../scripts/README.md`](../scripts/README.md). The lead runs this (not a teammate).
+      `git merge-base` + `git diff --name-only` live inside the script; see [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md) for what lives under this directory, and [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md) for gate-only merge-base / invocation semantics. The lead runs this (not a teammate).
 
    2. If exit code **0** → continue to step 2.5 (AUDIT spawn) below.
    3. If exit code **non-zero** → spawn a new **clean-coder** teammate — **standards-fix pass** — with instructions: read the script’s stderr, edit the repo until a **re-run** of the **same** gate command exits **0**, then one commit, `git push`, shutdown. Repeat standards-fix spawns until the gate exits **0** or **5** failed gate rounds (each round = one teammate session after a non-zero gate). If still non-zero after 5 rounds → exit reason = `error: code rules gate failed pre-audit`.

package/skills/bugteam/reference/teardown-publish-permissions.md

@@ -2,7 +2,7 @@
 
 ## Utility scripts (progressive disclosure)
 
-Fragile or repeatable shell sequences belong in `scripts/`. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Details: [`../scripts/README.md`](../scripts/README.md).
+Fragile or repeatable shell sequences belong in `_shared/pr-loop/scripts/`. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Script inventory and entry points: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
 
 ### Pre-flight (recommended before Step 0)
 

package/skills/bugteam/reference/workflow-path-a-orchestrated-teams.md

@@ -0,0 +1,113 @@
+# Bugteam — Path A workflow (orchestrated teams)
+
+Load when bugteam `SKILL.md` **Path routing** selects **Path A** (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` equals **`1`** after trim). Execute **after** shared `SKILL.md` steps through **Step 2 loop state**; then use this file for **harness-only** steps. Shared gate scripts, Step 3 cycle numbering, Step 2.5 `jq`/`gh` payload shapes, `PROMPTS.md`, and outcome XML rules remain in **`SKILL.md`**.
+
+## Step 2 harness — lifecycle, `TeamCreate`, and team metadata
+
+**This session is the lead.** Step 2 first resolves the team lifecycle from the [Team lifecycle](../SKILL.md#team-lifecycle-path-a-only) table in `SKILL.md`, then either creates or attaches to a team.
+
+**Lifecycle resolution (read once, then apply):**
+
+```python
+import os
+import re
+
+mode = os.environ.get("BUGTEAM_TEAM_LIFECYCLE", "auto").strip().lower() or "auto"
+attached_team_name = os.environ.get("BUGTEAM_TEAM_NAME", "").strip()
+
+if mode == "attach" and not attached_team_name:
+    raise RuntimeError(
+        "BUGTEAM_TEAM_LIFECYCLE=attach requires BUGTEAM_TEAM_NAME to name an existing team."
+    )
+```
+
+The mode then drives Step 2's `TeamCreate` decision:
+
+- **`mode == "attach"`** — skip `TeamCreate` entirely. Set `team_name = attached_team_name`, `team_owned = false`. Continue to teammate spawns using that `team_name`.
+
+- **`mode == "owned"`** — call `TeamCreate(team_name=<computed_team_name>, ...)` (form below). On the runtime error matching `Already leading team "(.+)"\.` → **fail** with `Already leading team <existing>; rerun with BUGTEAM_TEAM_LIFECYCLE=attach BUGTEAM_TEAM_NAME=<existing>`. On success, set `team_owned = true`.
+
+- **`mode == "auto"`** (default) — call `TeamCreate(team_name=<computed_team_name>, ...)`. On the same runtime error, parse the existing team name with the regex `r'Already leading team "([^"]+)"'`, set `team_name = <existing>`, `team_owned = false`, and continue without retrying `TeamCreate`. On success, set `team_owned = true`. Both branches honor §Team name below.
+
+**`TeamCreate` call shape (only when `mode != "attach"` and the auto branch did not already attach):**
+
+```
+TeamCreate(
+  team_name="<computed_team_name>",
+  description="Bugteam audit/fix loop for PR <number> (<owner>/<repo>)",
+  agent_type="team-lead"
+)
+```
+
+**Team name:** For a single-PR invocation use `bugteam-pr-<number>-<YYYYMMDDHHMMSS>`. For a multi-PR invocation use `bugteam-<YYYYMMDDHHMMSS>`. The timestamp is captured once at team-creation time. Apply the no-PR fallback (`bugteam-<sanitized-head>-<YYYYMMDDHHMMSS>`) only when no PR resolves at all. `TeamCreate` implements natural-language team creation ([`sources.md`](../sources.md) § Team creation in natural language).
+
+**Sanitize head branch (no-PR only):** replace characters outside `[A-Za-z0-9._-]` with `-` (e.g. `feat/foo*bar` → `feat-foo-bar`). Apply once; reuse everywhere below.
+
+**`<team_temp_dir>`:** `Path(tempfile.gettempdir()) / team_name` (lead resolves once to an absolute path; every shell gets that literal string).
+
+**Roles (spawned per loop, not here):** bugfind → `code-quality-agent` opus (4.7) at xhigh effort; bugfix → `clean-coder` opus (4.7) at xhigh effort. `model="opus"` resolves to Opus 4.7 on the Anthropic API and runs at the model's default `xhigh` effort level — see [`CONSTRAINTS.md`](../CONSTRAINTS.md) § **Opus 4.7 at xhigh effort for both teammates** for rationale. **Display:** inherit `teammateMode` from `~/.claude.json`. Reference subagent types by name when spawning teammates ([`sources.md`](../sources.md) § Referencing subagent types when spawning teammates).
+
+**Optional Groq-backed FIX path (explicit opt-in only):** when the user explicitly sets `BUGTEAM_FIX_IMPLEMENTER=groq-coder` before invocation, spawn the FIX teammate with `subagent_type="groq-coder"`. Before Step 3, `groq_bugteam.py` loads `packages/claude-dev-env/.env` when that file exists (gitignored; start from `packages/claude-dev-env/.env.example`). If `GROQ_API_KEY` is still unset after that load, stop and prompt the user to create `packages/claude-dev-env/.env` from the example path above—do not continue the Groq path without a key. Any other `BUGTEAM_FIX_IMPLEMENTER` value (or unset) keeps `clean-coder` on Opus. The FIX spawn XML in [`PROMPTS.md`](../PROMPTS.md) is identical for both implementers.
+
+**`--bugbot-retrigger` flag:** when present on the `/bugteam` invocation, after every successful FIX push in Step 3, post an additional `bugbot run` issue comment via the Step 2.5 issue-comments fallback endpoint (`POST .../issues/{issue}/comments`) to re-trigger Cursor's bugbot on the new commit. Omit when the flag is absent.
+
+## Step 2.5 — who posts (Path A)
+
+**Bugfind** posts one `POST .../pulls/<n>/reviews` per loop after audit. **Bugfix** posts `.../comments/<id>/replies` after push. The **lead’s** only PR write before Step 4.5 is unchanged from `SKILL.md` (Step 4.5 body edit).
+
+## AUDIT spawn (Path A)
+
+After shared setup in `SKILL.md` (`mkdir`, `gh pr diff`):
+
+```
+Agent(
+  subagent_type="code-quality-agent",
+  name="bugfind-pr<N>-loop<L>",
+  team_name="<team_name>",
+  model="opus",
+  description="Bugfind audit PR <N> loop <L>",
+  prompt="<audit XML; see PROMPTS.md>"
+)
+```
+
+Fresh `Agent` each loop; teammate context excludes lead history ([`sources.md`](../sources.md) § Teammate context isolation). [`PROMPTS.md`](../PROMPTS.md): XML + outcome schema. Lead reads `.bugteam-pr<N>-loop<L>.outcomes.xml`, fills `loop_comment_index` per `SKILL.md`.
+
+**Shutdown:** If `Agent` returned and the teammate already ended, skip. Otherwise:
+
+```
+SendMessage(
+  to="bugfind-pr<N>-loop<L>",
+  message={"type": "shutdown_request", "reason": "audit PR <N> loop <L> complete; outcome XML captured"}
+)
+```
+
+`approve: false` → `error: bugfind teammate refused shutdown` → Step 4 then 5 per `SKILL.md`.
+
+**Parallel auditors (`loop_count >= 4`):** after three full audit/fix rounds without convergence, issue three `Agent` calls in one assistant message with `team_name="<team_name>"` per `SKILL.md` § parallel variant naming (`-a` / `-b` / `-c`). Shutdown: parallel `SendMessage` to `b` and `c`, then `a`.
+
+## FIX spawn (Path A)
+
+```
+Agent(
+  subagent_type="clean-coder",
+  name="bugfix-pr<N>-loop<L>",
+  team_name="<team_name>",
+  model="opus",
+  description="Bugfix PR <N> loop <L>",
+  prompt="<fix XML; see PROMPTS.md>"
+)
+```
+
+**Shutdown:** same pattern as AUDIT; `SendMessage(to="bugfix-pr<N>-loop<L>", message={"type": "shutdown_request", "reason": "fix PR <N> loop <L> complete; commit <sha7> pushed"})`. `approve: false` → `error: bugfix teammate refused shutdown` → Step 4 then 5.
+
+Verify and outcome handling: unchanged from `SKILL.md` § FIX action (**Verify**, stuck message, [`PROMPTS.md`](../PROMPTS.md)).
+
+## Step 4 harness — after worktree remove, before shared `rmtree`
+
+Run **after** `SKILL.md` § Step 4 step 1 (`git worktree remove` for each PR).
+
+1. For each live teammate **spawned by this invocation**: `SendMessage(to="<name>", message={"type": "shutdown_request", "reason": "bugteam cycle ending"})`. `approve: false` on cleanup → log and continue. Teammates that pre-existed an attached team (mode `attach` or `auto` after the attach branch) are owned by the orchestrator, not this invocation — leave them alone.
+
+2. `TeamDelete()` — **only when `team_owned=true`** (set in Step 2 lifecycle resolution). When `team_owned=false`, **skip `TeamDelete`** and log `cleanup: skipped TeamDelete (team not owned by this invocation; lifecycle=<mode>)`. The orchestrator that originally created the team owns teardown — see [Team lifecycle](../SKILL.md#team-lifecycle-path-a-only).
+
+Then continue with `SKILL.md` § Step 4 step 3 (`<team_temp_dir>` cleanup, also gated on `team_owned`).

package/skills/bugteam/reference/workflow-path-b-task-harness.md

@@ -0,0 +1,48 @@
+# Bugteam — Path B workflow (Task harness)
+
+Load when bugteam `SKILL.md` **Path routing** selects **Path B** (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is not exactly **`1`** after trim — typical Cursor IDE). Execute **after** shared `SKILL.md` steps through **Step 2 loop state**. **Do not** run `TeamCreate` or `TeamDelete`. Harness substitutions vs Path A:
+
+| Path A | Path B |
+| --- | --- |
+| `TeamCreate(...)` | **Omit.** |
+| `Agent(..., team_name=..., ...)` | **`Task`** (or host-equivalent) with the same `model` and prompt contracts as Path A — **omit** `team_name`. `subagent_type` follows this file's **AUDIT** / **FIX spawn** sections (Claude Code: `code-quality-agent` / `clean-coder`; Cursor: `code-quality-agent` / `generalPurpose` + mandatory `clean-coder.md` **Read** on FIX when the enum rejects `clean-coder`). |
+| `SendMessage` shutdown | **Omit.** Await Task completion. |
+| `TeamDelete()` | **Omit.** |
+| Three parallel `Agent` (`loop_count >= 4`) | Three parallel **`Task`** with `subagent_type="code-quality-agent"`; merge outcomes in the lead like Path A `-a`/`-b`/`-c`. |
+
+## Step 2 harness — Path B
+
+No `TeamCreate`. After shared `SKILL.md` **Step 1** completes (PR scope **and** `<team_temp_dir>/pr-<N>/` per Step 1 items 1–3 there), use the same `team_name` string only as a **logical label** for paths under that `<team_temp_dir>`; do not pass `team_name` into spawns.
+
+**`--bugbot-retrigger` flag:** same as Path A [`workflow-path-a-orchestrated-teams.md`](workflow-path-a-orchestrated-teams.md) § Step 2 harness — the **lead** posts the issue comment after each successful FIX push when the flag is present.
+
+## Step 2.5 — who posts (Path B)
+
+The **lead** runs the **same** `gh api` / `jq` sequences as `SKILL.md` **Step 2.5** after reading each **`Task`** handoff / outcome XML — same JSON shapes and anchor rules; only **who executes the shell** changes.
+
+## AUDIT spawn (Path B)
+
+After shared setup in `SKILL.md` (`mkdir`, `gh pr diff`):
+
+`Task` with `subagent_type="code-quality-agent"`, **omit** `team_name`, same `model`, `description`, and `prompt="<audit XML; see PROMPTS.md>"` as Path A [`workflow-path-a-orchestrated-teams.md`](workflow-path-a-orchestrated-teams.md) § AUDIT spawn.
+
+Fresh **Task** each loop (clean-room intent: do not reuse prior Task transcript as audit input). Lead reads `.bugteam-pr<N>-loop<L>.outcomes.xml`, fills `loop_comment_index` per `SKILL.md`.
+
+**Parallel auditors (`loop_count >= 4`):** three **`Task`** calls with `subagent_type="code-quality-agent"` in one assistant message; merge outcomes in the lead exactly as Path A documents for variants `-a`/`-b`/`-c`. Await all three Tasks — no `SendMessage`.
+
+## FIX spawn (Path B)
+
+**Hosts that accept `clean-coder` as a `Task` subtype (typical Claude Code):** `Task` with `subagent_type="clean-coder"` (or `subagent_type="groq-coder"` when `BUGTEAM_FIX_IMPLEMENTER=groq-coder` per Path A optional Groq rules), **omit** `team_name`, same fields otherwise as Path A [`workflow-path-a-orchestrated-teams.md`](workflow-path-a-orchestrated-teams.md) § FIX spawn. Await Task completion — no `SendMessage`.
+
+**Cursor and other hosts with a fixed `Task` enum (no `clean-coder` value):** use `Task` with `subagent_type: "generalPurpose"` and put the **same** FIX obligations from Path A into the **`prompt`**, after a mandatory first step to **Read** the clean-coder agent markdown: macOS/Linux `$HOME/.claude/agents/clean-coder.md`, Windows `%USERPROFILE%\.claude\agents\clean-coder.md`. State that file is binding for naming, TDD when behavior changes, hooks, one commit, and scope. Do **not** use a bare `generalPurpose` prompt without that Read. Same bundle as [`../../pr-converge/SKILL.md`](../../pr-converge/SKILL.md) Fix protocol **Implement**. If `Task` cannot run, stop and notify the user.
+
+Verify and outcome handling: unchanged from `SKILL.md` § FIX action.
+## Step 4 harness — after worktree remove, before shared `rmtree`
+
+Run **after** `SKILL.md` § Step 4 step 1 (`git worktree remove` for each PR).
+
+**Omit** teammate `SendMessage` rounds and **`TeamDelete()`**. Then continue with `SKILL.md` § Step 4 step 3 (shared `rmtree` on `<team_temp_dir>`).
+
+## Clean-room note
+
+Path B approximates Path A isolation by spawning a **new** Task per AUDIT (and per FIX) with the same prompt contract as Path A, without reusing prior Task context as audit input.

package/skills/bugteam/scripts/reflow_skill_md.py

@@ -0,0 +1,298 @@
+"""Reflow packages/claude-dev-env/skills/bugteam/SKILL.md to 80 columns.
+
+Merge soft line breaks outside fenced blocks (space join; URL path fragments
+joined without a space only inside unfinished markdown link targets), then
+wrap with textwrap. Preserves fenced blocks verbatim.
+
+Same algorithm as ``packages/claude-dev-env/skills/pr-converge/scripts/reflow_skill_md.py``
+from https://github.com/jl-cmd/claude-code-config/pull/349 (branch
+``cursor/pr-converge-skill-line-wrap-ecd1``); ``SKILL_PATH`` points at bugteam
+``SKILL.md``. Link reference definitions (``[id]: url``) are treated as logical
+line starts so they are not merged with prior paragraphs.
+
+Run: python3 packages/claude-dev-env/skills/bugteam/scripts/reflow_skill_md.py
+"""
+
+from __future__ import annotations
+
+import re
+import textwrap
+from pathlib import Path
+
+MAX_WIDTH = 80
+SKILL_PATH = Path(__file__).resolve().parent.parent / "SKILL.md"
+
+ORDERED_RE = re.compile(r"^(\s*)(\d+\.\s)(.*)$")
+BULLET_RE = re.compile(r"^(\s*)([-*]\s)(.*)$")
+UNFINISHED_MD_LINK_TARGET = re.compile(r"\]\([^)]*$")
+
+
+def wrap_paragraph_plain(text: str) -> list[str]:
+    collapsed = " ".join(text.split())
+    if not collapsed:
+        return []
+    return textwrap.fill(
+        collapsed,
+        width=MAX_WIDTH,
+        break_long_words=False,
+        break_on_hyphens=False,
+    ).splitlines()
+
+
+def wrap_list_item(lead_ws: str, marker: str, body: str) -> list[str]:
+    collapsed = " ".join(body.split())
+    if not collapsed:
+        return [lead_ws + marker.rstrip()]
+    prefix = lead_ws + marker
+    subsequent = lead_ws + (" " * len(marker))
+    return textwrap.fill(
+        collapsed,
+        width=MAX_WIDTH,
+        initial_indent=prefix,
+        subsequent_indent=subsequent,
+        break_long_words=False,
+        break_on_hyphens=False,
+    ).splitlines()
+
+
+def reflow_yaml_description_block(lines: list[str], body_start: int) -> tuple[list[str], int]:
+    body_parts: list[str] = []
+    index = body_start
+    while index < len(lines):
+        line = lines[index]
+        if line.strip() == "---":
+            index += 1
+            break
+        stripped = line.lstrip()
+        if stripped:
+            body_parts.append(stripped)
+        index += 1
+    merged = " ".join(body_parts)
+    wrapped = textwrap.fill(
+        merged,
+        width=MAX_WIDTH,
+        initial_indent="  ",
+        subsequent_indent="  ",
+        break_long_words=False,
+        break_on_hyphens=False,
+    )
+    return wrapped.splitlines(), index
+
+
+def is_table_line(line: str) -> bool:
+    return line.lstrip().startswith("|")
+
+
+def is_link_reference_definition(stripped: str) -> bool:
+    return bool(re.match(r"^\[[^\]]+\]:\s+\S", stripped))
+
+
+def is_new_logical_line(stripped: str) -> bool:
+    if not stripped:
+        return False
+    if stripped.startswith("```"):
+        return True
+    if stripped.startswith("#"):
+        return True
+    if stripped == "---":
+        return True
+    if is_table_line(stripped):
+        return True
+    if stripped.startswith("<example>") or stripped.startswith("</example>"):
+        return True
+    if is_link_reference_definition(stripped):
+        return True
+    if ORDERED_RE.match(stripped) or BULLET_RE.match(stripped):
+        return True
+    return False
+
+
+def merge_without_space(buffer: str, continuation: str) -> bool:
+    """Join without space only for split markdown link URL paths."""
+    base = buffer.rstrip()
+    stripped = continuation.lstrip()
+    if not base or not stripped:
+        return False
+    if stripped.startswith("/") and UNFINISHED_MD_LINK_TARGET.search(base):
+        return True
+    return False
+
+
+def merge_soft_breaks(lines: list[str]) -> list[str]:
+    output: list[str] = []
+    index = 0
+    in_fence = False
+    while index < len(lines):
+        raw = lines[index]
+        line = raw.rstrip("\n")
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+            output.append(line)
+            index += 1
+            continue
+        if in_fence:
+            output.append(line)
+            index += 1
+            continue
+        if line.strip() == "":
+            output.append(line)
+            index += 1
+            continue
+        buffer_line = line
+        index += 1
+        while index < len(lines):
+            next_raw = lines[index].rstrip("\n")
+            if next_raw.strip() == "":
+                break
+            if next_raw.lstrip().startswith("```"):
+                break
+            stripped_next = next_raw.lstrip()
+            if is_new_logical_line(stripped_next):
+                break
+            if merge_without_space(buffer_line, stripped_next):
+                buffer_line = buffer_line.rstrip() + stripped_next
+            else:
+                buffer_line = f"{buffer_line.rstrip()} {stripped_next}"
+            index += 1
+        output.append(buffer_line)
+    return output
+
+
+def reflow_merged_line(line: str) -> list[str]:
+    stripped = line.strip()
+    if stripped == "":
+        return [""]
+    if stripped.startswith("```"):
+        return [line]
+    if stripped.startswith("#"):
+        if len(stripped) <= MAX_WIDTH:
+            return [stripped]
+        title = stripped.lstrip("#").strip()
+        level = len(stripped) - len(stripped.lstrip("#"))
+        prefix = "#" * level + " "
+        return textwrap.fill(
+            title,
+            width=MAX_WIDTH,
+            initial_indent=prefix,
+            subsequent_indent=prefix,
+            break_long_words=False,
+            break_on_hyphens=False,
+        ).splitlines()
+    if stripped == "---":
+        return ["---"]
+    if is_link_reference_definition(stripped):
+        return [stripped]
+    if is_table_line(stripped):
+        return [stripped]
+    if stripped.startswith("</example>"):
+        return [stripped]
+    if stripped.startswith("<example>"):
+        inner = stripped[len("<example>") :].strip()
+        if not inner:
+            return ["<example>"]
+        tag = "<example> "
+        subsequent = " " * len(tag)
+        return textwrap.fill(
+            " ".join(inner.split()),
+            width=MAX_WIDTH,
+            initial_indent=tag,
+            subsequent_indent=subsequent,
+            break_long_words=False,
+            break_on_hyphens=False,
+        ).splitlines()
+
+    ordered = ORDERED_RE.match(line)
+    if ordered:
+        return wrap_list_item(ordered.group(1), ordered.group(2), ordered.group(3))
+
+    bullet = BULLET_RE.match(line)
+    if bullet:
+        return wrap_list_item(bullet.group(1), bullet.group(2), bullet.group(3))
+
+    return wrap_paragraph_plain(stripped)
+
+
+def reflow_markdown_body(lines: list[str]) -> list[str]:
+    merged = merge_soft_breaks(lines)
+    output: list[str] = []
+    for each_line in merged:
+        if each_line.strip() == "":
+            output.append("")
+            continue
+        output.extend(reflow_merged_line(each_line))
+    return output
+
+
+def wrap_long_bash_fence_lines(lines: list[str]) -> list[str]:
+    """Hard-wrap only ```bash fence bodies that still exceed MAX_WIDTH."""
+    output: list[str] = []
+    in_bash_fence = False
+    for line in lines:
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            if not in_bash_fence:
+                lang = stripped[3:].strip().lower()
+                in_bash_fence = lang == "bash"
+            else:
+                in_bash_fence = False
+            output.append(line)
+            continue
+        if in_bash_fence and len(line) > MAX_WIDTH:
+            indent_len = len(line) - len(line.lstrip())
+            indent = line[:indent_len]
+            content = line.lstrip()
+            wrapped_segments: list[str] = []
+            rest = content
+            while len(rest) > MAX_WIDTH - len(indent):
+                room = MAX_WIDTH - len(indent) - 2
+                window = rest[:room]
+                break_at = window.rfind(" ")
+                if break_at <= 0:
+                    break_at = room
+                piece = rest[:break_at].rstrip()
+                rest = rest[break_at:].lstrip()
+                wrapped_segments.append(indent + piece + " \\")
+            if rest:
+                wrapped_segments.append(indent + ("  " if wrapped_segments else "") + rest)
+            output.extend(wrapped_segments)
+        else:
+            output.append(line)
+    return output
+
+
+def main() -> None:
+    raw = SKILL_PATH.read_text(encoding="utf-8")
+    lines = raw.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise SystemExit("expected YAML front matter starting with ---")
+
+    out: list[str] = ["---"]
+    index = 1
+    while index < len(lines):
+        line = lines[index]
+        if line.startswith("description: >-"):
+            out.append(line)
+            index += 1
+            desc_lines, index = reflow_yaml_description_block(lines, index)
+            out.extend(desc_lines)
+            out.append("---")
+            break
+        out.append(line)
+        index += 1
+
+    body = reflow_markdown_body(lines[index:])
+    body = wrap_long_bash_fence_lines(body)
+
+    text = "\n".join(out + body) + "\n"
+    SKILL_PATH.write_text(text, encoding="utf-8", newline="\n")
+
+    all_lines = text.splitlines()
+    long_rows = [(i, len(ln)) for i, ln in enumerate(all_lines, 1) if len(ln) > MAX_WIDTH]
+    print("SKILL.md reflowed; lines:", len(all_lines))
+    print("lines longer than %d: %d" % (MAX_WIDTH, len(long_rows)))
+    if long_rows[:20]:
+        print("first long:", long_rows[:20])
+
+
+if __name__ == "__main__":
+    main()

package/skills/bugteam/test_skill_additions.py

@@ -10,9 +10,16 @@ def _read_skill_text() -> str:
     return skill_path.read_text(encoding="utf-8")
 
 
+def _read_path_a_workflow_text() -> str:
+    workflow_path = (
+        pathlib.Path(__file__).parent / "reference" / "workflow-path-a-orchestrated-teams.md"
+    )
+    return workflow_path.read_text(encoding="utf-8")
+
+
 def test_skill_references_fix_implementer_env_var():
-    skill_text = _read_skill_text()
-    assert "BUGTEAM_FIX_IMPLEMENTER" in skill_text
+    workflow_text = _read_path_a_workflow_text()
+    assert "BUGTEAM_FIX_IMPLEMENTER" in workflow_text
 
 
 def test_skill_names_default_implementer_subagent_type():
@@ -21,10 +28,12 @@ def test_skill_names_default_implementer_subagent_type():
 
 
 def test_skill_names_optional_groq_implementer_subagent_type():
-    skill_text = _read_skill_text()
-    assert "groq-coder" in skill_text
+    workflow_text = _read_path_a_workflow_text()
+    assert "groq-coder" in workflow_text
 
 
 def test_skill_documents_bugbot_retrigger_flag():
     skill_text = _read_skill_text()
+    workflow_text = _read_path_a_workflow_text()
     assert "--bugbot-retrigger" in skill_text
+    assert "--bugbot-retrigger" in workflow_text