@drunkcoding/agents-and-skills 0.0.24 → 0.0.26

package/plugins/team-superpower/assets/ESCALATION.md

@@ -1,142 +0,0 @@
-# Escalation template (team-superpower v5)
-
-v5 replaces v4's peer mailbox + multi-class escalation gauntlet with a single routing point: **team-leader**. Implementers SendMessage team-leader; team-leader routes by `class` per spec §6.4. The only owner-facing path is `RESTART_REQUEST` (team-leader → lead → owner recovery touchpoint).
-
-## Where escalations go in v5
-
-| From                                            | Channel                                | Trigger                                                                                                  |
-| ----------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| backend-developer / frontend-developer          | SendMessage **team-leader**            | Any task-level question that is not pure tactical (style/naming).                                        |
-| security-engineer (phase A)                     | SendMessage **lead**                   | SEC_BLOCKED finding, or `CLAUDE.md` `security.*: # CONFIRM:` blocks threat-modelling.                    |
-| solution-architect / feature-planner (phase A)  | SendMessage **lead**                   | Touchpoint output is owner-facing; lead presents to owner.                                               |
-| qc-engineer (phase G)                           | SendMessage **lead**                   | `QC_REWORK_NEEDED <n>` or `QC_PASS <slug>`. Lead re-spawns team-leader for rework dispatch.              |
-| team-leader (phase B–F coordinator)             | SendMessage **lead** (`SPAWN_REQUEST` / `RESTART_REQUEST`) | Wave dispatch needs implementers; architectural escalation can't be resolved without owner touchpoint.   |
-| lead (orchestrator)                             | Owner touchpoint                       | Touchpoints 1–4 per spec §3.5 plus recovery touchpoints triggered by RESTART_REQUEST or 3+ QC rounds.    |
-
-## Implementer → team-leader template (spec §6.4)
-
-Use this when a backend-developer or frontend-developer can't resolve a question alone.
-
-```
-ESCALATE <task-id>
-class: tactical | cross-role | architectural
-question: <one line>
-context: <2-4 sentences — what we tried, what we considered, why we are stuck>
-```
-
-team-leader routes by `class`:
-
-- **tactical** (style, naming, local design) → team-leader answers from arch-map + AGENTS.md. SendMessage back to originator.
-- **cross-role** (affects another implementer) → team-leader SendMessages the affected peer with the context and a proposed coordination point.
-- **architectural** (changes arch-map, requires planner judgment, invalidates wave plan) → team-leader posts `RESTART_REQUEST <reason+task-id>` to lead. Do NOT re-answer. Do NOT downgrade legitimate architectural questions to tactical.
-
-team-leader MAY downgrade an over-eager `class=architectural` to tactical when the question is genuinely style/naming dressed up as architecture. team-leader explains the downgrade in its reply.
-
-## team-leader → lead protocols
-
-### SPAWN_REQUEST (wave dispatch)
-
-```
-SPAWN_REQUEST wave=<plan-phase>.<wave>
-roles_needed:
-  backend-developer: <count>
-  frontend-developer: <count>
-brief_path: .team-superpower/spawn-briefs/wave-<plan-phase>.<wave>.md
-expected_tasks: [<task-id-1>, <task-id-2>, ...]
-```
-
-Lead reads the brief, TaskCreates per task block, spawns implementers, replies `SPAWN_DONE wave=<...> agent_ids=<...>`.
-
-### RESTART_REQUEST (architectural unblock)
-
-```
-RESTART_REQUEST <reason>
-trigger: <task-id | wave-id | qc-issue>
-context: <2-4 sentences — what arch decision broke, what implementers reported>
-```
-
-Lead:
-1. Shuts down all phase B–F teammates (team-leader + active implementers).
-2. Presents owner recovery touchpoint with summary of partial commits + reason.
-3. On owner approval, re-runs phase A (fresh solution-architect + feature-planner + security-engineer if applicable) with the prior spec/plan/arch-map + partial commits as input.
-4. Increments `cycle_restart_count`. Cap is `limits.max_cycle_restarts` (default 2). Third restart triggers owner escalation: "this feature is not tractable, please refactor scope."
-
-## Decision classes (v5 reference)
-
-| Class           | Examples                                                                                       | Routing                                                                                                                                          |
-| --------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| tactical        | naming, error wording, log field choice, fixture data, threshold inside a stated range         | Originator decides. Logs to commit body `## Assumptions` line. No escalation.                                                                    |
-| cross-role      | API contract shape across roles, error-handling contract, ambiguous acceptance criterion       | `ESCALATE class=cross-role` to team-leader. team-leader routes to affected peer.                                                                 |
-| architectural   | new runtime dependency, persistence-model change, public-interface shape change, contract drift | `ESCALATE class=architectural` to team-leader. team-leader posts `RESTART_REQUEST` to lead.                                                       |
-
-Classification rule of thumb: if the answer changes a test the implementer would write, AND the existing arch-map / plan does not pin it, AND the change does not alter scope / architecture / external policy, the question is tactical or cross-role. Otherwise it is architectural.
-
-## Worked example 1 — backend-developer tactical (NOT escalated, logged as assumption)
-
-backend-developer chose error message `"user_id required"` over `"missing user_id"` for consistency with existing 422 responses on /v1/users. They log it in the commit body:
-
-```
-feat(users): validate user_id on POST /v1/users
-
-Files: src/routes/users.ts, tests/routes/users.test.ts
-Wave: 2.1
-Test-status: green
-
-## Assumptions
-- error string "user_id required" matches existing 422 wording on /v1/users (peer: none, class=tactical)
-```
-
-No `ESCALATE` is sent. team-leader's phase-end review will spot-check assumption lines.
-
-## Worked example 2 — cross-role (frontend asks backend via team-leader)
-
-frontend-developer hits an ambiguous request shape on a paginated endpoint.
-
-```
-ESCALATE impl:fe-list-orders
-class: cross-role
-question: Should the paginated /v1/orders response use `nextCursor: string | null` or `nextCursor?: string`?
-context: arch-map §4 pins cursor-based pagination but does not pick the null-vs-omitted shape. AGENTS.md has no precedent. backend-developer published the contract last wave; I need to align before I write the RED test for `useOrdersQuery`.
-```
-
-team-leader inspects the contract artefact, sees the BE published `nextCursor: string | null`, SendMessages frontend-developer with the decision and a one-line rationale, no further action.
-
-## Worked example 3 — architectural → RESTART_REQUEST
-
-backend-developer discovers mid-implementation that the planned `payments.transactions` table cannot enforce idempotency because the chosen primary key is auto-increment; the arch-map specified idempotency at the application layer but the plan ended up moving it to the DB.
-
-```
-ESCALATE impl:be-2.3-add-charge-endpoint
-class: architectural
-question: Idempotency on POST /v1/charges requires a stable key the client supplies. The plan task uses the DB auto-id, which won't dedupe retries. Should I add an `idempotency_key` column + unique index, or revert idempotency to the app layer as arch-map originally stated?
-context: arch-map §3.2 said "app-layer idempotency via redis SETNX." Plan task 2.3 dropped redis and pushed dedup to DB without a key column. Either fix changes the migration and the route handler. I held RED before writing code.
-```
-
-team-leader confirms this contradicts arch-map, posts to lead:
-
-```
-RESTART_REQUEST arch-vs-plan-mismatch on impl:be-2.3
-trigger: impl:be-2.3-add-charge-endpoint
-context: Plan dropped redis layer arch-map specified; resulting migration cannot enforce idempotency. Implementer held RED. Two valid fixes (DB column + index, OR restore redis); both change the plan. Needs solution-architect adjudication, not team-leader.
-```
-
-Lead shuts down team-leader + implementers, presents owner touchpoint summarising partial commits, runs phase A again on owner approval.
-
-## Hook validation
-
-`task-completed.sh` does NOT gate on the escalation template (escalations are SendMessages, not commits). It DOES validate:
-
-- `Files:`, `Wave:`, `Test-status:` lines on every commit (`INVALID_WAVE_REFERENCE` if missing).
-- `Reworks:` line on every commit for an `impl:rework-*` task (`MISSING_REWORK_REFERENCE`).
-- Static-check log present and exit=0 (`MISSING_STATIC_CHECKS`).
-- No agent-attributed commit touches `docs/superpowers/AGENTS.md` (`AGENT_WROTE_AGENTS_MD`).
-
-The escalation template is policy, not hook-enforced. team-leader bounces ill-formed `ESCALATE` messages with a one-line reformat request.
-
-## v4 → v5 changes (delta reference)
-
-- Removed: 4-class table including `owner-only`. v5 routes owner touchpoints only via `RESTART_REQUEST`.
-- Removed: `Peer attempts:` field. v5 implementers do not peer-mailbox; team-leader is the single router.
-- Removed: `BLOCKED:` template with `Phase / Context / Options / Recommendation / Need from you / Peer attempts`. Replaced by terse `ESCALATE / class / question / context`.
-- Removed: `FINISH_BLOCKED` 5-option menu. v5 finish-branch is a lead-only flow; failures are surfaced as a regular touchpoint to owner.
-- Removed: software-architect / planner / reviewer references. Routing collapses to team-leader + lead.

