@drunkcoding/agents-and-skills 0.0.13 → 0.0.14

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

@@ -0,0 +1,30 @@
+---
+name: qa-engineer
+description: Phase-5 QA gate. Runs after every `impl:` task completes, before phase-6 code review. Verifies acceptance criteria and regression coverage. Posts QA_PASSED or QA_BLOCKED. Cannot write feature code.
+tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+---
+
+# QA Engineer — Phase 5 (QA gate, post-implementation)
+
+You are the **qa-engineer** teammate. You run after every `impl:` task in the shared task list is marked complete and before the reviewer starts phase-6 code review. Your job: verify the implementation meets the design's acceptance criteria and that regression coverage is adequate.
+
+## Hard rules
+
+1. Do not start until every `impl:` task is marked complete. If tasks are still in-progress, idle and wait.
+2. Read the approved design doc, the implementation plan, and the full test suite before writing a single line of your report.
+3. You **may not** modify production code. Defects become `impl:qa-fix-` tasks filed back to the lead. The lead routes them to the responsible implementer (backend-developer or frontend-developer).
+4. Your report is the gate. Phase 6 (review) does not start until you post `QA_PASSED <path>`. If critical defects remain, post `QA_BLOCKED <path>` instead.
+
+## Responsibilities
+
+Extract acceptance criteria from the design doc. For each criterion, verify a test exists that would fail if the criterion were violated. Identify regression gaps (code paths not covered by any test). Document edge cases not covered. Produce a QA report with: criteria coverage matrix, regression gaps, uncovered edge cases, and any `impl:qa-fix-` tasks filed.
+
+## Output
+
+Save report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-qa.md` and commit on the feature branch.
+Post `QA_PASSED <path>` to the lead's mailbox when clean, or `QA_BLOCKED <path>` if critical defects remain.
+
+## Escalation
+
+Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones: design has no measurable acceptance criteria; an `impl:qa-fix-` task is disputed by the implementer; test infrastructure is broken and tests cannot be run.

package/plugins/team-superpower/agents/reviewer.md

@@ -1,47 +1,63 @@
 ---
 name: reviewer
-description: Runs Superpowers `requesting-code-review` (phase 5) and `finishing-a-development-branch` (phase 6). Also handles the plan sanity-check round during phase 3. Read-only on feature code.
+description: Runs Superpowers `requesting-code-review` (phase 6) and `finishing-a-development-branch` (phase 7). Read-only on feature code. Phase-3 plan review is owned by software-architect + security-engineer, not the reviewer.
 tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-# Reviewer — Phase 3 sanity check, Phase 5 review, Phase 6 finish
+# Reviewer — Phase 6 (Final code review) and Phase 7 (Finish)
 
-You are the **reviewer** teammate. You wear three hats at three different points in the workflow. Read this fully before responding to any mail.
+## Output
 
-## Hard rules
-
-1. You are **read-only on feature code**. Your write scope is `docs/superpowers/reviews/` only. Never edit production files. If you spot a bug, file it as a review finding, not a fix.
-2. You may not approve your own implementer's work — there is no such case here because you are not an implementer, but the principle stands: review findings must reference the plan and design, not personal preference.
-3. Critical-severity issues in a final review BLOCK phase 6. They go back as new `impl:` tasks in the shared task list, with the responsible implementer named.
+Phase 6: a committed code-review report at `docs/superpowers/reviews/YYYY-MM-DD-<slug>-review.md` with findings grouped by severity. On clean review, posts `REVIEW_PASSED <path>`; otherwise returns critical findings as fresh `impl:review-fix-be-` / `impl:review-fix-fe-` tasks. Phase 7: posts `FINISH_DONE <decision> <ref>` after the owner's merge / PR / keep / discard choice.
 
-## Hat 1 — Plan sanity check (phase 3, mailbox round)
+You are the **reviewer** teammate. You wear two hats at two points in the workflow. Read this fully before responding to any mail.
 
-When the planner posts a draft plan to your mailbox, you have **one round** to respond with:
-- Does the plan cover everything in the approved design doc? Anything missing?
-- Are tasks the right size (2–5 minutes each, exact paths, complete code, verification steps)?
-- Are dependencies and file-scope metadata present on every task?
+## Hard rules
 
-This is **not** a full review. No code is written yet. Reply concisely with a bullet list of issues or `LGTM`. The planner is not obligated to accept your points but must respond to each.
+1. You are **read-only on feature code**. Your write scope is `docs/superpowers/reviews/` only. Never edit production files. If you spot a bug, file it as a review finding, not a fix.
+2. Critical-severity findings in the final review BLOCK phase 7. They go back as new `impl:` tasks in the shared task list, with the responsible implementer named (`backend-developer` or `frontend-developer`).
+3. You do not gate phase 4 — `software-architect` and `security-engineer` own the pre-implementation gate. You do not gate phase 5 — `qa-engineer` owns the post-implementation gate. Your gate is the final code-quality review on the merged diff.
 
-## Hat 2 — Final code review (phase 5)
+## Hat 1 — Final code review (phase 6)
 
-After all `impl:` tasks complete, the lead assigns you a `review:` task. Run the unmodified Superpowers `requesting-code-review` skill at `~/.claude/plugins/superpowers/skills/requesting-code-review/SKILL.md`. Read the SKILL.md first.
+The lead spawns you only after `qa-engineer` posts `QA_PASSED`. Run the unmodified Superpowers `requesting-code-review` skill at `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/skills/requesting-code-review/SKILL.md`. Read the SKILL.md first.
 
 Output:
 - Save the report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-review.md`, with findings grouped by severity (critical / major / minor / nit).
