@drunkcoding/agents-and-skills 0.0.7 → 0.0.9

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "tech-graph",
       "source": "./plugins/tech-graph",
       "description": "6-step wizard for technical diagrams (SVG/PNG) via fireworks-tech-graph",
-      "version": "0.0.7",
+      "version": "0.0.9",
       "category": "diagram",
       "keywords": [
         "diagram",
@@ -26,7 +26,7 @@
       "name": "html-effectiveness",
       "source": "./plugins/html-effectiveness",
       "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
-      "version": "0.0.7",
+      "version": "0.0.9",
       "category": "reports",
       "keywords": [
         "html",
@@ -36,6 +36,22 @@
         "slide-deck",
         "decision-matrix"
       ]
+    },
+    {
+      "name": "team-superpower",
+      "source": "./plugins/team-superpower",
+      "description": "Coordination layer that runs the obra/superpowers skill chain across a Claude Code agent team — one /team-feature command takes an idea through brainstorming, plan, TDD implementation, review, and finish with at most 4 owner touchpoints.",
+      "version": "0.0.9",
+      "category": "workflow",
+      "keywords": [
+        "agent-teams",
+        "superpowers",
+        "tdd",
+        "orchestration",
+        "workflow",
+        "brainstorming",
+        "code-review"
+      ]
     }
   ]
 }

package/README.md

@@ -10,6 +10,7 @@ Published on npm as [`@drunkcoding/agents-and-skills`](https://www.npmjs.com/pac
 |--------|-------------|
 | [`tech-graph`](plugins/tech-graph) | 6-step wizard for technical diagrams (SVG + PNG). |
 | [`html-effectiveness`](plugins/html-effectiveness) | Conversational agent that generates self-contained interactive HTML reports from 20 templates. |
+| [`team-superpower`](plugins/team-superpower) | Agent-team conductor that runs the obra/superpowers skill chain end-to-end with at most 4 owner touchpoints. |
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Personal collection of Claude Code skills and agents, installable via `npx skills`.",
   "keywords": [
     "claude-code",

package/plugins/html-effectiveness/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "html-effectiveness",
   "displayName": "HTML Effectiveness Reports",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"
@@ -19,5 +19,8 @@
   ],
   "agents": [
     "agents/report-builder.md"
+  ],
+  "commands": [
+    "commands/html-report.md"
   ]
 }

package/plugins/html-effectiveness/commands/html-report.md

@@ -0,0 +1,13 @@
+---
+description: Conversational wizard that renders dense info as a self-contained interactive HTML report (status, incident, PR writeup, slide deck, decision matrix, ...).
+argument-hint: [optional one-line intent or path to existing .data.json]
+---
+
+Dispatch the `report-builder` subagent using the Agent tool. Pass `$ARGUMENTS` (which may be empty) as the initial intent seed in the subagent prompt.
+
+Subagent dispatch prompt template:
+
+> Run the html-effectiveness report wizard. Initial intent seed: `$ARGUMENTS`.
+> If the seed looks like a path to an existing `*.data.json` sidecar, enter the regen flow: load it, ask which slots to change, re-render. Otherwise classify the intent against `plugins/html-effectiveness/templates/manifest.json`, confirm the template pick with the user, fill slots (cap 6 questions), preview the data JSON, then render via `plugins/html-effectiveness/scripts/render.js`. Respect `html-effectiveness.reportDir` from repo `CLAUDE.md` (fallback `docs/reports/`).
+
+Do not render or write files in the main thread — the subagent owns the full wizard and the render call.

package/plugins/team-superpower/.claude-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "team-superpower",
+  "displayName": "Team Superpower",
+  "version": "0.0.9",
+  "description": "Coordination layer that runs the obra/superpowers skill chain across a Claude Code agent team — one /team-feature command takes an idea through brainstorming, plan, TDD implementation, review, and finish with at most 4 owner touchpoints.",
+  "author": {
+    "name": "Steven Hoang"
+  },
+  "keywords": [
+    "agent-teams",
+    "superpowers",
+    "tdd",
+    "orchestration",
+    "workflow",
+    "brainstorming",
+    "code-review"
+  ],
+  "agents": [
+    "agents/designer.md",
+    "agents/planner.md",
+    "agents/implementer.md",
+    "agents/reviewer.md"
+  ],
+  "commands": [
+    "commands/team-feature.md",
+    "commands/team-feature-resume.md",
+    "commands/team-cleanup.md"
+  ],
+  "hooks": "hooks/hooks.json"
+}

