stargue-publishing-engine/.claude/skills/bmad-plan/SKILL.md

---
name: bmad-plan
description: |
  BMAD 7-agent plan review workflow. Use when drafting any implementation
  plan that the CLAUDE.md "Multi-Agent Plan Review Gate" directive applies
  to. Ensures the gate is satisfied before ExitPlanMode is attempted —
  the PreToolUse hook at .claude/hooks/gate-plan-exit.sh will deny
  ExitPlanMode otherwise.
---

# BMAD Plan + 7-Agent Panel Review

## When to invoke

Every plan-mode session for a non-trivial implementation. CLAUDE.md mandates this for anything beyond the smallest of fixes. Skip only for genuine one-liners (typo, comment tweak) — and even then, think twice.

## Workflow (non-negotiable)

### Phase 1 — Draft

1. Write the plan to the plan file supplied by plan mode (e.g. `/home/devuser/.claude/plans/<slug>.md`).
2. The plan must follow CLAUDE.md format: `Context`, stages with DoD, critical files, verification, authorization gates, risks.
3. **Declare tier-2 applicability** at the top of the plan as an `Applicability:` line, e.g.:

   ```
   Applicability: tier-2 = [RBR, A11y]   # plan touches a migration and adds new UI
   ```

   Allowed values: `RBR` (Reversibility / Blast Radius), `A11y` (Accessibility), `Testability`. Empty list (`tier-2 = []`) is valid when none apply. The Analyst (Mary) is responsible for the call — see `.clinerules/12-foundational-principles.md > Tier-2 Principles` for when to declare each.

### Phase 1.5 — Harden the per-agent dispatch prompt via prompt-master

The 7 BMAD panel charters (`_bmad/bmm/agents/{analyst,architect,pm,sm,ux-designer,dev,tea}.md`) are the SSoT for each panelist's role and stay untouched. What this skill DOES build per-plan is the **dispatch prompt** — the message the session sends to each panelist along with the plan to review, the cross-cutting principle rubric (tier-1 + declared tier-2), and the verdict shape.

Per [`.clinerules/13-agent-spawning-protocol.md`](../../../.clinerules/13-agent-spawning-protocol.md), this dispatch prompt MUST be hardened before Phase 2:

1. Draft the dispatch template (one shape, parameterized per panelist).
2. Invoke the `prompt-master` skill with the draft + plan summary + principle rubric. One invocation covers all 7 panelists since they share dispatch structure.
3. Apply prompt-master's hardening to the dispatch (output-format lock, severity anchors, structural caps on verdict length, link-format lock, verification discipline).
4. **Add the standard graph-tool leverage block** (per [`memory-bank/agent-prompts/README.md > Graph-tool leverage`](../../../memory-bank/agent-prompts/README.md)) to the dispatch — instruct each panelist to consult CRG (`crg_*` MCP tools) and Graphify (`docs/architecture/knowledge-graph/GRAPH_REPORT.md`) before speculative file reads. CRG benchmarks at 8.2× token reduction; Dev (Amelia) and TEA (Murat) gain the most leverage from this.
5. Use the hardened dispatch in Phase 2 — substituting only the panelist-specific focus from the Phase 2 table.

This is the pattern that catches: link-format drift, unanchored severity calibration, soft length caps ignored, asymmetric specificity across panelists, and unverifiable aggregate claims. Skipping this step is the documented failure mode of the 2026-04-16 9-agent baseline audit.

### Phase 2 — Launch the 7 panel agents in parallel

**MUST launch each agent separately in parallel** per memory `feedback_separate_agents` — never consolidate them into one prompt.

Panel members (charters at `_bmad/bmm/agents/<name>.md`):

| Agent | Focus |
| --- | --- |
| Mary (analyst) | Requirements completeness, stakeholder alignment |
| Winston (architect) | Architectural soundness, scalability, technology selection |
| John (pm) | Business value, prioritization, risk identification |
| Bob (sm) | Story clarity, actionability, sprint-readiness |
| Sally (ux-designer) | User impact, UX considerations, accessibility |
| Amelia (dev) | Implementation feasibility, code patterns, existing code reuse |
| Murat (tea) | Test strategy, quality gates, CI/CD impact |