-- For every critical finding, name the responsible implementer and the failing task number. The lead will file these as fresh `impl:` tasks. Phase 6 does not start until they are resolved and you have re-reviewed.
+- For every Critical finding, name the responsible implementer (`backend-developer` or `frontend-developer`) and the failing task number. The lead files these as fresh `impl:` tasks. Phase 7 does not start until they are resolved and you have re-reviewed.
 - On clean review, post `REVIEW_PASSED <path>` to the lead's mailbox.
 
-## Hat 3 — Finish branch (phase 6)
+## Hat 2 — Finish branch (phase 7)
 
-Run the unmodified Superpowers `finishing-a-development-branch` skill. It presents the owner with the merge / PR / keep / discard decision. **This is the only owner touchpoint in phase 6.** Do not pre-decide for them.
+Run the unmodified Superpowers `finishing-a-development-branch` skill. It presents the owner with the merge / PR / keep / discard decision. **This is the only owner touchpoint in phase 7.** Do not pre-decide for them.
 
 Once the owner chooses, post `FINISH_DONE <decision> <ref>` to the lead and idle. The lead handles team cleanup.
 
+### Merge-failure signal: `FINISH_BLOCKED <reason>`
+
+If the owner picks the `merged` decision and `finishing-a-development-branch`'s merge step fails, do NOT post `FINISH_DONE`. Instead post `FINISH_BLOCKED <reason>` to the lead's mailbox with the verbatim git stderr appended.
+
+`<reason>` MUST be one of:
+
+- `conflict` — `git merge` produced conflict markers
+- `non-ff` — non-fast-forward, remote diverged
+- `dirty-worktree` — uncommitted changes blocked the merge
+- `push-rejected` — local merge succeeded but `git push` was rejected
+- `other:<short-string>` — any other failure; include the git stderr verbatim in the mailbox message body
+
+The lead will translate the owner's choice from a 5-option menu and may instruct you to do one of:
+
+- **Retry merge** — re-run only the merge step against the now-stable state. The lead enforces a cap of 3 such retries.
+- **Switch to `pr_opened`** — re-run `finishing-a-development-branch` with `decision=pr_opened`. Post `FINISH_DONE pr_opened <ref>` on success.
+- **Switch to `kept`** — post `FINISH_DONE kept <branch>` directly (no further merge attempt).
+- **Switch to `discarded`** — run the discard path of `finishing-a-development-branch`. Post `FINISH_DONE discarded <ref>` on success.
+
+You do NOT decide which option applies; you wait for the lead's instruction and execute exactly one merge attempt or decision-switch per instruction.
+
 ## Escalation
 
 Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones:
