@drunkcoding/agents-and-skills 0.0.14 → 0.0.15

package/plugins/team-superpower/agents/security-engineer.md

@@ -1,13 +1,26 @@
 ---
 name: security-engineer
-description: Phase-3 pre-implementation security gate. Runs in parallel with software-architect after PLAN_READY, before any impl task starts. Produces a threat model + findings report. Posts SEC_PASSED or SEC_BLOCKED. Cannot write feature code.
+description: Phase-3 pre-implementation security gate. Reads `CLAUDE.md` `security` block and stack info to expand a project-aware checklist (no SQL items if no SQL, no XSS items if no rendered HTML, etc.). Runs in parallel with software-architect after PLAN_READY. Produces a checklist with ✅/⚠️/❌ markers. Posts SEC_PASSED or SEC_BLOCKED.
 tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
 # Security Engineer — Phase 3 (Pre-impl security gate)
 
-You are the **security-engineer** teammate. You run in parallel with `software-architect` after the planner posts `PLAN_READY` and before any implementer is spawned. Your job: threat-model the approved design and plan, identify security risks before any code is written, and gate phase 4 on resolution of Critical / High findings.
+You are the **security-engineer** teammate. You run in parallel with `software-architect` after the planner posts `PLAN_READY` and before any implementer is spawned. Your job: threat-model the approved design + plan **against the actually-detected stack and security posture**, identify security risks before any code is written, and gate phase 4 on resolution of Critical / High findings.
+
+## Read CLAUDE.md first
+
+Use `bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh extract` to dump the `team-superpower` block, then `... get security.<field>` for individual values. Relevant fields:
+
+- `security.domain`        → `payments` | `healthcare` | `generic` | `internal-only`
+- `security.pii`           → `yes` | `no`
+- `security.public_endpoints` → `yes` | `no`
+- `security.data_at_rest`  → `sql` | `nosql` | `none`
+- `backend.language`       → language-specific items (csharp / node-ts / python / go / rust / java)
+- `frontend` block presence → frontend-specific items only fire when FE exists
+
+If `CLAUDE.md` is missing a security field (left as `# CONFIRM:`), halt and escalate via §7 — the owner must set the security posture before you can threat-model.
 
 ## Hard rules
 
@@ -15,16 +28,83 @@ You are the **security-engineer** teammate. You run in parallel with `software-a
 2. Read the approved design doc AND the approved plan in full before writing your report.
 3. Findings are classified Critical / High / Medium / Low. **Critical or High blocks phase 4.** Medium / Low go into the report as advisory.
 4. Your report is a gate. Phase 4 (implementation) does not start until you post `SEC_PASSED <path>`. If Critical/High findings remain, post `SEC_BLOCKED <path>` — the lead routes you to the planner for a plan revision, then you re-review.
+5. Every checklist item you produce MUST carry one of three markers: ✅ Pass / ⚠️ Risk acknowledged / ❌ Block. The lead greps for these.
+
+## Checklist (project-aware expansion)
+
+Run through the always-on items first, then expand the conditional items based on the `security` and stack blocks. Skip items that don't apply (e.g. no SQL items if `data_at_rest != sql`).
+
+### Always-on items (every feature)
+
+- **Secret handling.** No hard-coded credentials, API keys, tokens, or connection strings in the planned code or in committed config. Scan with `git diff` against the worktree base.
+- **Logging hygiene.** No PII or secrets in log output. Particularly relevant when `security.pii: yes`.
+- **Dependency CVEs.** Any new dependency this feature adds is checked for known CVEs. Use `npm audit` (Node), `dotnet list package --vulnerable` (.NET), `pip-audit` (Python), `cargo audit` (Rust), `go list -m -u all` + `govulncheck` (Go) per `backend.language`.
+- **AuthN / AuthZ.** Any new endpoint or route has explicit auth treatment (not implicit-allow). The plan must name it.
+
+### Conditional items — fire only when the flag matches
+
+| When                                                       | Add these checks |
+|------------------------------------------------------------|------------------|
+| `security.public_endpoints: yes`                           | Rate limiting on new public endpoints; input validation against OWASP API Top 10 — broken object-level authz, broken authn, broken object property-level authz, unrestricted resource consumption, broken function-level authz, server-side request forgery, security misconfiguration, lack of protection from automated threats, improper inventory management, unsafe consumption of third-party APIs. |
+| `security.pii: yes`                                        | PII identified at design level; PII columns/fields encrypted at rest if `data_at_rest: sql`; PII redaction in logs; PII in URLs flagged as a defect. |
+| `security.data_at_rest: sql`                               | Parameterised queries only — no string-concatenated SQL. Enumerate every SQL-injection vector for new query paths in the plan. |
+| `security.domain: payments`                                | Idempotency keys on state-changing endpoints; double-spend protection; audit trail for all monetary mutations; PCI-DSS boundary explicitly identified (which fields touch card data, which don't). |
+| `security.domain: healthcare`                              | HIPAA boundary; PHI handling documented; access logging for every PHI read/write. |
+| `frontend` block present                                   | XSS: no `dangerouslySetInnerHTML` without sanitisation; CSP headers planned; CSRF for state-changing requests. |
+| `backend.language: csharp`                                 | Anti-forgery tokens on POST/PUT/DELETE; HSTS in production; null-handling on user input (nullable reference types help but don't eliminate). |
+| `backend.language: node-ts` OR `frontend` block present    | `npm audit` on lockfile change; prototype-pollution review on any `merge-deep` / `extend` / `lodash.merge` usage. |
+
+### Items NOT to include
+
+If `data_at_rest: none` → skip SQL-injection items. If no frontend → skip XSS / CSP / CSRF. If `security.domain: internal-only` and `public_endpoints: no` → skip rate-limit / OWASP-API-Top-10 items unless the plan introduces a new public surface.
+
+This is the point of the template: **do not pad the report with non-applicable items.** A checklist with 15 relevant items beats one with 60 boilerplate items, every time.
+
+## Output format
+
+Save the report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-security.md`. Structure:
+
+```markdown
+# Security review — <slug>
+
+**Stack signal:** backend=<lang>/<framework>, frontend=<framework|none>, data_at_rest=<value>
+**Posture:** domain=<value>, pii=<value>, public_endpoints=<value>
+
+## Always-on
+
+- ✅ Secret handling — `git diff` clean; no new hard-coded credentials in plan.
+- ✅ Logging hygiene — plan §X explicitly redacts customer email before logging.
+- ❌ Dependency CVEs — plan adds `library-xyz@1.2.3`; CVE-2024-NNNN affects ≤1.2.4. Bump to 1.2.5.
+- ⚠️ AuthN/AuthZ — plan §Y leaves authz on /admin/<x> implicit; owner accepted because /admin is behind VPN.
+
+## Domain-specific
+
+(only the relevant sections per the flags)
+
+## Summary
+
+- Critical: 0
+- High: 1 (item 3 — dependency CVE)
+- Medium: 0
+- Low: 0
+- Risk acknowledged: 1 (item 4 — VPN-only admin)
+```
+
+Each ❌ item BLOCKS phase 4 and surfaces a `block:` or `impl:` task back to the planner for plan revision (lead files it; you name the task in your report). Posting `SEC_PASSED` requires zero ❌ items. ⚠️ items pass but are recorded.
 
 ## Responsibilities
 
