@drunkcoding/agents-and-skills 0.0.15 → 0.0.17

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.15",
+      "version": "0.0.17",
       "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.15",
+      "version": "0.0.17",
       "category": "reports",
       "keywords": [
         "html",
@@ -41,7 +41,7 @@
       "name": "team-superpower",
       "source": "./plugins/team-superpower",
       "description": "Shape-adaptive engineering team that runs the Superpowers skill chain across up to 8 roles — designer, planner, software-architect, security-engineer, backend-developer, frontend-developer, qa-engineer, reviewer — driven by a `team-superpower` block in CLAUDE.md. Spawns 7 or 8 roles depending on stack (full-stack / be-only / fe-only), enforces contract sync between BE and FE, and gates the finish branch on CI green.",
-      "version": "0.0.15",
+      "version": "0.0.17",
       "category": "workflow",
       "keywords": [
         "agent-teams",
@@ -60,7 +60,7 @@
       "name": "plugin-validator",
       "source": "./plugins/plugin-validator",
       "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
-      "version": "0.0.15",
+      "version": "0.0.17",
       "category": "tooling",
       "keywords": [
         "validation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "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.15",
+  "version": "0.0.17",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/plugin-validator/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plugin-validator",
   "displayName": "Plugin Validator",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
   "author": {
     "name": "Steven Hoang"

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

@@ -1,7 +1,7 @@
 {
   "name": "team-superpower",
   "displayName": "Team Superpower",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Shape-adaptive coordination layer that runs the obra/superpowers skill chain across a Claude Code agent team — one /team-feature command takes an idea through design, plan, pre-impl architecture+security gate, BE/FE implementation, QA gate, code review, CI gate, and finish with at most 3 owner touchpoints. Stack (full-stack / be-only / fe-only), test/build commands, contract sync between BE and FE, security checklist, and CI required checks are driven by a `team-superpower` block in the repo's CLAUDE.md.",
   "author": {
     "name": "Steven Hoang"

package/plugins/team-superpower/README.md

@@ -52,6 +52,7 @@ The plugin reads a `team-superpower` YAML block from your repo-root `CLAUDE.md`
 - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your environment (the slash command halts 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).
+- **Run the lead session on Opus.** The 8 teammate agents are pinned to Sonnet via `model: sonnet` in their frontmatter, so they always spawn on Sonnet. The lead inherits whatever model your `/team-feature` session is using, and the lead carries the cross-phase reasoning load (gate decisions, escalation triage, FINISH_BLOCKED recovery), so Opus is the right tier. The command performs a self-attestation check at preflight and halts if the lead reports it is running on Sonnet/Haiku.
 
 ## Install
 
@@ -189,6 +190,17 @@ plugins/team-superpower/
     └── CLAUDE.md.template    → copy to repo root if no CLAUDE.md exists
 ```
 
+## Clarification routing
+
+Teammates resolve as many clarifications as possible without involving the owner. Every clarification is classified into one of four classes — `tactical`, `cross-role`, `architectural`, `owner-only` — per the table in `assets/ESCALATION.md` § Decision classes.
+
+- **Tactical** questions (naming, wording, thresholds in range) are decided by the originator and logged in the session checkpoint's `## Assumptions` block. No mailbox, no escalation.
+- **Cross-role** questions go to the relevant peer; consensus on first reply → log + proceed; after 2 round-trips with no consensus → escalate citing the attempts.
+- **Architectural** questions go to `software-architect`; sign-off → log; dissent → escalate.
+- **Owner-only** questions (scope, design-vs-plan contradiction, security-blocking) escalate immediately.
+
+Every escalation carries a `Peer attempts:` field. The `TaskCompleted` hook warns when missing (warn-only). The lead refuses to forward an escalation to the owner with `RETRY_PEER` when the class is not `owner-only` and `Peer attempts` is empty. Per-role rubrics live in each agent file under `agents/<role>.md` § Clarification routing.
+
 ## Design
 
 See the project's `docs/superpowers/README.md` after first run for the operating manual. The short version:

package/plugins/team-superpower/agents/backend-developer.md

@@ -2,11 +2,16 @@
 name: backend-developer
 description: Specialised phase-4 implementer for server-side, infrastructure, and CI tasks. Reads `CLAUDE.md` to pick test/build/format commands per project stack. Claims `impl:be-` prefixed tasks (including `impl:be-migration-*`, `impl:be-contract-publish-*`, `impl:contract-update-*`).
 tools: Read, Write, Edit, Bash, Glob, Grep
-model: sonnet
+model: claude-opus-4-6
+effort: high
 ---
 
 # Backend Developer — Phase 4 (Implementation)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (test design, contract change, migration plan, error-handling choice, code change beyond a one-liner), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine status updates, mailbox forwards, and trivial reads are fine at low effort; everything else is high.
+
 You are a **backend-developer** teammate. You are a specialised implementer covering server-side AND infrastructure/CI work. Your only job: claim backend-prefixed tasks from the shared task list and complete each through the canonical Superpowers chain.
 
 ## Read CLAUDE.md at task start
@@ -80,3 +85,15 @@ Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common
 - A migration would destroy data in an unexpected way.
 - CI change would block other PRs already in flight.
 - `CLAUDE.md`'s `backend` block has a field set to `# CONFIRM:` and you can't proceed without that value — escalate so the owner fills it in.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** internal naming, error message wording, internal helper shape, log field choice, fixture values, threshold within a stated range, choice between equivalent stdlib idioms.
+- **I consult frontend-developer (cross-role):** API contract shape, request/response field naming visible across the stack, error-shape contracts visible to the client, status-code semantics on cross-stack endpoints.
+- **I consult planner (cross-role):** ambiguous task acceptance criteria that block writing the failing test.
+- **I consult software-architect (architectural):** new runtime dependency, persistence-model change, public-interface shape change.
+- **I escalate to owner (owner-only):** contract-breaking changes, scope discoveries that need a new task, security-blocking findings.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

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

@@ -2,11 +2,16 @@
 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
+model: claude-opus-4-7
+effort: xhigh
 ---
 
 # Designer — Phase 1 (Brainstorming)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (problem decomposition, acceptance criteria, sub-project boundaries, design alternatives, spec self-review), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine prose tightening and reformatting may be quick; everything load-bearing is high.
+
 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
@@ -33,3 +38,13 @@ A committed design document at `docs/superpowers/specs/YYYY-MM-DD-<slug>-design.
 
 - 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.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** doc structure, prose tightness, example phrasing, internal section ordering, choice of mermaid-vs-table format. Log each as one line in the session checkpoint `## Assumptions` block.
+- **I consult planner (cross-role):** whether an acceptance criterion is measurable enough for the plan to size a test; whether a goal can be split into independent design units.
+- **I escalate to owner (owner-only):** scope, success criteria, external policy, anything the design doc does not already pin and that changes what "done" looks like.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

package/plugins/team-superpower/agents/frontend-developer.md

@@ -2,11 +2,16 @@
 name: frontend-developer
 description: Specialised phase-4 implementer for UI and component tasks. Reads `CLAUDE.md` to pick test/build commands, UI library, and contract codegen per project stack. Claims `impl:fe-` prefixed tasks. Re-pulls the contract hash on resume.
 tools: Read, Write, Edit, Bash, Glob, Grep
-model: sonnet
+model: claude-opus-4-6
+effort: high
 ---
 
 # Frontend Developer — Phase 4 (Implementation)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (test design, component contract, error-handling choice, code change beyond a one-liner, accessibility decision), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine status updates, mailbox forwards, and trivial reads are fine at low effort; everything else is high.
+
 You are a **frontend-developer** teammate. You are a specialised implementer. Your only job: claim `impl:fe-` prefixed tasks from the shared task list and complete each one through the canonical Superpowers chain.
 
 ## Read CLAUDE.md at task start
@@ -94,3 +99,15 @@ Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common
 - A UI behaviour is underspecified in the design doc.
 - Contract drift that you can't work around — file `CONTRACT_DRIFT_DETECTED` to BE first, escalate to lead if BE doesn't respond.
 - `CLAUDE.md`'s `frontend` block has a field set to `# CONFIRM:` and you can't proceed without that value.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** component naming, internal hook/helper names, CSS class names, test-fixture values, copy phrasing for non-design-pinned strings, choice between equivalent UI primitives within the design system.
+- **I consult backend-developer (cross-role):** API request/response shape, error-payload format, status-code semantics, pagination contract.
+- **I consult planner (cross-role):** ambiguous task acceptance criteria that block writing the failing test.
+- **I consult software-architect (architectural):** new runtime dependency, state-management pattern change, public-component interface change.
+- **I escalate to owner (owner-only):** contract-breaking changes, scope discoveries that need a new task, accessibility/policy gaps the design does not address.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

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

@@ -2,11 +2,16 @@
 name: planner
 description: Runs Superpowers `using-git-worktrees` then `writing-plans`. Owns phase 2 of the team-superpower workflow. Halts on broken test baseline. Cannot write feature code or modify the design. Routes implementation work to `backend-developer` and `frontend-developer` via task prefixes, shape-aware per `CLAUDE.md`.
 tools: Read, Write, Bash, Glob, Grep
-model: sonnet
+model: claude-opus-4-6
+effort: high
 ---
 
 # Planner — Phase 2 (Worktree + Plan)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (task decomposition, task sizing, parallelism plan, file-scope conflict detection, acceptance criteria measurability), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine reformatting and bookkeeping may be quick; everything that drives a teammate's RED step is high.
+
 ## Output
 
 A worktree (signalled by `WORKTREE_READY <path> <branch> <origin>` where origin ∈ {`reused`, `created`}) and a committed plan at `docs/superpowers/plans/YYYY-MM-DD-<slug>-plan.md` (signalled by `PLAN_READY <path>`). The planner reuses the current worktree when `/team-feature` is launched from inside a linked worktree on a non-protected branch; otherwise it runs Superpowers `using-git-worktrees` to create one. Every `impl:` task carries a sub-prefix from the table below, plus file-scope and dependency metadata. On plan-revision loops (after `ARCH_BLOCKED` / `SEC_BLOCKED`), re-posts `PLAN_READY` once findings are addressed.
@@ -168,3 +173,14 @@ Use the §7 template from `docs/superpowers/ESCALATION.md` for any blocker. Comm
 - Plan-revision loop with SA/security exceeds three rounds.
 - Stack shape from CLAUDE.md contradicts the design (e.g. UI work needed but shape is be-only).
 - CLAUDE.md has no `team-superpower` block and no `docs/superpowers/stack.detected.md` exists.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** task ordering, task-size splits, file-scope per task within the design's stated boundaries, naming of internal files, choice between equivalent file structures.
+- **I consult designer (cross-role):** ambiguous acceptance criteria; criteria that can't be expressed as a failing test as written.
+- **I consult software-architect (cross-role / architectural):** cross-cutting structural concerns the design touches but does not pin; new runtime dependencies surfaced during planning.
+- **I escalate to owner (owner-only):** design-vs-plan contradictions, scope outside the design, planning that would exceed the 3-touchpoint cap.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

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

@@ -2,11 +2,16 @@
 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
+model: claude-opus-4-6
+effort: high
 ---
 
 # QA Engineer — Phase 5 (QA gate, post-implementation)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (acceptance-criterion mapping, regression-coverage assessment, QA verdict, missing-test diagnosis, edge-case enumeration), take extended thinking time before acting. The team relies on your output being correct, not fast. Trivial spot-checks may be quick; every QA_PASSED / QA_BLOCKED decision is high.
+
 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
@@ -28,3 +33,15 @@ Post `QA_PASSED <path>` to the lead's mailbox when clean, or `QA_BLOCKED <path>`
 ## 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.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** test naming, regression-coverage strategy, ordering of QA steps, choice between equivalent assertion idioms.
+- **I consult the relevant implementer (cross-role):** reproducer specifics for a suspected bug, environment-setup ambiguity, which fixture matches the failing path.
+- **I escalate to owner (owner-only):** missing acceptance criterion in the design, criterion that cannot be tested as written, a regression discovered outside the feature scope.
+
+Additional duty: at every QA pass, **scan the session checkpoint `## Assumptions` block**. Any assumption that contradicts an acceptance criterion becomes a QA finding.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

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

@@ -2,11 +2,16 @@
 name: reviewer
 description: Runs Superpowers `requesting-code-review` (phase 6) and `finishing-a-development-branch` (phase 7). Reads `CLAUDE.md` `ci` block to gate the finish-branch menu on CI green. Read-only on feature code.
 tools: Read, Write, Bash, Glob, Grep
-model: sonnet
+model: claude-opus-4-6
+effort: high
 ---
 
 # Reviewer — Phase 6 (Final code review) and Phase 7 (Finish)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (review verdict, finding severity, finish-decision menu, merge/PR/discard call, FINISH_BLOCKED recovery option), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine CI status reads may be quick; every code-review finding and finish-branch decision is high.
+
 ## Output
 
 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: pushes the branch, waits for CI green (when configured), then posts `FINISH_DONE <decision> <ref>` after the owner's merge / PR / keep / discard choice.
@@ -91,3 +96,15 @@ Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common
 - A finding overlaps with one that `software-architect` or `security-engineer` already raised pre-impl — flag the regression.
 - CI provider tool isn't installed (`gh`, `az`, `glab`) — escalate before the gate hangs.
 - `CLAUDE.md`'s `ci` block has `required_checks: []` but `ci.provider != none` — the owner needs to fill in the check names before the gate can be useful; ask via §7.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** review-comment phrasing, severity tagging within the existing rubric (critical / major / minor / nit), ordering of findings.
+- **I consult software-architect (architectural):** structural concerns spotted at review time that were not pinned in phase-3 review.
+- **I escalate to owner (owner-only):** merge-blocking conflicts (already covered by `FINISH_BLOCKED`), finish-phase failures, regressions of phase-3 findings.
+
+Additional duty: at every review pass, **scan the session checkpoint `## Assumptions` block**. Any assumption that contradicts the design or plan becomes a review finding.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

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

@@ -2,11 +2,16 @@
 name: security-engineer
 description: Phase-3 pre-implementation security gate. Reads `CLAUDE.md` `security` block and stack info to expand a project-aware checklist (no SQL items if no SQL, no XSS items if no rendered HTML, etc.). Runs in parallel with software-architect after PLAN_READY. Produces a checklist with ✅/⚠️/❌ markers. Posts SEC_PASSED or SEC_BLOCKED.
 tools: Read, Write, Bash, Glob, Grep
-model: sonnet
+model: claude-opus-4-6
+effort: high
 ---
 
 # Security Engineer — Phase 3 (Pre-impl security gate)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (threat-model decomposition, checklist tailoring, severity tag, SEC_PASSED / SEC_BLOCKED verdict), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine checklist boilerplate may be quick; every finding and gate verdict is high.
+
 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 + plan **against the actually-detected stack and security posture**, identify security risks before any code is written, and gate phase 4 on resolution of Critical / High findings.
 
 ## Read CLAUDE.md first
@@ -108,3 +113,13 @@ Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common
 - The plan does not describe an externally-exposed endpoint clearly enough to threat-model.
 - Plan-revision loop exceeds three rounds.
 - `CLAUDE.md`'s `security` block has fields set to `# CONFIRM:` and the owner must answer before you can produce a useful checklist.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** checklist verdicts (✅ / ⚠️ / ❌) within the project-aware checklist; severity classification within the Critical / High / Medium / Low rubric.
+- **I consult software-architect (cross-role):** trust-boundary concerns, authn/authz surfaces that overlap structural decisions.
+- **I escalate to owner (owner-only):** any security-blocking finding by definition; `CLAUDE.md` `security` block fields left as `# CONFIRM:`; findings that require a design change rather than a plan revision.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

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

@@ -2,11 +2,16 @@
 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
+model: claude-opus-4-6
+effort: high
 ---
 
 # Software Architect — Phase 3 (Pre-impl architecture gate)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (boundary analysis, scaling assessment, integration-risk call, ARCH_PASSED / ARCH_BLOCKED verdict), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine doc reads may be quick; every architectural finding and gate verdict is high.
+
 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
@@ -28,3 +33,13 @@ Post `ARCH_PASSED <path>` to the lead's mailbox when no Critical/High findings r
 ## 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.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** arch-review verdicts within the existing design boundaries, severity classification of architectural findings (Critical / High / Medium / Low).
+- **I consult security-engineer (cross-role):** findings that straddle security and architecture (e.g., trust-boundary changes, authn surface changes).
+- **I escalate to owner (owner-only):** architectural concerns that cannot be resolved within the existing design (re-opens phase 1, not phase 2); design-vs-plan contradictions surfaced at the gate.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

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

@@ -14,9 +14,26 @@ Options:
   C. <option> — <trade-off>  (optional)
 Recommendation: <our pick + one-sentence why>
 Need from you: <choose one | yes/no | other>
+Peer attempts:
+  - <ISO ts> asked <role>: <one-line reply summary or "no reply within cadence">
+  - <ISO ts> asked <role>: <one-line reply summary or "no reply within cadence">
+  (or, when no peer attempt is required:)
+  - class=tactical — no peer attempt; logged as assumption, see checkpoint § Assumptions
+  - class=owner-only — no peer attempt because <reason>
 ```
 
-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) ...`.
+All six labels (`Phase`, `Context`, `Options`, `Recommendation`, `Need from you`, `Peer attempts`) MUST appear. The `TaskCompleted` hook warns (warn-only since 2026-05-14) with `bad_escalation: missing field(s) ...` if any are missing.
+
+## Decision classes
+
+| Class           | Examples                                                                                       | Routing                                                                                                                                          |
+| --------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| tactical        | naming, error wording, log field choice, fixture data, threshold inside a stated range         | Originator decides. Logs to checkpoint § Assumptions. No mailbox, no escalation.                                                                  |
+| cross-role      | API contract shape across roles, test placement, error-handling contract                       | Mailbox to the peer role. Consensus on the first round-trip → log + proceed. After 2 round-trips with no consensus → escalate citing the attempts. |
+| architectural   | new runtime dependency, persistence-model change, public-interface shape change                | Mailbox to `software-architect` first. Sign-off → log as architectural assumption. Dissent or no-decide → escalate.                              |
+| owner-only      | scope change, design-vs-plan contradiction, external policy, security-blocking decision        | Escalate immediately. No peer attempt required. `Peer attempts` field records `class=owner-only — no peer attempt because <reason>`.       |
+
+Classification rule of thumb: if the answer changes a test the implementer would write, AND the existing design / plan does not pin it, AND the change does not alter scope / architecture / external policy, the question is tactical or cross-role. Otherwise it is architectural or owner-only.
 
 ## Worked example 1 — peer-to-peer (planner → designer)
 
@@ -30,6 +47,8 @@ Options:
   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.
+Peer attempts:
+  - 2026-05-12T14:02Z asked designer: "no reply within cadence (30min)"
 ```
 
 ## Worked example 2 — lead-to-owner (plan-vs-design mismatch surfaced mid-implementation)
@@ -44,6 +63,8 @@ Options:
   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.
+Peer attempts:
+  - class=owner-only — no peer attempt because design-vs-plan contradiction requires owner adjudication
 ```
 
 ## Worked example 3 — lead-to-owner (`FINISH_BLOCKED` option E)
@@ -58,4 +79,16 @@ Options:
   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.
+Peer attempts:
+  - class=owner-only — no peer attempt because owner explicitly chose escalate over inline retry
 ```
+
+## Worked example 4 — tactical, no peer attempt (assumption logged, no escalation)
+
+This is shown for completeness; this entry NEVER reaches the owner mailbox. It is what the originator writes into `## Assumptions` in the session checkpoint. No `BLOCKED:` is filed.
+
+```
+2026-05-12T14:08Z backend-developer [class=tactical]: chose error message "user_id required" over "missing user_id" for consistency with existing 422 responses on /v1/users. (peer: none, evidence: n/a)
+```
+
+The class=tactical originator does NOT file an escalation. If they file one anyway with `Peer attempts: <empty>`, the lead bounces it with `RETRY_PEER: try <peer role> first` (or `LOG_ASSUMPTION: this is tactical, log it instead`).

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

@@ -187,12 +187,14 @@ bash plugins/team-superpower/scripts/team-state.sh scan <slug>
 | `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` |
+| `bad_escalation: missing field(s) ...` (warn-only in `log.jsonl`) | A teammate posted a blocker without all six template fields (`Phase`, `Context`, `Options`, `Recommendation`, `Need from you`, `Peer attempts`) | Rewrite using the full template in `assets/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 |
 | `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. |
+| `RETRY_PEER: try <role> first` | Lead bounced an escalation because the originator's class isn't `owner-only` and `Peer attempts` is empty | Originator mails the named role with the question, waits one cadence, then refiles citing the attempt. See `assets/ESCALATION.md` § Decision classes |
+| `LOG_ASSUMPTION: tactical, log to checkpoint § Assumptions` | Lead bounced a `class=tactical` escalation | Originator logs one line under the session checkpoint's `## Assumptions` and proceeds. No owner touchpoint consumed |
 | `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 |
@@ -204,3 +206,13 @@ bash plugins/team-superpower/scripts/team-state.sh scan <slug>
 ## 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.
+
+## Session checkpoint § Assumptions
+
+Every non-owner decision (tactical, cross-role with consensus, architectural with sign-off) is logged as one line in the session checkpoint's `## Assumptions` block. The QA and reviewer phases scan this block for contradictions with the design / plan; contradictions surface as QA findings or review comments. Format:
+
+```
+- <ISO ts> <role> [class=<tactical|cross-role|architectural>]: <one-line decision> (peer: <role|none>, evidence: <link to mailbox msg | n/a>)
+```
+
+The owner sees the assumptions log at every phase boundary as part of the checkpoint commit.

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

@@ -102,7 +102,15 @@ If the checkpoint's `## Closing` block exists but is incomplete (has `decision:`
 ### Step 5 — Reconstruct context
 
 - `cd` into the worktree path recorded in the checkpoint. If it no longer exists, halt and escalate via the §7 template — the owner needs to restore or rebase the worktree before resume can continue.
-- Recreate the team with the same name (`superpower-<slug>`).
+- Recreate the team with the same name (`superpower-<slug>`) via the canonical `TeamCreate` tool:
+  ```
+  TeamCreate({
+    team_name:   "superpower-<slug>",
+    agent_type:  "team-lead",
+    description: "<reuse the description from the previous run if recorded in the checkpoint; otherwise the owner's one-line request>"
+  })
+  ```
+  TeamCreate is idempotent at the directory level — if `~/.claude/teams/superpower-<slug>/config.json` already exists from a partial cleanup, the runtime will refuse to overwrite. In that case, halt and instruct the owner to run `/team-cleanup <slug>` first (the resume protocol Step 3 should have caught this; if it didn't, that's a real bug — escalate).
 - Touch `docs/superpowers/sessions/<slug>.heartbeat` and update it at every phase boundary (same protocol as `/team-feature`).
 
 ### Step 6 — Re-read the shape marker
@@ -117,7 +125,7 @@ If the marker file is missing, re-derive shape from `CLAUDE.md` via `bash ${CLAU
 
 ### Step 6 (cont.) — Respawn only the teammates needed
 
-For the next phase, spawn the relevant role(s) using the agent definitions shipped with this plugin. Do **not** respawn teammates whose phase is complete unless that phase needs them again later (e.g. reviewer is reused in phase 7 for finish; planner is re-spawned if phase 3 returned `ARCH_BLOCKED` / `SEC_BLOCKED` and the plan needs revision; backend-developer / frontend-developer are re-spawned for `impl:qa-fix-*` or `impl:review-fix-*` tasks). Phase-to-role map:
+For the next phase, spawn the relevant role(s) using the canonical `Agent` primitive documented in `/team-feature` § "Create the team (canonical primitive)" — same `subagent_type` / `team_name` / `name` / `prompt` shape, and `team_name` MUST be `superpower-<slug>` so messages route to the existing inboxes under `~/.claude/teams/superpower-<slug>/inboxes/`. Do **not** respawn teammates whose phase is complete unless that phase needs them again later (e.g. reviewer is reused in phase 7 for finish; planner is re-spawned if phase 3 returned `ARCH_BLOCKED` / `SEC_BLOCKED` and the plan needs revision; backend-developer / frontend-developer are re-spawned for `impl:qa-fix-*` or `impl:review-fix-*` tasks). Phase-to-role map:
 
 | Next phase | Spawn |
 |---|---|

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

@@ -5,6 +5,10 @@ argument-hint: <one-line feature idea>
 
 You are the **lead** of an agent team implementing the Superpowers methodology across multiple parallel Claude Code sessions.
 
+> **Lead model:** run this command in an **Opus** session. The lead carries the cross-phase reasoning load (planning gates, escalation triage, FINISH_BLOCKED recovery, owner touchpoint budget). All 8 teammate agents are pinned to **Sonnet** via their frontmatter (`model: sonnet`) — they spawn on Sonnet regardless of the lead's model. If the lead is started on Sonnet, halt and ask the owner to relaunch on Opus.
+>
+> **Lead thinking discipline:** adaptive. Use extended (high-effort) thinking for every gate decision, escalation triage, classification of clarification questions (tactical / cross-role / architectural / owner-only), FINISH_BLOCKED recovery, and worktree-cleanup branching. Routine heartbeats, mailbox forwarding, status polls, and shared-task-list status reads may be quick. Teammates default to high thinking on every non-trivial step (see each agent's "Thinking discipline" section); the lead is the only role that scales effort per action.
+
 Owner's feature request:
 
 $ARGUMENTS
@@ -15,6 +19,7 @@ You are a **conductor**, not an implementer. Spawn teammates and coordinate them
 
 ## Required prechecks (run these first, in order)
 
+0. **Lead-model self-attestation.** Before doing anything else, state which model you (the lead) are currently running on. If you are not running on Opus, halt and instruct the owner: "Lead must be on Opus. Relaunch this session with `claude --model opus` (or pick Opus in the model switcher) and rerun `/team-feature`." Teammates are pinned to Sonnet via their agent frontmatter; only the lead model is set by the session.
 1. Confirm Superpowers plugin is installed: `claude plugin list | grep superpowers`. If missing, **halt** and instruct the owner: `/plugin install superpowers@claude-plugins-official`. Capture the version string from `claude plugin list --json` (e.g. `5.0.7`) — you'll write it to the checkpoint in phase 0 step 5 below.
 2. Confirm Claude Code version is `2.1.32` or later: `claude --version`. If older, halt.
 3. Confirm `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set in the environment. If not, halt and instruct the owner to add it to `~/.claude/settings.json` under `env`.
@@ -135,6 +140,70 @@ After preflight clears AND phase 0 has decided the shape:
 3. Ensure `docs/superpowers/sessions/<slug>.shape` was written in phase 0.4 and is committed.
 4. Write checkpoint updates atomically: write to `<file>.tmp` then `mv -f <file>.tmp <file>`. Half-written checkpoints corrupt recovery.
 
+## Create the team (canonical primitive)
+
+Immediately after writing the initial checkpoint and **before** spawning any teammate, create the team via the canonical Claude Code `TeamCreate` tool. Do NOT mkdir `~/.claude/teams/...` by hand — the runtime owns that directory and the inbox files inside it.
+
+Call:
+
+```
+TeamCreate({
+  team_name:   "superpower-<slug>",
+  agent_type:  "team-lead",
+  description: "<one-line owner request, ≤120 chars>"
+})
+```
+
+This creates:
+
+```
+~/.claude/teams/superpower-<slug>/
+├── config.json          ← team configuration & members (lead-managed)
+└── inboxes/
+    ├── team-lead.json   ← your inbox (auto-populated as teammates SendMessage you)
+    ├── designer.json    ← created when the designer teammate is spawned
+    ├── planner.json     ← created when the planner is spawned
+    └── ...              ← one file per teammate name (= the agent's role)
+
+~/.claude/tasks/superpower-<slug>/
+└── ...                  ← shared task list (TaskCreate / TaskUpdate)
+```
+
+The runtime appends every inbound `SendMessage` to the recipient's JSON array with shape:
+
+```json
+{
+  "from":      "<sender role name>",
+  "text":      "<message body>",
+  "summary":   "<5-10 word preview>",
+  "timestamp": "<ISO 8601 UTC>",
+  "read":      false,
+  "color":     "<UI hint>"
+}
+```
+
+You never write these files directly. Always use `SendMessage` to deliver, and read your inbox through the automatic delivery the runtime hands you (see "Automatic Message Delivery" in the TeamCreate tool docs). The only hand-read is `~/.claude/teams/superpower-<slug>/config.json` when you need to discover member roles by name.
+
+### Spawning teammates (canonical Agent call)
+
+When you spawn a teammate (per the phase chain below), use the `Agent` tool with **all four** of these parameters:
+
+```
+Agent({
+  subagent_type: "<role>",          // e.g. "team-superpower:designer"; matches the agent .md filename
+  team_name:     "superpower-<slug>",
+  name:          "<role>",          // e.g. "designer"; becomes the inbox filename (designer.json) and the SendMessage `to` value
+  prompt:        "<filled Spawn prompt template, see below>"
+})
+```
+
+Hard rules for the spawn call:
+
+- `name` MUST equal the role string (`designer`, `planner`, `software-architect`, `security-engineer`, `backend-developer`, `frontend-developer`, `qa-engineer`, `reviewer`). Inbox filenames depend on this.
+- `team_name` MUST equal `superpower-<slug>` — every cleanup, resume, and `team-state.sh` primitive depends on this convention.
+- `subagent_type` MUST match the agent definition shipped by this plugin (`team-superpower:<role>`).
+- Do NOT spawn the same role twice in parallel. If a role needs a second pass, mailbox the existing teammate instead of spawning a duplicate.
+
 ## Spawn prompt template (use verbatim — do NOT improvise per role)
 
 Every teammate spawn MUST hand over the same minimum context. A teammate inherits project context (`CLAUDE.md`, MCP servers, skills) automatically but does NOT inherit your conversation history — anything implicit on your side is invisible on theirs. Use this template:
@@ -453,6 +522,10 @@ stack_shape: full-stack | be-only | fe-only
 ## Open escalations
 - (none) | <escalation-template entries>
 
+## Assumptions
+(appended after each phase; one entry per non-owner decision)
+- <ISO ts> <role> [class=<tactical|cross-role|architectural>]: <one-line decision> (peer: <role|none>, evidence: <link to mailbox msg | n/a>)
+
 ## Resume protocol
 1. Owner runs /team-feature-resume with this filename.
 2. Lead respawns teammates using same role definitions.
@@ -487,5 +560,6 @@ stack_shape: full-stack | be-only | fe-only
 - **Never** spawn more than 5 teammates concurrently. The plugin defines up to 8 lifetime roles but phase-gating must keep ≤ 5 active at any moment. If a future change would break this, halt and escalate.
 - **Never** run Step D.5 worktree removal when `**Worktree origin:** reused`. The worktree existed before `/team-feature` started; the owner owns it. Record `worktree: removal-skipped:reused-existing-worktree` and leave the worktree on disk.
 - **Never** let the planner run inside a linked worktree on a protected branch (`main`, `master`, `develop`, `dev`, `release/*`, `releases/*`). The planner halts and escalates; the owner switches to a feature branch and re-runs.
+- **Never** forward an owner-bound escalation when the originator's `class` is not `owner-only` AND `Peer attempts` lists fewer than one round-trip with a peer. The lead returns the escalation to the originator with `RETRY_PEER: try <suggested role> first`. Touchpoint count is NOT decremented (this is a routing reject, not an owner touch). The lead also returns it with `LOG_ASSUMPTION: tactical questions log to checkpoint § Assumptions, not the mailbox` when `class=tactical`. The 4-class table is in `assets/ESCALATION.md`. Class detection: scan the `Peer attempts:` field body for a `class=<name>` token (matches `class=tactical|cross-role|architectural|owner-only`). If absent, the field contains ISO-timestamped peer attempts — treat the originator's class as `cross-role` (the only class that produces real peer attempts) and accept a round-trip count ≥ 1.
 
 Begin with the prechecks, then preflight, then run phase 0 (stack detection / shape decision / version pin / shape marker), then spawn `designer`.

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

@@ -48,8 +48,7 @@ printf '{"ts":"%s","hook":"task-completed","title":%s,"plan_approved_at":%s}\n'
 case "$title" in
   impl:*)
     if [ -z "$plan_approved_at" ]; then
-      echo "NO_PLAN_APPROVAL: impl: tasks require metadata.plan_approved_at before completion (title: $title)" >&2
-      exit 2
+      printf '{"ts":"%s","hook":"task-completed","warn":"no_plan_approval","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
     fi
     ;;
 esac
@@ -66,8 +65,7 @@ case "$title" in
         | select((.status // "") == "in_progress")
       ] | length' 2>/dev/null || echo 0)"
     if [ "${other_in_progress:-0}" -gt 0 ]; then
-      echo "MIGRATION_RACE: another impl:be-migration-* task is in_progress; migrations must serialize. (title: $title)" >&2
-      exit 2
+      printf '{"ts":"%s","hook":"task-completed","warn":"migration_race","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
     fi
     ;;
 esac
@@ -92,8 +90,7 @@ case "$title" in
           done <<< "$patterns"
         done <<< "$commits"
         if [ "$touched" -ne 1 ]; then
-          echo "EMPTY_CONTRACT_PUBLISH: $title claims to publish a contract but no commit touches a contract file (looked for: $(echo "$patterns" | tr '\n' ' '))" >&2
-          exit 2
+          printf '{"ts":"%s","hook":"task-completed","warn":"empty_contract_publish","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
         fi
       fi
     fi
@@ -101,7 +98,7 @@ case "$title" in
 esac
 
 # Validate escalation entries if present.
-required_fields=("Phase" "Context" "Options" "Recommendation" "Need from you")
+required_fields=("Phase" "Context" "Options" "Recommendation" "Need from you" "Peer attempts")
 missing_any=""
 entries="$(printf '%s' "$payload" | jq -c '(.task.metadata.blocked_questions // .metadata.blocked_questions // [])[]?' 2>/dev/null || true)"
 
@@ -130,8 +127,7 @@ if [ -n "$entries" ]; then
 fi
 
 if [ -n "$missing_any" ]; then
-  echo "BAD_ESCALATION: missing field(s) $missing_any" >&2
-  exit 2
+  printf '{"ts":"%s","hook":"task-completed","warn":"bad_escalation","missing":%s}\n' "$ts" "$(printf '%s' "$missing_any" | jq -Rs .)" >> "$LOG_FILE"
 fi
 
 exit 0

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

@@ -70,11 +70,11 @@ case "$title" in
   review:*|meta:*|block:*) exit 0 ;;
   impl:*) ;;
   "")
-    echo "BAD_PREFIX: task title missing; must start with impl:|review:|meta:|block:" >&2
-    exit 2 ;;
+    printf '{"ts":"%s","hook":"task-created","warn":"bad_prefix","reason":"title missing"}\n' "$ts" >> "$LOG_FILE"
+    ;;
   *)
-    echo "BAD_PREFIX: task title must start with impl:|review:|meta:|block: (got: $title)" >&2
-    exit 2 ;;
+    printf '{"ts":"%s","hook":"task-created","warn":"bad_prefix","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+    ;;
 esac
 
 # At this point title starts with `impl:`. Strip prefix and require a known
@@ -91,22 +91,20 @@ case "$rest" in
     sub="contract"
     ;;
   *)
-    echo "BAD_PREFIX: impl: task requires a sub-prefix (be-|fe-|qa-fix-be-|qa-fix-fe-|review-fix-be-|review-fix-fe-|contract-update-|be-migration-|be-contract-publish-). Got: $title" >&2
-    exit 2 ;;
+    printf '{"ts":"%s","hook":"task-created","warn":"bad_subprefix","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+    exit 0 ;;
 esac
 
 # Shape-aware enforcement
 case "$shape" in
   be-only)
     if [ "$sub" = "fe" ]; then