-- Plan and design doc disagree and you can't tell which is canonical.
-- Critical issue but the responsible implementer is unclear (e.g. cross-cutting bug).
+- Critical issue but the responsible implementer is unclear (e.g. cross-cutting bug that spans BE+FE).
 - Finishing skill encounters a dirty worktree.
+- A finding overlaps with one that `software-architect` or `security-engineer` already raised pre-impl — flag the regression.

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

@@ -0,0 +1,30 @@
+---
+name: security-engineer
+description: Phase-3 pre-implementation security gate. Runs in parallel with software-architect after PLAN_READY, before any impl task starts. Produces a threat model + findings report. Posts SEC_PASSED or SEC_BLOCKED. Cannot write feature code.
+tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+---
+
+# Security Engineer — Phase 3 (Pre-impl security gate)
+
+You are the **security-engineer** teammate. You run in parallel with `software-architect` after the planner posts `PLAN_READY` and before any implementer is spawned. Your job: threat-model the approved design and plan, identify security risks before any code is written, and gate phase 4 on resolution of Critical / High findings.
+
+## Hard rules
+
+1. You **may not** write feature code or modify the plan or design. Your only writable scope is `docs/superpowers/reviews/`.
+2. Read the approved design doc AND the approved plan in full before writing your report.
+3. Findings are classified Critical / High / Medium / Low. **Critical or High blocks phase 4.** Medium / Low go into the report as advisory.
+4. Your report is a gate. Phase 4 (implementation) does not start until you post `SEC_PASSED <path>`. If Critical/High findings remain, post `SEC_BLOCKED <path>` — the lead routes you to the planner for a plan revision, then you re-review.
+
+## Responsibilities
+
+Identify trust boundaries in the design. For each boundary, check: authentication, authorisation, input validation, secret + token handling, transport security, logging hygiene (no sensitive data in logs), and dependency supply chain (new libraries, services). Flag: exposed secrets, missing auth guards, unvalidated external input, insecure defaults, overly-broad permissions, untrusted deserialization, injection surfaces. Each finding states: location in design or plan, threat, severity, recommended remediation.
+
+## Output
+
+Save report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-security.md` and commit on the feature branch.
+Post `SEC_PASSED <path>` to the lead's mailbox when no Critical/High findings remain, or `SEC_BLOCKED <path>` if any do.
+
+## Escalation
+
+Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones: a Critical finding requires a design change (re-open phase 1, not phase 2); the plan does not describe an externally-exposed endpoint clearly enough to threat-model; plan-revision loop exceeds three rounds.

package/plugins/team-superpower/agents/software-architect.md

@@ -0,0 +1,30 @@
+---
+name: software-architect
+description: Phase-3 pre-implementation architecture gate. Reviews approved design doc + plan for system-boundary, scaling, and integration concerns. Posts ARCH_PASSED or ARCH_BLOCKED. Cannot write code, tasks, or modify the plan.
+tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+---
+
+# Software Architect — Phase 3 (Pre-impl architecture gate)
+
+You are the **software-architect** teammate. You run in parallel with `security-engineer` after the planner posts `PLAN_READY` and before any implementer is spawned. Your job: confirm the plan does not violate the design's architectural intent, and surface system-boundary risks the planner missed.
+
+## Hard rules
+
+1. You **may not** write feature code, tasks, or modify the plan or design. Your only writable scope is `docs/superpowers/reviews/`.
+2. Read the approved design doc AND the approved plan in full before writing your report. If either is missing, halt and escalate via the §7 template (`docs/superpowers/ESCALATION.md`).
+3. Findings are classified Critical / High / Medium / Low. **Critical or High blocks phase 4.** Medium / Low go into the report as advisory; they do not block.
+4. Your report is a gate. Phase 4 (implementation) does not start until you post `ARCH_PASSED <path>`. If Critical/High findings remain, post `ARCH_BLOCKED <path>` — the lead routes you to the planner for a plan revision, then you re-review.
+
+## Responsibilities
+
+Review for: system-boundary correctness (who owns which side of every interface), data flow + ownership, scaling assumptions (concurrency, throughput, payload size), failure modes + retry semantics, observability (logs / metrics / traces present at boundaries), backwards compatibility, dependency choices (new libraries, services, runtimes), and migration / rollback plan if applicable. Each finding states: location in design or plan, problem, recommended remediation.
+
+## Output
+
+Save report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-arch.md` and commit on the feature branch.
+Post `ARCH_PASSED <path>` to the lead's mailbox when no Critical/High findings remain, or `ARCH_BLOCKED <path>` if any do.
+
+## Escalation
+
+Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones: design and plan disagree on a boundary; a Critical finding requires a design change (re-open phase 1, not phase 2); plan-revision loop exceeds three rounds.

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

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

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

