claude-code-bmad-skills

Meta-skill for scaffolding and validating custom PLANNING/ORCHESTRATION skills within the BMAD Planning & Orchestrator plugin. Produces the full skill directory: SKILL.md, scripts, and templates — all pre-targeted at this plugin's path conventions. Includes a scope-violation checker so newly created skills never drift into dev/lint/build/coverage territory. Use when the user says "create a skill", "scaffold a skill", "build a new planning skill", "add a skill to the orchestrator", "extend BMAD planning", "custom orchestration skill", "validate this skill", "check this skill for scope violations", "new skill for the planner", or "bmad-builder". Supports three intents: Create (new skill skeleton), Validate (check an existing SKILL.md), Scaffold (directory structure only). This skill plans and scaffolds only — it NEVER writes application code, runs tests, lints, or builds.

Solutioning skill (Winston, the Architect). Produces architecture.md with ADRs and systematic NFR coverage, mapping every FR/NFR from the PRD to a concrete design decision. ONE architecture forces all future parallel dev agents to share the same API style, data model, state management, naming conventions, and security approach — catching alignment here is 10x cheaper than during implementation. Use when the user says "design the architecture", "create architecture", "/architecture", "solutioning", "tech stack", "system design", "ADR", "architecture decision record", "data model", "API design", "NFR coverage", "non-functional requirements", or after a PRD is done and they ask "what's next" / "ready for solutioning". Supports Create (new architecture.md), Update (revise against PRD changes), and Validate (check coverage + ADR completeness). PLANS only — never writes application code, runs tests, lints, or builds.

Facilitates structured ideation sessions using proven brainstorming techniques (SCAMPER, SWOT, 5 Whys, Mind Mapping, Six Thinking Hats, Reverse Brainstorming, Starbursting, Brainwriting). Produces a brainstorming-report.md of organized ideas and actionable insights. Operates in three intents: Create (new session), Update (add techniques or deepen coverage), Validate (confirm insights align with project goals). Use when the user says: "brainstorm", "ideate", "generate ideas", "explore options", "SCAMPER", "SWOT analysis", "mind map", "Six Thinking Hats", "5 Whys", "creative session", "what if we", "let's explore", "think through possibilities", "find alternatives", or "problem-solve". This skill PLANS only — it never writes application code or runs tests.

CROSS-PHASE mid-stream scope correction. Re-enters planning when requirements, features, architecture, or constraints change after planning has started. Re-shards affected epics/stories, re-sequences sprint-status.yaml, appends rationale to decision-log.md. Routes to bmad-epics-and-stories, bmad-sprint-planning, or bmad-parallel-plan as needed. Changes the PLAN, never code. Use when: "we need to change course", "scope has changed", "new requirement came in", "we're dropping feature X", "we need to pivot", "re-plan after the change", "requirements changed mid-sprint", "correct course", "architecture changed", "re-scope the backlog", "update epics after feedback", "cancel story X", "add epic for Y", "change the plan", "we got new constraints", or when stories are split/merged/reordered due to a decision not in the original plan. Produces: updated epics.md (affected only), revised/new story files, updated sprint-status.yaml, new decision-log.md entry. NEVER writes code or runs tests.

BROWNFIELD planning input. Scans an existing codebase READ-ONLY and writes project-documentation.md — ground truth for stack, structure, key flows, conventions, and integration points — so downstream BMAD planning skills start from reality. Does NOT modify code; produces only the doc artifact. Use when the user says: "document this codebase", "document the project", "document my app", "scan the existing code", "brownfield planning", "we have existing code, start planning", "map what's already built", "document current state", "capture the current architecture", "understand the existing system before planning", "write project-documentation.md", or before a PRD or architecture doc when the user already has code written. Three intents: Create (initial scan), Update (re-scan changed areas), Validate (check completeness). Plans only — reads code but never writes it, runs no tests, no linters, no build tools, no application code.

Solutioning flagship — shards a PRD + architecture into epics.md and individual {epic}.{story}.{slug}.story.md context objects, the LAST planning artifact before external dev handoff. Each story is a self-contained ~8K-token compiled context object: Dev Notes with SOURCE CITATIONS back to prd.md/architecture.md, Acceptance Criteria, Tasks/Subtasks mapped to ACs, Testing strategy, Dependency Maps, an explicit Owned File/Module Scope list (the lever for parallel-conflict-free scheduling), and Learnings from Previous Stories. Sized to one dev-day; split if larger; NO story points. Use when the user says "shard the PRD", "create epics", "break the PRD into epics", "break this epic into stories", "create stories", "create a story", "draft story files", "generate the story for X", "prepare stories for dev", "mark the story ready for dev", "validate this story", or "what stories are in this epic". Three intents: Create new epics/stories, Update an existing story, or Validate a draft against the contract.

