@drunkcoding/agents-and-skills 0.0.13 → 0.0.15

package/plugins/team-superpower/assets/CLAUDE.md.template

@@ -0,0 +1,96 @@
+# Project: <your-project-name>
+
+<!--
+  This file is the source of truth for project context. team-superpower reads
+  the structured `team-superpower` YAML block below to decide which teammates
+  to spawn and what test / build / format commands to use. The free-form prose
+  outside the block is passed verbatim to every teammate as project context.
+
+  team-superpower will NEVER overwrite this file. If it detects a missing
+  block, it writes its best guess to `docs/superpowers/stack.detected.md` for
+  you to copy/edit/paste here.
+
+  Delete this comment block before committing.
+-->
+
+<short narrative describing what the project is, who consumes it, and any cross-
+service dependencies your team should know about. Example: "This is the orders
+microservice for the storefront. APIs talk to the payments service via gRPC.
+PII goes through the redaction pipeline (see redaction-guide).">
+
+```team-superpower
+# ────────────────────────────────────────────────────────────────────────────
+# Backend
+# ────────────────────────────────────────────────────────────────────────────
+# Set `backend: none` (no further keys) if this is a frontend-only repo.
+backend:
+  language: csharp              # csharp | node-ts | python | go | rust | java
+  framework: aspnetcore         # framework name; e.g. aspnetcore | fastapi | express | nestjs | gin | axum | spring-boot
+  test_framework: xunit         # xunit | nunit | mstest | reqnroll | pytest | jest | vitest | go-testing | cargo-test | junit
+  build_command: dotnet build
+  test_command: dotnet test
+  format_command: dotnet format --verify-no-changes   # set to "none" if no style check is wired
+  migration_tool: ef-core       # ef-core | flyway | liquibase | alembic | django-migrations | prisma | typeorm | knex | none
+  package_manager: nuget        # nuget | npm | pnpm | yarn | bun | pip | poetry | pipenv | go-modules | cargo | maven | gradle
+
+# ────────────────────────────────────────────────────────────────────────────
+# Frontend
+# ────────────────────────────────────────────────────────────────────────────
+# Set `frontend: none` (no further keys) if this is a backend-only repo.
+frontend:
+  language: typescript          # typescript | javascript
+  framework: react              # react | vue | svelte | solid | angular | next | nuxt
+  bundler: vite                 # vite | webpack | rspack | next | nuxt | rollup | none
+  test_framework: vitest        # vitest | jest | none
+  e2e_framework: playwright     # playwright | cypress | none
+  ui_library: shadcn            # shadcn | mui | antd | tailwind-only | none
+  package_manager: pnpm         # npm | pnpm | yarn | bun
+  build_command: pnpm build
+  test_command: pnpm test
+
+# ────────────────────────────────────────────────────────────────────────────
+# Contracts — only relevant when both backend AND frontend are present.
+# ────────────────────────────────────────────────────────────────────────────
+contracts:
+  source_of_truth: openapi      # openapi | grpc | graphql | typescript | none
+  openapi_path: contracts/openapi.yaml
+  ts_gen_command: pnpm generate:api-types   # command that regenerates FE-consumable types from the contract
+
+# ────────────────────────────────────────────────────────────────────────────
+# CI — read by reviewer in phase 7 to gate the finish-branch decision.
+# ────────────────────────────────────────────────────────────────────────────
+ci:
+  provider: github-actions       # github-actions | azure-pipelines | gitlab-ci | circleci | none
+  workflow_path: .github/workflows/ci.yml
+  required_checks: ["build", "test", "lint"]
+  poll_timeout_minutes: 20
+
+# ────────────────────────────────────────────────────────────────────────────
+# Security — drives the security-engineer's checklist (phase 3).
+# ────────────────────────────────────────────────────────────────────────────
+security:
+  domain: payments               # payments | healthcare | generic | internal-only
+  pii: yes                       # yes | no
+  public_endpoints: yes          # yes | no
+  data_at_rest: sql              # sql | nosql | none
+
+# ────────────────────────────────────────────────────────────────────────────
+# Limits — operational tuning. Defaults are sensible; override only if needed.
+# ────────────────────────────────────────────────────────────────────────────
+limits:
+  phase_stall_minutes: 30        # within-phase stall watchdog window; two empty windows force a §7 escalation
+  max_tasks_per_implementer: 12  # planner halts and asks the owner to split the feature above this
+  max_concurrent_teammates: 5    # hard cap on parallel teammates (best-practice guidance from CLAUDE.md)
+```
+
+## Conventions
+
+<!--
+  Anything below is free-form prose. Capture local style rules, conventions
+  the architecture review or implementers should respect, and any "we don't do
+  X here" rules. Implementers will read this at task start.
+-->
+
+- (Example) File-scoped namespaces, nullable reference types on.
+- (Example) React components are function components only.
+- (Example) All API endpoints require `[Authorize]` unless explicitly marked `[AllowAnonymous]`.

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