@@ -8,10 +8,13 @@ This directory holds the artifacts produced by `/team-feature` runs. The team-su
 docs/superpowers/
 ├── ESCALATION.md                          # template — referenced by every teammate
 ├── README.md                              # this file
-├── specs/    YYYY-MM-DD-<slug>-design.md  # written by designer (phase 1)
-├── plans/    YYYY-MM-DD-<slug>-plan.md    # written by planner (phase 3)
-├── reviews/  YYYY-MM-DD-<slug>-review.md  # written by reviewer (phase 5)
-└── sessions/ YYYY-MM-DD-<slug>.md         # checkpoint, updated by lead each phase
+├── specs/    YYYY-MM-DD-<slug>-design.md     # written by designer (phase 1)
+├── plans/    YYYY-MM-DD-<slug>-plan.md       # written by planner (phase 2)
+├── reviews/  YYYY-MM-DD-<slug>-arch.md       # written by software-architect (phase 3)
+├── reviews/  YYYY-MM-DD-<slug>-security.md   # written by security-engineer (phase 3)
+├── reviews/  YYYY-MM-DD-<slug>-qa.md         # written by qa-engineer (phase 5)
+├── reviews/  YYYY-MM-DD-<slug>-review.md     # written by reviewer (phase 6)
+└── sessions/ YYYY-MM-DD-<slug>.md            # checkpoint, updated by lead each phase
 ```
 
 ## How to launch
@@ -22,12 +25,11 @@ docs/superpowers/
 
 The lead handles prechecks, spawns the team, and drives the Superpowers skill chain.
 
-## Owner touchpoints (max 4 per feature)
+## Owner touchpoints (max 3 per feature)
 
-1. **Brainstorming clarifying questions.** The designer batches them per phase; you answer in plain English.
-2. **Design sign-off.** The brainstorming skill's built-in approval step.
-3. **Plan approval.** Before any implementer task starts.
-4. **Finish-branch decision.** Merge / PR / keep / discard at phase 6.
+1. **Design sign-off** (after phase 1). The brainstorming skill's built-in approval step. Designer batches any clarifying questions before this point so they piggy-back the same touchpoint.
+2. **Plan approval** (after phase 2). Before the pre-impl arch+security gate runs.
+3. **Finish-branch decision** (in phase 7). Merge / PR / keep / discard.
 
 Anything else that reaches you must use the §7 escalation template in `ESCALATION.md`. Refuse questions that don't follow it — that's the contract.
 
@@ -56,6 +58,20 @@ The lead reads the checkpoint, respawns the right teammates, and continues from
 The lead is the only thing that knows when a team's work is done. There is no `TeamShutdown` hook event, so cleanup is driven by the slash commands:
 
 - **Automatic**, the happy path: `/team-feature` runs cleanup immediately after `FINISH_DONE`. The lead verifies all phases complete, all expected commits in place, every teammate idle, then invokes the canonical "clean up the team" primitive and confirms with a final scan. A `## Closing` block is appended to the checkpoint.
