@drunkcoding/agents-and-skills 0.0.13 → 0.0.15

package/plugins/html-effectiveness/tests/manifest.test.js

@@ -0,0 +1,61 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = dirname(HERE);
+const MANIFEST = JSON.parse(readFileSync(join(PLUGIN_ROOT, 'templates/manifest.json'), 'utf8'));
+const VALID_BUNDLES = new Set(['base', 'components', 'charts']);
+
+const entries = Object.entries(MANIFEST).filter(([k]) => k !== '_meta');
+
+test('manifest declares 20 vendored templates', () => {
+  assert.equal(entries.length, 20, `expected 20 entries, got ${entries.length}`);
+});
+
+test('_meta records upstream SHA and fetch date', () => {
+  const meta = MANIFEST._meta;
+  assert.ok(meta, '_meta missing');
+  assert.match(meta.upstream_sha, /^[0-9a-f]{40}$/, 'upstream_sha must be 40-char hex');
+  assert.match(meta.fetched_at, /^\d{4}-\d{2}-\d{2}$/, 'fetched_at must be YYYY-MM-DD');
+  assert.equal(meta.upstream_repo, 'ThariqS/html-effectiveness');
+});
+
+for (const [id, entry] of entries) {
+  test(`${id}: required fields present`, () => {
+    for (const f of ['title', 'use_cases', 'pattern', 'slots', 'asset_bundles']) {
+      assert.ok(f in entry, `${id} missing field "${f}"`);
+    }
+    assert.ok(Array.isArray(entry.use_cases), `${id} use_cases must be array`);
+    assert.ok(entry.use_cases.length > 0, `${id} use_cases must be non-empty`);
+    assert.equal(typeof entry.pattern, 'string', `${id} pattern must be string`);
+    assert.equal(typeof entry.slots, 'object', `${id} slots must be object`);
+  });
+
+  test(`${id}: asset_bundles valid`, () => {
+    assert.ok(Array.isArray(entry.asset_bundles), `${id} asset_bundles not array`);
+    for (const b of entry.asset_bundles) {
+      assert.ok(VALID_BUNDLES.has(b), `${id} asset_bundles contains invalid "${b}"`);
+    }
+  });
+
+  test(`${id}: template file exists`, () => {
+    const tmplRel = entry.tmpl || `templates/${id}.html.tmpl`;
+    const tmplAbs = join(PLUGIN_ROOT, tmplRel);
+    assert.ok(existsSync(tmplAbs), `${id} template file missing: ${tmplRel}`);
+  });
+
+  test(`${id}: fixture file exists`, () => {
+    const fix = join(PLUGIN_ROOT, `tests/fixtures/${id}.data.json`);
+    assert.ok(existsSync(fix), `${id} fixture missing: tests/fixtures/${id}.data.json`);
+    const data = JSON.parse(readFileSync(fix, 'utf8'));
+    for (const [slot, schemaRaw] of Object.entries(entry.slots)) {
+      const schema = typeof schemaRaw === 'string' ? { type: schemaRaw } : schemaRaw;
+      if (schema.required) {
+        assert.ok(slot in data, `${id} fixture missing required slot "${slot}"`);
+      }
+    }
+  });
+}

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

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

package/plugins/plugin-validator/skills/validate-agents/SKILL.md