@@ -6,7 +6,7 @@ Every owner-facing question and every "I'm blocked" peer message MUST use this e
 
 ```
 BLOCKED: <one-line question>
-Phase: <brainstorming | worktree | plan | implementation | review | finish>
+Phase: <design | plan | pre_impl_review | implementation | qa | review | finish>
 Context: <2-4 sentences — what we tried, what we considered, why we are stuck>
 Options:
   A. <option> — <trade-off>
@@ -35,13 +35,27 @@ Need from you: choose A/B/C.
 ## Worked example 2 — lead-to-owner (plan-vs-design mismatch surfaced mid-implementation)
 
 ```
-BLOCKED: implementer-1 reports that task impl:add-user-endpoint specifies POST /users, but the approved design doc says PUT /users/{id}. Which is canonical?
+BLOCKED: backend-developer reports that task impl:be-add-user-endpoint specifies POST /users, but the approved design doc says PUT /users/{id}. Which is canonical?
 Phase: implementation
-Context: The plan was approved 2026-05-12T09:14Z. Task 4 reads "POST /users → 201 Created with body". Design doc §3 (approved 2026-05-12T08:51Z) reads "idempotent PUT /users/{id}, 200 or 201". Both choices change the test the implementer writes in the RED step. We have not yet written code for this task — TDD held the line.
+Context: The plan was approved 2026-05-12T09:14Z. Task 4 reads "POST /users → 201 Created with body". Design doc §3 (approved 2026-05-12T08:51Z) reads "idempotent PUT /users/{id}, 200 or 201". Both choices change the test the backend-developer writes in the RED step. We have not yet written code for this task — TDD held the line.
 Options:
-  A. Owner confirms PUT /users/{id} is correct → planner amends task 4 → owner re-approves the plan delta → implementer proceeds.
-  B. Owner confirms POST /users is correct → designer amends the design doc → owner re-approves the design delta → implementer proceeds.
+  A. Owner confirms PUT /users/{id} is correct → planner amends task 4 → owner re-approves the plan delta → backend-developer proceeds.
+  B. Owner confirms POST /users is correct → designer amends the design doc → owner re-approves the design delta → backend-developer proceeds.
   C. Owner reopens the design question entirely (the two APIs imply different semantics).
 Recommendation: A — the design doc was approved first and the discrepancy reads as a plan-writing slip, not a design change. But this is a load-bearing decision and we won't move without your call.
 Need from you: choose A/B/C.
 ```
+
+## Worked example 3 — lead-to-owner (`FINISH_BLOCKED` option E)
+
+```
+BLOCKED: Merge of feature/user-search into main failed: push rejected because origin/main advanced. Owner picked option E (escalate) from the 5-option menu rather than retrying inline.
+Phase: finish
+Context: Reviewer attempted `git push` after a clean local merge. Push was rejected: "Updates were rejected because the remote contains work that you do not have locally." The remote moved between phase 6 and phase 7. The lead's 5-option menu was presented; owner chose E because they want to coordinate the rebase manually rather than have the team retry blind.
+Options:
+  A. Owner rebases the feature branch locally onto origin/main, signals "ready to retry"; lead instructs reviewer to retry merge (counts as 1/3 retries).
+  B. Owner pulls latest origin/main into trunk first, then signals; lead retries.
+  C. Owner switches the decision to pr_opened and merges via GitHub UI.
+Recommendation: A — the conflict surface is small and a clean rebase plus retry is the cheapest path. We won't move until you say which.
+Need from you: choose A/B/C.
+```

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

@@ -2,16 +2,103 @@
 
 This directory holds the artifacts produced by `/team-feature` runs. The team-superpower plugin seeds it on first use; afterwards, the design / plan / review / checkpoint files for each feature are written by the team and committed.
 
+## 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`, `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`. 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).
+- `security` — `domain` (`payments` / `healthcare` / `generic` / `internal-only`), `pii`, `public_endpoints`, `data_at_rest`.
+
+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 | Teammates spawned |
+|-------|-------------------|
+| `full-stack`  | designer, planner, software-architect, security-engineer, backend-developer, frontend-developer, qa-engineer, reviewer (8) |
+| `be-only`     | designer, planner, software-architect, security-engineer, backend-developer, qa-engineer, reviewer (7) — no `frontend-developer` |
+| `fe-only`     | designer, planner, software-architect, security-engineer, frontend-developer, qa-engineer, reviewer (7) — no `backend-developer` |
+
+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
+
+The numbers above (7 or 8) are the **lifetime** team size, not the parallelism. Roles are phase-gated: only the teammates needed for the current phase are alive at any moment. The maximum concurrency is **2 teammates in parallel**:
+
+| Phase | Concurrent teammates |
+|-------|----------------------|
+| 1 design        | 1 (designer) |
+| 2 plan          | 1 (planner) |
+| 3 pre-impl gate | 2 (software-architect + security-engineer, parallel) |
+| 4 implementation | 1 (`be-only` or `fe-only`) or 2 (`full-stack`, after `CONTRACT_PUBLISHED`) |
+| 5 QA            | 1 (qa-engineer) |
+| 6 review        | 1 (reviewer) |
+| 7 finish        | 1 (reviewer, hat 2 — reused) |
+
+This matches the Claude Code agent-team best practice of "3–5 teammates in parallel, 5–6 tasks each". The lead caps concurrency at 5 (configurable via `limits.max_concurrent_teammates` in CLAUDE.md) and refuses to start a phase that would exceed it. The planner caps tasks per implementer at 12 (configurable via `limits.max_tasks_per_implementer`) and asks the owner to split the feature if a plan would exceed it.
+
+If the 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. This is the within-phase stall watchdog — heartbeat-at-phase-boundaries alone doesn't catch silent hangs.
+
+#### 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 inside it. The signal `WORKTREE_READY <path> <branch> <origin>` carries `origin: reused` and the checkpoint records `**Worktree origin:** reused`.
+
+Detection is automatic — no config needed:
+
+| Where `/team-feature` is launched | Branch                                                    | Behavior |
+|---|---|---|
+| Linked worktree                   | feature branch (anything not protected)                   | **Reuse** the current worktree. |
+| Linked worktree                   | `main`, `master`, `develop`, `dev`, `release/*`, `releases/*` | **Halt.** Switch to a feature branch (`git checkout -b feature/<slug>`) 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 — Step D.5 auto-removal after merge **does not run** when origin is `reused`; the Closing block records `worktree: removal-skipped:reused-existing-worktree` and the worktree stays on disk. Created worktrees are removed after a successful merge as before.
+
+The clean-test-baseline check still runs in both modes. If you reused a worktree with uncommitted changes that break the baseline, the planner halts with a §7 escalation asking you to stash or commit first.
+
+### 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-4 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>`: BE files it (often after FE posts `CONTRACT_DRIFT_DETECTED`), updates the contract, runs `ts_gen_command`, posts `CONTRACT_UPDATED`, and FE resumes after re-pulling the contract hash.
+
+### 5. CI gate before finish
+
+The reviewer pushes the branch in phase 7, 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. Every CI variant counts as the **same** finish-branch touchpoint — the 3-touchpoint cap holds.
+
+### 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 4.
+
+### 7. Superpowers version pinning
+
+The lead reads the installed Superpowers version in phase 0 and writes it to the checkpoint frontmatter (`superpowers_version`). On `/team-feature-resume`, the lead checks whether the installed version still matches. If not, you see a 3-option menu (continue anyway / roll back Superpowers / discard this feature). The pin is informational + safety — never a hard block; you can always continue.
+
 ## Layout
 
 ```
 docs/superpowers/
 ├── ESCALATION.md                          # template — referenced by every teammate
 ├── README.md                              # this file
-├── specs/    YYYY-MM-DD-<slug>-design.md  # written by designer (phase 1)
-├── plans/    YYYY-MM-DD-<slug>-plan.md    # written by planner (phase 3)
-├── reviews/  YYYY-MM-DD-<slug>-review.md  # written by reviewer (phase 5)
-└── sessions/ YYYY-MM-DD-<slug>.md         # checkpoint, updated by lead each phase
+├── specs/    YYYY-MM-DD-<slug>-design.md     # written by designer (phase 1)
+├── plans/    YYYY-MM-DD-<slug>-plan.md       # written by planner (phase 2)
+├── reviews/  YYYY-MM-DD-<slug>-arch.md       # written by software-architect (phase 3)
+├── reviews/  YYYY-MM-DD-<slug>-security.md   # written by security-engineer (phase 3)
+├── reviews/  YYYY-MM-DD-<slug>-qa.md         # written by qa-engineer (phase 5)
+├── reviews/  YYYY-MM-DD-<slug>-review.md     # written by reviewer (phase 6)
+└── sessions/ YYYY-MM-DD-<slug>.md            # checkpoint, updated by lead each phase
 ```
 
 ## How to launch