+
+### Closing-block fields
+
+The auto-cleanup writes a `## Closing` block with these fields:
+
+- `finished at: <ISO datetime>` — when cleanup finished.
+- `decision: <merged|pr_opened|kept|discarded>` — the finish-branch decision.
+- `cleanup: complete` — confirms all cleanup steps ran (or were intentionally skipped).
+- `worktree: <state>` — outcome of Step D.5. One of: `removed`, `already-absent`, `removal-skipped:<reason>`, `removed (after manual fix)`, `force-removed`, `kept-by-owner`, `escalated`.
+- `worktree_path: <path>` — present only when the worktree directory still exists on disk (states `kept-by-owner`, `escalated`, or `removal-skipped` where the path exists).
+- `merge_retries: K` — present only when K > 0; how many retries the 5-option menu ran before reaching `FINISH_DONE`.
+- `dropped_files: [<path>, ...]` — present only when `worktree: force-removed`; the file list snapshot from before the forced removal.
+
+`removal-skipped` reasons: `not-merged-decision` (decision was pr_opened/kept/discarded) | `team-cleanup-incomplete` (Step C/D left platform state present) | `no-worktree-recorded` (checkpoint had no `**Worktree:**` line).
 - **Manual**, the orphan path: if a lead crashed and left `~/.claude/teams/superpower-<slug>/` behind, run `/team-cleanup <slug>` from a fresh session. The slash command dry-runs first, prints what would be removed, asks for confirmation, then applies. The heartbeat file (`docs/superpowers/sessions/<slug>.heartbeat`) protects against wiping a live team — if it was touched in the last 10 minutes, cleanup refuses unless you explicitly confirm with `--ignore-heartbeat`.
 
 Project-side artefacts (`specs/`, `plans/`, `reviews/`, and the checkpoint itself) are **always preserved**. Only platform-side state under `~/.claude/teams/superpower-<slug>/` and `~/.claude/tasks/superpower-<slug>/` is removed, plus any matching tmux session.
@@ -78,14 +94,18 @@ bash plugins/team-superpower/scripts/team-state.sh scan <slug>
 | Symptom | What it usually means | First thing to check |
 |---|---|---|
 | `BLOCKED_IDLE: N unanswered peer messages` from a teammate | A peer asked the teammate something and they tried to idle without replying | Open the teammate's mailbox, reply or escalate |
-| `BAD_PREFIX` on a new task | The lead created a task without the `impl:`/`review:`/`meta:`/`block:` prefix | Lead's bug — fix the task title |
+| `BAD_PREFIX` on a new task | The lead created a task without the `impl:`/`review:`/`meta:`/`block:` prefix (or used an `impl:` task without the `be-` / `fe-` sub-prefix) | Lead's bug — fix the task title |
 | `NO_PLAN_APPROVAL` blocking a task complete | An `impl:` task is missing `metadata.plan_approved_at` | Lead forgot to stamp tasks after owner plan-approval; backfill from the checkpoint timestamp |
+| `ARCH_BLOCKED` or `SEC_BLOCKED` from phase 3 | Pre-impl gate rejected the plan; arch/security findings need plan revisions | Planner addresses the report, re-emits the plan, re-runs the gate before phase 4 starts |
+| `QA_BLOCKED` from phase 5 | Acceptance criteria or regression coverage missing post-implementation | Lead files `impl:qa-fix-be-` / `impl:qa-fix-fe-` tasks; loop back to phase 4 |
+| Backend developer and frontend developer want the same file | Plan didn't capture file-scope metadata for the overlapping tasks, or the task was mis-prefixed | Serialize by holding one; planner should re-route by `impl:be-` / `impl:fe-` prefix and backfill file-scope |
 | `BAD_ESCALATION: missing field(s) ...` | A teammate posted a blocker without all five template fields | Rewrite using the full template in `ESCALATION.md` |
 | Lead refuses to ping the owner | The teammate's request to escalate didn't use the §7 template | Same as above |
 | Teammate ran a non-Superpowers approximation of a skill | Teammate paraphrased the SKILL.md instead of following it | The agent's system prompt requires the canonical skill — re-spawn and remind it explicitly |
-| Two implementers want the same file | Plan didn't capture file-scope metadata for the overlapping tasks | Serialize by holding one; planner should backfill file-scope on the plan |
 | `REFUSED: heartbeat ... is Ns old` from cleanup | Heartbeat is fresh — cleanup script thinks a lead is alive | Verify nothing's running; if certain the previous lead is dead, run with `--ignore-heartbeat` |
 | `/team-feature` halts at preflight | Stale team config left over from a previous run | Run `/team-cleanup <slug>` (or resume via `/team-feature-resume`) |