package/plugins/team-superpower/README.md

@@ -0,0 +1,150 @@
+# team-superpower
+
+Coordination layer that runs the [obra/superpowers](https://github.com/obra/superpowers) skill chain across a Claude Code **agent team**. One `/team-feature` command takes an idea through brainstorming → worktree → plan → TDD implementation → review → finish, with at most **4 owner touchpoints**.
+
+This plugin is *not* a fork of Superpowers. It consumes Superpowers skills as-installed and only adds the orchestration: who runs which skill, when, and how teammates talk without bothering the owner.
+
+## What you get
+
+- Three slash commands: `/team-feature`, `/team-feature-resume`, `/team-cleanup`.
+- Four agent roles, each with a tightly-scoped system prompt mapping it to specific Superpowers skills:
+  - `designer` — runs `brainstorming`.
+  - `planner` — runs `using-git-worktrees`, then `writing-plans`.
+  - `implementer` — runs `subagent-driven-development` + `test-driven-development` per task.
+  - `reviewer` — runs `requesting-code-review`, then `finishing-a-development-branch`.
+- Three guardrail hooks (registered automatically via `hooks/hooks.json`):
+  - `TeammateIdle` — refuses idle while peer mail is unanswered.
+  - `TaskCreated` — enforces `impl:`/`review:`/`meta:`/`block:` task title prefixes.
+  - `TaskCompleted` — gates `impl:` completions on `plan_approved_at` and validates escalation entries.
+- `scripts/team-state.sh` — the inspection + cleanup helper. Called by the slash commands; also runnable directly.
+- Robustness primitives baked into the workflow:
+  - **Preflight scan** in `/team-feature` and `/team-feature-resume` — detects orphaned team config, stale task lists, and in-flight runs before doing anything destructive.
+  - **Heartbeat file** at `docs/superpowers/sessions/<slug>.heartbeat` — touched at every phase boundary; cleanup refuses to wipe state while the heartbeat is fresh.
+  - **Atomic checkpoint writes** (tmp + rename) — half-written checkpoints can't corrupt recovery.
+  - **Automatic cleanup after `FINISH_DONE`** — the lead verifies all phases complete, all commits in place, teammates idle, then runs the canonical "clean up the team" primitive followed by a verification scan. No manual `rm -rf` required.
+  - **`/team-cleanup [slug]`** for the case where a previous lead crashed and the canonical cleanup path is no longer available.
+- Templates seeded into your project on first use: `docs/superpowers/ESCALATION.md` (escalation template + 2 worked examples) and `docs/superpowers/README.md` (onboarding + troubleshooting).
+
+## Requirements
+
+- Claude Code `2.1.32` or later.
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your environment (the slash command will halt if absent).
+- The Superpowers plugin installed: `/plugin install superpowers@claude-plugins-official`.
+- `jq` on `$PATH` (the hooks degrade to log-only when missing, but you want them enforcing).
+
+## Install
+
+```text
+/plugin marketplace add baoduy/agents-and-skills
+/plugin install team-superpower@drunkcoding
+```
+
+Then make sure the agent-teams env flag is set in `~/.claude/settings.json`:
+
+```json
+{
+  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
+  "teammateMode": "in-process"
+}
+```
+
+## Use
+
+```text
+/team-feature add a /healthcheck endpoint that returns 200 OK
+```
+
+You will be interrupted at most four times:
+
+1. Brainstorming clarifying questions (batched per phase).
+2. Design sign-off.
+3. Plan approval.
+4. Finish-branch decision (merge / PR / keep / discard).
+
+Anything else that reaches you uses the escalation template in `docs/superpowers/ESCALATION.md`. If a teammate pings you without using the template, that's a bug — file it.
+
+## Resume after `/resume` drops the team
+
+```text
+/team-feature-resume YYYY-MM-DD-<slug>.md
+```
+
+The lead reads the committed checkpoint in `docs/superpowers/sessions/`, scans `~/.claude/teams/superpower-<slug>/` for orphaned platform state, runs cleanup if the heartbeat indicates the previous lead is dead, then respawns the right teammates and continues from the next unchecked phase. Completed phases are not redone.
+
+## Clean up after a crashed lead
+
+```text
+/team-cleanup <slug>
+/team-cleanup --all
+```
+
+Use this when a previous lead died (terminal closed, `/resume` lost the team, OS killed the process) and left `~/.claude/teams/superpower-<slug>/` behind. Project-side artefacts under `docs/superpowers/{specs,plans,reviews}` are preserved; only platform-side state is removed.
+
+The slash command dry-runs first, prints what would be removed, and asks for confirmation. The heartbeat file at `docs/superpowers/sessions/<slug>.heartbeat` is checked — if it was touched in the last 10 minutes, cleanup refuses unless the owner explicitly confirms with `--ignore-heartbeat` that the previous lead is dead.
+
+The helper script is also runnable directly:
+
+```bash
+bash plugins/team-superpower/scripts/team-state.sh scan          # list all teams
+bash plugins/team-superpower/scripts/team-state.sh scan <slug>   # inspect one
+bash plugins/team-superpower/scripts/team-state.sh cleanup <slug>          # dry-run
+bash plugins/team-superpower/scripts/team-state.sh cleanup <slug> --force  # apply
+```
+
+## Automatic cleanup after the feature ships
+
+`/team-feature` runs cleanup automatically the instant the reviewer reports `FINISH_DONE` (merge / PR / keep / discard). Before wiping anything, the lead verifies:
+
+- every phase from brainstorming through finish is complete in the checkpoint
+- the shared task list has zero in-progress tasks
+- the expected commits exist on the worktree (design, plan, TDD pairs of test + code, review report, and any merge / PR-prep commit per the finish decision)
+- all teammates are idle and shut down
+
+Only then does it invoke the canonical "clean up the team" primitive, verify with a scan that `~/.claude/teams/superpower-<slug>/` is gone, and append a `## Closing` block to the checkpoint. If any step fails, the lead halts and instructs the owner to run `/team-cleanup <slug>` manually. **No `rm -rf` runs on a half-finished feature.**
+
+## Layout
+
+```
+plugins/team-superpower/
+├── .claude-plugin/plugin.json
+├── README.md
+├── agents/
+│   ├── designer.md
+│   ├── planner.md
+│   ├── implementer.md
+│   └── reviewer.md
+├── commands/
+│   ├── team-feature.md
+│   ├── team-feature-resume.md
+│   └── team-cleanup.md
+├── hooks/
+│   ├── hooks.json
+│   ├── teammate-idle.sh
+│   ├── task-created.sh
+│   └── task-completed.sh
+├── scripts/
+│   └── team-state.sh      → inspection + cleanup helper, called by the slash commands
+└── assets/
+    ├── ESCALATION.md      → seeded to docs/superpowers/ESCALATION.md on first run
+    └── SESSION_README.md  → seeded to docs/superpowers/README.md on first run
+```
+
+## Design
+
+See the project's `docs/superpowers/README.md` after first run for the operating manual. The short version:
+
+- The **lead** is a conductor. It never runs a Superpowers skill itself.
+- Teammates run **canonical, unmodified** Superpowers skills. They are forbidden from paraphrasing or replacing them.
+- TDD is enforced by `subagent-driven-development` + `test-driven-development` per implementer task. The `TaskCompleted` hook is a backstop, not the primary control.
+- All cross-team chatter that needs an owner decision goes through the §7 escalation template. The hook spot-checks the template fields and refuses malformed escalations.
+- Every phase boundary writes a checkpoint to `docs/superpowers/sessions/<slug>.md`. That's the only thing that survives a `/resume` failure — the slash command `/team-feature-resume` reads it back.
+
+## Out of scope
+
+- Token-usage metrics per teammate per phase.
+- Per-role permission allowlists.
+- Frontend/backend specialist implementers (defer until pattern proves out).
+
+## License
+
+MIT.

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

@@ -0,0 +1,31 @@
+---
+name: designer
+description: Runs the Superpowers `brainstorming` skill end-to-end to produce an owner-approved design document. Owns phase 1 of the team-superpower workflow. Cannot write code, plans, or any artifact outside `docs/superpowers/specs/`.
+tools: Read, Write, Glob, Grep
+model: sonnet
+---
+
+# Designer — Phase 1 (Brainstorming)
+
+You are the **designer** teammate on a team-superpower agent team. The lead spawned you to run **one** Superpowers skill: `brainstorming`. Your output is a committed design document that the owner has signed off on. Nothing more.
+
+## Hard rules
+
+1. Run the unmodified Superpowers `brainstorming` skill at `~/.claude/plugins/superpowers/skills/brainstorming/SKILL.md`. Follow it verbatim. Do not invent steps, skip the visual-companion offer, or collapse the clarifying-question loop. Read the SKILL.md before you do anything else.
+2. **Never** write code, plans, worktree commands, or anything outside `docs/superpowers/specs/`.
+3. Save the design doc to `docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md` and commit it. The brainstorming skill already prescribes this; do not deviate from its filename pattern. The `<slug>` is given to you by the lead in your spawn prompt.
+4. Before sending a clarifying question to the owner, **post it to the lead via mailbox first**. The lead may answer from project context or escalate. Never DM the owner directly.
+5. Every escalation you do raise MUST use the template in `docs/superpowers/ESCALATION.md`. No exceptions, even for one-line questions.
+6. When the owner signs off on the design, post `DESIGN_APPROVED <path>` to the lead's mailbox where `<path>` is the absolute path of the design doc. Then idle.
+
+## What you must NOT do
+
+- Decide implementation strategy. The plan is the planner's job.
+- Pick a stack, framework, or library beyond what the brainstorming skill explicitly asks you to discuss with the owner.
+- Touch the worktree. There is no worktree yet — it is created in phase 2.
+- Skip the owner sign-off step inside the brainstorming skill. Phase 2 cannot start without an approved design.
+
+## When you idle
+
+- If you have unanswered inbound peer messages (`from != "lead"`, `replied == false`), the `TeammateIdle` hook will block your idle with `BLOCKED_IDLE`. Either reply or escalate per the template before going idle.
+- After `DESIGN_APPROVED` is posted, idle. The lead will not call you again for this feature.

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

@@ -0,0 +1,46 @@
+---
+name: implementer
+description: Executes one `impl:` task at a time via Superpowers `subagent-driven-development` with `test-driven-development` (RED-GREEN-REFACTOR). Owns phase 4 of the team-superpower workflow. Cannot modify the plan or touch files outside its assigned task.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# Implementer — Phase 4 (Implementation)
+
+You are an **implementer** teammate. There may be one or more of you running in parallel. Your only job: self-claim `impl:`-prefixed tasks from the shared task list and complete each one through the canonical Superpowers chain.
+
+## Hard rules
+
+1. For every task, run the unmodified Superpowers `subagent-driven-development` skill at `~/.claude/plugins/superpowers/skills/subagent-driven-development/SKILL.md`. It dispatches a fresh subagent for the task and applies the two-stage review (spec compliance, then code quality). Read the SKILL.md before claiming your first task.
+2. Inside that flow, every code change MUST go through the canonical `test-driven-development` skill: RED (failing test first) → GREEN (minimal code to pass) → REFACTOR. **If you ever realise you wrote production code before a failing test existed, delete that code and start the task over.** This is non-negotiable per the TDD skill.
+3. You **may not modify the plan**. If the plan is wrong, halt and escalate to the lead via the §7 template (`docs/superpowers/ESCALATION.md`). The lead will route it to the planner; a plan change requires owner approval.
+4. You **may not edit files assigned to another active implementer task**. Before opening any file, read the shared task list and confirm no `in-progress` task on a peer claims that path. If overlap is unavoidable, post a coordination message to the lead and wait.
+5. Mark a task complete **only** after the two-stage review inside `subagent-driven-development` passes. The `TaskCompleted` hook will reject your completion if `metadata.plan_approved_at` is missing — make sure it's stamped from the lead's plan-approval handoff.
+6. One task at a time. Do not batch.
+
+## Task claiming protocol
+
+1. Read the shared task list. Pick the lowest-numbered `impl:` task whose dependencies are all complete and whose file scope does not overlap an in-progress peer task.
+2. Mark it in-progress with your teammate id.
+3. Run subagent-driven-development.
+4. On completion (two-stage review passed): mark the task complete with the required metadata.
+
+## When the plan is wrong
+
+Escalate. Do NOT silently work around it. Example escalation:
+
+```
+BLOCKED: Task impl:add-user-endpoint specifies POST /users but design doc says PUT /users/{id}. Which is correct?
+Phase: implementation
+Context: Plan task 4 reads "POST /users → 201". Design doc §3 reads "PUT /users/{id} idempotent". I can write either but they are not equivalent and the test I'd write differs.
+Options:
+  A. Follow the plan (POST) and let reviewer flag if wrong.
+  B. Halt; planner amends; owner re-approves the plan delta.
+  C. Owner clarifies design intent directly.
+Recommendation: B — the plan is the source of truth for code, and a plan that contradicts the approved design must be reconciled before more tasks are claimed.
+Need from you: choose A/B/C.
+```
+
+## When you idle
+
+After a task completes, claim the next eligible one. If none are available and you have no unanswered inbound mail, idle. The `TeammateIdle` hook will block idle if peer mail is unanswered.

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

@@ -0,0 +1,42 @@
+---
+name: planner
+description: Runs Superpowers `using-git-worktrees` then `writing-plans`. Owns phase 2-3 of the team-superpower workflow. Halts on broken test baseline. Cannot write feature code or modify the design.
+tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+---
+
+# Planner — Phase 2 (Worktree) and Phase 3 (Plan)
+
+You are the **planner** teammate. You run two Superpowers skills sequentially: first `using-git-worktrees`, then `writing-plans`. Both must be the unmodified canonical versions from `~/.claude/plugins/superpowers/skills/`.
+
+## Phase 2 — `using-git-worktrees`
+
+1. Read `~/.claude/plugins/superpowers/skills/using-git-worktrees/SKILL.md` first.
+2. Run the skill end-to-end: create the isolated branch, run project setup, verify clean test baseline.
+3. **If the clean-test-baseline check fails, halt immediately and escalate to the lead via the §7 template (`docs/superpowers/ESCALATION.md`).** Do NOT proceed onto a broken baseline. Your escalation must include exact failing test names and the project's setup command output.
+4. When complete, post `WORKTREE_READY <path> <branch>` to the lead's mailbox.
+
+## Phase 3 — `writing-plans`
+
+1. Read `~/.claude/plugins/superpowers/skills/writing-plans/SKILL.md` first.
+2. Read the approved design doc the lead handed you (path will be in your spawn prompt).
+3. Run the skill verbatim. Every task you produce MUST be 2–5 minutes of work with **exact file paths, complete code, and explicit verification steps**. Anything vaguer than that — fix it before posting.
+4. Each task in the plan MUST also declare:
+   - the files it will touch (so the lead can serialize overlapping tasks)
+   - a dependency list (which task numbers must complete first)
+5. Save the plan to `docs/superpowers/plans/YYYY-MM-DD-<slug>-plan.md` and commit it.
+6. **Before submitting the plan to the lead**, post the draft to the `reviewer` teammate's mailbox for a sanity-check round (not a full review — just: matches the design doc, task sizing is right, verification steps present). Wait one round. Incorporate or rebut the reviewer's points; do not start a debate loop.
+7. Then post `PLAN_READY <path>` to the lead, who will route it to the owner for approval.
+
+## Hard rules
+
+- The plan **may not** modify or contradict the approved design doc. If a planning detail forces a design change, halt and escalate to the lead — the design must be re-approved before the plan can change.
+- You **may not** write feature code. None. Not even a stub. The plan describes code; the implementer writes it.
+- You **may not** mark the plan complete until the owner approves it. The lead will tell you.
+
+## Escalation
+
+Use the §7 template from `docs/superpowers/ESCALATION.md` for any blocker. Common ones:
+- Test baseline is red.
+- Design doc is ambiguous on a load-bearing decision.
+- A task can't be cut to under 5 minutes without losing meaning — flag it instead of hiding the bloat.

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

@@ -0,0 +1,47 @@
+---
+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.
+tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+---
+
+# Reviewer — Phase 3 sanity check, Phase 5 review, Phase 6 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.
+
+## 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.
+
+## Hat 1 — Plan sanity check (phase 3, mailbox round)
+
+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?
+
+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.
+
+## Hat 2 — Final code review (phase 5)
+
+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.
+
+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.
+- On clean review, post `REVIEW_PASSED <path>` to the lead's mailbox.
+
+## Hat 3 — Finish branch (phase 6)
+
+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.
+
+Once the owner chooses, post `FINISH_DONE <decision> <ref>` to the lead and idle. The lead handles team cleanup.
+
+## 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).
+- Finishing skill encounters a dirty worktree.

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

@@ -0,0 +1,47 @@
+# Escalation template (team-superpower)
+
+Every owner-facing question and every "I'm blocked" peer message MUST use this exact format. The `TaskCompleted` hook spot-checks for the field labels, and the lead refuses to forward escalations that don't match.
+
+## Template
+
+```
+BLOCKED: <one-line question>
+Phase: <brainstorming | worktree | plan | implementation | review | finish>
+Context: <2-4 sentences — what we tried, what we considered, why we are stuck>
+Options:
+  A. <option> — <trade-off>
+  B. <option> — <trade-off>
+  C. <option> — <trade-off>  (optional)
+Recommendation: <our pick + one-sentence why>
+Need from you: <choose one | yes/no | other>
+```
+
+All five labels (`Phase`, `Context`, `Options`, `Recommendation`, `Need from you`) MUST appear. Missing any → the hook blocks the task completion with `BAD_ESCALATION: missing field(s) ...`.
+
+## Worked example 1 — peer-to-peer (planner → designer)
+
+```
+BLOCKED: Acceptance criterion "fast" on req #4 is not measurable. What does "fast" mean here?
+Phase: plan
+Context: I am sizing tasks for the search endpoint. Design doc §4 says "results must come back fast." The plan needs a concrete number so the test the implementer writes can fail until the number is hit. I considered defaulting to "p95 < 200ms on a 10k-row fixture" but that's me guessing on the owner's behalf.
+Options:
+  A. Adopt p95 < 200ms on the 10k-row fixture and proceed — designer can re-open if wrong.
+  B. Pause planning; designer amends the design doc with a measurable number; owner re-approves the doc delta.
+  C. Drop the criterion from the plan and tag it as a follow-up.
+Recommendation: B — "fast" is the kind of vague that costs a rewrite later, and the design doc is the right place to fix it once.
+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?
+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.
+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.
+  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.
+```

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

@@ -0,0 +1,98 @@
+# Superpowers session workspace
+
+This directory holds the artifacts produced by `/team-feature` runs. The team-superpower plugin seeds it on first use; afterwards, the design / plan / review / checkpoint files for each feature are written by the team and committed.
+
+## Layout
+
+```
+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
+```
+
+## How to launch
+
+```text
+/team-feature <one-line feature idea>
+```
+
+The lead handles prechecks, spawns the team, and drives the Superpowers skill chain.
+
+## Owner touchpoints (max 4 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.
+
+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.
+
+## Reading a checkpoint
+
+`sessions/YYYY-MM-DD-<slug>.md` is the source of truth for in-flight features. Each phase boundary appends or updates:
+
+- The `## Phases` checklist (which phases are done, file paths to the artifacts).
+- The `## Teammates` block (role, agent id, current task or `idle`).
+- The `## Open escalations` block (anything blocking the owner or a peer).
+
+The lead commits this file after every phase transition. If the lead crashes, your feature lives in this file.
+
+## Recovery — `/team-feature-resume`
+
+If `/resume` drops the team mid-feature (the platform doesn't restore in-process teammates yet), use:
+
+```text
+/team-feature-resume <checkpoint-filename>
+```
+
+The lead reads the checkpoint, respawns the right teammates, and continues from the next unchecked phase. Completed phases are not redone. A resume-log entry is appended to the checkpoint for the audit trail.
+
+## Cleanup model
+
+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.
+- **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.
+
+## Heartbeat protocol
+
+The lead touches `docs/superpowers/sessions/<slug>.heartbeat` at every phase boundary. Future sessions read its mtime to decide whether a previous lead is still alive:
+
+- mtime < 10 minutes → lead is likely alive; cleanup refuses without explicit override.
+- mtime ≥ 10 minutes (or file missing) → safe to clean up.
+
+If you ever want to confirm liveness manually:
+
+```bash
+bash plugins/team-superpower/scripts/team-state.sh scan <slug>
+```
+
+## Troubleshooting
+
+| 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 |
+| `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 |
+| `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`) |
+| 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 |
+
+## Emergency bypass
+
+`--dangerously-skip-permissions` will let a single task ship without the hooks firing. **Don't.** The hooks exist because Superpowers gates exist. Use the escalation template to surface the blocker properly.
+
+## Where the methodology lives
+
+The team-superpower plugin is purely the coordination layer. The actual development discipline (TDD, plan format, two-stage review, branch hygiene) is owned by the upstream [obra/superpowers](https://github.com/obra/superpowers) skills. If a skill's behaviour changes, the team picks it up automatically — agents reference skills by name, not by content.