@@ -22,12 +109,11 @@ docs/superpowers/
 
 The lead handles prechecks, spawns the team, and drives the Superpowers skill chain.
 
-## Owner touchpoints (max 4 per feature)
+## Owner touchpoints (max 3 per feature)
 
-1. **Brainstorming clarifying questions.** The designer batches them per phase; you answer in plain English.
-2. **Design sign-off.** The brainstorming skill's built-in approval step.
-3. **Plan approval.** Before any implementer task starts.
-4. **Finish-branch decision.** Merge / PR / keep / discard at phase 6.
+1. **Design sign-off** (after phase 1). The brainstorming skill's built-in approval step. Designer batches any clarifying questions before this point so they piggy-back the same touchpoint.
+2. **Plan approval** (after phase 2). Before the pre-impl arch+security gate runs.
+3. **Finish-branch decision** (in phase 7). Merge / PR / keep / discard.
 
 Anything else that reaches you must use the §7 escalation template in `ESCALATION.md`. Refuse questions that don't follow it — that's the contract.
 
@@ -56,6 +142,20 @@ The lead reads the checkpoint, respawns the right teammates, and continues from
 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
+
+The auto-cleanup writes a `## Closing` block with these fields:
+
+- `finished at: <ISO datetime>` — when cleanup finished.
+- `decision: <merged|pr_opened|kept|discarded>` — the finish-branch decision.
+- `cleanup: complete` — confirms all cleanup steps ran (or were intentionally skipped).
+- `worktree: <state>` — outcome of Step D.5. One of: `removed`, `already-absent`, `removal-skipped:<reason>`, `removed (after manual fix)`, `force-removed`, `kept-by-owner`, `escalated`.
+- `worktree_path: <path>` — present only when the worktree directory still exists on disk (states `kept-by-owner`, `escalated`, or `removal-skipped` where the path exists).
+- `merge_retries: K` — present only when K > 0; how many retries the 5-option menu ran before reaching `FINISH_DONE`.
+- `dropped_files: [<path>, ...]` — present only when `worktree: force-removed`; the file list snapshot from before the forced removal.
+
+`removal-skipped` reasons: `not-merged-decision` (decision was pr_opened/kept/discarded) | `team-cleanup-incomplete` (Step C/D left platform state present) | `no-worktree-recorded` (checkpoint had no `**Worktree:**` line).
 - **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 — if it was touched in the last 10 minutes, cleanup refuses unless you explicitly confirm with `--ignore-heartbeat`.
 
 Project-side artefacts (`specs/`, `plans/`, `reviews/`, and the checkpoint itself) are **always preserved**. Only platform-side state under `~/.claude/teams/superpower-<slug>/` and `~/.claude/tasks/superpower-<slug>/` is removed, plus any matching tmux session.
@@ -78,14 +178,22 @@ bash plugins/team-superpower/scripts/team-state.sh scan <slug>
 | Symptom | What it usually means | First thing to check |
 |---|---|---|
 | `BLOCKED_IDLE: N unanswered peer messages` from a teammate | A peer asked the teammate something and they tried to idle without replying | Open the teammate's mailbox, reply or escalate |
