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

name, description

name	description
bmad-plan	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, 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) 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.

Phase 3 — Write verdicts file

After all 7 agents return, write:

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

Shape (enforced by the hook):

{
  "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.