@drunkcoding/agents-and-skills 0.0.14 → 0.0.15

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

@@ -15,13 +15,92 @@ You are a **conductor**, not an implementer. Spawn teammates and coordinate them
 
 ## 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,33 +128,89 @@ 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. **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` then `PLAN_READY <path>`. 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.
+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 (backend-developer + frontend-developer, parallel).** Read the approved plan. Create one shared-task-list entry per plan task with title `impl:be-<short-name>` or `impl:fe-<short-name>` per the prefix the planner assigned, body = full task text including verification, and dependency + file-scope metadata from the plan. Spawn one `backend-developer` and one `frontend-developer`. They self-claim by prefix. **You must 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.
+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).** Same reviewer runs `finishing-a-development-branch`. 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>` instead, follow **Phase 7 merge-failure handling** below.
+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 of `finishing-a-development-branch` failed for the `merged` decision. Handle it inline — this is the same owner touchpoint as the finish-branch decision continued, NOT a new touchpoint.
+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` / `other:<short-string>` (see `agents/reviewer.md` § Hat 2 for the full enum and what each reason means).
+`<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).
@@ -184,12 +319,14 @@ Runs only after Step C / D have brought platform state to absent. Removes the pl
 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):
 
@@ -241,7 +378,7 @@ Append a closing block to the checkpoint:
 - dropped_files: [<path>, ...]     # only when state == force-removed
 ```
 
-`removal-skipped` reasons: `not-merged-decision` | `team-cleanup-incomplete` | `no-worktree-recorded`.
+`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."
 
@@ -249,6 +386,20 @@ Remove the `<slug>.heartbeat` file. Commit the checkpoint. Confirm to the owner:
 
 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. Design sign-off (phase 1, the brainstorming skill's built-in step).
@@ -262,11 +413,21 @@ 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] design → docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md
@@ -279,12 +440,13 @@ After every phase boundary, write `docs/superpowers/sessions/YYYY-MM-DD-<slug>.m
 - [ ] 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
 - software-architect (agent-id: ...) — idle
 - security-engineer (agent-id: ...) — idle
-- backend-developer (agent-id: ...) — active on task impl:be-<name>
-- frontend-developer (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
 
@@ -313,4 +475,17 @@ After every phase boundary, write `docs/superpowers/sessions/YYYY-MM-DD-<slug>.m
 - **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.
 
-Begin with the prechecks, then preflight, then spawn `designer`.
+## 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/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=""

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

@@ -5,13 +5,23 @@
 #   - task.title: string
 #
 # Title MUST start with one of: impl:, review:, meta:, block:
-# Otherwise exit 2 with stderr BAD_PREFIX so the team-team runtime refuses
-# the task and surfaces the failure to the lead.
+# v2 additions:
+#   - impl: tasks MUST carry a sub-prefix (be-, fe-, qa-fix-be-, qa-fix-fe-,
+#     review-fix-be-, review-fix-fe-, contract-update-, be-migration-,
+#     be-contract-publish-) — bare `impl:foo` is rejected.
+#   - Shape-marker file at docs/superpowers/sessions/<slug>.shape (written by
+#     the lead in phase 0) restricts which sub-prefixes are allowed:
+#       be-only      → only `impl:be-*`, `impl:contract-update-*` allowed
+#       fe-only      → only `impl:fe-*`, `impl:contract-update-*` allowed
+#       full-stack   → all sub-prefixes allowed
+#   - Slug is taken from .task.metadata.slug or .metadata.slug, with fallback
+#     to the most-recent .shape file when only one exists.
 
 set -euo pipefail
 
 LOG_DIR="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/hooks"
 LOG_FILE="$LOG_DIR/log.jsonl"
+SESSIONS_DIR="${CLAUDE_PROJECT_DIR:-$PWD}/docs/superpowers/sessions"
 mkdir -p "$LOG_DIR"
 
 ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
@@ -29,11 +39,36 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 title="$(printf '%s' "$payload" | jq -r '.task.title // .title // ""' 2>/dev/null || echo "")"
+slug="$(printf '%s' "$payload" | jq -r '.task.metadata.slug // .metadata.slug // ""' 2>/dev/null || echo "")"
 
-printf '{"ts":"%s","hook":"task-created","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+# Resolve shape from the slug's marker file. If slug is unknown but exactly
+# one .shape file exists, use it (single in-flight feature is the common case).
+shape=""
+if [ -d "$SESSIONS_DIR" ]; then
+  shape_file=""
+  if [ -n "$slug" ] && [ -f "$SESSIONS_DIR/$slug.shape" ]; then
+    shape_file="$SESSIONS_DIR/$slug.shape"
+  else
+    count="$(find "$SESSIONS_DIR" -maxdepth 1 -type f -name '*.shape' 2>/dev/null | wc -l | tr -d ' ')"
+    if [ "$count" = "1" ]; then
+      shape_file="$(find "$SESSIONS_DIR" -maxdepth 1 -type f -name '*.shape' 2>/dev/null | head -n1)"
+    fi
+  fi
+  if [ -n "$shape_file" ] && [ -f "$shape_file" ]; then
+    shape="$(head -n1 "$shape_file" | tr -d '[:space:]')"
+  fi
+fi
+
+printf '{"ts":"%s","hook":"task-created","title":%s,"shape":%s}\n' \
+  "$ts" \
+  "$(printf '%s' "$title" | jq -Rs .)" \
+  "$(printf '%s' "$shape" | jq -Rs .)" \
+  >> "$LOG_FILE"
 
+# Top-level prefix check
 case "$title" in
-  impl:*|review:*|meta:*|block:*) exit 0 ;;
+  review:*|meta:*|block:*) exit 0 ;;
+  impl:*) ;;
   "")
     echo "BAD_PREFIX: task title missing; must start with impl:|review:|meta:|block:" >&2
     exit 2 ;;
@@ -41,3 +76,43 @@ case "$title" in
     echo "BAD_PREFIX: task title must start with impl:|review:|meta:|block: (got: $title)" >&2
     exit 2 ;;
 esac
+
+# At this point title starts with `impl:`. Strip prefix and require a known
+# sub-prefix.
+rest="${title#impl:}"
+case "$rest" in
+  be-*|qa-fix-be-*|review-fix-be-*|be-migration-*|be-contract-publish-*)
+    sub="be"
+    ;;
+  fe-*|qa-fix-fe-*|review-fix-fe-*)
+    sub="fe"
+    ;;
+  contract-update-*)
+    sub="contract"
+    ;;
+  *)
+    echo "BAD_PREFIX: impl: task requires a sub-prefix (be-|fe-|qa-fix-be-|qa-fix-fe-|review-fix-be-|review-fix-fe-|contract-update-|be-migration-|be-contract-publish-). Got: $title" >&2
+    exit 2 ;;
+esac
+
+# Shape-aware enforcement
+case "$shape" in
+  be-only)
+    if [ "$sub" = "fe" ]; then
+      echo "SHAPE_REJECTED: shape is 'be-only'; impl:fe-* tasks are not allowed for this feature." >&2
+      exit 2
+    fi
+    ;;
+  fe-only)
+    if [ "$sub" = "be" ]; then
+      echo "SHAPE_REJECTED: shape is 'fe-only'; impl:be-* tasks are not allowed for this feature." >&2
+      exit 2
+    fi
+    ;;
+  full-stack|"")
+    # full-stack: anything goes. Empty shape: hook can't tell — accept and
+    # let the lead serialize/validate. Logged above for tuning.
+    ;;
+esac
+
+exit 0