-| `BAD_PREFIX` on a new task | The lead created a task without the `impl:`/`review:`/`meta:`/`block:` prefix | Lead's bug — fix the task title |
+| `BAD_PREFIX` on a new task | The lead created a task without the `impl:`/`review:`/`meta:`/`block:` prefix (or used an `impl:` task without one of the v2 sub-prefixes: `be-`, `fe-`, `qa-fix-be-`, `qa-fix-fe-`, `review-fix-be-`, `review-fix-fe-`, `contract-update-`, `be-migration-`, `be-contract-publish-`) | Lead's bug — fix the task title |
+| `SHAPE_REJECTED: shape is 'be-only'` (or `fe-only`) | A task was created with a prefix the shape doesn't allow (e.g. `impl:fe-*` in a BE-only repo) | Planner or lead bug — re-check `docs/superpowers/sessions/<slug>.shape` and re-emit |
+| `MIGRATION_RACE` on task complete | Two `impl:be-migration-*` tasks were `in_progress` simultaneously | Lead should serialize migrations; backend-developer should idle if another migration is in flight |
+| `EMPTY_CONTRACT_PUBLISH` on task complete | A `impl:be-contract-publish-*` task completed but no commit touched a contract file | Backend-developer didn't actually publish; investigate and re-run the task |
+| `superpowers_version` mismatch on resume | Superpowers was upgraded between feature start and resume | Pick continue / rollback / discard from the 3-option menu |
 | `NO_PLAN_APPROVAL` blocking a task complete | An `impl:` task is missing `metadata.plan_approved_at` | Lead forgot to stamp tasks after owner plan-approval; backfill from the checkpoint timestamp |
+| `ARCH_BLOCKED` or `SEC_BLOCKED` from phase 3 | Pre-impl gate rejected the plan; arch/security findings need plan revisions | Planner addresses the report, re-emits the plan, re-runs the gate before phase 4 starts |
+| `QA_BLOCKED` from phase 5 | Acceptance criteria or regression coverage missing post-implementation | Lead files `impl:qa-fix-be-` / `impl:qa-fix-fe-` tasks; loop back to phase 4 |
+| Backend developer and frontend developer want the same file | Plan didn't capture file-scope metadata for the overlapping tasks, or the task was mis-prefixed | Serialize by holding one; planner should re-route by `impl:be-` / `impl:fe-` prefix and backfill file-scope |
 | `BAD_ESCALATION: missing field(s) ...` | A teammate posted a blocker without all five template fields | Rewrite using the full template in `ESCALATION.md` |
 | Lead refuses to ping the owner | The teammate's request to escalate didn't use the §7 template | Same as above |
 | Teammate ran a non-Superpowers approximation of a skill | Teammate paraphrased the SKILL.md instead of following it | The agent's system prompt requires the canonical skill — re-spawn and remind it explicitly |
-| Two implementers want the same file | Plan didn't capture file-scope metadata for the overlapping tasks | Serialize by holding one; planner should backfill file-scope on the plan |
 | `REFUSED: heartbeat ... is Ns old` from cleanup | Heartbeat is fresh — cleanup script thinks a lead is alive | Verify nothing's running; if certain the previous lead is dead, run with `--ignore-heartbeat` |
 | `/team-feature` halts at preflight | Stale team config left over from a previous run | Run `/team-cleanup <slug>` (or resume via `/team-feature-resume`) |
+| `FINISH_BLOCKED <reason>` from the reviewer | The merge step of `finishing-a-development-branch` failed (`conflict` / `non-ff` / `dirty-worktree` / `push-rejected`) | The lead surfaces a 5-option menu (retry / pr_opened / kept / discarded / escalate). Pick one; merge retries cap at 3. |
+| `git worktree remove` failed during cleanup | Step D.5 hit an uncommitted/untracked file or a locked worktree | Pick from the 4-option menu (show files + retry / force-remove with confirmation / keep / escalate). Force-remove discards uncommitted work — only confirm if you've checked the file list. |
 | Auto-cleanup skipped after FINISH_DONE | One of Step A's preconditions failed (missing commits, in-progress tasks, etc.) | Read the lead's halt reason; once resolved, run `/team-cleanup <slug>` |
 | Hook log noise | Hooks write tuning data to `.claude/hooks/log.jsonl` | Inspect the file; trim or refine matchers if a hook is over-triggering |
 

package/plugins/team-superpower/commands/team-feature-resume.md

@@ -28,6 +28,24 @@ Same prechecks as `/team-feature`:
 
 Halt on any failure.
 