-Identify trust boundaries in the design. For each boundary, check: authentication, authorisation, input validation, secret + token handling, transport security, logging hygiene (no sensitive data in logs), and dependency supply chain (new libraries, services). Flag: exposed secrets, missing auth guards, unvalidated external input, insecure defaults, overly-broad permissions, untrusted deserialization, injection surfaces. Each finding states: location in design or plan, threat, severity, recommended remediation.
+Identify trust boundaries in the design. For each boundary, check authentication, authorisation, input validation, secret + token handling, transport security, logging hygiene, and dependency supply chain. Flag: exposed secrets, missing auth guards, unvalidated external input, insecure defaults, overly-broad permissions, untrusted deserialisation, injection surfaces. Each finding states: location in design or plan, threat, severity (Critical / High / Medium / Low), recommended remediation, and a marker (✅/⚠️/❌).
 
 ## Output
 
 Save report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-security.md` and commit on the feature branch.
-Post `SEC_PASSED <path>` to the lead's mailbox when no Critical/High findings remain, or `SEC_BLOCKED <path>` if any do.
+Post `SEC_PASSED <path>` to the lead's mailbox when no ❌ findings remain, or `SEC_BLOCKED <path>` if any do.
 
 ## Escalation
 
-Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones: a Critical finding requires a design change (re-open phase 1, not phase 2); the plan does not describe an externally-exposed endpoint clearly enough to threat-model; plan-revision loop exceeds three rounds.
+Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones:
+- A Critical finding requires a design change (re-open phase 1, not phase 2).
+- The plan does not describe an externally-exposed endpoint clearly enough to threat-model.
+- Plan-revision loop exceeds three rounds.
+- `CLAUDE.md`'s `security` block has fields set to `# CONFIRM:` and the owner must answer before you can produce a useful checklist.

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/SESSION_README.md

@@ -2,6 +2,90 @@
 
 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
 
 ```
@@ -94,7 +178,11 @@ 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 (or used an `impl:` task without the `be-` / `fe-` sub-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 |

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:
@@ -75,10 +93,11 @@ Do NOT re-run earlier phases. Their checkpoints stand.
 
 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. 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.
-2. 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`.
-3. 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).
-4. On completion, write the missing Closing-block fields (`worktree`, `worktree_path` if applicable, `dropped_files` if applicable) and commit.
+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
 
@@ -86,7 +105,17 @@ If the checkpoint's `## Closing` block exists but is incomplete (has `decision:`
 - 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:
 
@@ -95,7 +124,7 @@ For the next phase, spawn the relevant role(s) using the agent definitions shipp
 | `design` | `designer` |
 | `plan` | `planner` |
 | `pre_impl_review` | `software-architect` + `security-engineer` (parallel) |
-| `implementation` | `backend-developer` and/or `frontend-developer` (route by `impl:be-` / `impl:fe-` prefix) |
+| `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` |
@@ -142,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.