@drunkcoding/agents-and-skills 0.0.7 → 0.0.9

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

@@ -0,0 +1,70 @@
+---
+description: Inspect and clean up team-superpower team state — orphaned configs, task lists, tmux sessions left by a dead lead.
+argument-hint: [slug] | --all
+---
+
+Inspect and (with owner confirmation) remove orphaned team-superpower state from `~/.claude/teams/superpower-*/` and `~/.claude/tasks/superpower-*/`. Preserves project-side artefacts (`docs/superpowers/{specs,plans,reviews}`) — only platform-side state is removed.
+
+Argument:
+
+$ARGUMENTS
+
+## What "orphaned" means
+
+A team is orphaned when:
+
+- Its team config lives at `~/.claude/teams/superpower-<slug>/` but the lead process is dead, so no Claude Code session can talk to it.
+- The agent-teams runtime can't reuse it because the lead-for-a-team is fixed for that team's lifetime (per [docs](https://code.claude.com/docs/en/agent-teams)).
+- The canonical "ask the lead to clean up" path is unavailable because there is no lead.
+
+This command is the manual fallback for that case. **If a live lead exists, do not use this command** — message the lead and ask it to "clean up the team" via the native primitive instead.
+
+## Procedure
+
+Run the helper script `${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh` to do the work. It accepts a subcommand and treats every destructive operation as opt-in (`--force`).
+
+### Step 1 — Decide scope
+
+- If `$ARGUMENTS` is empty: run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan` and show the output to the owner. Ask which slug to clean (or `--all`).
+- If `$ARGUMENTS` is `--all`: enumerate every slug from the scan and process each in turn.
+- Otherwise treat `$ARGUMENTS` as the slug.
+
+### Step 2 — Inspect
+
+For the chosen slug, run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>`. Quote the output verbatim to the owner. Pay attention to the `liveness` line:
+
+| `liveness` | What it means | What to do |
+|---|---|---|
+| `LIKELY ALIVE` | Heartbeat is < 10min old | **Stop.** Tell the owner the previous lead may still be running. Ask them to verify nothing is in flight before forcing cleanup. |
+| `stale` or `unknown` | Heartbeat old or absent | Proceed to step 3. |
+
+### Step 3 — Dry-run
+
+Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug>` (no `--force`). Exit code 1 with a "would remove" list is expected. Quote the list to the owner.
+
+If exit code is 4, there is nothing to clean — report and exit.
+
+### Step 4 — Confirm and apply
+
+Ask the owner to confirm the dry-run list. On confirmation, run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug> --force`.
+
+- Exit code 0: report success and show the appended `## Cleanup` block from the checkpoint.
+- Exit code 3 (heartbeat refusal): the owner confirmed nothing is in flight, but the heartbeat is fresh. Re-run with `--force --ignore-heartbeat` only after the owner re-confirms in writing (in the chat) that the previous lead is dead.
+
+### Step 5 — Verify
+
+Re-run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>` and confirm `team_config_state: absent` and `task_list_state: absent`.
+
+## What this command will NOT do
+
+- It will not touch any project-side files except to append a `## Cleanup` block to the checkpoint markdown.
+- It will not delete the design doc, plan, or review report — those are the durable record of the work and are kept regardless.
+- It will not run when there is a live lead. The heartbeat refusal is the safety check.
+- It will not iterate `--all` without per-slug owner confirmation when any slug shows `LIKELY ALIVE`.
+
+## When to use
+
+- After `/resume` left a team config behind that no current session can talk to.
+- After a crash or kill of the lead mid-feature.
+- Before `/team-feature` if the preflight scan there reports orphaned state.
+- Routinely after an in-flight feature is abandoned.

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

@@ -0,0 +1,111 @@
+---
+description: Resume a team-superpower workflow from a committed checkpoint file in docs/superpowers/sessions/. Handles stale team state from a dead lead.
+argument-hint: <checkpoint-filename>
+---
+
+You are the **lead** resuming an in-flight team-superpower workflow. `/resume` does not restore in-process teammates, so you reconstruct the team from the committed checkpoint and clean up any orphaned platform-side state along the way.
+
+Checkpoint argument:
+
+$ARGUMENTS
+
+## Resume protocol (strict order)
+
+### Step 1 — Locate the checkpoint
+
+If `$ARGUMENTS` is a bare filename, prefix `docs/superpowers/sessions/`. Read it. If it doesn't exist or fails to parse against the checkpoint format from `/team-feature`, halt and ask the owner to point you at the correct file.
+
+Extract `<slug>` from the checkpoint filename (`YYYY-MM-DD-<slug>.md`) and from the `**Team:**` line if present (`superpower-<slug>`). They must match.
+
+If the checkpoint has a `## Closing` block with `cleanup: complete`, halt: the feature already finished. Tell the owner.
+
+### Step 2 — Verify environment
+
+Same prechecks as `/team-feature`:
+- Superpowers plugin installed
+- Claude Code ≥ 2.1.32
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+
+Halt on any failure.
+
+### Step 3 — Preflight scan
+
+Run:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>
+```
+
+Decide based on the output:
+
+| Scan result | Interpretation | Action |
+|---|---|---|
+| All states `absent`, no heartbeat | Lead exited cleanly without auto-cleanup, or platform-side state was already wiped. | Proceed to Step 4 (fresh respawn). |
+| Team config `present`, heartbeat older than 10 min (`liveness: stale`) | Previous lead is dead, platform state lingers. | Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug> --force`. The heartbeat check will allow it because it's stale. Then proceed to Step 4. |
+| Team config `present`, heartbeat fresh (`liveness: LIKELY ALIVE`) | A lead may still be running. | **Halt.** Tell the owner you detected what looks like a live lead. Ask them to verify nothing is in flight before re-running. If the owner confirms the previous lead is dead, instruct them to run `/team-cleanup <slug>` (which will require `--ignore-heartbeat`) and then re-run this command. |
+| Team config `absent` but task_list or tmux still present | Partial cleanup from a previous attempt. | Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug> --force`. Proceed. |
+
+After any cleanup, re-run the scan and confirm `team_config_state: absent` before continuing.
+
+### Step 4 — Identify resume point
+
+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.
+
+### 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>`).
+- 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
+
+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).
+
+Hand each respawned teammate:
+- the slug
+- the relevant artefact paths
+- a note that this is a resume; they should pick up at the next pending task
+
+### Step 7 — Re-import the shared task list
+
+If resuming inside phase 4 (implementation):
+
+1. Read the plan.
+2. Recreate any `impl:` tasks that were pending or in-progress at checkpoint time. The `TaskCreated` hook enforces the prefix; the `TaskCompleted` hook requires `plan_approved_at` metadata — carry the timestamp forward from the checkpoint.
+3. Skip `impl:` tasks that the checkpoint records as `complete` and whose corresponding commits exist on the worktree branch (verify with `git log --oneline -- <task-files>`). If a checkpoint marks a task complete but the commits are missing, halt — that's tampered or corrupted state.
+
+### Step 8 — Append a resume log entry
+
+Append to the checkpoint (atomic write — tmp + rename) and commit:
+
+```markdown
+## Resume log
+- resumed at: <ISO datetime>
+- next phase: <phase name>
+- respawned: <comma-separated role list>
+- preflight cleanup: <yes|no — what was cleaned>
+```
+
+### Step 9 — Resume the phase chain
+
+Continue per the same rules as `/team-feature`:
+- four allowed owner touchpoints, nothing else without §7 template
+- checkpoint after every phase boundary, atomic writes
+- heartbeat touched at every phase boundary
+- automatic cleanup after `FINISH_DONE`
+
+## Hard rules
+
+- **Never** restart a completed phase. If a phase is checked in the checkpoint and the corresponding artefact + commits exist, trust it.
+- **Never** assume teammates are still alive. They are not. Always respawn from the role definitions.
+- **Never** silently change a previously approved design or plan. If the resumed state contradicts them, halt and escalate.
+- **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.
+
+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

