@drunkcoding/agents-and-skills 0.0.14 → 0.0.16

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,27 +93,46 @@ 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
 
 - `cd` into the worktree path recorded in the checkpoint. If it no longer exists, halt and escalate via the §7 template — the owner needs to restore or rebase the worktree before resume can continue.
-- Recreate the team with the same name (`superpower-<slug>`).
+- Recreate the team with the same name (`superpower-<slug>`) via the canonical `TeamCreate` tool:
+  ```
+  TeamCreate({
+    team_name:   "superpower-<slug>",
+    agent_type:  "team-lead",
+    description: "<reuse the description from the previous run if recorded in the checkpoint; otherwise the owner's one-line request>"
+  })
+  ```
+  TeamCreate is idempotent at the directory level — if `~/.claude/teams/superpower-<slug>/config.json` already exists from a partial cleanup, the runtime will refuse to overwrite. In that case, halt and instruct the owner to run `/team-cleanup <slug>` first (the resume protocol Step 3 should have caught this; if it didn't, that's a real bug — escalate).
 - Touch `docs/superpowers/sessions/<slug>.heartbeat` and update it at every phase boundary (same protocol as `/team-feature`).
 
-### Step 6 — Respawn only the teammates needed
+### Step 6 — Re-read the shape marker
+
+Read `docs/superpowers/sessions/<slug>.shape` and `stack_shape` from the checkpoint frontmatter. They must match — if they disagree, halt and escalate (one was hand-edited). The shape determines which implementer to respawn:
+
+- `full-stack` → both `backend-developer` and `frontend-developer` are eligible to respawn.
+- `be-only` → only `backend-developer`. NEVER respawn `frontend-developer` for a `be-only` feature.
+- `fe-only` → only `frontend-developer`. NEVER respawn `backend-developer`.
+
+If the marker file is missing, re-derive shape from `CLAUDE.md` via `bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh shape CLAUDE.md` and write the marker file before continuing.
+
+### Step 6 (cont.) — Respawn only the teammates needed
 
-For the next phase, spawn the relevant role(s) using the agent definitions shipped with this plugin. Do **not** respawn teammates whose phase is complete unless that phase needs them again later (e.g. reviewer is reused in phase 7 for finish; planner is re-spawned if phase 3 returned `ARCH_BLOCKED` / `SEC_BLOCKED` and the plan needs revision; backend-developer / frontend-developer are re-spawned for `impl:qa-fix-*` or `impl:review-fix-*` tasks). Phase-to-role map:
+For the next phase, spawn the relevant role(s) using the canonical `Agent` primitive documented in `/team-feature` § "Create the team (canonical primitive)" — same `subagent_type` / `team_name` / `name` / `prompt` shape, and `team_name` MUST be `superpower-<slug>` so messages route to the existing inboxes under `~/.claude/teams/superpower-<slug>/inboxes/`. 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:
 
 | Next phase | Spawn |
 |---|---|
 | `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 +179,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.

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

@@ -5,6 +5,10 @@ argument-hint: <one-line feature idea>
 
 You are the **lead** of an agent team implementing the Superpowers methodology across multiple parallel Claude Code sessions.
 
+> **Lead model:** run this command in an **Opus** session. The lead carries the cross-phase reasoning load (planning gates, escalation triage, FINISH_BLOCKED recovery, owner touchpoint budget). All 8 teammate agents are pinned to **Sonnet** via their frontmatter (`model: sonnet`) — they spawn on Sonnet regardless of the lead's model. If the lead is started on Sonnet, halt and ask the owner to relaunch on Opus.
+>
+> **Lead thinking discipline:** adaptive. Use extended (high-effort) thinking for every gate decision, escalation triage, classification of clarification questions (tactical / cross-role / architectural / owner-only), FINISH_BLOCKED recovery, and worktree-cleanup branching. Routine heartbeats, mailbox forwarding, status polls, and shared-task-list status reads may be quick. Teammates default to high thinking on every non-trivial step (see each agent's "Thinking discipline" section); the lead is the only role that scales effort per action.
+
 Owner's feature request:
 
 $ARGUMENTS
@@ -15,13 +19,93 @@ 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`.
+0. **Lead-model self-attestation.** Before doing anything else, state which model you (the lead) are currently running on. If you are not running on Opus, halt and instruct the owner: "Lead must be on Opus. Relaunch this session with `claude --model opus` (or pick Opus in the model switcher) and rerun `/team-feature`." Teammates are pinned to Sonnet via their agent frontmatter; only the lead model is set by the session.
+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 +133,153 @@ 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.
+
+## Create the team (canonical primitive)
+
+Immediately after writing the initial checkpoint and **before** spawning any teammate, create the team via the canonical Claude Code `TeamCreate` tool. Do NOT mkdir `~/.claude/teams/...` by hand — the runtime owns that directory and the inbox files inside it.
+
+Call:
+
+```
+TeamCreate({
+  team_name:   "superpower-<slug>",
+  agent_type:  "team-lead",
+  description: "<one-line owner request, ≤120 chars>"
+})
+```
+
+This creates:
+
+```
+~/.claude/teams/superpower-<slug>/
+├── config.json          ← team configuration & members (lead-managed)
+└── inboxes/
+    ├── team-lead.json   ← your inbox (auto-populated as teammates SendMessage you)
+    ├── designer.json    ← created when the designer teammate is spawned
+    ├── planner.json     ← created when the planner is spawned
+    └── ...              ← one file per teammate name (= the agent's role)
+
+~/.claude/tasks/superpower-<slug>/
+└── ...                  ← shared task list (TaskCreate / TaskUpdate)
+```
+
+The runtime appends every inbound `SendMessage` to the recipient's JSON array with shape:
+
+```json
+{
+  "from":      "<sender role name>",
+  "text":      "<message body>",
+  "summary":   "<5-10 word preview>",
+  "timestamp": "<ISO 8601 UTC>",
+  "read":      false,
+  "color":     "<UI hint>"
+}
+```
+
+You never write these files directly. Always use `SendMessage` to deliver, and read your inbox through the automatic delivery the runtime hands you (see "Automatic Message Delivery" in the TeamCreate tool docs). The only hand-read is `~/.claude/teams/superpower-<slug>/config.json` when you need to discover member roles by name.
+
+### Spawning teammates (canonical Agent call)
+
+When you spawn a teammate (per the phase chain below), use the `Agent` tool with **all four** of these parameters:
+
+```
+Agent({
+  subagent_type: "<role>",          // e.g. "team-superpower:designer"; matches the agent .md filename
+  team_name:     "superpower-<slug>",
+  name:          "<role>",          // e.g. "designer"; becomes the inbox filename (designer.json) and the SendMessage `to` value
+  prompt:        "<filled Spawn prompt template, see below>"
+})
+```
+
+Hard rules for the spawn call:
+
+- `name` MUST equal the role string (`designer`, `planner`, `software-architect`, `security-engineer`, `backend-developer`, `frontend-developer`, `qa-engineer`, `reviewer`). Inbox filenames depend on this.
+- `team_name` MUST equal `superpower-<slug>` — every cleanup, resume, and `team-state.sh` primitive depends on this convention.
+- `subagent_type` MUST match the agent definition shipped by this plugin (`team-superpower:<role>`).
+- Do NOT spawn the same role twice in parallel. If a role needs a second pass, mailbox the existing teammate instead of spawning a duplicate.
+
+## 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` / `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:
 