Each agent MUST return a structured verdict. Tier-1 principles are scored on every plan; tier-2 principles are scored only when declared in the plan's `Applicability` line (see Phase 1 step 3).

```
VERDICT: APPROVE | REVISE | REJECT
CONFIDENCE: low | medium | high
STRENGTHS: - …
GAPS: - …
PRINCIPLES (tier-1, always):
  SEBP:  { score: 1-5, rationale: "…" }
  SSoT:  { score: 1-5, rationale: "…" }
  FPT:   { score: 1-5, rationale: "…" }
  DiDSP: { score: 1-5, rationale: "…" }
  PbD:   { score: 1-5, rationale: "…" }
  OF:    { score: 1-5, rationale: "…" }
PRINCIPLES (tier-2, only if declared):
  RBR:         { score: 1-5, rationale: "…" }   # if applicable
  A11y:        { score: 1-5, rationale: "…" }   # if applicable
  Testability: { score: 1-5, rationale: "…" }   # if applicable
ONE-LINE SUMMARY: …
```

### Foundational Principle Scoring (gate-enforced)

All 7 agents MUST score the plan against the **six tier-1 principles**. They MUST also score every **tier-2 principle declared in `applicable_tier2`** for this plan. The hook denies `ExitPlanMode` if any required score is below 3, missing, or has no rationale.

**Tier-1 (always scored):**

| Principle | Definition | Score 1 (violation) → 5 (exemplary) |
|-----------|------------|-------------------------------------|
| **SEBP** — Software Engineering Best Practices | SOLID, DRY, separation of concerns, clear boundaries | 1 = duplicated logic / leaky abstractions; 5 = clean composition, no smell |
| **SSoT** — Single Source of Truth | One authoritative source per concept (constants, types, schemas, config) | 1 = duplicated constants/types/config; 5 = every fact has exactly one home |
| **FPT** — First Principle Thinking | Reasoning grounded in this codebase + verified docs, not training-data assumptions | 1 = "Next.js probably does X" without checking; 5 = cites file paths, runs probes |
| **DiDSP** — Defense in Depth Security | Layered security: input validation, authz, rate limits, audit, least privilege | 1 = unvalidated input or missing authz on sensitive op; 5 = multiple independent layers + audit |
| **PbD** — Privacy by Design | GDPR Art. 25: minimisation, purpose limitation, retention, lawful basis, user rights | 1 = collects PII without purpose / no erasure path; 5 = active minimisation + lifecycle wired |
| **OF** — Observability First | Structured logs, metrics, audit on every meaningful boundary | 1 = silent failure paths; 5 = correlation IDs, audit on regulated ops, dashboards referenced |

**Tier-2 (scored only when declared):**

| Principle | Declare when… | Score 1 → 5 |
|-----------|---------------|-------------|
| **RBR** — Reversibility / Blast Radius | Plan touches migrations, deletes, third-party calls, shared infra, CI/CD, prod data | 1 = destructive, no rollback; 5 = expand-then-contract + flags + recovery procedure |
| **A11y** — Accessibility (WCAG 2.2 AA) | Plan introduces or significantly changes user-facing UI | 1 = keyboard-trap / colour-only state; 5 = keyboard parity, contrast, screen-reader tested |
| **Testability** | Plan introduces or significantly changes business logic / domain rules / boundaries | 1 = logic embedded in framework callbacks, hidden globals; 5 = pure cores, injectable seams |

A score of 3 means "adequate, no blocking concerns." Below 3 blocks the plan. Score 1–2 must be paired with a `REVISE` or `REJECT` verdict and a concrete gap entry.

Full doctrine, definitions, and acceptance signals: [`.clinerules/12-foundational-principles.md`](../../../.clinerules/12-foundational-principles.md).

### Phase 3 — Write verdicts file

After all 7 agents return, write:

```
/tmp/bmad-panel-verdicts-${CLAUDE_SESSION_ID}.json
```

Shape (enforced by the hook):

