@drunkcoding/agents-and-skills 0.0.13 → 0.0.15

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

@@ -1,5 +1,5 @@
 ---
-description: Launch a Superpowers-compliant agent team to deliver a feature end-to-end with at most 4 owner touchpoints, with automatic team cleanup after the finish phase.
+description: Launch a Superpowers-compliant agent team to deliver a feature end-to-end with at most 3 owner touchpoints, with automatic team cleanup after the finish phase.
 argument-hint: <one-line feature idea>
 ---
 
@@ -11,17 +11,96 @@ $ARGUMENTS
 
 ## Your job
 
-You are a **conductor**, not an implementer. Spawn teammates and coordinate them through the canonical Superpowers skill chain. Do not run skills yourself — delegate every skill to the correct teammate. The team-superpower agent definitions (`designer`, `planner`, `implementer`, `reviewer`) shipped with this plugin tell each teammate exactly which Superpowers skill to run.
+You are a **conductor**, not an implementer. Spawn teammates and coordinate them through the canonical Superpowers skill chain. Do not run skills yourself — delegate every skill to the correct teammate. The team-superpower agent definitions (`designer`, `planner`, `software-architect`, `security-engineer`, `backend-developer`, `frontend-developer`, `qa-engineer`, `reviewer`) shipped with this plugin tell each teammate exactly which Superpowers skill to run.
 
 ## Required prechecks (run these first, in order)
 
-1. Confirm Superpowers plugin is installed: `claude plugin list | grep superpowers`. If missing, **halt** and instruct the owner: `/plugin install superpowers@claude-plugins-official`.
+1. Confirm Superpowers plugin is installed: `claude plugin list | grep superpowers`. If missing, **halt** and instruct the owner: `/plugin install superpowers@claude-plugins-official`. Capture the version string from `claude plugin list --json` (e.g. `5.0.7`) — you'll write it to the checkpoint in phase 0 step 5 below.
 2. Confirm Claude Code version is `2.1.32` or later: `claude --version`. If older, halt.
 3. Confirm `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set in the environment. If not, halt and instruct the owner to add it to `~/.claude/settings.json` under `env`.
 4. Generate a kebab-case `<slug>` from the owner's request. Use it in every artifact filename for the rest of the run. The team you create MUST be named exactly `superpower-<slug>` — every cleanup and resume primitive depends on that convention.
 5. Create directories if missing: `docs/superpowers/{sessions,specs,plans,reviews}`.
 6. Seed `docs/superpowers/ESCALATION.md` from `${CLAUDE_PLUGIN_ROOT}/assets/ESCALATION.md` if it does not already exist. Seed `docs/superpowers/README.md` from `${CLAUDE_PLUGIN_ROOT}/assets/SESSION_README.md` if missing. Commit any seeded files.
 
+## Phase 0 — Stack detection, version pinning, shape decision
+
+This phase runs **after** preflight clears (see the next section) and **before** spawning any teammate. It decides which teammates to spawn and pins the Superpowers version so a mid-feature skill update can't corrupt recovery.
+
+### 0.1 — Read CLAUDE.md, or detect
+
+1. Check whether `CLAUDE.md` exists at the repo root AND contains a fenced `team-superpower` block:
+   ```bash
+   bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh extract CLAUDE.md
+   ```
+   - Exit 0: a block was extracted. Parse it. Skip to 0.2.
+   - Exit 1 (file missing or no block): run detection.
+
+2. Run detection:
+   ```bash
+   bash ${CLAUDE_PLUGIN_ROOT}/scripts/detect-stack.sh "$PWD" > /tmp/team-superpower-detected.yaml
+   ```
+   - Exit 0 (confident): write the detected YAML (plus a one-line header) to `docs/superpowers/stack.detected.md` and commit. Halt with this message to the owner (via §7 escalation): "I detected this stack — `docs/superpowers/stack.detected.md`. Review the `# CONFIRM:` lines, paste the corrected block into a `team-superpower` fenced section of your CLAUDE.md (or create CLAUDE.md from `${CLAUDE_PLUGIN_ROOT}/assets/CLAUDE.md.template`), then re-run `/team-feature`." **Do NOT auto-edit CLAUDE.md — the spec forbids it.**
+   - Exit 1 (no signal): halt. Escalate to the owner: "No backend or frontend signal found in the repo. Create a CLAUDE.md from `${CLAUDE_PLUGIN_ROOT}/assets/CLAUDE.md.template` and re-run."
+   - Exit 2 (ambiguous): write the detected YAML to `docs/superpowers/stack.detected.md` with both candidate BE languages marked; halt and escalate so the owner picks one.
+
+### 0.2 — Determine stack shape
+
+Use the parser:
+
+```bash
+shape="$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh shape CLAUDE.md)"
+```
+
+`$shape` is one of `full-stack` | `be-only` | `fe-only` | `none`. If `none` (the block has `backend: none` AND `frontend: none`), halt and escalate — that combination is non-sensical.
+
+### 0.3 — Cross-validate: claimed stack vs. filesystem
+
+For every claimed component, verify at least one corresponding source file exists. Example checks:
+
+- `backend.language: csharp` → at least one `*.csproj` or `*.sln` exists.
+- `backend.language: node-ts` → `package.json` exists and declares a server dep (`express`, `fastify`, `koa`, `@nestjs/core`, etc.).
+- `frontend.framework: react` → `package.json` declares `react`.
+- `contracts.source_of_truth: openapi` → an OpenAPI file exists at `contracts.openapi_path` if specified.
+
+If any claimed component has no file evidence, halt and escalate. CLAUDE.md is the contract, but a contract that contradicts the filesystem is a bug to flag, not a configuration to act on.
+
+### 0.4 — Write the shape marker
+
+Write the resolved shape to a marker file the hooks read:
+
+```bash
+mkdir -p docs/superpowers/sessions
+echo "$shape" > docs/superpowers/sessions/<slug>.shape
+git add docs/superpowers/sessions/<slug>.shape
+```
+
+The `TaskCreated` hook reads this marker to enforce shape-appropriate `impl:` sub-prefixes.
+
+### 0.5 — Decide team composition (shape-adaptive spawn)
+
+| Shape         | Teammates to spawn |
+|---------------|--------------------|
+| `full-stack`  | designer, planner, software-architect, security-engineer, backend-developer, frontend-developer, qa-engineer, reviewer (**8 total**) |
+| `be-only`     | designer, planner, software-architect, security-engineer, backend-developer, qa-engineer, reviewer (**7 total**) |
+| `fe-only`     | designer, planner, software-architect, security-engineer, frontend-developer, qa-engineer, reviewer (**7 total**) |
+
+`software-architect`, `security-engineer`, `qa-engineer`, and `reviewer` are stack-agnostic and ALWAYS spawn. Designer, planner, and the implementers adapt.
+
+Spawning happens at phase boundaries (you don't spawn implementers until phase 4 starts; you don't spawn the reviewer until phase 6) — this section just decides which teammates the team will EVER spawn for this feature. Record the list in the checkpoint.
+
+### 0.6 — Pin the Superpowers version
+
+Read the installed Superpowers version (from precheck step 1) and write it to the checkpoint frontmatter. This pins the skill-set for this feature. `/team-feature-resume` reads it back and refuses to continue if the installed version has drifted.
+
+The frontmatter format is in the **Checkpointing** section below; the relevant added fields are:
+
+```yaml
+superpowers_version: <e.g. 5.0.7>
+plugin_version: <team-superpower plugin version>
+claude_code_version: <e.g. 2.1.32>
+stack_shape: full-stack | be-only | fe-only
+```
+
 ## Preflight — detect stale or orphaned state
 
 Before writing any checkpoint or spawning any teammate, run the helper:
@@ -49,43 +128,155 @@ Same-session check: if the current Claude Code session already manages an agent
 
 ## Initial checkpoint and heartbeat
 
-After preflight clears:
+After preflight clears AND phase 0 has decided the shape:
 
-1. Write the initial checkpoint `docs/superpowers/sessions/YYYY-MM-DD-<slug>.md` per the format in the **Checkpointing** section and commit it.
+1. Write the initial checkpoint `docs/superpowers/sessions/YYYY-MM-DD-<slug>.md` per the format in the **Checkpointing** section — including the v2 frontmatter fields (`superpowers_version`, `plugin_version`, `claude_code_version`, `stack_shape`) — and commit it.
 2. `touch docs/superpowers/sessions/<slug>.heartbeat` and commit (or leave uncommitted — the file is intentionally ephemeral; either is fine). **Touch this heartbeat at every phase boundary** and any time you remain active for more than ~10 minutes inside a phase. The cleanup script uses its mtime to decide whether a future session is allowed to wipe state.
-3. Write checkpoint updates atomically: write to `<file>.tmp` then `mv -f <file>.tmp <file>`. Half-written checkpoints corrupt recovery.
+3. Ensure `docs/superpowers/sessions/<slug>.shape` was written in phase 0.4 and is committed.
+4. Write checkpoint updates atomically: write to `<file>.tmp` then `mv -f <file>.tmp <file>`. Half-written checkpoints corrupt recovery.
+
+## Spawn prompt template (use verbatim — do NOT improvise per role)
+
+Every teammate spawn MUST hand over the same minimum context. A teammate inherits project context (`CLAUDE.md`, MCP servers, skills) automatically but does NOT inherit your conversation history — anything implicit on your side is invisible on theirs. Use this template:
+
+```
+You are the <role> teammate for feature `<slug>`.
+
+Stack shape: <full-stack | be-only | fe-only>   (read docs/superpowers/sessions/<slug>.shape if you need to confirm)
+Worktree:    <absolute path>                    (planner records this in WORKTREE_READY)
+Resume:      <yes | no>                         (yes when spawned by /team-feature-resume; pick up at the next pending task)
+
+Read first:
+  - CLAUDE.md (free-form prose AND the `team-superpower` block)
+  - Your role brief: <relative path to plugins/team-superpower/agents/<role>.md>
+  - <role-relevant artefact paths — list them all; e.g. design doc, plan, ARCH/SEC reports, QA report>
+
+Open escalations:
+  <one-line summary per open escalation in the checkpoint, or "(none)">
+
+Your task: <one sentence describing the specific phase work the role is being spawned for>
+Mailbox signal expected back: <e.g. DESIGN_APPROVED <path>, PLAN_READY <path>, ARCH_PASSED <path>, BE_DONE <task-id>, etc.>
+```
+
+Fill every field. If a field is genuinely N/A for a role (e.g. there is no QA report when spawning the designer), write `n/a` rather than omitting the line — the template's stability is what keeps respawns deterministic.
 
 ## Phase chain (strict order — no skipping, no inlining)
 