@@ -18,7 +18,7 @@ find plugins -path '*/agents/*.md'
 find plugins -path '*/.claude-plugin/plugin.json'
 ```
 
-For each `plugin.json`, parse and check whether the `agents` key is present (any shape). Emit one `[FAIL]` per plugin that declares it. Then validate every agent `.md` file as below.
+For each `plugin.json`, parse the optional `agents` field if present (see "`agents` field rule" below). Then validate every agent `.md` file as below.
 
 ## Spec Compliance Checks
 
@@ -30,7 +30,7 @@ For each `plugin.json`, parse and check whether the `agents` key is present (any
 | `description` length | 1-1024 chars, non-empty |
 | `tools` optional | Comma-separated string; each name appears in the valid-tool list below |
 | `model` optional | One of `sonnet`, `opus`, `haiku`, `inherit` |
-| No `agents` key in plugin.json | The plugin loader rejects any `agents` field with `agents: Invalid input`. Agent files are auto-discovered from `<plugin>/agents/*.md`. If `plugin.json` declares an `agents` array (or any other shape), flag as `[FAIL]` and recommend deleting the key. Confirmed against `anthropics/claude-code` official plugins (`pr-review-toolkit`, `frontend-design`, `commit-commands`, `hookify`) — none declare `agents`. |
+| `agents` field rule | Optional. Per https://code.claude.com/docs/en/plugins-reference#component-path-fields, value is `string` or `array`. Each entry must be a relative path starting with `./` (per "Path behavior rules"). If field is absent, agents are auto-discovered from `<plugin>/agents/*.md`. **Failure modes**: (a) value type other than string/array → `[FAIL]`. (b) entry does not start with `./` → `[FAIL]` (loader rejects with `agents: Invalid input` for bare filenames like `"reviewer.md"`). (c) entry points outside plugin root (contains `..`) → `[FAIL]`. (d) entry path does not exist on disk → `[FAIL]`. (e) field present and replaces the default `agents/` directory while files there exist that are not listed → `[WARN]` (loader silently drops them; v2.1.140+ shows `/doctor` warning). |
 
 ### Valid tool names (Claude Code ≥ 2.1.139)
 

package/plugins/plugin-validator/skills/validate-commands/SKILL.md

@@ -18,7 +18,7 @@ find plugins -path '*/commands/*.md'
 find plugins -path '*/.claude-plugin/plugin.json'
 ```
 
-For each `plugin.json`, parse and check whether the `commands` key is present (any shape). Emit one `[FAIL]` per plugin that declares it. Then validate every command `.md` file as below.
+For each `plugin.json`, parse the optional `commands` field if present (see "`commands` field rule" below). Then validate every command `.md` file as below.
 
 ## Spec Compliance Checks
 
@@ -31,7 +31,7 @@ For each `plugin.json`, parse and check whether the `commands` key is present (a
 | `model` optional | One of `sonnet`, `opus`, `haiku`, `inherit` |
 | Filename → command | Filename minus `.md` is lowercase alphanumeric + hyphens; produces `/<filename>` |
 | Body non-empty | At least one non-blank line after frontmatter |
-| No `commands` key in plugin.json | The plugin loader rejects any `commands` field with `commands: Invalid input`. Command files are auto-discovered from `<plugin>/commands/*.md`. If `plugin.json` declares a `commands` array (or any other shape), flag as `[FAIL]` and recommend deleting the key. Confirmed against `anthropics/claude-code` official plugins (`pr-review-toolkit`, `frontend-design`, `commit-commands`, `hookify`) — none declare `commands`. |
+| `commands` field rule | Optional. Per https://code.claude.com/docs/en/plugins-reference#component-path-fields, value is `string` or `array`. Each entry must be a relative path starting with `./` (per "Path behavior rules"). If field is absent, commands are auto-discovered from `<plugin>/commands/*.md`. **Failure modes**: (a) value type other than string/array → `[FAIL]`. (b) entry does not start with `./` → `[FAIL]` (loader rejects with `commands: Invalid input` for bare filenames). (c) entry points outside plugin root (contains `..`) → `[FAIL]`. (d) entry path does not exist on disk → `[FAIL]`. (e) field present and replaces the default `commands/` directory while files there exist that are not listed → `[WARN]` (loader silently drops them; v2.1.140+ shows `/doctor` warning). |
 
 ### Valid tool names (Claude Code ≥ 2.1.139)
 

package/plugins/plugin-validator/skills/validate-hooks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: validate-hooks
-description: Validates plugin hooks (plugin.json hooks field and any referenced hooks.json) in plugins/** against the Claude Code plugin spec. Use via /validate-hooks command.
+description: Validates plugin hooks (plugin.json hooks field and any hooks/hooks.json) in plugins/** against the Claude Code plugin spec. Use via /validate-hooks command.
 license: MIT
 metadata:
   author: Steven Hoang
@@ -9,37 +9,74 @@ metadata:
 
 # Validate Hooks
 
-Validate plugin hooks under `plugins/**` against the Claude Code plugin spec. Scope: `plugins/**` only — local-only `.claude/skills/` and `.claude/hooks/` are out of scope.
+Validate plugin hooks under `plugins/**` against the Claude Code plugin spec (https://code.claude.com/docs/en/hooks, https://code.claude.com/docs/en/plugins-reference#hooks). Scope: `plugins/**` only — local-only `.claude/hooks/` is out of scope.
 
 ## Discovery
 
 ```bash
-find plugins -name 'hooks.json'
-find plugins -name 'plugin.json' -path '*/.claude-plugin/*'
+/usr/bin/find plugins -name 'hooks.json'
+/usr/bin/find plugins -name 'plugin.json' -path '*/.claude-plugin/*'
 ```
 
-Parse each `plugin.json`. If its `hooks` field is an inline object, validate inline. If its `hooks` field is a string path, that is a hard `[FAIL]` (see Spec Compliance below) — but still attempt to resolve and parse the referenced file for additional checks.
+For each `plugin.json`, classify the `hooks` field:
+
+| Form | Action |
+|------|--------|
+| absent | Use auto-discovery: validate `<plugin_root>/hooks/hooks.json` if it exists. If neither field nor file exist, plugin has no hooks — skip. |
+| string path | Resolve relative to plugin root, parse referenced JSON, validate. |
+| array of paths | Resolve each, parse, validate each. |
+| object (inline config) | Validate inline. |
+
+All four forms are spec-legal. **Do not flag the `hooks` field for being a string, array, or object.**
+
+If both inline `hooks` and `hooks/hooks.json` exist, emit `[WARN]` — duplication invites drift; pick one source of truth.
 
 ## Spec Compliance Checks
 
 | Check | Rule |
 |-------|------|
-| `hooks` field shape | Must be an inline object. String-path form (`"hooks": "<path>"`) is rejected by the Claude Code plugin loader with `hooks: Invalid input`. Flag as `[FAIL]`. |
-| Top-level event keys | One of: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `Notification`, `PreCompact`, `SessionStart`, `SessionEnd` |
-| Event value | Array of matcher groups |
-| Matcher group shape | `{ matcher: string, hooks: [...] }` |
-| Hook entry shape | `{ type: "command"\|"prompt", command?: string, prompt?: string, timeout?: integer }` |
-| Command path resolves | Resolves relative to plugin root, or uses `${CLAUDE_PROJECT_DIR}` / `${CLAUDE_PLUGIN_ROOT}` |
-| Executable bit | Referenced shell script has `+x` |
-| Regex compiles | Matcher value compiles as a Python `re` pattern |
+| Top-level container | The hooks config is an object with a single `hooks` key whose value is an object keyed by event name. |
+| Event name in allowlist | One of the 28 events below. |
+| Event value | Array of matcher groups. |
+| Matcher group shape | `{ matcher?: string, hooks: [...] }` (matcher optional). |
+| Hook entry `type` | One of: `command`, `http`, `mcp_tool`, `prompt`, `agent`. |
+| Hook entry shape (command) | `{ type: "command", command: string, args?: array, timeout?: integer, statusMessage?: string, if?: string, once?: boolean }`. |
+| Hook entry shape (http) | `{ type: "http", url: string, headers?: object, timeout?: integer, ... }`. |
+| Hook entry shape (mcp_tool) | `{ type: "mcp_tool", server: string, tool: string, ... }`. |
+| Hook entry shape (prompt) | `{ type: "prompt", prompt: string, model?: string, timeout?: integer, ... }`. |
+| Hook entry shape (agent) | `{ type: "agent", agent: string, prompt?: string, timeout?: integer, ... }`. |
+| Command path resolves | Resolves relative to plugin root, or uses `${CLAUDE_PROJECT_DIR}` / `${CLAUDE_PLUGIN_ROOT}`. |
+| Executable bit | Referenced shell script has `+x`. |
+| Regex compiles | Matcher value compiles as a Python `re` pattern (only checked when matcher contains characters outside `[A-Za-z0-9_|]`). |
+
+### Allowed event names (28)
+
+```
+SessionStart, Setup, InstructionsLoaded, UserPromptSubmit, UserPromptExpansion,
+PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure,
+PostToolBatch, Notification, SubagentStart, SubagentStop,
+TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle,
+ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove,
+PreCompact, PostCompact, SessionEnd, Elicitation, ElicitationResult
+```
+
+### Events that do NOT support `matcher`
+
+```
+UserPromptSubmit, PostToolBatch, Stop, TeammateIdle,
+TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, CwdChanged
+```
+
+If a matcher group under one of these events sets a `matcher` field, emit `[WARN]` — the field is silently ignored by the loader. Not a `[FAIL]`.
 
 ## Best-Practice Checks
 
 | Check | Rule |
 |-------|------|
-| No absolute user paths | Body of command does not contain `/Users/<name>/...` or `/home/<name>/...` |
-| Timeout sane | `timeout` ≤ 60 unless inline comment justifies |
-| Prompt-type targets exist | `prompt`-type hooks reference skills or commands that exist on disk |
+| No absolute user paths | Body of `command` does not contain `/Users/<name>/...` or `/home/<name>/...`. |
+| Timeout sane | `timeout` ≤ 60 unless inline comment justifies. |
+| Prompt/agent targets exist | `prompt`-type and `agent`-type hooks reference skills, commands, or agents that exist on disk. |
+| `${CLAUDE_PLUGIN_ROOT}` quoting | Shell-form commands wrap `${CLAUDE_PLUGIN_ROOT}` in double quotes (path may contain spaces). |
 
 ## How to Run
 
@@ -52,13 +89,15 @@ Parse each `plugin.json`. If its `hooks` field is an inline object, validate inl
 
    ### plugins/<plugin>/<file>
    - [PASS] <check description>
+   - [WARN] <check description>: <details>
    - [FAIL] <check description>: <details>
    ```
 
-4. Final tally: `Summary: <N> hooks files scanned. <P> pass, <F> fail.`
+4. Final tally: `Summary: <N> hooks files scanned. <P> pass, <F> fail, <W> warn.`
 
 ## References
 
-- [Claude Code plugin docs](https://docs.claude.com/en/docs/claude-code/plugins.md)
+- Hook event lifecycle: https://code.claude.com/docs/en/hooks
+- Plugin hook location + types: https://code.claude.com/docs/en/plugins-reference#hooks
 - Resolution evidence: see `docs/superpowers/specs/2026-05-13-plugin-validation-skills-design.md` § Resolution 1
 - Sibling skills: `validate-skills`, `validate-agents`, `validate-commands`

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

@@ -1,8 +1,8 @@
 {
   "name": "team-superpower",
   "displayName": "Team Superpower",
-  "version": "0.0.13",
-  "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.15",
+  "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"
   },
@@ -13,41 +13,9 @@
     "orchestration",
     "workflow",
     "brainstorming",
-    "code-review"
-  ],
-  "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"
-          }
-        ]
-      }
-    ]
-  }
+    "code-review",
+    "architecture",
+    "security",
+    "qa"
+  ]
 }

package/plugins/team-superpower/README.md

@@ -1,34 +1,55 @@
 # 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**.
+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 design → plan → architecture + security gate → BE/FE implementation → QA gate → code review → finish, with at most **3 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.
+This plugin is *not* a fork of Superpowers. It consumes Superpowers skills as-installed and adds the orchestration: who runs which skill, when, and how teammates talk without bothering the owner.
+
+## v2 — shape-adaptive, project-aware
+
+The plugin reads a `team-superpower` YAML block from your repo-root `CLAUDE.md` to drive every stack decision: BE-only repos do not spawn a frontend teammate, FE-only repos do not spawn a backend teammate, full-stack repos get both plus a contract-publish gate. Test/build/format commands come from `CLAUDE.md` — no more hard-coded `dotnet test`. CI green is required before the finish-branch menu (when a CI provider is configured). The security engineer's checklist is project-aware (no SQL items if no SQL, no XSS items if no HTML). The Superpowers version is pinned at session start so mid-feature skill drift can't corrupt recovery. See `assets/CLAUDE.md.template` for the schema and `docs/superpowers/README.md` (seeded on first run) for the operating manual.
 
 ## 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`.
+- **Eight agent roles**, each with a tightly-scoped system prompt mapping it to specific Superpowers skills or gate behaviour:
+  - `designer` — runs `brainstorming` (phase 1).
+  - `planner` — runs `using-git-worktrees` then `writing-plans` (phase 2). Routes implementation by `impl:be-` / `impl:fe-` prefix.
+  - `software-architect` — phase-3 pre-impl architecture gate. Reviews design + plan. Posts `ARCH_PASSED` / `ARCH_BLOCKED`.
+  - `security-engineer` — phase-3 pre-impl security gate, parallel with `software-architect`. Threat-models design + plan. Posts `SEC_PASSED` / `SEC_BLOCKED`.
+  - `backend-developer` — phase-4 implementer for `impl:be-` tasks (server, data, infra, CI). Runs `subagent-driven-development` + `test-driven-development` per task.
+  - `frontend-developer` — phase-4 implementer for `impl:fe-` tasks. Same skill chain.
+  - `qa-engineer` — phase-5 post-impl QA gate. Verifies acceptance criteria + regression coverage. Posts `QA_PASSED` / `QA_BLOCKED`.
+  - `reviewer` — phase-6 runs `requesting-code-review`; phase-7 runs `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.
+  - `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.
+- `scripts/team-state.sh` — 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.
+  - **Two gate phases** (pre-impl arch+security, post-impl QA) — block forward progress until findings resolve, so the reviewer at phase 6 sees clean code-quality issues only, not architectural or security regressions.
   - **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).
 
+## Phase chain at a glance
+
+| Phase | Role(s) | Output | Gate? |
+|---|---|---|---|
+| 1 Design | `designer` | Design doc → `docs/superpowers/specs/` | Owner approval |
+| 2 Plan | `planner` | Worktree + plan with `impl:be-` / `impl:fe-` tasks → `docs/superpowers/plans/` | Owner approval |
+| 3 Pre-impl review (parallel) | `software-architect` + `security-engineer` | ARCH + SEC reports → `docs/superpowers/reviews/` | Both must post PASSED |
+| 4 Implementation (parallel) | `backend-developer` + `frontend-developer` | TDD commits on feature branch | All `impl:` tasks complete |
+| 5 QA | `qa-engineer` | QA report → `docs/superpowers/reviews/` | `QA_PASSED` |
+| 6 Code review | `reviewer` | Review report → `docs/superpowers/reviews/` | `REVIEW_PASSED` |
+| 7 Finish | `reviewer` | Merge / PR / keep / discard | Owner decision |
+
 ## Requirements
 
 - Claude Code `2.1.32` or later.
-- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your environment (the slash command will halt if absent).
+- `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).
 
@@ -54,15 +75,30 @@ Then make sure the agent-teams env flag is set in `~/.claude/settings.json`:
 /team-feature add a /healthcheck endpoint that returns 200 OK
 ```
 
-You will be interrupted at most four times:
+You will be interrupted at most three times:
 
-1. Brainstorming clarifying questions (batched per phase).
-2. Design sign-off.
-3. Plan approval.
-4. Finish-branch decision (merge / PR / keep / discard).
+1. Design sign-off (after phase 1).
+2. Plan approval (after phase 2).
+3. Finish-branch decision — merge / PR / keep / discard (in phase 7).
 
 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.
 
+## Task prefix routing
+
+The planner assigns every `impl:` task one of two sub-prefixes; the lead routes by prefix:
+
+| Prefix | Routed to | Scope |
+|---|---|---|
+| `impl:be-` | `backend-developer` | Server-side code, APIs, data, schemas, migrations, infra / CI scripts, Docker, IaC |
+| `impl:fe-` | `frontend-developer` | UI components, pages, client-side state, styles, browser assets |
+
+Defect-fix tasks filed mid-flight inherit the routing prefix:
+
+| Prefix | Filed by | Routed to |
+|---|---|---|
+| `impl:qa-fix-be-` / `impl:qa-fix-fe-` | `qa-engineer` (phase 5) | matching BE / FE implementer |
+| `impl:review-fix-be-` / `impl:review-fix-fe-` | `reviewer` (phase 6) | matching BE / FE implementer |
+
 ## Resume after `/resume` drops the team
 
 ```text
@@ -95,13 +131,30 @@ bash plugins/team-superpower/scripts/team-state.sh cleanup <slug> --force  # app
 
 `/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
+- every phase from design 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)
+- the expected commits exist on the worktree (design, plan, ARCH+SEC reports, TDD pairs of test + code, QA report, 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.**
 
+### Worktree removal on merge
+
+When (and only when) the finish decision is `merged` AND the platform-cleanup scan shows everything `absent`, the lead now runs a Step D.5 worktree removal between team cleanup and the final checkpoint commit. `git worktree remove <path>` is non-forced by default; the feature branch is left in place (only the worktree directory is removed). If `git worktree remove` fails (untracked files, locked worktree, in-progress git operation), the lead presents a 4-option menu:
+
+| | Option | Behaviour |
+|---|---|---|
+| A | Show files + retry | Lists blocking files via `git status --short` + `git diff --stat`, then retries (cap 3). |
+| B | Force remove | Discards uncommitted work in the worktree (requires typed `yes` confirmation). |
+| C | Keep worktree | Leaves the directory on disk; owner removes manually. |
+| D | Escalate | §7 escalation with verbatim stderr. |
+
+Other finish decisions (`pr_opened`, `kept`, `discarded`) skip Step D.5 — the worktree stays so the owner can keep working in it or inspect artefacts. The Closing block records the outcome with a `worktree:` field.
+
+### Merge-failure menu
+
+If the reviewer's merge step in phase 7 fails (`conflict` / `non-ff` / `dirty-worktree` / `push-rejected`), it posts `FINISH_BLOCKED <reason>` instead of `FINISH_DONE`. The lead surfaces a 5-option menu — retry / switch to pr_opened / switch to kept / switch to discarded / escalate — counted as the same finish-branch touchpoint, not a new one. Retries cap at 3; after the 3rd `FINISH_BLOCKED`, option A drops. The cap persists across `/team-feature-resume` via the checkpoint.
+
 ## Layout
 
 ```
@@ -111,7 +164,11 @@ plugins/team-superpower/
 ├── agents/
 │   ├── designer.md
 │   ├── planner.md
-│   ├── implementer.md
+│   ├── software-architect.md
+│   ├── security-engineer.md
+│   ├── backend-developer.md
+│   ├── frontend-developer.md
+│   ├── qa-engineer.md
 │   └── reviewer.md
 ├── commands/
 │   ├── team-feature.md
@@ -120,13 +177,16 @@ plugins/team-superpower/
 ├── hooks/
 │   ├── hooks.json
 │   ├── teammate-idle.sh
-│   ├── task-created.sh
-│   └── task-completed.sh
+│   ├── task-created.sh       → recognises v2 sub-prefixes and the shape marker
+│   └── task-completed.sh     → migration serialization + contract-publish verification
 ├── scripts/
-│   └── team-state.sh      → inspection + cleanup helper, called by the slash commands
+│   ├── team-state.sh         → inspection + cleanup helper
+│   ├── detect-stack.sh       → filesystem-based stack detection (BE / FE / contracts / CI)
+│   └── parse-claudemd.sh     → extract the team-superpower block from CLAUDE.md
 └── assets/
-    ├── ESCALATION.md      → seeded to docs/superpowers/ESCALATION.md on first run
-    └── SESSION_README.md  → seeded to docs/superpowers/README.md on first run
+    ├── ESCALATION.md         → seeded to docs/superpowers/ESCALATION.md on first run
+    ├── SESSION_README.md     → seeded to docs/superpowers/README.md on first run
+    └── CLAUDE.md.template    → copy to repo root if no CLAUDE.md exists
 ```
 
 ## Design
@@ -136,6 +196,7 @@ See the project's `docs/superpowers/README.md` after first run for the operating
 - 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.
+- **Two gate phases** keep the reviewer's job small. Architecture and security issues are caught at phase 3 (pre-impl) so implementers don't waste cycles on plans that fail review. QA defects are caught at phase 5 (post-impl) so the reviewer at phase 6 only deals with code-quality findings.
 - 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.
 
@@ -143,7 +204,7 @@ See the project's `docs/superpowers/README.md` after first run for the operating
 
 - Token-usage metrics per teammate per phase.
 - Per-role permission allowlists.
-- Frontend/backend specialist implementers (defer until pattern proves out).
+- Standalone devops, technical-writer, or minimal-change-engineer roles — infra/CI folds into `backend-developer`; documentation lands in PR descriptions and inline; minimal-change patterns are scoped per task by the planner.
 
 ## License
 

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

@@ -0,0 +1,82 @@
+---
+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
+---
+
+# Backend Developer — Phase 4 (Implementation)
+
+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
+
+Before claiming your first task — and on every resume — read the repo-root `CLAUDE.md`. Use `bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh get backend.<field>` to fetch individual scalars. The `backend` block defines your toolbelt:
+
+| `CLAUDE.md` key             | How you use it |
+|-----------------------------|----------------|
+| `backend.test_command`      | Use after every RED→GREEN cycle to verify. Never hard-code `dotnet test` or `npm test`. |
+| `backend.build_command`     | Use to confirm the project still builds. |
+| `backend.format_command`    | Run after REFACTOR if defined and not `none`. |
+| `backend.test_framework`    | xunit / nunit / mstest / **reqnroll** / pytest / jest / vitest / etc. Reqnroll changes how tests are written — see below. |
+| `backend.migration_tool`    | Names the migration runner. Schema-touching tasks come with `impl:be-migration-*` prefix; do not invent your own migrations outside that prefix. |
+| `backend.package_manager`   | Use the project's package manager when adding deps — do not silently switch (`pnpm` ≠ `npm` ≠ `yarn`). |
+
+Also read the free-form prose in CLAUDE.md (sections after the YAML block, e.g. `## Conventions`). Style rules, naming, and "we don't do X here" guidance live there. Apply them.
+
+If `CLAUDE.md` has no `team-superpower` block, halt and escalate via §7. The lead's phase 0 should have already produced `docs/superpowers/stack.detected.md` — work from that if so, otherwise escalate to the owner.
+
+## Hard rules
+
+1. Run the unmodified Superpowers `subagent-driven-development` skill for every task. Read `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/skills/subagent-driven-development/SKILL.md` before claiming your first task.
+2. Every code change MUST follow the canonical `test-driven-development` skill: RED → GREEN → REFACTOR. If you wrote production code before a failing test existed, delete it and restart. Non-negotiable.
+3. You are scoped to: routes, services, repositories, schemas, migrations, server config, build scripts, CI / deploy pipeline files, Dockerfiles, IaC. Do NOT touch frontend files (`components/`, `pages/`, browser `assets/`). If a task bleeds into frontend scope, halt and escalate.
+4. You **may not** modify the plan or the design. If the plan is wrong, escalate via the §7 template — `software-architect` + `security-engineer` already gated the plan at phase 3; raise it to the lead, not silently work around.
+5. You handle `impl:qa-fix-be-` and `impl:review-fix-be-` tasks (filed by `qa-engineer` and `reviewer` respectively).
+6. Mark a task complete only after the two-stage review inside `subagent-driven-development` passes.
+7. **Migrations serialize.** If your claim is `impl:be-migration-*` and another `impl:be-migration-*` task is `in_progress`, idle and wait — do NOT claim. The `TaskCompleted` hook also enforces this with `MIGRATION_RACE` as a backstop.
+8. **Use the test framework from CLAUDE.md.** Do not hard-code `dotnet test` / `npm test` / `pytest`. If `backend.test_framework: reqnroll`, expect `.feature` Gherkin files in the plan — write step bindings against them rather than authoring xUnit tests yourself. The planner owns the Gherkin.
+9. **Use the format command from CLAUDE.md** after every REFACTOR, unless `backend.format_command` is `none` or unset.
+
+## Contract-publish task (full-stack only)
+
+If your claim is `impl:be-contract-publish-<slug>`:
+
+1. Read `contracts.source_of_truth`, `contracts.openapi_path` (or analogous), and `contracts.ts_gen_command` from CLAUDE.md.
+2. Generate or update the contract artefact per the plan's instructions for this feature. Commit the artefact.
+3. Run `contracts.ts_gen_command` (or the equivalent for grpc / graphql / typescript) to regenerate FE-consumable types. Commit the generated output.
+4. Set `metadata.contract_files` on the task (so the `TaskCompleted` hook can confirm a commit touched it).
+5. Post `CONTRACT_PUBLISHED <task-id>` to the lead's mailbox — the lead will not assign any `impl:fe-*` task until it sees this.
+6. Mark the task complete. The `TaskCompleted` hook will refuse completion if no commit on this task touches a contract file — that's the backstop against silent no-ops.
+
+## Mid-implementation contract drift
+
+If, during a non-publish backend task, you discover the published contract needs to change:
+
+1. Halt your current task (do not partially-edit the contract sideways).
+2. File a new task titled `impl:contract-update-<topic>` (the hook recognizes the prefix). Self-claim it.
+3. The lead pauses all `impl:fe-*` work via mailbox.
+4. Update the contract files. Run `contracts.ts_gen_command` to regenerate FE-consumable types. Commit.
+5. Post `CONTRACT_UPDATED <task-id>` to the lead's mailbox.
+6. The lead resumes FE work — FE will re-pull the contract hash before continuing.
+7. Resume your original task.
+
+If a `frontend-developer` posts `CONTRACT_DRIFT_DETECTED <details>` to your mailbox first, follow the same flow: halt your current task (if any), file the `impl:contract-update-*` task, fix the contract, post `CONTRACT_UPDATED`, resume.
+
+## Responsibilities
+
+Claim the lowest-numbered eligible backend task (any of `impl:be-*`, `impl:be-migration-*`, `impl:be-contract-publish-*`, `impl:contract-update-*`, `impl:qa-fix-be-*`, `impl:review-fix-be-*`), mark it in-progress, run subagent-driven-development, mark complete. Repeat until no eligible tasks remain, then idle.
+
+## Output
+
+Committed code on the feature branch per task. No separate report needed.
+Post `BE_DONE <task-id>` to the lead's mailbox after each task completes. For contract tasks, also post `CONTRACT_PUBLISHED <task-id>` (on publish) or `CONTRACT_UPDATED <task-id>` (on drift fix).
+
+## Escalation
+
+Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common blockers:
+- Task scope bleeds into frontend files.
+- Plan contradicts design doc on an API contract.
+- 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.

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

@@ -11,13 +11,17 @@ You are the **designer** teammate on a team-superpower agent team. The lead spaw
 
 ## 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.
+1. Run the unmodified Superpowers `brainstorming` skill at `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/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.
 
+## Output
+
+A committed design document at `docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md`, owner-approved per the brainstorming skill's sign-off step. Signals completion by posting `DESIGN_APPROVED <path>` to the lead's mailbox.
+
 ## What you must NOT do
 
 - Decide implementation strategy. The plan is the planner's job.