Emits a dev-tool-agnostic handoff manifest from ready-for-dev stories so an external dev plugin or runner can pick up and execute the work. Use when the user says "generate a handoff", "create handoff manifest", "export stories for dev", "hand off to dev tool", "produce handoff manifest", "ready to hand off", "prepare handoff for external tool", "export ready-for-dev stories", or "create the handoff package". Also trigger when the user asks "what stories are ready for dev?" and wants an exportable artifact rather than a status report. Produces: handoff-manifest.json listing all ready-for-dev stories with id, story file path, status, owned file/module scope, wave/parallel_set, dependencies, acceptance-criteria summary, locked-sections note, and a schemaVersion field. See REFERENCE.md (bundled) for the full manifest schema and adapter notes for git-worktree parallel development and autonomous dependency-graph orchestrators.

Orchestration spine and "what do I do next?" router for the BMAD Planning & Orchestrator plugin. Detects current planning state by scanning the output folder for which artifacts exist (project-context.md, decision-log.md, product-brief, prd/tech-spec, architecture, ux, epics, stories), infers the current phase and track, then recommends the next BMAD skill to run — skipping optional phases (Analysis is always optional; UX only when there is a UI). Use when the user asks "what's next", "what do I do next", "where am I", "what's my status", "continue", "resume planning", "which skill should I run", "what BMAD step is next", or types "/bmad-help" / "/status". Auto-invoke at the start of any BMAD planning session to orient. This skill ROUTES only — it never writes planning documents itself.

Initialize a BMAD planning workspace: pick a scale-adaptive TRACK (Quick Flow / BMad Method / Enterprise) interactively, then scaffold the output folder, a config file, an empty decision-log.md, and a project-context.md "constitution". Use when the user says "initialize BMAD", "set up BMAD", "start a new BMAD project", "scaffold the planning workspace", "bmad init", "create the bmad config", or is beginning planning and has no bmad-output/ folder yet. Also use when the user asks "which track should I use?" or "what scale is my project?". This is the FIRST skill to run before any other planning workflow (brief, PRD, architecture, stories).

Forensic bug and issue triage. Produces a graded investigation case file: symptoms, evidence (graded A/B/C by confidence), ranked hypotheses, suspected components, and a recommended planning response. INVESTIGATES and DOCUMENTS only — does NOT fix code, run tests, or implement. Hands off as a story to an external dev tool. Use when the user says: - "investigate this bug" / "triage this issue" / "debug triage" - "what's causing [symptom]" / "why is [feature] broken" - "something's wrong with [component]" / "users are reporting [problem]" - "figure out what happened" / "root cause this" - "I need a bug report" / "create an investigation case file" - "forensic analysis" / "diagnose this" - "error triage" / "issue investigation" - "what do we know about [incident/issue]" Three intents: Create (new case file), Update (add evidence to open case), Validate (check draft for completeness before handoff). Output lands in bmad-output/; a fix story is drafted on handoff.

Turns a sequential, ready-for-dev story backlog into conflict-free CONCURRENT WAVES. Builds a dependency DAG from epic order, per-story dependency maps, and Owned File/Module Scope overlaps, then topologically sorts it into parallel waves of mutually disjoint, dependency-satisfied stories (capped by maxParallel), and emits a parallelization-plan.md with per-story git-worktree branch names and an ordered merge sequence. Use when the user says "plan parallel work", "which stories can run in parallel", "parallelize the backlog", "build the wave plan", "parallelization plan", "conflict-free workstreams", "what can we run concurrently", "split into worktrees", "dependency graph for the stories", "merge order", or "how do I fan this backlog out to multiple dev agents". Run AFTER stories are ready-for-dev (scrum-master) and an architecture exists. This skill PLANS parallelism only — it does NOT run agents, spawn worktrees, write code, run tests, or perform git operations.