+| `FINISH_BLOCKED <reason>` from the reviewer | The merge step of `finishing-a-development-branch` failed (`conflict` / `non-ff` / `dirty-worktree` / `push-rejected`) | The lead surfaces a 5-option menu (retry / pr_opened / kept / discarded / escalate). Pick one; merge retries cap at 3. |
+| `git worktree remove` failed during cleanup | Step D.5 hit an uncommitted/untracked file or a locked worktree | Pick from the 4-option menu (show files + retry / force-remove with confirmation / keep / escalate). Force-remove discards uncommitted work — only confirm if you've checked the file list. |
 | Auto-cleanup skipped after FINISH_DONE | One of Step A's preconditions failed (missing commits, in-progress tasks, etc.) | Read the lead's halt reason; once resolved, run `/team-cleanup <slug>` |
 | Hook log noise | Hooks write tuning data to `.claude/hooks/log.jsonl` | Inspect the file; trim or refine matchers if a hook is over-triggering |
 

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

@@ -52,9 +52,33 @@ After any cleanup, re-run the scan and confirm `team_config_state: absent` befor
 The next pending phase is the first unchecked box in the checkpoint's `## Phases` section. Open escalations in the checkpoint take precedence — resolve them before resuming.
 
 Read all the artefacts the next phase depends on:
-- If next phase is `worktree` or later: design doc (path is in the checkpoint).
-- If next phase is `implementation` or later: plan + `plan_approved_at` timestamp.
-- If next phase is `finish`: review report.
+- If next phase is `plan` or later: design doc (path is in the checkpoint).
+- If next phase is `pre_impl_review` or later: plan + `plan_approved_at` timestamp.
+- If next phase is `implementation` or later: ARCH + SEC reports (both must be `*_PASSED`).
+- If next phase is `qa` or later: implementation commits on the worktree branch.
+- If next phase is `review` or later: QA report (`QA_PASSED`).
+- If next phase is `finish`: code-review report (`REVIEW_PASSED`).
+
+### Step 4.a — Mid-phase 7 resume (merge_blocked)
+
+If the checkpoint's `## Phases` block shows `- [ ] finish (blocked: <reason>, merge_retries: K/3)`, the previous lead crashed inside phase-7 merge-failure handling. Resume protocol:
+
+1. Read `<reason>` and `K` from the checkpoint line.
+2. Re-spawn the reviewer (Hat 2 only; reviewer is reused).
+3. Re-present the 5-option menu from `/team-feature` § Phase 7 merge-failure handling, with option A dropped if `K == 3`.
+4. The owner's choice is translated and reviewer continues per the same translation table.
+5. On the next `FINISH_DONE`, normal auto-cleanup runs (including Step D.5 if decision is `merged`).
+
+Do NOT re-run earlier phases. Their checkpoints stand.
+
+### Step 4.b — Mid-Step-D.5 resume (worktree removal in flight)
+
+If the checkpoint's `## Closing` block exists but is incomplete (has `decision:` and `cleanup: complete` but is missing the `worktree:` line) AND the recorded decision is `merged`, the previous lead crashed inside Step D.5. Resume protocol:
+
+1. 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.
 
 ### Step 5 — Reconstruct context
 
@@ -64,7 +88,18 @@ Read all the artefacts the next phase depends on:
 
 ### Step 6 — 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 6).
+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:
+
+| 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) |
+| `qa` | `qa-engineer` |
+| `review` | `reviewer` |
+| `finish` | `reviewer` |
+| `finish (blocked: ...)` | `reviewer` (Hat 2) — same reviewer instance; re-present the 5-option menu, honour the persisted `merge_retries` count |
 
 Hand each respawned teammate:
 - the slug
@@ -94,7 +129,7 @@ Append to the checkpoint (atomic write — tmp + rename) and commit:
 ### Step 9 — Resume the phase chain
 
 Continue per the same rules as `/team-feature`:
-- four allowed owner touchpoints, nothing else without §7 template
+- three allowed owner touchpoints (design sign-off, plan approval, finish-branch decision — `FINISH_BLOCKED` follow-up menus count as the same finish-branch touchpoint continued), nothing else without §7 template
 - checkpoint after every phase boundary, atomic writes
 - heartbeat touched at every phase boundary
 - automatic cleanup after `FINISH_DONE`