-1. **Brainstorming (designer).** Spawn the `designer` teammate. Hand it `<slug>` and the owner's request. Wait for `DESIGN_APPROVED <path>` in your mailbox. If the designer asks a clarifying question, answer from project context if unambiguous; otherwise batch with any open questions and use the §7 escalation template to the owner. Checkpoint: `phase: brainstorming, status: complete`. Touch heartbeat.
-2. **Worktree + plan (planner).** Spawn the `planner` teammate. Hand it `<slug>` and the design doc path. Wait for `WORKTREE_READY` then `PLAN_READY <path>`. Route the plan to the owner for approval (third owner touchpoint). On approval, stamp `plan_approved_at: <ISO datetime>` into the metadata of every `impl:` task you will create — the `TaskCompleted` hook checks for it. Checkpoint: `phase: plan, status: approved`. Touch heartbeat.
-3. **Implementation (implementers, 1–3 in parallel).** Read the approved plan. Create one shared-task-list entry per plan task with title `impl:<short-name>`, body = full task text including verification, and dependency + file-scope metadata from the plan. Spawn one `implementer` teammate. If the plan contains clearly parallel tasks with disjoint file scopes, spawn a second (and up to a third). Implementers self-claim. **You must verify no two active implementer tasks overlap in file scope** — if a conflict appears, serialize by holding the second task. Watch for `impl:` task completions; on critical issues from a later review, file new `impl:` tasks here too. Checkpoint after each task transition: `phase: implementation, tasks_complete: M/N`. Touch heartbeat at every transition.
-4. **Review (reviewer).** Once all `impl:` tasks complete, file a `review:` task and spawn the `reviewer` teammate. Wait for `REVIEW_PASSED <path>`. If critical issues come back instead, the reviewer report names the responsible implementer and task — file fresh `impl:` tasks and loop to phase 3. Checkpoint: `phase: review, status: pass | critical_issues_returned`. Touch heartbeat.
-5. **Finish (reviewer).** Same reviewer runs `finishing-a-development-branch`. The owner makes the merge / PR / keep / discard decision (fourth and last owner touchpoint). On `FINISH_DONE <decision> <ref>`, checkpoint: `phase: finish, status: <merged|pr_opened|kept|discarded>`. Touch heartbeat.
+1. **Design (designer).** Spawn the `designer` teammate. Hand it `<slug>` and the owner's request. Wait for `DESIGN_APPROVED <path>` in your mailbox. If the designer asks a clarifying question, answer from project context if unambiguous; otherwise batch with any open questions and use the §7 escalation template to the owner. Checkpoint: `phase: design, status: complete`. Touch heartbeat.
+
+2. **Plan (planner).** Spawn the `planner` teammate. Hand it `<slug>` and the design doc path. Wait for `WORKTREE_READY <path> <branch> <origin>` (`<origin>` ∈ {`reused`, `created`} — if the planner posts the legacy 2-arg form, treat as `created` for backward compatibility) then `PLAN_READY <path>`. Record both `**Worktree:** <path>` and `**Worktree origin:** <origin>` in the checkpoint. Route the plan to the owner for approval (second owner touchpoint). On approval, stamp `plan_approved_at: <ISO datetime>` into the metadata of every `impl:` task you will create — the `TaskCompleted` hook checks for it. Checkpoint: `phase: plan, status: approved`. Touch heartbeat.
+
+3. **Pre-impl review gate (software-architect + security-engineer, parallel).** Spawn both. Hand each the design doc path AND the plan path. Wait for `ARCH_PASSED <path>` AND `SEC_PASSED <path>`. If either posts `ARCH_BLOCKED` / `SEC_BLOCKED`, route the findings to `planner` for a plan revision, then re-route to whichever gate is still blocking. Cap at three plan-revision rounds — escalate to owner via §7 if it does not converge. Checkpoint: `phase: pre_impl_review, status: passed | blocked`. Touch heartbeat.
+
+4. **Implementation (shape-adaptive, parallel where allowed).** Read the approved plan. Create one shared-task-list entry per plan task with the planner's assigned title (`impl:be-*`, `impl:fe-*`, `impl:be-migration-*`, `impl:be-contract-publish-*`), body = full task text including verification, and `depends_on` + `files` + `tests` + `estimated_minutes` + `plan_approved_at` metadata from the plan.
+
+   **Spawn rule (shape-adaptive):**
+   - `full-stack`: spawn one `backend-developer` AND one `frontend-developer`.
+   - `be-only`: spawn one `backend-developer` only. Do NOT spawn `frontend-developer`.
+   - `fe-only`: spawn one `frontend-developer` only. Do NOT spawn `backend-developer`.
+
+   **Contract publish (full-stack only).** If the planner emitted `impl:be-contract-publish-<slug>` as the first task, the backend-developer claims it first. Do NOT release any `impl:fe-*` task to the frontend-developer until you see `CONTRACT_PUBLISHED <task-id>` in your mailbox. The plan tasks already encode `depends_on: [impl:be-contract-publish-<slug>]` on every FE task, but you enforce the gate at the assignment level too.
+
+   **Mid-implementation contract drift.** If you receive `CONTRACT_DRIFT_DETECTED` from frontend-developer, or backend-developer files an `impl:contract-update-*` task on its own, pause all `impl:fe-*` in-flight work (post a "pause" message to frontend-developer's mailbox; it will idle on its current task). Wait for `CONTRACT_UPDATED <task-id>` from backend-developer, then unpause FE. Frontend-developer re-pulls the contract hash on resume.
+
+   **Migration serialization.** `impl:be-migration-*` tasks must run one at a time. The planner chains them via `depends_on`, the `TaskCompleted` hook is a backstop with `MIGRATION_RACE`, and you enforce it at assignment: do not release a second migration task while one is `in_progress`.
+
+   **File-scope conflict check.** Verify no two active implementer tasks overlap in file scope — if a conflict appears, serialize by holding the second task. Watch for `BE_DONE` / `FE_DONE`.
+
+   Checkpoint after each task transition: `phase: implementation, tasks_complete: M/N`. Touch heartbeat at every transition.
+
+5. **QA gate (qa-engineer).** Once every `impl:` task is complete, spawn `qa-engineer`. Wait for `QA_PASSED <path>` or `QA_BLOCKED <path>`. If blocked, the QA report contains `impl:qa-fix-be-` / `impl:qa-fix-fe-` tasks — file them in the shared task list and loop to phase 4. Checkpoint: `phase: qa, status: passed | blocked`. Touch heartbeat.
+
+6. **Code review (reviewer).** Once `QA_PASSED`, file a `review:` task and spawn the `reviewer` teammate. Wait for `REVIEW_PASSED <path>`. If critical issues come back instead, the reviewer report names the responsible implementer (`backend-developer` or `frontend-developer`) and the failing task — file `impl:review-fix-be-` / `impl:review-fix-fe-` tasks and loop to phase 4. Checkpoint: `phase: review, status: pass | critical_issues_returned`. Touch heartbeat.
+
+7. **Finish (reviewer, with CI gate).** Same reviewer runs `finishing-a-development-branch`. Before presenting the finish menu, the reviewer pushes the branch and (if `ci.provider != none`) polls CI per the `ci` block in CLAUDE.md until all `required_checks` go green, time out, or fail. On CI red, the reviewer posts `FINISH_BLOCKED ci-red <failed-checks>` and you surface the merge-failure menu with an added option F **"Show CI logs"**. On CI timeout, the reviewer posts `FINISH_BLOCKED ci-timeout` and you surface a 3-option menu (re-poll / switch to `pr_opened` / escalate). The CI gate is the **same finish-branch touchpoint** — no new touchpoint.
+
+   The owner makes the merge / PR / keep / discard decision (third and last owner touchpoint). On `FINISH_DONE <decision> <ref>`, checkpoint: `phase: finish, status: <merged|pr_opened|kept|discarded>`. Touch heartbeat. If the reviewer posts `FINISH_BLOCKED <reason>` (any reason — merge or CI), follow **Phase 7 merge-failure handling** below.
+
+## Phase 7 merge-failure handling
+
+When the reviewer posts `FINISH_BLOCKED <reason>` (instead of `FINISH_DONE`), the merge step or the CI gate failed. Handle it inline — this is the same owner touchpoint as the finish-branch decision continued, NOT a new touchpoint.
+
+`<reason>` is one of `conflict` / `non-ff` / `dirty-worktree` / `push-rejected` / `ci-red <failed-checks>` / `ci-timeout` / `other:<short-string>` (see `agents/reviewer.md` § Hat 2 for the full enum and what each reason means).
+
+### CI-specific menus
+
+For `ci-red <failed-checks>` use the standard 5-option merge-failure menu **plus an option F: Show CI logs**, which runs `gh run view --log-failed` (or the provider equivalent the reviewer is using) and pipes the output into the conversation, then re-presents the menu.
+
+For `ci-timeout` use a 3-option menu:
+
+> **CI did not finish within the poll window.** Pick one:
+> - **A. Re-poll** — wait another `ci.poll_timeout_minutes` for CI to finish.
+> - **B. Switch to pr_opened** — open a PR; the owner deals with CI on the PR side.
+> - **E. Escalate** — §7 escalation, full reviewer status appended.
+
+Re-poll is the same finish-branch touchpoint continued. The `merge_retries` counter does NOT apply to CI re-polls (it tracks merge attempts, not CI polls); cap re-polls at 3 instead, recorded as `ci_repolls: K/3` in the checkpoint.
+
+1. Read the mailbox message. Stash `<reason>` and the verbatim git stderr.
+2. Update the checkpoint: `phase: finish, status: merge_blocked, reason: <reason>, merge_retries: K/3` where `K` is the count of prior retry attempts in this run (start at 0).
+3. Touch the heartbeat.
+4. Present the 5-option menu below to the owner.
+5. Translate the owner's choice into the next instruction to the reviewer per the table.
+
+### 5-option merge-failure menu
+
+Present verbatim:
+
+> **Merge failed:** `<reason>`. Pick one:
+> - **A. Retry merge** — re-attempt the merge now (you've resolved conflicts externally or upstream has stabilised).
+> - **B. Switch to pr_opened** — open a PR for human merge instead.
+> - **C. Switch to kept** — keep the worktree as-is, you'll handle the merge later.
+> - **D. Switch to discarded** — drop the branch entirely.
+> - **E. Escalate** — pause and surface a §7 escalation with full git output.
+
+Translation:
+
+| Choice | Reviewer instruction | Expected next signal |
+|---|---|---|
+| **A** | "Retry the merge step only. Do not re-do design/plan/etc." Increment `merge_retries`. | `FINISH_DONE merged <ref>` OR a new `FINISH_BLOCKED <reason>` |
+| **B** | "Re-run `finishing-a-development-branch` with `decision=pr_opened`." | `FINISH_DONE pr_opened <ref>` |
+| **C** | "Post `FINISH_DONE kept <branch>` directly. Do not attempt another merge." | `FINISH_DONE kept <ref>` |
+| **D** | "Run the discard path of `finishing-a-development-branch`." | `FINISH_DONE discarded <ref>` |
+| **E** | Lead posts §7 template to owner with verbatim git stderr; halts until owner responds. | Owner directs manually |
+
+### Retry cap
+
+`merge_retries` is bounded at 3. Before presenting the menu, check the current value:
+
+- `merge_retries < 3` → present all five options.
+- `merge_retries == 3` → drop option A. The menu shows B/C/D/E only.
+
+The counter is persisted in the checkpoint so `/team-feature-resume` honours it across sessions.
+
+### Flow rejoin
+
+On any `FINISH_DONE <decision>` (any decision), flow rejoins normal phase 7: checkpoint `phase: finish, status: <decision>`, then run **Automatic cleanup** below. Auto-cleanup Step D.5 (worktree removal) runs only when `decision == merged`.
 
 ## Automatic cleanup (runs after `FINISH_DONE`)
 
-The instant phase 5 records `FINISH_DONE`, run cleanup **before idling**. Do this in order, halting and escalating to the owner if any step fails:
+The instant phase 7 records `FINISH_DONE`, run cleanup **before idling**. Do this in order, halting and escalating to the owner if any step fails:
 
 ### Step A — Verify safety preconditions
 
 Confirm all of the following from the checkpoint and the task list:
 
-- Every phase from `brainstorming` through `finish` is checked complete.
+- Every phase from `design` through `finish` is checked complete.
 - The shared task list has zero `in_progress` tasks. Every `impl:` and `review:` task is `completed`.
-- Phase 5 returned a recognised decision: `merged`, `pr_opened`, `kept`, or `discarded`.
-- The expected git commits exist on the worktree branch. Run `git log --oneline -20` and confirm:
+- Phase 7 returned a recognised decision: `merged`, `pr_opened`, `kept`, or `discarded`.
+- The expected git commits exist on the worktree branch. Run `git log --oneline -30` and confirm:
   - A design doc commit under `docs/superpowers/specs/`
   - A plan commit under `docs/superpowers/plans/`
+  - An ARCH report commit AND a SEC report commit under `docs/superpowers/reviews/` (phase-3 gate)
   - One or more implementation commits (TDD pairs of test + code on the same files; the test commit precedes the code commit per the `test-driven-development` skill)
-  - A review report commit under `docs/superpowers/reviews/`
+  - A QA report commit under `docs/superpowers/reviews/` (phase-5 gate)
+  - A code-review report commit under `docs/superpowers/reviews/`
   - If the finish decision is `merged` or `pr_opened`, the corresponding merge / PR-prep commit
 
 If any of these is missing, **halt cleanup**, escalate with the §7 template, and instruct the owner to inspect manually. **Do not run cleanup on a half-finished feature.**
 
 ### Step B — Shut down teammates gracefully
 
-For each live teammate (`designer`, `planner`, every `implementer`, `reviewer`):
+For each live teammate (`designer`, `planner`, `software-architect`, `security-engineer`, every `backend-developer`, every `frontend-developer`, `qa-engineer`, `reviewer`):
 
 1. Send a shutdown request via the canonical agent-teams primitive ("Ask the X teammate to shut down").
 2. Wait for graceful exit.
@@ -117,6 +308,61 @@ bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug> --force
 
 The heartbeat refusal check applies. If it fires, you are still touching the heartbeat (or another lead is alive) — investigate before forcing. If the only reason is your own fresh heartbeat from this session, pass `--ignore-heartbeat` (you know the lead is you and you are about to exit).
 
+### Step D.5 — Worktree removal (on successful merge only)
+
+Runs only after Step C / D have brought platform state to absent. Removes the planner's git worktree when, and only when, the feature was actually merged.
+
+**Trigger conditions** (ALL must be true; any miss → skip and record the reason in the Closing block):
+
+1. `FINISH_DONE merged <ref>` is recorded in the checkpoint.
+2. Step A precondition check passed.
+3. Step B teammate shutdown was clean.
+4. The post-Step-C (or post-Step-D) scan shows `team_config_state: absent`, `task_list_state: absent`, `tmux_state: absent`.
+5. The checkpoint has a non-empty `**Worktree:**` field.
+6. The checkpoint records `**Worktree origin:** created`. A `reused` origin means the worktree existed before this run — it is the owner's, not ours to remove.
+
+If any condition fails, record `worktree: removal-skipped:<reason>` in the Closing block (Step E) where `<reason>` is one of:
+
+- `not-merged-decision` — finish decision was `pr_opened`, `kept`, or `discarded`.
+- `team-cleanup-incomplete` — Step C/D left platform state present.
+- `no-worktree-recorded` — checkpoint has no `**Worktree:**` line.
+- `reused-existing-worktree` — `**Worktree origin:** reused`; the owner pre-existed the worktree and keeps it.
+
+**Procedure** (only when all trigger conditions pass):
+
+1. Read the worktree path from the checkpoint's `**Worktree:**` line. Call it `WT_PATH`.
+2. `cd` to the repo root (the **main** worktree, NOT `WT_PATH`). `git worktree remove` refuses when the current directory is inside the target.
+3. Run `git worktree list --porcelain`. If `WT_PATH` is not listed (already pruned, manual removal, etc.), record `worktree: already-absent` in the Closing block and skip to Step E.
+4. Touch the heartbeat.
+5. Run `git worktree remove "$WT_PATH"` (non-forced).
+6. On success → record `worktree: removed` in the Closing block. Touch heartbeat. Proceed to Step E.
+7. On non-zero exit → enter the **4-option remove-failure menu** below.
+
+**Branch handling:** `git worktree remove` does NOT delete the branch. The feature branch survives this step. Branch deletion is left to the owner.
+
+### 4-option remove-failure menu
+
+Triggered when `git worktree remove "$WT_PATH"` exits non-zero. Common causes: untracked files, locked worktree, in-progress git operation, owner pre-seeded files.
+
+Present verbatim:
+
+> **Could not remove worktree** `<WT_PATH>`. Git said: `<stderr>`. Pick one:
+> - **A. Show files + retry** — list what's blocking, then retry the remove.
+> - **B. Force remove** — discard uncommitted work in `<WT_PATH>` and remove. (Confirmation required.)
+> - **C. Keep worktree** — leave it on disk; you'll remove it manually later.
+> - **D. Escalate** — pause and surface a §7 escalation with the verbatim stderr.
+
+Translation:
+
+| Choice | Action | Closing-block record |
+|---|---|---|
+| **A** | Run `git -C "$WT_PATH" status --short` and `git -C "$WT_PATH" diff --stat`. Surface output to owner. Retry `git worktree remove "$WT_PATH"`. Cap: 3 retries per Step D.5. On success: record `worktree: removed (after manual fix)` and proceed to Step E. On 3rd retry still failing: drop option A from the next menu and force B/C/D. | See action column. |
+| **B** | Lead prompts: `"This will discard uncommitted work in <WT_PATH>. Confirm force-remove? (type 'yes' to confirm)"`. On `yes`: snapshot the file list from the pre-remove `git -C "$WT_PATH" status --short` (or take a snapshot now if option A hasn't run), then run `git worktree remove --force "$WT_PATH"`. On any other input: abort B, re-present the menu. | `worktree: force-removed`, `dropped_files: [<path>, ...]` |
+| **C** | Log `WT_PATH` in the Closing block. Tell the owner: `"Worktree retained at <WT_PATH>. Remove manually with 'git worktree remove <WT_PATH>' once you've handled it."` Proceed to Step E. | `worktree: kept-by-owner`, `worktree_path: <WT_PATH>` |
+| **D** | Halt Step D.5. Post the §7 template to the owner with the verbatim stderr from the failed remove. Wait for direction. | `worktree: escalated`, `worktree_path: <WT_PATH>` |
+
+In all four cases, Step E still runs after Step D.5 closes (whether by success or by the owner's menu choice). Step E records the outcome in the Closing block.
+
 ### Step E — Final checkpoint commit
 
 Append a closing block to the checkpoint:
@@ -126,20 +372,39 @@ Append a closing block to the checkpoint:
 - finished at: <ISO datetime>
 - decision: <merged|pr_opened|kept|discarded>
 - cleanup: complete
+- worktree: <removed | already-absent | removal-skipped:<reason> | removed (after manual fix) | force-removed | kept-by-owner | escalated>
+- worktree_path: <path>            # present whenever the worktree directory still exists on disk after cleanup (states: kept-by-owner, escalated, or removal-skipped where the path exists)
+- merge_retries: K                 # only when K > 0; matches the final value of the mid-phase counter
+- dropped_files: [<path>, ...]     # only when state == force-removed
 ```
 
+`removal-skipped` reasons: `not-merged-decision` | `team-cleanup-incomplete` | `no-worktree-recorded` | `reused-existing-worktree`.
+
 Remove the `<slug>.heartbeat` file. Commit the checkpoint. Confirm to the owner: "Team cleaned up. Feature complete."
 
 ### Step F — If anything failed
 
 Tell the owner exactly which step failed, include the script output verbatim, and instruct them to run `/team-cleanup <slug>` once they have confirmed nothing else is running. Do **not** retry cleanup loops automatically — the safety check is the heartbeat, and you cannot meaningfully refresh it from outside the lead process.
 
+## Within-phase stall watchdog
+
+Heartbeat at phase boundaries is not enough — a teammate can hang silently mid-phase and you'd never notice. Run a watchdog:
+
+1. Read `limits.phase_stall_minutes` from CLAUDE.md (`bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh get limits.phase_stall_minutes CLAUDE.md`). Default to **30** if unset.
+2. Inside any phase, if the watchdog window elapses with **no mailbox message AND no shared-task-list state transition** from the active teammate(s):
+   - Send a ping to the teammate's mailbox: `STATUS_CHECK <slug> — no activity for <N> minutes; reply with current status or progress note.`
+   - Start a second watchdog window of the same length.
+3. If a second watchdog window also elapses with no reply: surface a §7 escalation to the owner with the teammate's last-known status, the elapsed wall time, and the current phase. Halt — do NOT silently respawn or force-cancel; the owner decides.
+
+The watchdog is **not** an owner touchpoint by itself — pinging the teammate is internal. Escalation step 3 is what reaches the owner, and only via the §7 template (so it doesn't count against the 3 allowed touchpoints either).
+
+Reset the watchdog on every received mailbox message and every task transition. Touch the heartbeat each time you reset.
+
 ## Owner touchpoints (the ONLY allowed pings to the owner)
 
-1. Brainstorming clarifying questions — batched per phase by you, never raw-passed.
-2. Design sign-off (the brainstorming skill's built-in step).
-3. Plan approval before phase 3 starts.
-4. Finish-branch decision in phase 6.
+1. Design sign-off (phase 1, the brainstorming skill's built-in step).
+2. Plan approval before phase 3 starts.
+3. Finish-branch decision in phase 7.
 
 **Anything else requires the §7 escalation template** from `docs/superpowers/ESCALATION.md`. Refuse to ping the owner without it. Cleanup runs without owner involvement when Step A passes.
 
@@ -148,24 +413,41 @@ Tell the owner exactly which step failed, include the script output verbatim, an
 After every phase boundary, write `docs/superpowers/sessions/YYYY-MM-DD-<slug>.md` atomically (tmp + rename) per this format and commit it. This is the only way the workflow survives a `/resume` failure:
 
 ```markdown
+---
+slug: <slug>
+started: <ISO datetime>
+superpowers_version: <e.g. 5.0.7>
+plugin_version: <team-superpower plugin version>
+claude_code_version: <e.g. 2.1.32>
+stack_shape: full-stack | be-only | fe-only
+---
+
 # Session: <slug>
 **Started:** <ISO datetime>
 **Last update:** <ISO datetime>
 **Team:** superpower-<slug>
 **Worktree:** <path>
+**Worktree origin:** created | reused        # `reused` means the owner launched `/team-feature` from inside a linked worktree; Step D.5 skips removal in that case
 
 ## Phases
-- [x] brainstorming → docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md
+- [x] design → docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md
 - [x] worktree → <branch>
 - [x] plan → docs/superpowers/plans/YYYY-MM-DD-<slug>-plan.md (approved <datetime>)
+- [x] pre_impl_review → arch + sec PASSED
 - [ ] implementation (M/N tasks complete)
+- [ ] qa
 - [ ] review
-- [ ] finish
+- [ ] finish — when `FINISH_BLOCKED <reason>` is in flight, this line reads `- [ ] finish (blocked: <reason>, merge_retries: K/3)` instead, and stays unchecked until `FINISH_DONE` arrives.
 
 ## Teammates
+(list reflects stack_shape — omit the implementer that doesn't exist for be-only / fe-only)
 - designer (agent-id: ...) — idle
 - planner (agent-id: ...) — idle
-- implementer-1 (agent-id: ...) — active on task impl:<name>
+- software-architect (agent-id: ...) — idle
+- security-engineer (agent-id: ...) — idle
+- backend-developer (agent-id: ...) — active on task impl:be-<name>    # full-stack | be-only
+- frontend-developer (agent-id: ...) — idle                              # full-stack | fe-only
+- qa-engineer (agent-id: ...) — idle
 - reviewer (agent-id: ...) — idle
 
 ## Open escalations
@@ -181,10 +463,29 @@ After every phase boundary, write `docs/superpowers/sessions/YYYY-MM-DD-<slug>.m
 
 - **Never** run a Superpowers skill yourself. Always delegate to the correct teammate.
 - **Never** modify, replace, or skip a Superpowers skill. Consume them as-installed.
-- **Never** let an implementer write code before the plan is approved. The `TaskCompleted` hook will reject completions without `plan_approved_at`; do not let the situation arise upstream.
+- **Never** start phase 4 before both `ARCH_PASSED` and `SEC_PASSED` are recorded. The phase-3 gate is non-optional.
+- **Never** start phase 6 before `QA_PASSED` is recorded. The phase-5 gate is non-optional.
+- **Never** let an implementer write code before the plan is approved AND the phase-3 gate has passed. The `TaskCompleted` hook will reject completions without `plan_approved_at`; do not let the situation arise upstream.
 - **Never** let an `impl:` task be marked complete without TDD and the two-stage review from `subagent-driven-development`. The hook is a backstop, not a primary control.
-- **Never** ping the owner without the §7 template, except for the four allowed touchpoints listed above.
+- **Never** ping the owner without the §7 template, except for the three allowed touchpoints listed above.
 - **Never** skip the automatic cleanup block after `FINISH_DONE`. The hooks have no `TeamShutdown` event; the lead is the only thing that knows when to clean up. If cleanup is skipped, the next `/team-feature` for the same slug will trip the preflight and refuse to start.
 - **Never** force cleanup while the heartbeat is fresh and you didn't write it. That's the signal that another lead is alive.
-
-Begin with the prechecks, then preflight, then spawn `designer`.
+- **Never** run Step D.5 worktree removal unless the finish decision is `merged` AND the platform-cleanup scan (Step C, or Step D fallback) shows every state `absent`. Other decisions or partial cleanups must record `worktree: removal-skipped:<reason>` and leave the worktree on disk.
+- **Never** force-remove a worktree (`--force`) without explicit owner confirmation in the 4-option menu. The default remove is non-forced; force only on option B with a typed `yes`.
+- **Never** retry merge more than 3 times. After the 3rd `FINISH_BLOCKED`, drop option A from the 5-option menu and require B/C/D/E.
+- **Never** treat the `FINISH_BLOCKED` menu as a new owner touchpoint. It is the same finish-branch touchpoint continued — the 3-touchpoint cap stays at 3.
+
+## Hard rules (v2 additions)
+
+- **Never** spawn `frontend-developer` in a `be-only` shape, or `backend-developer` in a `fe-only` shape. The shape was decided in phase 0.5 from CLAUDE.md (or the auto-detection fallback the owner has confirmed); deviating means a different team than the owner agreed to.
+- **Never** auto-edit the user's `CLAUDE.md`. Phase 0 writes to `docs/superpowers/stack.detected.md` only and asks the owner to paste/edit. The user's CLAUDE.md is theirs.
+- **Never** release an `impl:fe-*` task before `CONTRACT_PUBLISHED` arrives (full-stack with `contracts.source_of_truth != none`).
+- **Never** release a second `impl:be-migration-*` task while one is `in_progress`. The hook is a backstop; you are the primary control.
+- **Never** present the finish-branch menu before the CI gate either passes or is explicitly bypassed (CI red → menu with "Show CI logs"; CI timeout → 3-option menu; `ci.provider: none` → skip the gate entirely but still push).
+- **Never** wait passively on a teammate for longer than `limits.phase_stall_minutes` (default 30) without running the within-phase stall watchdog above. Two consecutive stall windows with no teammate activity must escalate via §7.
+- **Never** improvise a spawn prompt. Use the **Spawn prompt template** verbatim — leave fields as `n/a` rather than omitting them.
+- **Never** spawn more than 5 teammates concurrently. The plugin defines up to 8 lifetime roles but phase-gating must keep ≤ 5 active at any moment. If a future change would break this, halt and escalate.
+- **Never** run Step D.5 worktree removal when `**Worktree origin:** reused`. The worktree existed before `/team-feature` started; the owner owns it. Record `worktree: removal-skipped:reused-existing-worktree` and leave the worktree on disk.
+- **Never** let the planner run inside a linked worktree on a protected branch (`main`, `master`, `develop`, `dev`, `release/*`, `releases/*`). The planner halts and escalates; the owner switches to a feature branch and re-runs.
+
+Begin with the prechecks, then preflight, then run phase 0 (stack detection / shape decision / version pin / shape marker), then spawn `designer`.

package/plugins/team-superpower/hooks/hooks.json

@@ -2,7 +2,6 @@
   "hooks": {
     "TeammateIdle": [
       {
-        "matcher": "*",
         "hooks": [
           { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/teammate-idle.sh" }
         ]
@@ -10,7 +9,6 @@
     ],
     "TaskCreated": [
       {
-        "matcher": "*",
         "hooks": [
           { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/task-created.sh" }
         ]
@@ -18,7 +16,6 @@
     ],
     "TaskCompleted": [
       {
-        "matcher": "*",
         "hooks": [
           { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/task-completed.sh" }
         ]

package/plugins/team-superpower/hooks/task-completed.sh

@@ -6,12 +6,15 @@
 #   - task.title: string
 #   - task.metadata.plan_approved_at: string (ISO datetime), required for impl: tasks
 #   - task.metadata.blocked_questions: array of strings (optional)
+#   - task.metadata.commits: array of git SHAs (optional, used by v2 checks)
+#   - task.metadata.contract_files: array of paths (optional, for contract-publish)
 #
-# Rules:
-#   - impl: task -> plan_approved_at MUST be present (exit 2 NO_PLAN_APPROVAL)
-#   - any blocked_questions entry -> must mention every escalation field
-#     (Phase, Context, Options, Recommendation, Need from you)
-#     otherwise exit 2 BAD_ESCALATION: missing field(s) <list>
+# v2 rules added on top of v1:
+#   - impl:be-migration-* completions: refuse if another in-progress migration
+#     exists in the shared task list payload (anti-race).
+#   - impl:be-contract-publish-* completions: at least one commit on this task
+#     must touch a contracts file (default `contracts/` directory, or paths
+#     listed in metadata.contract_files). Verified via `git show --name-only`.
 
 set -euo pipefail
 
@@ -51,6 +54,52 @@ case "$title" in
     ;;
 esac
 
+# v2: migration serialization. If this is a migration task, verify no other
+# `impl:be-migration-*` task is currently in_progress in the shared task list
+# (payload.tasks[]). The lead also enforces this; the hook is a backstop.
+case "$title" in
+  impl:be-migration-*)
+    other_in_progress="$(printf '%s' "$payload" | jq -r --arg me "$title" '
+      [ .tasks[]?
+        | select((.title // "") != $me)
+        | select(((.title // "") | startswith("impl:be-migration-")))
+        | select((.status // "") == "in_progress")
+      ] | length' 2>/dev/null || echo 0)"
+    if [ "${other_in_progress:-0}" -gt 0 ]; then
+      echo "MIGRATION_RACE: another impl:be-migration-* task is in_progress; migrations must serialize. (title: $title)" >&2
+      exit 2
+    fi
+    ;;
+esac
+
+# v2: contract-publish must actually touch a contracts file in at least one
+# of its commits. Best-effort: skip if git unavailable or no commits recorded.
+case "$title" in
+  impl:be-contract-publish-*)
+    if command -v git >/dev/null 2>&1; then
+      commits="$(printf '%s' "$payload" | jq -r '(.task.metadata.commits // .metadata.commits // [])[]?' 2>/dev/null || true)"
+      patterns="$(printf '%s' "$payload" | jq -r '(.task.metadata.contract_files // .metadata.contract_files // ["contracts/"])[]?' 2>/dev/null || echo "contracts/")"
+      if [ -n "$commits" ]; then
+        touched=0
+        while IFS= read -r sha; do
+          [ -z "$sha" ] && continue
+          files="$(git show --no-color --name-only --pretty=format: "$sha" 2>/dev/null || true)"
+          while IFS= read -r pat; do
+            [ -z "$pat" ] && continue
+            if printf '%s\n' "$files" | grep -qE "(^|/)${pat//./\\.}"; then
+              touched=1; break 2
+            fi
+          done <<< "$patterns"
+        done <<< "$commits"
+        if [ "$touched" -ne 1 ]; then
+          echo "EMPTY_CONTRACT_PUBLISH: $title claims to publish a contract but no commit touches a contract file (looked for: $(echo "$patterns" | tr '\n' ' '))" >&2
+          exit 2
+        fi
+      fi
+    fi
+    ;;
+esac
+
 # Validate escalation entries if present.
 required_fields=("Phase" "Context" "Options" "Recommendation" "Need from you")
 missing_any=""