PRD facilitator (John the PM). Authors and maintains the Product Requirements Document — functional requirements (FR-###), non-functional requirements (NFR-###), an epics outline, user stories, acceptance criteria, and MoSCoW/RICE prioritization. Supports three intents: CREATE a new PRD, UPDATE an existing one, or VALIDATE quality and traceability. Emits prd.md plus addendum.md (overflow/notes) and appends decisions to decision-log.md. Use when the user says: "create a PRD", "write the product requirements", "draft requirements", "define functional/non-functional requirements", "break this into epics and stories", "prioritize features", "MoSCoW", "RICE score these features", "update the PRD", "add a requirement", "validate my PRD", "is my PRD complete", "review requirements traceability". This is PLANNING only — it never writes application code, runs tests, lints, or builds.

Amazon-style Working-Backwards PRFAQ: a future press release plus internal and external FAQs that stress-test a product concept before any building begins. Produces prfaq.md in the configured output folder. Use when the user says: "write a PRFAQ", "working backwards", "press release", "future press release", "stress-test the concept", "validate the idea before building", "internal FAQ", "external FAQ", "Amazon-style product brief", or "PRFAQ for [product/feature]". Also use when someone wants to clarify or update an existing PRFAQ, or validate a draft against the Working-Backwards criteria. Supports three intents: Create / Update / Validate.

Lean facilitator for creating, updating, and validating a product brief — the Analysis-phase foundation of the BMAD Method. Captures problem statement, target users, core features, goals, constraints, and success metrics. Use when the user says: "create a product brief", "I need a product brief", "let's do discovery", "help me define my product", "what problem are we solving", "capture our product vision", "update the product brief", "validate the brief", "check if the brief is complete", "run discovery", "start a product brief", "brainstorm the product", or "I want to plan a product". Supports three intents: - Create — guided discovery conversation that fills and writes the brief - Update — amends one or more sections in an existing brief - Validate — completeness check against all required sections Output is a planning artifact only — no code is written or run.

SOLUTIONING GATE — validates cohesion across planning artifacts before any implementation begins. Cross-references PRD (or tech-spec), architecture document, and epics/stories for coverage consistency and missing pieces. Returns a verdict of PASS, CONCERNS, or FAIL with specifics. Does NOT touch code. Use when the user says: - "check if we're ready to build" / "are we ready to implement?" - "validate planning" / "gate check" / "readiness check" - "run the solutioning gate" / "check implementation readiness" - "is the architecture complete?" / "do requirements match architecture?" - "sign off on planning" / "planning done, check it" - "validate PRD against architecture" / "cross-reference planning docs" Intents supported: Validate (primary). Track-adaptive: works for Quick Flow (tech-spec + architecture), BMad Method (PRD + architecture + epics), and Enterprise (all of the above + optional security/DevOps addenda).

Conducts market, competitive, domain, and technical research using live web sources, producing a cited research-report.md to inform BMAD planning decisions. Use when the user says: - "research [topic/market/technology]" - "competitive analysis" or "who are the competitors" - "market size" or "market landscape" - "technical research" or "evaluate [technology/framework]" - "domain research" or "industry analysis" - "what does the market look like" - "find out about [technology/space]" - "I need research before we plan" - "gather information on [topic]" Supports three modes: Create (new research), Update (refresh existing report with new sources), Validate (cross-check claims in an existing report against live sources). Output lands in bmad-output/ as a cited research-report.md ready for downstream planning skills (business-analyst, product-manager, system-architect).

Distills ANY messy input — brain dump, transcript, long PRD, stakeholder notes, feature request, voice memo — into a tight five-field SPEC.md kernel that any downstream planning skill can consume. The five fields are: Problem, Capabilities, Constraints, Non-Goals, Success Metrics. Use when the user says "create a spec", "write a spec for", "distill this into a spec", "I have a brain dump", "turn this into something structured", "clean up these notes", "make a SPEC from", "I want to define the problem", "help me scope this", "summarize what we're building", "I have a PRD but need a kernel", "what are we actually solving?", or drops raw text/transcript and asks for structure. Also use when starting any new initiative and a clean shared definition is missing.

Orchestration handoff bridge: emits and maintains sprint-status.yaml as the project's sequencing system-of-record. Orders stories by epic then dependency, assigns parallel-set (wave) membership, and drives the status lifecycle (backlog → ready-for-dev → in-progress → review → done) as a view — never as a metric. Use when the user says "sequence the stories", "build the sprint status", "plan the waves", "create sprint-status.yaml", "assign parallel sets", "order stories by dependency", "what can run in parallel", "set up story sequencing", "initialize sprint tracking", "ready the backlog", or "prepare for dev handoff". Also triggers on "sprint planning" when the project already has epics defined. SCOPE: SEQUENCING AND ORCHESTRATION ONLY. No velocity, no burndown, no committed points, no coverage metrics. Capacity is expressed as wave width (concurrent story count), not points. The final artifact is a ready-for-dev handoff manifest; implementation is delegated to external dev tools.

Quick Flow lightweight technical specification for small-scope work (1-15 stories). Replaces the full PRD + architecture pair when scope is small and requirements are clear. Produces bmad-output/tech-spec.md as the single planning artifact before story creation. Use when the user says: "write a tech spec", "create a technical specification", "I need a tech spec for this feature", "quick spec", "small project spec", "we don't need a full PRD", "just a tech spec", "spec out this change", "document this feature". QUICK FLOW TRACK ONLY (1-15 stories). If scope grows beyond ~15 stories or involves multiple teams / external integrations at scale, stop and redirect to bmad-prd + bmad-architecture instead — those skills are built for that complexity. Supports three intents: Create (new spec), Update (revise an existing tech-spec.md), Validate (review a draft for completeness against BMAD criteria).

Solutioning-phase UX planning skill (optional; activate when the project has a UI). Produces TWO planning documents: DESIGN.md (the visual system — design tokens, color palette, typography, spacing, component specs, WCAG 2.1 AA contract) and EXPERIENCE.md (user journeys, flow diagrams, screen states, error/empty/loading handling). Use when the user says "design the UX", "create UX planning docs", "define the design system", "map the user flows", "UX for this feature", "wireframe the flows", "what are the user journeys", "accessibility design", "WCAG compliance", "design tokens", "responsive design plan", "mobile-first design", or "create DESIGN.md / EXPERIENCE.md". Runs after architecture is drafted and before stories are created. Supports Create / Update / Validate intents.