+### Step 2.5 — Superpowers version-pin check
+
+Read the checkpoint frontmatter (the YAML block between `---` markers at the top of the file). Extract `superpowers_version`. Read the currently-installed Superpowers version (`claude plugin list --json` → grep for `superpowers`). Compare:
+
+- **Versions match** → proceed.
+- **Versions differ** → halt and surface this 3-option menu to the owner:
+
+  > **Superpowers version drifted** since this feature started:
+  > - pinned in checkpoint: `<pinned>`
+  > - currently installed: `<current>`
+  >
+  > Skill semantics may have shifted. Pick one:
+  > - **A. Continue anyway** — accept the risk; semantics may differ mid-feature.
+  > - **B. Roll back Superpowers** — owner runs `/plugin install superpowers@<pinned>` and re-runs `/team-feature-resume`. (Lead halts; cannot install plugins itself.)
+  > - **C. Discard this feature** — halt resume; the owner manually cleans state via `/team-cleanup <slug>` and starts fresh.
+
+  This is **not** counted as a touchpoint because it only happens on resume after a rare Superpowers update. On choice A, log `superpowers_pin_overridden: <pinned> → <current>` to the resume-log block; on choice B halt without changes; on choice C halt and instruct the owner to `/team-cleanup`.
+
 ### Step 3 — Preflight scan
 
 Run:
@@ -52,9 +70,34 @@ After any cleanup, re-run the scan and confirm `team_config_state: absent` befor
 The next pending phase is the first unchecked box in the checkpoint's `## Phases` section. Open escalations in the checkpoint take precedence — resolve them before resuming.
 
 Read all the artefacts the next phase depends on:
