claude-dev-env 1.34.1 → 1.36.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/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

package/skills/bugteam/test_team_lifecycle.py

@@ -0,0 +1,94 @@
+"""Markdown assertion tests for bugteam team-lifecycle decoupling.
+
+Locks in the contract that the bugteam skill must:
+  - support three team lifecycle modes (`owned`, `attach`, `auto`)
+  - default to `auto` (back-compat for solo invocations, safe for nested ones)
+  - skip `TeamDelete` when the invocation did not create the team
+  - parse the runtime's `Already leading team "<name>"` error and attach
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+
+def _read(relative_path: str) -> str:
+    here = pathlib.Path(__file__).parent
+    return (here / relative_path).read_text(encoding="utf-8")
+
+
+def _skill_text() -> str:
+    return _read("SKILL.md")
+
+
+def _path_a_text() -> str:
+    return _read("reference/workflow-path-a-orchestrated-teams.md")
+
+
+def _constraints_text() -> str:
+    return _read("CONSTRAINTS.md")
+
+
+def test_skill_documents_three_team_lifecycle_modes():
+    skill_text = _skill_text()
+    assert "BUGTEAM_TEAM_LIFECYCLE" in skill_text
+    assert "owned" in skill_text
+    assert "attach" in skill_text
+    assert "auto" in skill_text
+
+
+def test_skill_documents_auto_as_default_lifecycle():
+    skill_text = _skill_text()
+    assert "default" in skill_text.lower()
+    assert "BUGTEAM_TEAM_LIFECYCLE" in skill_text
+    auto_default_phrases = [
+        "default: `auto`",
+        "default `auto`",
+        "defaults to `auto`",
+        "defaults to auto",
+        "default to `auto`",
+    ]
+    assert any(phrase in skill_text for phrase in auto_default_phrases)
+
+
+def test_skill_documents_BUGTEAM_TEAM_NAME_env_for_attach_mode():
+    skill_text = _skill_text()
+    assert "BUGTEAM_TEAM_NAME" in skill_text
+
+
+def test_path_a_workflow_handles_already_leading_team_error():
+    workflow_text = _path_a_text()
+    assert 'Already leading team "' in workflow_text
+    assert "team_owned" in workflow_text
+
+
+def test_path_a_workflow_step_4_skips_team_delete_when_not_owned():
+    workflow_text = _path_a_text()
+    assert "TeamDelete" in workflow_text
+    assert "team_owned" in workflow_text
+    skip_phrases = [
+        "skip `TeamDelete`",
+        "skip TeamDelete",
+        "omit `TeamDelete`",
+        "omit TeamDelete",
+        "do not call `TeamDelete`",
+        "do not call TeamDelete",
+    ]
+    assert any(phrase in workflow_text for phrase in skip_phrases)
+
+
+def test_path_a_workflow_documents_attach_mode_reuses_team_name():
+    workflow_text = _path_a_text()
+    assert "BUGTEAM_TEAM_NAME" in workflow_text
+    assert "attach" in workflow_text
+
+
+def test_constraints_lead_only_cleanup_includes_team_owned():
+    constraints_text = _constraints_text()
+    assert "team_owned" in constraints_text
+
+
+def test_constraints_warn_against_owned_mode_inside_orchestrator():
+    constraints_text = _constraints_text()
+    assert "orchestrator" in constraints_text.lower()
+    assert "attach" in constraints_text

package/skills/findbugs/SKILL.md

@@ -121,7 +121,7 @@ When the agent returns, report concisely:
 - The cleared categories so the user can see coverage breadth
 - Any open questions the agent could not resolve from the diff alone
 
-Offer the next step without auto-executing it: `Want me to spawn clean-coder to fix the P0/P1 findings?`
+Offer the next step without auto-executing it: `Want me to run /fixbugs for the P0/P1 findings?`
 
 Delete the scoped temp diff at `<diff_temp_path>` after the audit completes (or moves to a fix flow). Temporary diff files do not belong in the working tree.
 
@@ -143,7 +143,7 @@ Verified clean: <category>, <category>, <category>
 Open questions:
   <if any>
 
-Want me to spawn clean-coder to fix the P0/P1 findings?
+Want me to run /fixbugs for the P0/P1 findings?
 ```
 
 ## Constraints
@@ -177,7 +177,7 @@ Claude: [resolves PR #42 from current branch, fetches full diff, spawns code-qua
 
 `Open questions: none`
 
-`Want me to spawn clean-coder to fix the P0 + P1s?`
+`Want me to run /fixbugs for the P0 + P1s?`
 </example>
 
 <example>

package/skills/fixbugs/SKILL.md

@@ -3,7 +3,7 @@ name: fixbugs
 description: >-
   Fixes the bugs surfaced by the most recent /findbugs invocation by handing
   the findings to /agent-prompt, which authors a structured XML prompt and
-  spawns a background sonnet clean-coder agent to implement every fix in one
+  spawns a background sonnet implementer (via /agent-prompt) to apply every fix in one
   commit on the existing branch. Default scope: all severities. Optional
   argument filters by severity (e.g. /fixbugs P0, /fixbugs P0+P1).
   Triggers: '/fixbugs', 'fix all the bugs', 'apply the audit fixes',
@@ -66,8 +66,8 @@ Fix the following bugs surfaced by /findbugs on
 [for each filtered finding, one bullet:]
 - [<severity>] <file:line> (<category>): <description>
 
-Deploy a clean-coder background agent (model: sonnet) to implement all fixes
-in one commit on the existing branch and push. Constraints:
+Deploy a background implementer (model: sonnet) to implement all fixes
+in one commit on the existing branch and push. The implementer must **Read** the clean-coder agent file first (`~/.claude/agents/clean-coder.md`; Windows `%USERPROFILE%\.claude\agents\clean-coder.md`) and treat it as binding; on Cursor use `Task` + `generalPurpose` with that Read in the prompt when `clean-coder` is not a valid `Task` subtype. Constraints:
 - Modify only the files referenced in the bug list above.
 - Do NOT change the PR base, do NOT rebase, do NOT amend, do NOT --force.
 - Do NOT skip git hooks (no --no-verify, no --no-gpg-sign).
@@ -106,7 +106,7 @@ When `/fixbugs` short-circuits (no findings, no PR, empty filter, zero bugs), th
 <example>
 User: `/findbugs` → returns `1 P0 / 2 P1 / 0 P2`
 User: `/fixbugs`
-Claude: [recovers all 3 findings, resolves PR scope, invokes /agent-prompt with a goal targeting all 3 bugs; /agent-prompt presents the XML + Outcome digest + AskUserQuestion; on Launch it, the background sonnet clean-coder spawns]
+Claude: [recovers all 3 findings, resolves PR scope, invokes /agent-prompt with a goal targeting all 3 bugs; /agent-prompt presents the XML + Outcome digest + AskUserQuestion; on Launch it, the background sonnet implementer spawns]
 </example>
 
 <example>

package/skills/monitor-open-prs/SKILL.md

@@ -19,6 +19,7 @@ description: >-
 
 - When this skill applies — refusal cases and trigger conditions
 - Discovery — live `gh search prs` across both owner scopes
+- Team lifecycle — single long-lived team for the whole sweep
 - Wrapping — `bws run` for GROQ_API_KEY injection
 - Dispatch — `/bugteam <numbers...>` with groq-coder + retrigger
 - Post-convergence polling — bugbot replies and re-invocation
@@ -40,6 +41,35 @@ Refusals — first match wins; respond with the quoted line exactly and stop:
 
 Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho"])` to merge the live open-PR list across both scopes. The helper runs `gh search prs --owner <owner> --state open --json number,repository,url,headRefName,baseRefName` once per owner and flattens the result to a uniform dict shape with keys `number`, `owner`, `repo`, `head_ref`, `base_ref`, `url`. Empty scopes contribute empty lists; an entirely empty sweep returns `[]` and exits cleanly.
 
+## Team Lifecycle
+
+`/monitor-open-prs` dispatches one `/bugteam` per discovered PR — often more than ten in a sweep. Per-invocation `TeamCreate` / `TeamDelete` from each `/bugteam` would either collide on the runtime's `Already leading team` rule or tear down the wrong team mid-sweep, depending on dispatch order. The sweep instead owns a **single long-lived team for the whole sweep** and passes that team to every `/bugteam` invocation in attach mode. See [bugteam Team lifecycle](../bugteam/SKILL.md#team-lifecycle-path-a-only).
+
+**Before the first dispatch:**
+
+1. Capture `sweep_id = <YYYYMMDDHHMMSS>` once at sweep start. This is the same convention as bugteam's team-name timestamp.
+2. Compute `team_name = "bugteam-monitor-<sweep_id>"`.
+3. `TeamCreate(team_name=<team_name>, description="monitor-open-prs sweep <sweep_id>", agent_type="team-lead")`. The orchestrator (this session) becomes the lead.
+
+**For every `/bugteam` dispatch** (parallel fan-out or serial), prepend the two attach-mode env vars to the wrapped command so bugteam reuses the orchestrator's team and skips its own `TeamCreate` / `TeamDelete`:
+
+```bash
+bws run \
+  --project-id c69cedc5-aea1-4aa8-b350-b4300145d978 \
+  -- \
+  env BUGTEAM_TEAM_LIFECYCLE=attach \
+      BUGTEAM_TEAM_NAME=<team_name> \
+      BUGTEAM_FIX_IMPLEMENTER=groq-coder \
+  /bugteam --bugbot-retrigger <pr_numbers...>
+```
+
+**Teardown — only after every PR has exited polling** (see §Post-Convergence Polling): the sweep is done; no further `/bugteam` invocation will run. At that point, and only at that point:
+
+1. `TeamDelete()` (orchestrator is the lead; no arguments).
+2. Print one cleanup line into the §Final Report: `team teardown: TeamDelete <team_name>` (success) or the error message on failure.
+
+If a hard blocker or user stop ends the sweep early, the orchestrator is shutting down: still call `TeamDelete()` once after polling stops for the in-flight PRs.
+
 ## Secret Wrapping
 
 Every `/bugteam` dispatch runs inside `bws run` so `GROQ_API_KEY` is injected from Bitwarden Secrets Manager without touching the filesystem. The project and secret UUIDs are fixed for this skill:
@@ -59,9 +89,9 @@ The `bws run` subshell resolves the project's secrets and exports them for the w
 For each discovered PR:
 
 1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
-2. From that checkout, invoke `/bugteam <pr_number>` under the `bws run` wrapper above.
+2. From that checkout, invoke `/bugteam <pr_number>` under the `bws run` wrapper from §Team Lifecycle (the wrapper already carries `BUGTEAM_TEAM_LIFECYCLE=attach` and `BUGTEAM_TEAM_NAME=<team_name>` so bugteam reuses the sweep-owned team).
 3. The `BUGTEAM_FIX_IMPLEMENTER=groq-coder` env var routes the FIX role to the `groq-coder` subagent. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
-4. Bugteam runs its own 10-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
+4. Bugteam runs its own 10-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below). Each invocation skips its own `TeamCreate` / `TeamDelete` because of attach mode — only the sweep owns team teardown (§Team Lifecycle).
 
 **Fan-out (optional):** when the discovered list has more than one PR, the skill may spawn `/bugteam` dispatches in parallel by issuing multiple `Agent` calls in a single assistant message. Each dispatch operates in its own per-PR worktree (bugteam Step 1.1). Serialize when the caller sets an explicit `--serial` flag.
 

package/skills/monitor-open-prs/test_team_lifecycle.py

@@ -0,0 +1,46 @@
+"""Markdown assertion tests for monitor-open-prs team lifecycle.
+
+Locks in the contract that the sweep must:
+  - own a single long-lived team for every dispatched /bugteam
+  - pass attach mode + the team name into each per-PR /bugteam dispatch
+  - tear down only after all PR polling completes
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+
+def _skill_text() -> str:
+    here = pathlib.Path(__file__).parent
+    return (here / "SKILL.md").read_text(encoding="utf-8")
+
+
+def test_skill_creates_one_team_for_the_whole_sweep():
+    skill_text = _skill_text()
+    assert "TeamCreate" in skill_text
+    sweep_phrases = [
+        "one team for the whole sweep",
+        "single team for the sweep",
+        "single long-lived team",
+    ]
+    assert any(phrase in skill_text for phrase in sweep_phrases)
+
+
+def test_skill_passes_attach_lifecycle_to_each_bugteam_dispatch():
+    skill_text = _skill_text()
+    assert "BUGTEAM_TEAM_LIFECYCLE" in skill_text
+    assert "attach" in skill_text
+    assert "BUGTEAM_TEAM_NAME" in skill_text
+
+
+def test_skill_tears_down_team_after_polling_completes():
+    skill_text = _skill_text()
+    assert "TeamDelete" in skill_text
+    teardown_phrases = [
+        "after every PR has exited polling",
+        "after polling completes",
+        "after the sweep",
+        "after all polling",
+    ]
+    assert any(phrase in skill_text for phrase in teardown_phrases)