```json
{
  "plan_file": "<path to plan file>",
  "created_at": "<ISO 8601>",
  "applicable_tier2": ["RBR", "A11y"],
  "verdicts": [
    {
      "agent": "analyst",
      "verdict": "APPROVE | REVISE | REJECT",
      "confidence": "low | medium | high",
      "summary": "one-line summary from the agent",
      "gaps": ["…", "…"],
      "principles": {
        "SEBP":  { "score": 4, "rationale": "…" },
        "SSoT":  { "score": 5, "rationale": "…" },
        "FPT":   { "score": 4, "rationale": "…" },
        "DiDSP": { "score": 3, "rationale": "…" },
        "PbD":   { "score": 4, "rationale": "…" },
        "OF":    { "score": 4, "rationale": "…" },
        "RBR":   { "score": 3, "rationale": "…" },
        "A11y":  { "score": 4, "rationale": "…" }
      }
    },
    { "agent": "architect", ... },
    { "agent": "pm", ... },
    { "agent": "sm", ... },
    { "agent": "ux-designer", ... },
    { "agent": "dev", ... },
    { "agent": "tea", ... }
  ]
}
```

Notes on the shape:

- `applicable_tier2` mirrors the `Applicability:` line from the plan (Phase 1 step 3). Allowed values: `RBR`, `A11y`, `Testability`. An empty array `[]` is valid and means no tier-2 principles apply.
- Each verdict's `principles` object MUST cover all six tier-1 keys plus every key in `applicable_tier2`. Tier-2 keys not declared SHOULD be omitted (the hook ignores them).

Requirements enforced by `gate-plan-exit.sh`:

- `verdicts` is an array of ≥7 entries.
- Every entry has non-empty `agent` and `verdict`.
- Zero entries with `verdict: "REJECT"` (any REJECT blocks exit).
- `applicable_tier2` (when present) contains only `RBR`, `A11y`, or `Testability`.
- Every verdict has `principles.{SEBP,SSoT,FPT,DiDSP,PbD,OF}` with numeric `.score >= 3` and non-empty `.rationale`.
- Every verdict has the same fields for every key in `applicable_tier2`.

### Phase 4 — Consolidate

1. Read all 7 verdicts. Merge gap/concern items into an action list.
2. Revise the plan file to address every REVISE item. Cite which agent raised each concern (traceability).
3. If unanimous APPROVE: proceed to Phase 5.
4. If any REVISE remains after plan revision: re-run the panel or escalate to the user.
5. If any REJECT: revise or escalate; do not bypass.

### Phase 5 — Exit

1. Call `ExitPlanMode`. The hook reads the verdicts file, confirms ≥7 entries and no REJECTs, and allows the call.
2. After user approves, copy the plan to `docs/plans/{YYYY-MM-DD}-{topic}.md` per CLAUDE.md filing rule (plans in `.claude/plans/` are ephemeral).

## Failure modes

- **Hook denies with "verdicts file missing"**: you haven't written `/tmp/bmad-panel-verdicts-${CLAUDE_SESSION_ID}.json` yet. Run the panel (Phase 2) and write the file (Phase 3).
- **Hook denies with "only N/7 verdicts"**: an agent result was dropped. Re-launch only the missing agents and update the file.
- **Hook denies with "N panel agent(s) returned REJECT"**: revise the plan or escalate — do not remove REJECTs from the file without addressing their substance.
- **Hook denies with "foundational principle scoring failed"**: one or more verdicts is missing the `principles` object, has a required `.score < 3`, or has an empty `.rationale` for a tier-1 key or a declared tier-2 key. Re-engage the agent(s) whose verdicts triggered the failure with the rubric in *Foundational Principle Scoring* — never raise a score without substantive justification.
- **Hook denies with "applicable_tier2 contains unknown principle(s)"**: the `applicable_tier2` array contains a value other than `RBR`, `A11y`, or `Testability`. Fix the typo or remove the entry — do not extend the allowed set without updating both this skill and `.clinerules/12-foundational-principles.md`.

## Anti-patterns (do not do)

- Do not skip the panel and call ExitPlanMode directly. The hook will deny.
- Do not batch agents into a single prompt. Per memory `feedback_separate_agents`, always separate + parallel.
- Do not write fabricated verdicts to the file to bypass the gate. The gate exists to protect plan quality; bypassing it defeats the purpose and will be caught by the next review.
- Do not use this skill for trivial one-line fixes — see CLAUDE.md scope rules.