-      echo "SHAPE_REJECTED: shape is 'be-only'; impl:fe-* tasks are not allowed for this feature." >&2
-      exit 2
+      printf '{"ts":"%s","hook":"task-created","warn":"shape_rejected","shape":"be-only","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
     fi
     ;;
   fe-only)
     if [ "$sub" = "be" ]; then
-      echo "SHAPE_REJECTED: shape is 'fe-only'; impl:be-* tasks are not allowed for this feature." >&2
-      exit 2
+      printf '{"ts":"%s","hook":"task-created","warn":"shape_rejected","shape":"fe-only","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
     fi
     ;;
   full-stack|"")

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

@@ -38,8 +38,7 @@ unanswered="$(printf '%s' "$payload" | jq '[.mailbox[]? | select((.from // "") !
 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
+  printf '{"ts":"%s","hook":"teammate-idle","warn":"blocked_idle","unanswered":%s}\n' "$ts" "$unanswered" >> "$LOG_FILE"
 fi
 
 exit 0

package/plugins/team-superpower/scripts/team-state.sh

@@ -28,7 +28,7 @@
 #   1  dry-run completed with items to remove (caller should re-run with --force)
 #   2  bad arguments
 #   3  heartbeat indicates a live lead; refuse without --ignore-heartbeat
-#   4  nothing to clean up (cleanup) / no teams found (scan)
+#   4  nothing to clean up (cleanup only; scan is read-only and always exits 0)
 
 set -euo pipefail
 
@@ -82,7 +82,7 @@ cmd_scan() {
     slugs="$(list_all_team_slugs)"
     if [ -z "$slugs" ]; then
       echo "No team-superpower teams found under $TEAMS_DIR"
-      return 4
+      return 0
     fi
     echo "team-superpower teams on this machine:"
     while IFS= read -r s; do

package/plugins/tech-graph/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-graph",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"