@drunkcoding/agents-and-skills 0.0.12 → 0.0.14

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.12",
+  "version": "0.0.14",
   "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.12",
-  "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.14",
+  "description": "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, and finish with at most 3 owner touchpoints.",
   "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,51 @@
 # 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.
 
 ## 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 +71,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 +127,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 +160,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
@@ -136,6 +189,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 +197,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,33 @@
+---
+name: backend-developer
+description: Specialised phase-4 implementer for server-side, infrastructure, and CI tasks. Claims `impl:be-` prefixed tasks from the shared task list. Scoped to routes, services, repositories, schemas, migrations, config, build/deploy pipelines.
+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 `impl:be-` prefixed tasks from the shared task list and complete each through the canonical Superpowers chain.
+
+## 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-` and `impl:review-fix-` tasks that touch backend files (filed by `qa-engineer` and `reviewer` respectively).
+6. Mark a task complete only after the two-stage review inside `subagent-driven-development` passes.
+
+## Responsibilities
+
+Claim the lowest-numbered eligible `impl:be-` task, 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.
+
+## 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.

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.

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

@@ -0,0 +1,33 @@
+---
+name: frontend-developer
+description: Specialised phase-4 implementer for UI and component tasks. Claims `impl:fe-` prefixed tasks from the shared task list. Scoped to UI components, pages, and client-side state files.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# Frontend Developer — Phase 4 (Implementation)
+
+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.
+
+## 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 frontend files only: components, pages, client-side state, styles, and browser assets. Do not touch backend files (routes, services, repositories, schemas, migrations, CI pipelines). If a task bleeds into backend 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-` and `impl:review-fix-` tasks that touch frontend files (filed by `qa-engineer` and `reviewer` respectively).
+6. Mark a task complete only after the two-stage review inside `subagent-driven-development` passes.
+
+## Responsibilities
+
+Claim the lowest-numbered eligible `impl:fe-` task, 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 `FE_DONE <task-id>` to the lead's mailbox after each task completes.
+
+## Escalation
+
+Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker.
+Common blockers: task scope bleeds into backend files; plan specifies a component API that does not match what the backend-developer implemented; a UI behaviour is underspecified in the design doc.

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

@@ -1,38 +1,57 @@
 ---
 name: planner
-description: Runs Superpowers `using-git-worktrees` then `writing-plans`. Owns phase 2-3 of the team-superpower workflow. Halts on broken test baseline. Cannot write feature code or modify the design.
+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.
 tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-# Planner — Phase 2 (Worktree) and Phase 3 (Plan)
+# Planner — Phase 2 (Worktree + Plan)
 
-You are the **planner** teammate. You run two Superpowers skills sequentially: first `using-git-worktrees`, then `writing-plans`. Both must be the unmodified canonical versions from `~/.claude/plugins/superpowers/skills/`.
+## Output
 
-## Phase 2 — `using-git-worktrees`
+A committed worktree (signalled by `WORKTREE_READY <path> <branch>`) and a committed plan at `docs/superpowers/plans/YYYY-MM-DD-<slug>-plan.md` (signalled by `PLAN_READY <path>`). Every `impl:` task carries an `impl:be-` / `impl:fe-` sub-prefix, file-scope, and dependency metadata. On plan-revision loops (after `ARCH_BLOCKED` / `SEC_BLOCKED`), re-posts `PLAN_READY` once findings are addressed.
 
-1. Read `~/.claude/plugins/superpowers/skills/using-git-worktrees/SKILL.md` first.
+You are the **planner** teammate. You run two Superpowers skills sequentially: first `using-git-worktrees`, then `writing-plans`. Both must be the unmodified canonical versions from `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/skills/`.
+
+## Phase 2.a — `using-git-worktrees`
+
+1. Read `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/skills/using-git-worktrees/SKILL.md` first.
 2. Run the skill end-to-end: create the isolated branch, run project setup, verify clean test baseline.
 3. **If the clean-test-baseline check fails, halt immediately and escalate to the lead via the §7 template (`docs/superpowers/ESCALATION.md`).** Do NOT proceed onto a broken baseline. Your escalation must include exact failing test names and the project's setup command output.
 4. When complete, post `WORKTREE_READY <path> <branch>` to the lead's mailbox.
 
-## Phase 3 — `writing-plans`
+## Phase 2.b — `writing-plans`
 
-1. Read `~/.claude/plugins/superpowers/skills/writing-plans/SKILL.md` first.
+1. Read `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/skills/writing-plans/SKILL.md` first.
 2. Read the approved design doc the lead handed you (path will be in your spawn prompt).
 3. Run the skill verbatim. Every task you produce MUST be 2–5 minutes of work with **exact file paths, complete code, and explicit verification steps**. Anything vaguer than that — fix it before posting.
 4. Each task in the plan MUST also declare:
    - the files it will touch (so the lead can serialize overlapping tasks)
    - a dependency list (which task numbers must complete first)
+
+### Task prefix convention
+
+Every `impl:` task MUST carry a sub-prefix so the lead can route it to the correct implementer without reading every task body. Only two implementer roles exist; anything outside their domain belongs in a different phase or must be folded into one of them.
+
+| Prefix | Routed to | Scope |
+|---|---|---|
+| `impl:be-` | `backend-developer` | Server-side code, APIs, data, infra/CI scripts, build / deploy pipeline tweaks |
+| `impl:fe-` | `frontend-developer` | Client-side code, UI, browser assets |
+
+Defect-fix tasks filed mid-flight by `qa-engineer` or `reviewer` use `impl:qa-fix-` / `impl:review-fix-` and inherit the `be-` or `fe-` routing of the file they touch.
+
 5. Save the plan to `docs/superpowers/plans/YYYY-MM-DD-<slug>-plan.md` and commit it.
-6. **Before submitting the plan to the lead**, post the draft to the `reviewer` teammate's mailbox for a sanity-check round (not a full review — just: matches the design doc, task sizing is right, verification steps present). Wait one round. Incorporate or rebut the reviewer's points; do not start a debate loop.
-7. Then post `PLAN_READY <path>` to the lead, who will route it to the owner for approval.
+6. Post `PLAN_READY <path>` to the lead. The lead routes the plan to the owner for approval, then to `software-architect` + `security-engineer` for the phase-3 gate.
+
+## Plan-revision loop
+
+If `software-architect` posts `ARCH_BLOCKED` or `security-engineer` posts `SEC_BLOCKED`, the lead routes the findings to you. Revise the plan to address every Critical / High finding, commit the revision, and post `PLAN_READY <path>` again. Three revision rounds maximum — escalate to the lead via §7 if the loop fails to converge.
 
 ## Hard rules
 
-- The plan **may not** modify or contradict the approved design doc. If a planning detail forces a design change, halt and escalate to the lead — the design must be re-approved before the plan can change.
+- The plan **may not** modify or contradict the approved design doc. If a planning detail forces a design change, halt and escalate — the design must be re-approved before the plan can change.
 - You **may not** write feature code. None. Not even a stub. The plan describes code; the implementer writes it.
-- You **may not** mark the plan complete until the owner approves it. The lead will tell you.
+- You **may not** mark the plan complete until the owner approves it AND `software-architect` + `security-engineer` both post their PASSED signals.
 
 ## Escalation
 
@@ -40,3 +59,4 @@ Use the §7 template from `docs/superpowers/ESCALATION.md` for any blocker. Comm
 - Test baseline is red.
 - Design doc is ambiguous on a load-bearing decision.
 - A task can't be cut to under 5 minutes without losing meaning — flag it instead of hiding the bloat.
+- Plan-revision loop with SA/security exceeds three rounds.