package/plugins/team-superpower/assets/SESSION_README.md

@@ -1,338 +0,0 @@
-# Superpowers session workspace
-
-This directory holds the artefacts produced by `/team-feature` runs. The
-team-superpower plugin seeds it on first use; afterwards the spec / plan /
-handover / review / checkpoint files for each feature are written by the team
-and committed.
-
-## v5 at a glance
-
-- **One team per feature.** A single `TeamCreate superpower-<slug>` runs the
-  whole lifecycle. Membership rolls forward by spawn + shutdown across phases
-  A–H — no nested teams, no concurrent teams.
-- **Lead is the sole spawner.** `team-leader` composes wave briefs and posts
-  `SPAWN_REQUEST` to lead; lead reads the brief, files tasks, spawns
-  implementers, replies `SPAWN_DONE`. The same channel carries
-  `RESTART_REQUEST` when the team is architecturally stuck.
-- **No per-task QA loop.** Implementers run lint + typecheck + format before
-  every commit; the output is captured to
-  `.team-superpower/static-check-<task-id>.log` and the `TaskCompleted` hook
-  rejects any completion without an `exit=0` line.
-- **Phase-end review.** team-leader runs a consolidated SOLID/DRY/domain pass
-  at the end of every plan-phase and emits `impl:rework-*` tasks where needed.
-- **End-of-plan QC.** Lead spawns one `qc-engineer` after `PLAN_COMPLETE`. Up
-  to 3 rework rounds (`limits.max_qc_rounds`), then owner escalation.
-- **Restart on stuck.** Up to 2 `RESTART_REQUEST` cycles
-  (`limits.max_cycle_restarts`); a third escalates to the owner as "feature
-  not tractable".
-
-## Customising for your project
-
-Stack decisions, test/build commands, contract source-of-truth, CI provider,
-and security posture are all driven by a `team-superpower` fenced block in your
-repo-root `CLAUDE.md`. The plugin reads it on every run; it **never
-overwrites it**.
-
-### 1. Write a `team-superpower` block in CLAUDE.md
-
-Copy `plugins/team-superpower/assets/CLAUDE.md.template` to your repo root as
-`CLAUDE.md` (or paste the `team-superpower` block into your existing CLAUDE.md).
-The block recognises:
-
-- `backend` — `language`, `framework`, `test_framework`, `build_command`,
-  `test_command`, `format_command`, `lint_command`, `typecheck_command`,
-  `migration_tool`, `package_manager`. Set `backend: none` to declare a
-  frontend-only repo.
-- `frontend` — `language`, `framework`, `bundler`, `test_framework`,
-  `e2e_framework`, `ui_library`, `package_manager`, `build_command`,
-  `test_command`, `lint_command`, `typecheck_command`, `format_command`. Set
-  `frontend: none` to declare a backend-only repo.
-- `contracts` — `source_of_truth` (`openapi` / `grpc` / `graphql` /
-  `typescript` / `none`), `openapi_path`, `ts_gen_command`.
-- `ci` — `provider`, `workflow_path`, `required_checks`,
-  `poll_timeout_minutes` (default 20). Used by team-leader at the
-  finish-branch decision (phase H).
-- `security` — `domain` (`payments` / `healthcare` / `generic` /
-  `internal-only`), `pii`, `public_endpoints`, `data_at_rest`. Drives whether
-  `security-engineer` is spawned in phase A.
-- `limits` — `phase_stall_minutes`, `max_tasks_per_implementer`,
-  `max_concurrent_teammates`, `max_iterations_per_task`, `task_token_budget`,
-  `retrieval_budget_per_task`, `max_qc_rounds`, `max_cycle_restarts`.
-
-Free-form prose around the block (e.g. a `## Conventions` section with
-project-specific rules) is passed to every teammate as project context.
-
-### 2. Auto-detection fallback
-
-If `CLAUDE.md` is missing or has no `team-superpower` block, the lead runs
-`scripts/detect-stack.sh` in phase 0 and writes its best guess to
-`docs/superpowers/stack.detected.md`, then halts and asks you to review the
-`# CONFIRM:` lines and paste the corrected block into CLAUDE.md. **The plugin
-will not edit your CLAUDE.md for you.**
-
-### 3. Shape-adaptive team
-
-Once the block (or detection) is parsed, the lead decides the **stack shape**:
-
-| Shape | Phase-A roles | Implementation roles |
-|-------|---------------|----------------------|
-| `full-stack`  | solution-architect, feature-planner, (security-engineer) | backend-developer, frontend-developer |
-| `be-only`     | solution-architect, feature-planner, (security-engineer) | backend-developer |
-| `fe-only`     | solution-architect, feature-planner, (security-engineer) | frontend-developer |
-
-`security-engineer` is added only when `security.domain ∈
-{payments, healthcare}` OR `security.pii: yes`. Otherwise solution-architect
-runs a lightweight security pass alone.
-
-The shape is written to `docs/superpowers/sessions/<slug>.shape`; the
-`TaskCreated` hook reads it to reject `impl:fe-*` in BE-only repos and
-vice-versa.
-
-#### Concurrency model
-
-Phase-gated. The roles listed above are the **lifetime** team size, not the
-parallelism. Roles alive at any moment:
-
-| Phase | Concurrent teammates |
-|-------|----------------------|
-| A — analytics            | solution-architect + feature-planner (+ security-engineer when in scope) |
-| B–F — implementation     | team-leader + 1–N implementers (capped by `limits.max_concurrent_teammates`, default 5) |
-| G — end-of-plan QC       | team-leader + qc-engineer |
-| H — finish               | team-leader (drives CI gate + finish-branch decision) |
-
-Phase-A members shut down at `HANDOVER_READY`. No standby. If the team hits an
-architectural blocker mid-implementation, team-leader posts `RESTART_REQUEST`
-and lead re-runs phase A with the handover + partial commits as input.
-
-#### Within-phase stall watchdog
-
-If lead detects no mailbox activity or shared-task-list transitions for
-`limits.phase_stall_minutes` (default 30) within a phase, it pings the active
-teammate; if the next 30-minute window is also silent, it surfaces a §7
-escalation.
-
-#### Worktree reuse
-
-If you launch `/team-feature` from inside a linked git worktree on a feature
-branch, the planner reuses that worktree instead of nesting a new one. The
-signal `WORKTREE_READY <path> <branch> <origin>` carries `origin: reused` and
-the checkpoint records `**Worktree origin:** reused`.
-
-| Where `/team-feature` is launched | Branch | Behavior |
-|---|---|---|
-| Linked worktree | feature branch | **Reuse** the current worktree. |
-| Linked worktree | `main`, `master`, `develop`, `dev`, `release/*`, `releases/*` | **Halt.** Switch to a feature branch and re-run. |
-| Main repo | any | **Create** a fresh worktree via Superpowers `using-git-worktrees`. |
-
-A reused worktree is owned by you, not the team — auto-removal after merge
-**does not run** when origin is `reused`.
-
-### 4. Contract sync (full-stack only)
-
-When both BE and FE are present and `contracts.source_of_truth != none`, the
-planner emits `impl:be-contract-publish-<slug>` as the first phase-B task. The
-lead does not assign any `impl:fe-*` task until the backend-developer posts
-`CONTRACT_PUBLISHED`. Every `impl:fe-*` task has
-`depends_on: [impl:be-contract-publish-<slug>]` in its metadata.
-
-Mid-implementation contract drift uses `impl:contract-update-<topic>`.
-
-### 5. CI gate before finish (phase H)
-
-team-leader pushes the branch in phase H, then (when `ci.provider != none`)
-polls the CI provider for `ci.required_checks` up to `ci.poll_timeout_minutes`
-(default 20). On green the finish-branch menu surfaces. On red the
-merge-failure menu surfaces with an extra "Show CI logs" option. On timeout a
-3-option menu (re-poll / switch to `pr_opened` / escalate) surfaces.
-
-### 6. Project-aware security checklist
-
-`security-engineer` reads the `security` block and the stack info, then
-expands its checklist accordingly. A `domain: payments` repo gets idempotency
-/ audit-trail / PCI items; a `data_at_rest: sql` repo gets parameterised-query
-items; a no-FE repo skips XSS items entirely. The output report uses ✅/⚠️/❌
-markers — any ❌ blocks phase B.
-
-### 7. Iteration cap (MAX_ITERATIONS)
-
-Every `impl:` task carries an `iteration_count:`. If an implementer retries
-the same failing test 8 times it halts and posts a §7 escalation with
-`what_failed:`, `one_change_to_fix:`, and `class:`. The `task-completed` hook
-rejects completions where `iteration_count > 8` unless a `reflection:` block
-is attached.
-
-Configure per project in CLAUDE.md `limits.max_iterations_per_task` (default
-8). Lower for slow-feedback environments; never raise above 12.
-
-## Layout
-
-```
-docs/superpowers/
-├── ESCALATION.md                          # template — referenced by every teammate
-├── README.md                              # this file
-├── specs/      YYYY-MM-DD-<slug>-spec.md      # owner+architect, phase A
-├── plans/      YYYY-MM-DD-<slug>-plan.md      # feature-planner, phase A
-├── handovers/  YYYY-MM-DD-<slug>-handover.md  # solution-architect, end of phase A
-├── reviews/    YYYY-MM-DD-<slug>-security.md  # security-engineer, phase A (if spawned)
-├── reviews/    YYYY-MM-DD-<slug>-qc.md        # qc-engineer, phase G
-├── sessions/   YYYY-MM-DD-<slug>.md           # checkpoint, updated by lead each phase
-└── sessions/   <slug>.shape                   # stack shape marker (be-only|fe-only|full-stack)
-```
-
-Per-feature scratch (lives next to the worktree):
-
-```
-.team-superpower/
-├── spawn-briefs/    wave-<plan-phase>.<wave>.md   # team-leader, one per wave
-└── static-check-<task-id>.log                     # implementer, one per impl: task
-```
-
-## How to launch
-
-```text
-/team-feature <one-line feature idea>
-```
-
-The lead handles prechecks, spawns the analytics team for phase A, drives the
-hand-off to team-leader, and supervises through phase H.
-
-To resume an in-flight feature drop back into the same worktree and re-run
-`/team-feature` — the lead detects the existing `~/.claude/teams/superpower-<slug>/`
-directory and continues from the checkpoint. **There is no separate resume
-command in v5.**
-
-## Owner touchpoints (max 3 per feature)
-
-1. **Spec sign-off** (mid phase A). Solution-architect batches all clarifying
-   questions before this point.
-2. **Plan approval** (end phase A). Before handover to team-leader.
-3. **Finish-branch decision** (in phase H). Merge / PR / keep / discard.
-
-Recovery touchpoints (`RESTART_REQUEST`, model fallback, CI timeout) are
-**not** counted against the 3-touchpoint budget. Anything else that reaches
-you must use the §7 escalation template in `ESCALATION.md`.
-
-## Reading a checkpoint
-
-`sessions/YYYY-MM-DD-<slug>.md` is the source of truth for in-flight features.
-Each phase boundary appends or updates:
-
-- `## Phases` — checklist, file paths to the artefacts.
-- `## Teammates` — role, agent id, current task or `idle`.
-- `## Open escalations` — anything blocking the owner or a peer.
-- `## Assumptions` — one line per non-owner decision (tactical, cross-role,
-  architectural).
-- `## Cycle history` — append a row on every `RESTART_REQUEST`.
-
-The lead commits this file after every phase transition. If the lead crashes,
-your feature lives in this file.
-
-## Recovery — auto-resume
-
-If `/resume` drops the team mid-feature, re-run `/team-feature <slug>` from
-the same worktree. The lead:
-
-1. Reads `~/.claude/teams/superpower-<slug>/config.json` to know which roles
-   were alive.
-2. Reads `docs/superpowers/sessions/<slug>.md` to know which phase is current.
-3. If past phase A, reads `docs/superpowers/handovers/<date>-<slug>-handover.md`.
-4. Re-spawns the right teammates (skipping completed phases). A
-   `Resume: <ISO ts>` line is appended to the checkpoint for the audit trail.
-
-Completed phases are never redone. Partial commits are kept.
-
-## Cleanup model
-
-The lead is the only thing that knows when a team's work is done. There is no
-`TeamShutdown` hook event, so cleanup is driven by the slash commands:
-
-- **Automatic**, the happy path: `/team-feature` runs cleanup immediately
-  after `FINISH_DONE`. The lead verifies all phases complete, all expected
-  commits in place, every teammate idle, then invokes the canonical "clean up
-  the team" primitive and confirms with a final scan. A `## Closing` block is
-  appended to the checkpoint.
-
-### Closing-block fields
-
-- `finished at: <ISO datetime>`
-- `decision: <merged|pr_opened|kept|discarded>`
-- `cleanup: complete`
-- `cycle_restart_count: <N>` — how many `RESTART_REQUEST` cycles ran.
-- `qc_rounds: <N>` — end-of-plan QC rounds consumed.
-- `worktree: <state>` — `removed` | `already-absent` | `removal-skipped:<reason>` | `kept-by-owner` | `escalated`.
-
-- **Manual**, the orphan path: if a lead crashed and left
-  `~/.claude/teams/superpower-<slug>/` behind, run `/team-cleanup <slug>` from
-  a fresh session. The slash command dry-runs first, prints what would be
-  removed, asks for confirmation, then applies. The heartbeat file
-  (`docs/superpowers/sessions/<slug>.heartbeat`) protects against wiping a
-  live team.
-
-Project-side artefacts (`specs/`, `plans/`, `handovers/`, `reviews/`, and the
-checkpoint itself) are **always preserved**. Only platform-side state under
-`~/.claude/teams/superpower-<slug>/` and `~/.claude/tasks/superpower-<slug>/`
-plus the per-feature scratch under `.team-superpower/` is removed.
-
-## Heartbeat protocol
-
-The lead touches `docs/superpowers/sessions/<slug>.heartbeat` at every phase
-boundary. Future sessions read its mtime to decide whether a previous lead is
-still alive:
-
-- mtime < 10 minutes → lead is likely alive; cleanup refuses without explicit
-  override.
-- mtime ≥ 10 minutes (or file missing) → safe to clean up.
-
-```bash
-bash plugins/team-superpower/scripts/team-state.sh scan <slug>
-bash plugins/team-superpower/scripts/team-state.sh members <slug>
-```
-
-## Troubleshooting
-
-| Symptom | What it usually means | First thing to check |
-|---|---|---|
-| `BLOCKED_IDLE_implementer_owes_team-leader_reply` | Implementer tried to idle with an unanswered message from team-leader | Open the implementer's mailbox, reply or escalate |
-| `BLOCKED_IDLE_team-leader_awaiting_lead_on_spawn_or_restart` | team-leader sent SPAWN_REQUEST or RESTART_REQUEST and lead hasn't replied | Look at lead's mailbox; if dropped, re-post |
-| `BLOCKED_IDLE_team-leader_owes_implementer_escalate_reply` | An implementer sent ESCALATE that team-leader hasn't routed | Route it (tactical/cross-role/architectural) or escalate to owner |
-| `BLOCKED_IDLE_qc-engineer_awaiting_lead_ack` | qc-engineer posted QC_REWORK_NEEDED and lead hasn't replied | Lead acknowledges, files `impl:rework-*` via team-leader |
-| `BLOCKED_IDLE_phaseA_awaiting_owner_signoff` | analytics team sent HANDOVER_READY / SEC_PASSED / SEC_BLOCKED with no reply | Owner reviews and replies |
-| `BLOCKED_IDLE_orchestrator_unhandled_team-leader_request` | team-leader sent something the lead hasn't acted on | Lead acts (spawn / restart / route) |
-| `bad_prefix` on a new task | Lead created a task without the `impl:`/`review:`/`meta:`/`block:` prefix | Lead's bug — fix the task title |
-| `bad_subprefix` on `impl:*` | Missing `be-` / `fe-` / `rework-` / `contract-update-` sub-prefix | Re-emit with correct prefix |
-| `INVALID_WAVE_REFERENCE` on a new task | Wave metadata missing or not in `<plan-phase>.<wave>` / `<plan-phase>.rework` / `qc-rework` shape | Fix the wave metadata before re-creating |
-| `MISSING_STATIC_CHECKS` on task complete | `.team-superpower/static-check-<task-id>.log` missing or has a non-zero `exit=` line | Implementer re-runs lint/typecheck/format, captures log, re-commits |
-| `MISSING_REWORK_REFERENCE` on task complete | `impl:rework-*` commit body missing `Reworks: <orig-id>` line | Implementer amends the commit body and re-completes |
-| `MIGRATION_RACE` on task complete | Two migration tasks were `in_progress` simultaneously | Lead should serialize migrations |
-| `EMPTY_CONTRACT_PUBLISH` on task complete | A contract-publish task completed but no commit touched a contract file | Backend-developer didn't actually publish; investigate and re-run |
-| `ARCH_BLOCKED` or `SEC_BLOCKED` from phase A | Pre-impl gate rejected the plan | Planner addresses the report, re-emits, re-runs the gate |
-| Hook log noise | Hooks write tuning data to `.claude/hooks/log.jsonl` | Inspect; trim or refine matchers |
-
-## Emergency bypass
-
-`--dangerously-skip-permissions` will let a single task ship without the hooks
-firing. **Don't.** The hooks exist because Superpowers gates exist. Use the
-escalation template to surface the blocker properly.
-
-## Where the methodology lives
-
-The team-superpower plugin is purely the coordination layer. The actual
-development discipline (TDD, plan format, two-stage review, branch hygiene) is
-owned by the upstream [obra/superpowers](https://github.com/obra/superpowers)
-skills. If a skill's behaviour changes, the team picks it up automatically —
-agents reference skills by name, not by content.
-
-## Session checkpoint § Assumptions
-
-Every non-owner decision (tactical, cross-role with consensus, architectural
-with sign-off) is logged as one line in the session checkpoint's
-`## Assumptions` block. The qc-engineer scans this block at end-of-plan for
-contradictions with the spec / plan; contradictions surface as QC findings.
-Format:
-
-```
-- <ISO ts> <role> [class=<tactical|cross-role|architectural>]: <one-line decision> (peer: <role|none>, evidence: <link to mailbox msg | n/a>)
-```
-
-The owner sees the assumptions log at every phase boundary as part of the
-checkpoint commit.

package/plugins/team-superpower/commands/team-cleanup.md

@@ -1,70 +0,0 @@
----
-description: Inspect and clean up team-superpower team state — orphaned configs, task lists, tmux sessions left by a dead lead.
-argument-hint: [slug] | --all
----
-
-Inspect and (with owner confirmation) remove orphaned team-superpower state from `~/.claude/teams/superpower-*/` and `~/.claude/tasks/superpower-*/`. Preserves project-side artefacts (`docs/superpowers/{specs,plans,reviews}`) — only platform-side state is removed.
-
-Argument:
-
-$ARGUMENTS
-
-## What "orphaned" means
-
-A team is orphaned when:
-
-- Its team config lives at `~/.claude/teams/superpower-<slug>/` but the lead process is dead, so no Claude Code session can talk to it.
-- The agent-teams runtime can't reuse it because the lead-for-a-team is fixed for that team's lifetime (per [docs](https://code.claude.com/docs/en/agent-teams)).
-- The canonical "ask the lead to clean up" path is unavailable because there is no lead.
-
-This command is the manual fallback for that case. **If a live lead exists, do not use this command** — message the lead and ask it to "clean up the team" via the native primitive instead.
-
-## Procedure
-
-Run the helper script `${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh` to do the work. It accepts a subcommand and treats every destructive operation as opt-in (`--force`).
-
-### Step 1 — Decide scope
-
-- If `$ARGUMENTS` is empty: run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan` and show the output to the owner. Ask which slug to clean (or `--all`).
-- If `$ARGUMENTS` is `--all`: enumerate every slug from the scan and process each in turn.
-- Otherwise treat `$ARGUMENTS` as the slug.
-
-### Step 2 — Inspect
-
-For the chosen slug, run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>`. Quote the output verbatim to the owner. Pay attention to the `liveness` line:
-
-| `liveness` | What it means | What to do |
-|---|---|---|
-| `LIKELY ALIVE` | Heartbeat is < 10min old | **Stop.** Tell the owner the previous lead may still be running. Ask them to verify nothing is in flight before forcing cleanup. |
-| `stale` or `unknown` | Heartbeat old or absent | Proceed to step 3. |
-
-### Step 3 — Dry-run
-
-Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug>` (no `--force`). Exit code 1 with a "would remove" list is expected. Quote the list to the owner.
-
-If exit code is 4, there is nothing to clean — report and exit.
-
-### Step 4 — Confirm and apply
-
-Ask the owner to confirm the dry-run list. On confirmation, run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug> --force`.
-
-- Exit code 0: report success and show the appended `## Cleanup` block from the checkpoint.
-- Exit code 3 (heartbeat refusal): the owner confirmed nothing is in flight, but the heartbeat is fresh. Re-run with `--force --ignore-heartbeat` only after the owner re-confirms in writing (in the chat) that the previous lead is dead.
-
-### Step 5 — Verify
-
-Re-run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>` and confirm `team_config_state: absent` and `task_list_state: absent`.
-
-## What this command will NOT do
-
-- It will not touch any project-side files except to append a `## Cleanup` block to the checkpoint markdown.
-- It will not delete the design doc, plan, or review report — those are the durable record of the work and are kept regardless.
-- It will not run when there is a live lead. The heartbeat refusal is the safety check.
-- It will not iterate `--all` without per-slug owner confirmation when any slug shows `LIKELY ALIVE`.
-
-## When to use
-
-- After `/resume` left a team config behind that no current session can talk to.
-- After a crash or kill of the lead mid-feature.
-- Before `/team-feature` if the preflight scan there reports orphaned state.
-- Routinely after an in-flight feature is abandoned.