@@ -0,0 +1,190 @@
+---
+description: Launch a Superpowers-compliant agent team to deliver a feature end-to-end with at most 4 owner touchpoints, with automatic team cleanup after the finish phase.
+argument-hint: <one-line feature idea>
+---
+
+You are the **lead** of an agent team implementing the Superpowers methodology across multiple parallel Claude Code sessions.
+
+Owner's feature request:
+
+$ARGUMENTS
+
+## Your job
+
+You are a **conductor**, not an implementer. Spawn teammates and coordinate them through the canonical Superpowers skill chain. Do not run skills yourself — delegate every skill to the correct teammate. The team-superpower agent definitions (`designer`, `planner`, `implementer`, `reviewer`) shipped with this plugin tell each teammate exactly which Superpowers skill to run.
+
+## 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`.
+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.
+
+## Preflight — detect stale or orphaned state
+
+Before writing any checkpoint or spawning any teammate, run the helper:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan
+```
+
+Then run a targeted scan for this run's slug:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>
+```
+
+Interpret the output:
+
+| Outcome | What to do |
+|---|---|
+| `No team-superpower teams found` and no checkpoint for `<slug>` | Clean slate. Proceed. |
+| Team config exists for `<slug>` and `liveness: LIKELY ALIVE` | Halt. Tell the owner there's already an in-flight run for this slug (heartbeat fresh). Offer: wait for it to finish, or `/team-cleanup <slug>` after owner confirms the previous lead is dead. |
+| Team config exists for `<slug>` and `liveness: stale` or `unknown` | Tell the owner: "Stale state from a previous run detected." Offer two paths: **(a) Resume** via `/team-feature-resume YYYY-MM-DD-<slug>.md`, or **(b) Cleanup and restart** via `/team-cleanup <slug>` then re-run `/team-feature`. Halt — do NOT auto-decide. |
+| Other slugs have configs but not this one | Note in the checkpoint that other in-flight runs exist; proceed with this slug. |
+
+Same-session check: if the current Claude Code session already manages an agent team (the runtime enforces "one team per session"), halt. The owner must finish or `/team-cleanup` the current team before launching a new feature.
+
+## Initial checkpoint and heartbeat
+
+After preflight clears:
+
+1. Write the initial checkpoint `docs/superpowers/sessions/YYYY-MM-DD-<slug>.md` per the format in the **Checkpointing** section 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.
+
+## Phase chain (strict order — no skipping, no inlining)
+
+1. **Brainstorming (designer).** Spawn the `designer` teammate. Hand it `<slug>` and the owner's request. Wait for `DESIGN_APPROVED <path>` in your mailbox. If the designer asks a clarifying question, answer from project context if unambiguous; otherwise batch with any open questions and use the §7 escalation template to the owner. Checkpoint: `phase: brainstorming, status: complete`. Touch heartbeat.
+2. **Worktree + plan (planner).** Spawn the `planner` teammate. Hand it `<slug>` and the design doc path. Wait for `WORKTREE_READY` then `PLAN_READY <path>`. Route the plan to the owner for approval (third owner touchpoint). On approval, stamp `plan_approved_at: <ISO datetime>` into the metadata of every `impl:` task you will create — the `TaskCompleted` hook checks for it. Checkpoint: `phase: plan, status: approved`. Touch heartbeat.
+3. **Implementation (implementers, 1–3 in parallel).** Read the approved plan. Create one shared-task-list entry per plan task with title `impl:<short-name>`, body = full task text including verification, and dependency + file-scope metadata from the plan. Spawn one `implementer` teammate. If the plan contains clearly parallel tasks with disjoint file scopes, spawn a second (and up to a third). Implementers self-claim. **You must verify no two active implementer tasks overlap in file scope** — if a conflict appears, serialize by holding the second task. Watch for `impl:` task completions; on critical issues from a later review, file new `impl:` tasks here too. Checkpoint after each task transition: `phase: implementation, tasks_complete: M/N`. Touch heartbeat at every transition.
+4. **Review (reviewer).** Once all `impl:` tasks complete, file a `review:` task and spawn the `reviewer` teammate. Wait for `REVIEW_PASSED <path>`. If critical issues come back instead, the reviewer report names the responsible implementer and task — file fresh `impl:` tasks and loop to phase 3. Checkpoint: `phase: review, status: pass | critical_issues_returned`. Touch heartbeat.
+5. **Finish (reviewer).** Same reviewer runs `finishing-a-development-branch`. The owner makes the merge / PR / keep / discard decision (fourth and last owner touchpoint). On `FINISH_DONE <decision> <ref>`, checkpoint: `phase: finish, status: <merged|pr_opened|kept|discarded>`. Touch heartbeat.
+
+## Automatic cleanup (runs after `FINISH_DONE`)
+
+The instant phase 5 records `FINISH_DONE`, run cleanup **before idling**. Do this in order, halting and escalating to the owner if any step fails:
+
+### Step A — Verify safety preconditions
+
+Confirm all of the following from the checkpoint and the task list:
+
+- Every phase from `brainstorming` through `finish` is checked complete.
+- The shared task list has zero `in_progress` tasks. Every `impl:` and `review:` task is `completed`.
+- Phase 5 returned a recognised decision: `merged`, `pr_opened`, `kept`, or `discarded`.
+- The expected git commits exist on the worktree branch. Run `git log --oneline -20` and confirm:
+  - A design doc commit under `docs/superpowers/specs/`
+  - A plan commit under `docs/superpowers/plans/`
+  - One or more implementation commits (TDD pairs of test + code on the same files; the test commit precedes the code commit per the `test-driven-development` skill)
+  - A review report commit under `docs/superpowers/reviews/`
+  - If the finish decision is `merged` or `pr_opened`, the corresponding merge / PR-prep commit
+
+If any of these is missing, **halt cleanup**, escalate with the §7 template, and instruct the owner to inspect manually. **Do not run cleanup on a half-finished feature.**
+
+### Step B — Shut down teammates gracefully
+
+For each live teammate (`designer`, `planner`, every `implementer`, `reviewer`):
+
+1. Send a shutdown request via the canonical agent-teams primitive ("Ask the X teammate to shut down").
+2. Wait for graceful exit.
+3. If a teammate rejects shutdown, surface the rejection reason to the owner via the §7 template and halt cleanup.
+
+The agent-teams runtime refuses team cleanup while any teammate is alive — this step is non-optional.
+
+### Step C — Run the canonical team cleanup
+
+Ask the team-teams runtime to clean up the team (the native lead primitive: phrase it as a natural-language "clean up the team" instruction to yourself). Verify by running:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh scan <slug>
+```
+
+Expected after the runtime cleanup:
+
+- `team_config_state: absent`
+- `task_list_state: absent`
+- `tmux_state: absent` (or `tmux` not installed)
+
+### Step D — Manual sweep (only if Step C left residue)
+
+If the scan after Step C still shows any `present` lines, run:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/team-state.sh cleanup <slug> --force
+```
+
+The heartbeat refusal check applies. If it fires, you are still touching the heartbeat (or another lead is alive) — investigate before forcing. If the only reason is your own fresh heartbeat from this session, pass `--ignore-heartbeat` (you know the lead is you and you are about to exit).
+
+### Step E — Final checkpoint commit
+
+Append a closing block to the checkpoint:
+
+```markdown
+## Closing
+- finished at: <ISO datetime>
+- decision: <merged|pr_opened|kept|discarded>
+- cleanup: complete
+```
+
+Remove the `<slug>.heartbeat` file. Commit the checkpoint. Confirm to the owner: "Team cleaned up. Feature complete."
+
+### Step F — If anything failed
+
+Tell the owner exactly which step failed, include the script output verbatim, and instruct them to run `/team-cleanup <slug>` once they have confirmed nothing else is running. Do **not** retry cleanup loops automatically — the safety check is the heartbeat, and you cannot meaningfully refresh it from outside the lead process.
+
+## Owner touchpoints (the ONLY allowed pings to the owner)
+
+1. Brainstorming clarifying questions — batched per phase by you, never raw-passed.
+2. Design sign-off (the brainstorming skill's built-in step).
+3. Plan approval before phase 3 starts.
+4. Finish-branch decision in phase 6.
+
+**Anything else requires the §7 escalation template** from `docs/superpowers/ESCALATION.md`. Refuse to ping the owner without it. Cleanup runs without owner involvement when Step A passes.
+
+## Checkpointing
+
+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
+# Session: <slug>
+**Started:** <ISO datetime>
+**Last update:** <ISO datetime>
+**Team:** superpower-<slug>
+**Worktree:** <path>
+
+## Phases
+- [x] brainstorming → docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md
+- [x] worktree → <branch>
+- [x] plan → docs/superpowers/plans/YYYY-MM-DD-<slug>-plan.md (approved <datetime>)
+- [ ] implementation (M/N tasks complete)
+- [ ] review
+- [ ] finish
+
+## Teammates
+- designer (agent-id: ...) — idle
+- planner (agent-id: ...) — idle
+- implementer-1 (agent-id: ...) — active on task impl:<name>
+- reviewer (agent-id: ...) — idle
+
+## Open escalations
+- (none) | <escalation-template entries>
+
+## Resume protocol
+1. Owner runs /team-feature-resume with this filename.
+2. Lead respawns teammates using same role definitions.
+3. Lead reads this checkpoint, identifies next pending task, resumes.
+```
+
+## Hard rules
+
+- **Never** run a Superpowers skill yourself. Always delegate to the correct teammate.
+- **Never** modify, replace, or skip a Superpowers skill. Consume them as-installed.
+- **Never** let an implementer write code before the plan is approved. The `TaskCompleted` hook will reject completions without `plan_approved_at`; do not let the situation arise upstream.
+- **Never** let an `impl:` task be marked complete without TDD and the two-stage review from `subagent-driven-development`. The hook is a backstop, not a primary control.
+- **Never** ping the owner without the §7 template, except for the four allowed touchpoints listed above.
+- **Never** skip the automatic cleanup block after `FINISH_DONE`. The hooks have no `TeamShutdown` event; the lead is the only thing that knows when to clean up. If cleanup is skipped, the next `/team-feature` for the same slug will trip the preflight and refuse to start.
+- **Never** force cleanup while the heartbeat is fresh and you didn't write it. That's the signal that another lead is alive.
+
+Begin with the prechecks, then preflight, then spawn `designer`.

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

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "TeammateIdle": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/teammate-idle.sh" }
+        ]
+      }
+    ],
+    "TaskCreated": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/task-created.sh" }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/task-completed.sh" }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# TaskCompleted hook — gate implementation completions on plan approval and
+# validate any embedded escalation entries.
+#
+# Accepts a JSON payload on stdin with at minimum:
+#   - task.title: string
+#   - task.metadata.plan_approved_at: string (ISO datetime), required for impl: tasks
+#   - task.metadata.blocked_questions: array of strings (optional)
+#
+# 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>
+
+set -euo pipefail
+
+LOG_DIR="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/hooks"
+LOG_FILE="$LOG_DIR/log.jsonl"
+mkdir -p "$LOG_DIR"
+
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+payload="$(cat || true)"
+
+if [ -z "$payload" ]; then
+  printf '{"ts":"%s","hook":"task-completed","skipped":"empty payload"}\n' "$ts" >> "$LOG_FILE"
+  exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '{"ts":"%s","hook":"task-completed","skipped":"jq not installed"}\n' "$ts" >> "$LOG_FILE"
+  exit 0
+fi
+
+title="$(printf '%s' "$payload" | jq -r '.task.title // .title // ""' 2>/dev/null || echo "")"
+plan_approved_at="$(printf '%s' "$payload" | jq -r '.task.metadata.plan_approved_at // .metadata.plan_approved_at // ""' 2>/dev/null || echo "")"
+
+printf '{"ts":"%s","hook":"task-completed","title":%s,"plan_approved_at":%s}\n' \
+  "$ts" \
+  "$(printf '%s' "$title" | jq -Rs .)" \
+  "$(printf '%s' "$plan_approved_at" | jq -Rs .)" \
+  >> "$LOG_FILE"
+
+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
+    fi
+    ;;
+esac
+
+# Validate escalation entries if present.
+required_fields=("Phase" "Context" "Options" "Recommendation" "Need from you")
+missing_any=""
+entries="$(printf '%s' "$payload" | jq -c '(.task.metadata.blocked_questions // .metadata.blocked_questions // [])[]?' 2>/dev/null || true)"
+
+if [ -n "$entries" ]; then
+  while IFS= read -r entry; do
+    [ -z "$entry" ] && continue
+    raw="$(printf '%s' "$entry" | jq -r '.' 2>/dev/null || printf '%s' "$entry")"
+    missing=""
+    for field in "${required_fields[@]}"; do
+      if ! printf '%s' "$raw" | grep -qE "(^|[^A-Za-z])${field}[[:space:]]*:"; then
+        if [ -z "$missing" ]; then
+          missing="$field"
+        else
+          missing="$missing, $field"
+        fi
+      fi
+    done
+    if [ -n "$missing" ]; then
+      if [ -z "$missing_any" ]; then
+        missing_any="$missing"
+      else
+        missing_any="$missing_any | $missing"
+      fi
+    fi
+  done <<< "$entries"
+fi
+
+if [ -n "$missing_any" ]; then
+  echo "BAD_ESCALATION: missing field(s) $missing_any" >&2
+  exit 2
+fi
+
+exit 0

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

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# TaskCreated hook — enforce title prefix on shared task list entries.
+#
+# Accepts a JSON payload on stdin. Required field:
+#   - task.title: string
+#
+# Title MUST start with one of: impl:, review:, meta:, block:
+# Otherwise exit 2 with stderr BAD_PREFIX so the team-team runtime refuses
+# the task and surfaces the failure to the lead.
+
+set -euo pipefail
+
+LOG_DIR="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/hooks"
+LOG_FILE="$LOG_DIR/log.jsonl"
+mkdir -p "$LOG_DIR"
+
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+payload="$(cat || true)"
+
+if [ -z "$payload" ]; then
+  printf '{"ts":"%s","hook":"task-created","skipped":"empty payload"}\n' "$ts" >> "$LOG_FILE"
+  exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '{"ts":"%s","hook":"task-created","skipped":"jq not installed"}\n' "$ts" >> "$LOG_FILE"
+  exit 0
+fi
+
+title="$(printf '%s' "$payload" | jq -r '.task.title // .title // ""' 2>/dev/null || echo "")"
+
+printf '{"ts":"%s","hook":"task-created","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+
+case "$title" in
+  impl:*|review:*|meta:*|block:*) exit 0 ;;
+  "")
+    echo "BAD_PREFIX: task title missing; must start with impl:|review:|meta:|block:" >&2
+    exit 2 ;;
+  *)
+    echo "BAD_PREFIX: task title must start with impl:|review:|meta:|block: (got: $title)" >&2
+    exit 2 ;;
+esac

package/plugins/team-superpower/hooks/teammate-idle.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# TeammateIdle hook — block idle if there are unanswered inbound peer messages.
+#
+# Reads the hook event payload from stdin. Expected JSON fields (best-effort —
+# the agent-teams runtime may evolve; we only fail closed on what we can verify):
+#   - mailbox: array of { from, replied, ... }
+#   - teammate: string (the idling teammate's role)
+#
+# Behaviour:
+#   - count messages where from != "lead" AND replied == false
+#   - if count > 0  -> exit 2 with stderr BLOCKED_IDLE
+#   - else          -> exit 0
+#
+# Logs every invocation to .claude/hooks/log.jsonl in the project root for tuning.
+
+set -euo pipefail
+
+LOG_DIR="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/hooks"
+LOG_FILE="$LOG_DIR/log.jsonl"
+mkdir -p "$LOG_DIR"
+
+payload="$(cat || true)"
+
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+if [ -z "$payload" ]; then
+  printf '{"ts":"%s","hook":"teammate-idle","skipped":"empty payload"}\n' "$ts" >> "$LOG_FILE"
+  exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '{"ts":"%s","hook":"teammate-idle","skipped":"jq not installed"}\n' "$ts" >> "$LOG_FILE"
+  exit 0
+fi
+
+unanswered="$(printf '%s' "$payload" | jq '[.mailbox[]? | select((.from // "") != "lead") | select((.replied // false) == false)] | length' 2>/dev/null || echo 0)"
+
+printf '{"ts":"%s","hook":"teammate-idle","unanswered":%s}\n' "$ts" "$unanswered" >> "$LOG_FILE"
+
+if [ "${unanswered:-0}" -gt 0 ]; then
+  echo "BLOCKED_IDLE: $unanswered unanswered peer messages. Reply or escalate via ESCALATION.md before idling." >&2
+  exit 2
+fi
+
+exit 0