-- If next phase is `worktree` or later: design doc (path is in the checkpoint).
-- If next phase is `implementation` or later: plan + `plan_approved_at` timestamp.
-- If next phase is `finish`: review report.
+- If next phase is `plan` or later: design doc (path is in the checkpoint).
+- If next phase is `pre_impl_review` or later: plan + `plan_approved_at` timestamp.
+- If next phase is `implementation` or later: ARCH + SEC reports (both must be `*_PASSED`).
+- If next phase is `qa` or later: implementation commits on the worktree branch.
+- If next phase is `review` or later: QA report (`QA_PASSED`).
+- If next phase is `finish`: code-review report (`REVIEW_PASSED`).
+
+### Step 4.a — Mid-phase 7 resume (merge_blocked)
+
+If the checkpoint's `## Phases` block shows `- [ ] finish (blocked: <reason>, merge_retries: K/3)`, the previous lead crashed inside phase-7 merge-failure handling. Resume protocol:
+
+1. Read `<reason>` and `K` from the checkpoint line.
+2. Re-spawn the reviewer (Hat 2 only; reviewer is reused).
+3. Re-present the 5-option menu from `/team-feature` § Phase 7 merge-failure handling, with option A dropped if `K == 3`.
+4. The owner's choice is translated and reviewer continues per the same translation table.
+5. On the next `FINISH_DONE`, normal auto-cleanup runs (including Step D.5 if decision is `merged`).
+
+Do NOT re-run earlier phases. Their checkpoints stand.
+
+### Step 4.b — Mid-Step-D.5 resume (worktree removal in flight)
+
+If the checkpoint's `## Closing` block exists but is incomplete (has `decision:` and `cleanup: complete` but is missing the `worktree:` line) AND the recorded decision is `merged`, the previous lead crashed inside Step D.5. Resume protocol:
+
+1. Read `**Worktree origin:**` from the checkpoint. If it is `reused`, Step D.5 should never have run — abort the mid-Step-D.5 path: append `worktree: removal-skipped:reused-existing-worktree` to the Closing block, commit, and exit normally. The owner's pre-existing worktree stays on disk. Skip to Step 5 of the resume protocol only if there is still feature work to resume; otherwise the resume terminates here.
+2. Verify Step A–D conditions still hold by running `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>` — all states must be `absent`. If anything is `present`, halt and instruct the owner to run `/team-cleanup <slug>` before resuming.
+3. Re-run Step D.5 from the top: read `**Worktree:**`, `cd` to repo root, check `git worktree list --porcelain`, attempt non-forced remove. The procedure is idempotent — if the worktree was already removed in the prior session it'll be recorded as `already-absent`.
+4. On remove failure, re-enter the 4-option remove-failure menu fresh (no carry-over retry count — the prior session's count was not persisted because Step D.5 retries are per-session, not per-run; this is intentional, the owner sees a fresh menu).
+5. On completion, write the missing Closing-block fields (`worktree`, `worktree_path` if applicable, `dropped_files` if applicable) and commit.
 
 ### Step 5 — Reconstruct context
 
@@ -62,9 +105,30 @@ Read all the artefacts the next phase depends on:
 - Recreate the team with the same name (`superpower-<slug>`).
 - Touch `docs/superpowers/sessions/<slug>.heartbeat` and update it at every phase boundary (same protocol as `/team-feature`).
 
-### Step 6 — Respawn only the teammates needed
+### Step 6 — Re-read the shape marker
+
+Read `docs/superpowers/sessions/<slug>.shape` and `stack_shape` from the checkpoint frontmatter. They must match — if they disagree, halt and escalate (one was hand-edited). The shape determines which implementer to respawn:
+
+- `full-stack` → both `backend-developer` and `frontend-developer` are eligible to respawn.
+- `be-only` → only `backend-developer`. NEVER respawn `frontend-developer` for a `be-only` feature.
+- `fe-only` → only `frontend-developer`. NEVER respawn `backend-developer`.
+
+If the marker file is missing, re-derive shape from `CLAUDE.md` via `bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh shape CLAUDE.md` and write the marker file before continuing.
+
+### Step 6 (cont.) — Respawn only the teammates needed
+
+For the next phase, spawn the relevant role(s) using the agent definitions shipped with this plugin. Do **not** respawn teammates whose phase is complete unless that phase needs them again later (e.g. reviewer is reused in phase 7 for finish; planner is re-spawned if phase 3 returned `ARCH_BLOCKED` / `SEC_BLOCKED` and the plan needs revision; backend-developer / frontend-developer are re-spawned for `impl:qa-fix-*` or `impl:review-fix-*` tasks). Phase-to-role map:
 
-For the next phase, spawn the relevant role(s) using the agent definitions shipped with this plugin. Do **not** respawn teammates whose phase is complete unless that phase needs them again later (e.g. reviewer is reused in phase 6).
+| Next phase | Spawn |
+|---|---|
+| `design` | `designer` |
+| `plan` | `planner` |
+| `pre_impl_review` | `software-architect` + `security-engineer` (parallel) |
+| `implementation` | `backend-developer` and/or `frontend-developer`, **filtered by stack_shape** (be-only ⇒ BE only; fe-only ⇒ FE only; full-stack ⇒ both, route by prefix) |
+| `qa` | `qa-engineer` |
+| `review` | `reviewer` |
+| `finish` | `reviewer` |
+| `finish (blocked: ...)` | `reviewer` (Hat 2) — same reviewer instance; re-present the 5-option menu, honour the persisted `merge_retries` count |
 
 Hand each respawned teammate:
 - the slug
@@ -94,7 +158,7 @@ Append to the checkpoint (atomic write — tmp + rename) and commit:
 ### Step 9 — Resume the phase chain
 
 Continue per the same rules as `/team-feature`:
-- four allowed owner touchpoints, nothing else without §7 template
+- three allowed owner touchpoints (design sign-off, plan approval, finish-branch decision — `FINISH_BLOCKED` follow-up menus count as the same finish-branch touchpoint continued), nothing else without §7 template
 - checkpoint after every phase boundary, atomic writes
 - heartbeat touched at every phase boundary
 - automatic cleanup after `FINISH_DONE`
@@ -107,5 +171,7 @@ Continue per the same rules as `/team-feature`:
 - **Never** skip Step 3 preflight. Stale team configs cause runtime errors and silently re-use the wrong session IDs.
 - **Never** force-cleanup state with a fresh heartbeat unless the owner has confirmed in writing the previous lead is dead.
 - **Never** skip the resume-log commit. It is the audit trail that proves the resume happened.
+- **Never** respawn an implementer for a shape that excludes it (`frontend-developer` in `be-only`, `backend-developer` in `fe-only`). The hooks will reject the implementer's task creations anyway, but spawning is your decision and you do not bypass the shape.
+- **Never** silently ignore a `superpowers_version` mismatch. Always surface the 3-option menu at Step 2.5.
 
 If anything in the checkpoint looks tampered with or inconsistent (e.g. plan marked approved but no plan file exists, completed task with missing commits), halt and escalate to the owner with the §7 template. Do not paper over.