-`<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).
+> **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 +388,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 +447,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 +455,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 +482,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,18 +509,23 @@ 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
 
 ## Open escalations
 - (none) | <escalation-template entries>
 
+## Assumptions
+(appended after each phase; one entry per non-owner decision)
+- <ISO ts> <role> [class=<tactical|cross-role|architectural>]: <one-line decision> (peer: <role|none>, evidence: <link to mailbox msg | n/a>)
+
 ## Resume protocol
 1. Owner runs /team-feature-resume with this filename.
 2. Lead respawns teammates using same role definitions.
@@ -313,4 +548,18 @@ 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.
+- **Never** forward an owner-bound escalation when the originator's `class` is not `owner-only` AND `Peer attempts` lists fewer than one round-trip with a peer. The lead returns the escalation to the originator with `RETRY_PEER: try <suggested role> first`. Touchpoint count is NOT decremented (this is a routing reject, not an owner touch). The lead also returns it with `LOG_ASSUMPTION: tactical questions log to checkpoint § Assumptions, not the mailbox` when `class=tactical`. The 4-class table is in `assets/ESCALATION.md`. Class detection: scan the `Peer attempts:` field body for a `class=<name>` token (matches `class=tactical|cross-role|architectural|owner-only`). If absent, the field contains ISO-timestamped peer attempts — treat the originator's class as `cross-role` (the only class that produces real peer attempts) and accept a round-trip count ≥ 1.
+
+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
 
@@ -45,14 +48,57 @@ printf '{"ts":"%s","hook":"task-completed","title":%s,"plan_approved_at":%s}\n'
 case "$title" in
   impl:*)
     if [ -z "$plan_approved_at" ]; then
-      echo "NO_PLAN_APPROVAL: impl: tasks require metadata.plan_approved_at before completion (title: $title)" >&2
-      exit 2
+      printf '{"ts":"%s","hook":"task-completed","warn":"no_plan_approval","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+    fi
+    ;;
+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
+      printf '{"ts":"%s","hook":"task-completed","warn":"migration_race","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+    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
+          printf '{"ts":"%s","hook":"task-completed","warn":"empty_contract_publish","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+        fi
+      fi
     fi
     ;;
 esac
 
 # Validate escalation entries if present.
-required_fields=("Phase" "Context" "Options" "Recommendation" "Need from you")
+required_fields=("Phase" "Context" "Options" "Recommendation" "Need from you" "Peer attempts")
 missing_any=""
 entries="$(printf '%s' "$payload" | jq -c '(.task.metadata.blocked_questions // .metadata.blocked_questions // [])[]?' 2>/dev/null || true)"
 
@@ -81,8 +127,7 @@ if [ -n "$entries" ]; then
 fi
 
 if [ -n "$missing_any" ]; then
-  echo "BAD_ESCALATION: missing field(s) $missing_any" >&2
-  exit 2
+  printf '{"ts":"%s","hook":"task-completed","warn":"bad_escalation","missing":%s}\n' "$ts" "$(printf '%s' "$missing_any" | jq -Rs .)" >> "$LOG_FILE"
 fi
 
 exit 0