Bmad

BMAD Packet-First Router

Use bmad as the common-layer BMAD/BMM front door.

The job is not to dump every phase command or runtime setup rule. The job is to: 1. identify the packet the user already has, 2. choose the project level and likely current phase, 3. recommend the single next artifact or gate that reduces ambiguity now, 4. route runtime-, review-, execution-, or game-specific detail outward.

Read references/intake-packets-and-route-outs.md first for the fastest routing model. Use references/core-routing.md, references/status-and-review.md, and references/runtime-and-module-boundaries.md when you need more depth.

When to use this skill

• The user wants to start or resume a BMAD/BMM-style workflow from mixed project state
• The user asks what phase comes next after idea notes, a PRD, a tech spec, architecture work, or partial implementation
• The user has an existing repo, issue, review note, or brownfield status and needs the next artifact chosen truthfully
• The user wants a vendor-neutral BMAD front door before dropping into Claude-, Codex-, or Gemini-specific runtime overlays
• The user needs help deciding whether the next move is ideation, planning, architecture, approval, execution slicing, or runtime handoff

When not to use this skill

• The main need is open-ended concept shaping before project framing exists → use bmad-idea
• The main need is a game-production packet (GDD, playtest notes, build issues, launch beats) → use bmad-gds
• The main need is artifact approval, annotation, or plan review → use plannotator
• The main need is execution-ready backlog slicing after the next artifact is already known → use task-planning
• The main need is runtime-specific orchestration setup for Claude Code → use omc
• The main need is Codex-first workflow runtime behavior → use omx
• The main need is Gemini / Antigravity portable harness setup → use ohmg

Instructions

Step 1: Normalize the intake as one primary packet

Before talking about phases, choose the single best packet that describes the current ask:

bmad_packet:
  packet_type:
    - concept-packet
    - planning-packet
    - architecture-packet
    - review-gate-packet
    - execution-packet
    - runtime-handoff-packet
    - brownfield-resume-packet
  evidence_in_hand:
    - idea-notes
    - product-brief
    - prd
    - tech-spec
    - architecture-draft
    - review-feedback
    - active-repo
    - issue-or-bug-link
    - sprint-plan
    - milestone-or-launch-pressure
  project_type: web-app | backend-api | mobile-app | game | library | automation | unknown
  project_level: 0 | 1 | 2 | 3 | 4 | unknown
  runtime_context: claude | codex | gemini | opencode | mixed | unknown
  main_constraint: ambiguity | review-blocker | execution-readiness | runtime-setup | brownfield-drift | unknown

Rules:

• Pick one primary packet first, even if the user mentions several artifacts.
• If the packet is obviously pre-planning, say so and route to bmad-idea early.
• If the packet is mostly game-production coordination, route to bmad-gds early.
• If the request starts from an existing repo, issue, or partial implementation, prefer brownfield-resume-packet over pretending the project is greenfield.

Step 2: Choose project level before artifact depth

Use this scale:

• Level 0 — single atomic change, bug fix, config tweak
• Level 1 — small feature, limited files, low coordination cost
• Level 2 — medium feature set, cross-cutting behavior, clear planning + architecture need
• Level 3 — complex integration, multiple subsystems, API/data contracts, multi-sprint delivery
• Level 4 — major overhaul, platform migration, enterprise-scale coordination

Do not force architecture or heavyweight planning onto level 0–1 work unless the visible packet truly requires it.

Step 3: Infer the likely current phase from the packet

Use the packet to infer the current BMAD phase, not the other way around:

Guiding rules:

• Prefer the smallest truthful next artifact.
• If an artifact already exists but has not been reviewed, the next move is often the review gate, not another new document.
• If the request is really a runtime/setup ask, keep bmad short and route outward.

Step 4: Choose one next artifact, not a parallel stack

Pick the single next artifact or gate that best reduces ambiguity now:

Step 5: Route specialist work explicitly

If the front-door decision is made, route the rest clearly:

• bmad-idea → pre-planning concept framing before formal BMAD artifacts exist
• plannotator → review / approval gate for PRD, architecture, sprint plan, or plan diffs
• task-planning → execution-ready slicing after the next artifact is approved or obvious
• omc → Claude-first runtime orchestration, hooks, team mode, stop callbacks
• omx → Codex-first orchestration, AGENTS.md injection, workflow skills, tmux team runtime
• ohmg → Gemini / Antigravity portable harness, .agents/ source of truth, generated runtime views
• bmad-gds → game-specific production routing

Leave a short reason for the route-out. Do not just name the neighboring skill.

Step 6: Keep state and review visible

When a project already uses BMAD state files or helper scripts, keep them in the loop:

• inspect status/config artifacts before recommending a phase leap
• if a required artifact exists but lacks approval, route to plannotator
• prefer script/status awareness over re-deriving the workflow from scratch
• use brownfield evidence honestly instead of pretending the project is still at idea stage

Step 7: Produce a compact BMAD routing brief

Always return this structure:

# BMAD Routing Brief

## Scope
- Packet type: ...
- Project type: ...
- Project level: 0 | 1 | 2 | 3 | 4
- Runtime context: ...
- Confidence: high | medium | low

## Current phase
- analysis | planning | solutioning | implementation | mixed | unknown
- Why: ...

## Recommended next move
- product-brief | prd | tech-spec | architecture | review gate | sprint-plan | story packet | workflow-status update | runtime handoff

## Why this is next
- 2-4 bullets grounded in the packet

## Route-outs
- Skill / module: ...
- Why: ...
- What to pass forward: ...

## What not to do yet
- 1-3 bullets preventing premature detail or the wrong lane

Step 8: Push detail into references

Do not inflate the main response with every helper script, command family, or runtime rule. Use the references when needed:

• intake packets and route-outs
• core routing model
• status files, scripts, and review gates
• runtime and module boundaries

Output format

Return a short BMAD routing brief.

Required qualities:

• choose one primary packet before choosing the next artifact
• make the project-level assumption explicit
• keep review-gate visibility before phase advancement
• keep runtime/setup detail separated from the common BMAD layer
• keep the result under roughly 400-700 words unless the user asks for a full workflow packet

Examples

Example 1: brownfield repo, unclear next step

Input

Use bmad. We already have a repo and some product notes, but planning drifted and I don't know whether we need a PRD, architecture, or just sprint planning.

Output sketch

• Packet type: brownfield-resume-packet
• Likely phase: mixed
• Recommended next move: workflow-status update, then whichever artifact is actually missing
• Route-outs only after the missing artifact is identified

Example 2: architecture exists, execution weak

Input

We already wrote the architecture doc for our API migration. What should we do next in BMAD?

Output sketch

• Packet type: architecture-packet
• Current phase: solutioning
• Recommended next move: review gate if architecture is unreviewed, otherwise sprint-plan
• Route-out: plannotator first, task-planning second

Example 3: runtime-specific follow-up

Input

I want BMAD for Codex CLI. What should I actually use?

Output sketch

• Keep bmad as the packet/phase router
• Packet type: runtime-handoff-packet
• Route Codex runtime specifics to omx
• Do not turn bmad into a Codex setup guide

Best practices

1. Act like a packet-first router — start from the artifact or evidence the user already has. 2. Choose level before depth — level 0–1 and level 2–4 should not produce the same paperwork. 3. Keep review visible — if approval is the blocker, say so before inventing a new artifact. 4. Keep runtime overlays separate — omc, omx, and ohmg own vendor/runtime specifics. 5. Prefer one clear handoff — one next move plus one or two route-outs beats a giant workflow dump. 6. Use references for deep detail — helper scripts, status rules, and runtime boundaries belong in support docs.

References

• Intake packets and route-outs
• Core routing model
• Status files, scripts, and review gates
• Runtime and module boundaries
• ./scripts/init-project.sh
• ./scripts/check-status.sh
• ./scripts/phase-gate-review.sh
• Upstream BMAD README
• ../bmad-idea/SKILL.md
• ../plannotator/SKILL.md
• ../task-planning/SKILL.md
• ../omc/SKILL.md
• ../omx/SKILL.md
• ../ohmg/SKILL.md
• ../bmad-gds/SKILL.md

BMAD Orchestrator Reference

This document provides detailed reference information for the BMAD Orchestrator skill.

Table of Contents

• Workflow Routing Logic
• Project Level Guidelines
• Status File Structure
• Configuration Details
• File Operations
• Variable Substitution

Workflow Routing Logic

Determination Algorithm

Input: workflow_status array from docs/bmm-workflow-status.yaml
Output: recommended next workflow command

Step 1: Identify current phase
  - Scan workflow_status array
  - Find last completed workflow (status = file path)
  - Determine phase number of last completion

Step 2: Check for required workflows in current/next phase
  - If in Phase 1 (Analysis):
    * If no product-brief: Recommend /product-brief
    * If product-brief complete: Move to Phase 2

  - If in Phase 2 (Planning):
    * Level 0-1:
      - If no tech-spec: Recommend /tech-spec (required)
      - If PRD desired: Suggest /prd (optional)
    * Level 2+:
      - If no PRD: Recommend /prd (required)
      - If tech-spec desired: Suggest /tech-spec (optional)

  - If in Phase 3 (Solutioning):
    * Level 2+:
      - If no architecture: Recommend /architecture (required)
    * Level 0-1:
      - Skip to Phase 4

  - If in Phase 4 (Implementation):
    * If no sprint-status.yaml: Recommend /sprint-planning
    * If sprint active: Recommend /create-story
    * If stories exist: Recommend /dev-story

Step 3: Return recommendation with explanation

Phase Transition Rules

Phase 1 → Phase 2:

• Transition when: Product brief complete OR user explicitly skips analysis
• Required before transition: None (Analysis is optional)

Phase 2 → Phase 3:

• Transition when: PRD or Tech Spec complete
• Required before transition:
• Level 0-1: Tech Spec complete
• Level 2+: PRD complete
• Gate rule: if the current phase document already has a terminal plannotator result for the same document hash, do not relaunch review until the document changes

Phase 3 → Phase 4:

• Transition when: Architecture complete (if required)
• Required before transition:
• Level 0-1: None (skip Phase 3)
• Level 2+: Architecture complete
• Gate rule: phase advancement still requires a reviewed artifact; unchanged reviewed architecture should not be re-opened

Phase 4 completion:

• All stories in sprint-status.yaml marked as "done"
• Final review/retrospective complete

Project Level Guidelines

Level 0: Single Atomic Change (1 story)

Characteristics:

• Bug fix
• Small configuration change
• Single file modification
• No breaking changes

Required workflows:

• Tech Spec (brief, 1-2 pages)
• Single story
• Direct implementation

Skip:

• Product brief (unless complex bug)
• PRD
• Architecture
• Sprint planning

Typical timeline: Hours to 1 day

Level 1: Small Feature (1-10 stories)

Characteristics:

• New small feature
• Limited scope
• 1-3 files affected
• Minimal dependencies

Required workflows:

• Tech Spec
• Sprint planning (simple)

Optional but recommended:

• Product brief (if feature requires context)
• PRD (if stakeholder alignment needed)

Skip:

• Architecture (unless significant design needed)

Typical timeline: 1-5 days

Level 2: Medium Feature Set (5-15 stories)

Characteristics:

• Multiple related features
• 5-20 files affected
• Some dependencies
• Database changes likely

Required workflows:

• PRD
• Architecture
• Sprint planning

Optional:

• Product brief (recommended)
• Tech spec (for complex components)

Typical timeline: 1-3 weeks

Level 3: Complex Integration (12-40 stories)

Characteristics:

• System integration
• Multiple subsystems
• 20-50 files affected
• API contracts
• Third-party integrations

Required workflows:

• Product brief (strongly recommended)
• PRD (detailed)
• Architecture (comprehensive)
• Sprint planning (multiple sprints)

Typical timeline: 3-8 weeks

Level 4: Enterprise Expansion (40+ stories)

Characteristics:

• Major system overhaul
• 50+ files affected
• Multiple teams
• Platform changes
• Infrastructure updates

Required workflows:

• Product brief (required)
• PRD (extensive)
• Architecture (system-wide)
• Sprint planning (multiple sprints)
• Gate checks

Typical timeline: 2-6 months

Status File Structure

Workflow Status Schema

# docs/bmm-workflow-status.yaml

project_name: "string"
project_type: "web-app|mobile-app|api|game|library|other"
project_level: 0-4
communication_language: "string"
output_language: "string"
last_updated: "ISO-8601 timestamp"

workflow_status:
  - name: "workflow-name"
    phase: 1-4
    status: "optional|recommended|required|{file-path}|skipped"
    description: "Brief description"
    # Added by phase-gate-review.sh when plannotator approves the document:
    plannotator_review: "approved"       # set on plannotator Approve click
    reviewed_at: "ISO-8601 timestamp"   # timestamp of approval

Status Values

• "optional" - Workflow can be skipped without impact
• "recommended" - Strongly suggested but not blocking
• "required" - Must be completed to proceed
• "conditional" - Required based on project level (replaced during init)
• "{file-path}" - Completed, shows output file location
• "skipped" - User explicitly chose to skip

plannotator Review Fields

Written by scripts/phase-gate-review.sh when a phase document is approved via plannotator:

• `plannotator_review` - "approved" when the document passed plannotator gate review
• `reviewed_at` - ISO-8601 timestamp of when the review was approved

These fields are optional — they are only present on workflow entries that have been reviewed. Use them to audit which phase documents were human-reviewed before phase transition. If you persist a document hash alongside them, the recommended policy is "same hash, same decision, no re-entry".

Updating Status

When a workflow completes: 1. Read docs/bmm-workflow-status.yaml 2. Find workflow by name 3. Update status to file path: "docs/prd-myapp-2025-01-11.md" 4. Update last_updated timestamp 5. Write updated file

Example Edit operation:

# Before
- name: prd
  phase: 2
  status: "required"
  description: "Product Requirements Document"

# After
- name: prd
  phase: 2
  status: "docs/prd-myapp-2025-01-11.md"
  description: "Product Requirements Document"

Configuration Details

Project Config (bmad/config.yaml)

Complete schema:

# Project identification
project_name: "string"
project_type: "web-app|mobile-app|api|game|library|other"
project_level: 0-4

# Output settings
output_folder: "docs"  # relative to project root
stories_folder: "docs/stories"

# Language settings
communication_language: "English|Spanish|French|etc"
document_output_language: "English|Spanish|French|etc"

# BMAD version
bmad_version: "6.0.0"

# Optional: Custom overrides
agent_overrides_folder: "bmad/agent-overrides"

Global Config (~/.claude/config/bmad/config.yaml)

version: "6.0.0"
ide: "claude-code"

# User defaults
user_name: "string"
user_skill_level: "beginner|intermediate|expert"

# Communication defaults
communication_language: "English"
document_output_language: "English"

# Default paths
default_output_folder: "docs"

# Enabled modules
modules_enabled:
  - core
  - bmm
  # - bmb (optional)
  # - cis (optional)

# Advanced settings
auto_update_status: true
verbose_mode: false

Config Priority

1. Project config (bmad/config.yaml) - highest priority 2. Global config (~/.claude/config/bmad/config.yaml) - default values 3. Built-in defaults - fallback

File Operations

Reading Config Files

Load project config:

Tool: Read
Path: {project-root}/bmad/config.yaml
Parse: YAML
Extract: project_name, project_type, project_level, output_folder

Load global config:

Tool: Read
Path: ~/.claude/config/bmad/config.yaml
Parse: YAML
Extract: user_name, communication_language, default_output_folder

Merge configs:

Result = Global config + Project config (project overrides global)

Writing Status Files

Create workflow status:

Tool: Write
Path: {project-root}/{output_folder}/bmm-workflow-status.yaml
Content: Processed template with variables substituted

Update workflow status:

Tool: Edit
Path: {project-root}/{output_folder}/bmm-workflow-status.yaml
Old: status: "required"
New: status: "docs/prd-myapp-2025-01-11.md"

Directory Creation

Initialize project structure:

Tool: Bash
Commands:
  mkdir -p bmad/agent-overrides
  mkdir -p docs/stories
  mkdir -p .claude/commands/bmad

Variable Substitution

Standard Variables

Used in templates during initialization:

{{PROJECT_NAME}}           → config: project_name
{{PROJECT_TYPE}}           → config: project_type
{{PROJECT_LEVEL}}          → config: project_level
{{USER_NAME}}              → global config: user_name
{{DATE}}                   → current date (YYYY-MM-DD)
{{TIMESTAMP}}              → current timestamp (ISO 8601)
{{OUTPUT_FOLDER}}          → config: output_folder

Conditional Variables

Based on project level:

{{PRD_STATUS}}             → "required" if level >= 2
                           → "recommended" if level == 1
                           → "optional" if level == 0

{{TECH_SPEC_STATUS}}       → "required" if level <= 1
                           → "optional" if level >= 2

{{ARCHITECTURE_STATUS}}    → "required" if level >= 2
                           → "optional" if level <= 1

Substitution Process

1. Load template file 2. Collect variable values from:

• Project config
• Global config
• Current date/time
• User input

3. Replace all {{VARIABLE}} occurrences 4. Validate no unreplaced variables remain 5. Return processed content

Example:

# Template
project_name: "{{PROJECT_NAME}}"
project_level: {{PROJECT_LEVEL}}

# After substitution with project_name="MyApp", project_level=2
project_name: "MyApp"
project_level: 2

File Path Standards

Standard Paths

Project root: {project-root}/
Config: {project-root}/bmad/config.yaml
Status: {project-root}/{output_folder}/bmm-workflow-status.yaml
Sprint: {project-root}/{output_folder}/sprint-status.yaml
Stories: {project-root}/{output_folder}/stories/
Templates: {project-root}/bmad/agent-overrides/ (optional)

Output File Naming

Convention: {workflow-name}-{project-name}-{date}.md

Examples:

docs/product-brief-myapp-2025-01-11.md
docs/prd-myapp-2025-01-11.md
docs/architecture-myapp-2025-01-11.md
docs/tech-spec-myapp-2025-01-11.md

Story File Naming

Convention: story-{epic-id}-{story-id}.md

Examples:

docs/stories/story-E001-S001.md
docs/stories/story-E001-S002.md
docs/stories/story-E002-S001.md

Error Handling Patterns

Missing Config File

Error: bmad/config.yaml not found

Response:
  1. Inform user project not initialized
  2. Display: "BMAD not detected in this project."
  3. Ask: "Would you like to initialize BMAD with /workflow-init?"
  4. Do NOT proceed with operation

Invalid YAML

Error: YAML parsing failed

Response:
  1. Show error message
  2. Display file path
  3. Show line number if available
  4. Options:
     a. "I can try to fix the YAML syntax"
     b. "You can manually edit the file"
     c. "I can reinitialize with /workflow-init (will overwrite)"

Inconsistent Status

Error: Status file doesn't match project level

Example: Level 2 project but PRD marked as "optional"

Response:
  1. Explain inconsistency
  2. Show expected vs actual
  3. Offer: "I can regenerate the status file to match your project level"

Missing Template

Error: Template file not found

Response:
  1. Log warning (if verbose mode)
  2. Use inline fallback template
  3. Continue operation
  4. Note: "Using default template"

Display Formatting

Status Display Format

Project: {project_name} ({project_type}, Level {level})

✓ Phase 1: Analysis
  ✓ product-brief (docs/product-brief-myapp-2025-01-11.md)
  - research (optional)

→ Phase 2: Planning [CURRENT]
  ⚠ prd (required - NOT STARTED)
  - tech-spec (optional)

Phase 3: Solutioning
  - architecture (required)

Phase 4: Implementation
  - sprint-planning (required)

Symbols Used

• ✓ - Completed
• ⚠ - Required but not started
• → - Current phase indicator
• - - Optional or not applicable

Color Coding (if supported)

• Green: Completed workflows
• Yellow: Required but incomplete
• Gray: Optional workflows
• Blue: Current phase

Best Practices

For Initialization

1. Always collect project info before creating files 2. Validate project level is 0-4 3. Create all directories before files 4. Use absolute paths for file operations 5. Confirm successful creation to user

For Status Checks

1. Load config first to get output_folder path 2. Check if status file exists before reading 3. Parse YAML carefully with error handling 4. Display in clear, hierarchical format 5. Always provide actionable next step

For Routing

1. Check current phase before recommending 2. Consider project level in recommendations 3. Explain why a workflow is recommended 4. Offer to execute recommended workflow 5. Allow user to choose different path

For Updates

1. Read current file before editing 2. Update timestamp when modifying 3. Validate YAML after changes 4. Confirm update to user 5. Update related files if needed (e.g., sprint-status)

Core Routing Model

Use bmad as the common-layer BMAD/BMM router.

Canonical job

1. Determine the primary intake packet the user actually has now 2. Determine project level (0–4) 3. Determine current phase (analysis, planning, solutioning, implementation, mixed, or unknown) 4. Choose the single next artifact or gate 5. Route detailed follow-up to the correct adjacent skill or module

Phase ladder

Level guidance

• Level 0 — minimal paperwork; bug fix or tiny change
• Level 1 — light planning, small feature
• Level 2 — clear PRD + architecture + execution packet
• Level 3 — strong cross-system planning and multi-sprint coordination
• Level 4 — enterprise-scale overhaul with strict gates

Preferred outputs

Good bmad outputs are short and decisive:

• current phase
• next artifact
• why it is next
• route-outs
• what not to do yet

Anti-patterns

Avoid turning bmad into:

• a giant command encyclopedia
• a runtime-specific setup guide
• a replacement for task-planning
• a replacement for plannotator
• a game-production orchestrator (bmad-gds owns that lane)
• a testing or release-gate specialist (route to TEA references or adjacent skills)

Intake Packets and Route-Outs

Use this file when the request is messy and you need the quickest truthful front-door choice.

Primary packet selector

Choose one packet first.

Brownfield rule

If the request starts from a real repo, issue, failing implementation, or stale artifacts, do not pretend it is a clean greenfield BMAD start.

Preferred move: 1. acknowledge the brownfield packet, 2. state the likely current phase as mixed or unknown if necessary, 3. recommend the smallest truthful next artifact or status update.

Project-level guardrails

• Level 0–1: prefer lighter artifacts; often tech-spec or direct implementation slice after a quick review.
• Level 2+: usually needs stronger planning + architecture visibility.
• Level 3–4: treat approval and handoff discipline as first-class, not optional.

Route-out rules

Route to bmad-idea

Use when the packet is still about concept shaping, positioning, audience, or the core problem rather than execution planning.

Route to plannotator

Use when the correct artifact already exists and the next real blocker is review/approval.

Route to task-planning

Use when the next artifact is already clear and the remaining work is execution slicing, backlog cleanup, sprint prep, or milestone planning.

Route to omc, omx, or ohmg

Use when the plan is ready and the real question is runtime-native execution, settings/rules/hooks, or agent orchestration behavior.

Route to bmad-gds

Use when the packet is mostly game-specific: GDD, playtest synthesis, build issues, demo readiness, launch beats, or milestone pressure.

Anti-patterns

• Do not recommend three parallel artifacts just to sound comprehensive.
• Do not bury a missing review gate under fresh document creation.
• Do not let runtime setup swallow the common BMAD layer.
• Do not treat a brownfield repo like a blank-sheet idea exercise.

Runtime and Module Boundaries

The bmad skill should stay vendor-neutral at the core. Runtime overlays and specialist modules add depth around it.

Runtime overlays

Rule: let bmad choose the next phase artifact, then route runtime-specific execution/setup to the matching overlay.

Adjacent specialist skills

Specialist module depth

Upstream BMAD also favors a core-plus-modules shape:

• TEA — testing, NFR, automation, release-gate depth
• Game Dev Studio — game workflow specialization
• Builder — creating custom BMAD-compatible modules and skills
• Creative modules — fuzzy-front-end ideation and structured creativity

Why this separation matters

A core BMAD entrypoint stays maintainable when it owns:

• project level
• current phase
• next artifact
• route-outs

It becomes noisy when it also tries to own:

• vendor runtime setup
• review UI setup
• testing/release-gate playbooks
• domain-specific production flows
• every command surface from every module

Status Files, Scripts, and Review Gates

bmad works best when it acknowledges project state instead of restarting the workflow from memory every time.

Local helper scripts

• scripts/init-project.sh — bootstrap BMAD config/templates for a project
• scripts/check-status.sh — inspect current workflow status
• scripts/phase-gate-review.sh — submit a phase artifact for review before advancement
• scripts/validate-config.sh — validate BMAD config/state files

Local templates and state hints

• templates/config.template.yaml
• templates/workflow-status.template.yaml
• REFERENCE.md includes the historical docs/bmm-workflow-status.yaml structure and transition rules

Review gate policy

Before advancing a phase, ask: 1. Does the required artifact already exist? 2. Has that artifact been reviewed/approved? 3. If the artifact exists but has not been reviewed, should the next move be plannotator rather than another new document?

Recommended handoff to plannotator

Use plannotator when the core BMAD decision is already made and a human-approval surface is the real blocker:

• PRD review before architecture
• architecture review before sprint planning / implementation
• sprint-plan or plan-diff review before execution

Practical rule

When state files or helper scripts are present:

• prefer inspecting/updating them first
• keep recommendations consistent with the visible state
• avoid phase jumps that ignore already-created artifacts

Fabric Patterns for BMAD Workflows

fabric is an AI prompt CLI with 250+ reusable patterns. Use it to analyze, improve, and summarize BMAD phase documents.

Prerequisite: fabric --setup (configure API keys and default model)

---

Per-Phase Fabric Usage

Phase 1: Analysis

# Extract insights from product brief
cat docs/product-brief-*.md | fabric -p analyze_paper --stream

# Extract wisdom, insights, and lessons
cat docs/product-brief-*.md | fabric -p extract_wisdom

# Summarize research findings
cat docs/research-*.md | fabric -p create_summary

Phase 2: Planning

# Deep analysis of PRD
cat docs/prd-*.md | fabric -p analyze_paper --stream

# Check for strong vs weak claims in requirements
cat docs/prd-*.md | fabric -p analyze_claims

# Improve PRD writing quality before plannotator review
cat docs/prd-*.md | fabric -p improve_writing > /tmp/prd-improved.md

# Extract key decisions and risks
cat docs/tech-spec-*.md | fabric -p extract_wisdom

Phase 3: Solutioning

# Summarize architecture decisions
cat docs/architecture-*.md | fabric -p create_summary

# Extract wisdom from architecture doc
cat docs/architecture-*.md | fabric -p extract_wisdom

# Security review of architecture
cat docs/architecture-*.md | fabric -p ask_secure_by_design

# Improve architecture doc before review
cat docs/architecture-*.md | fabric -p improve_writing > /tmp/arch-improved.md

# Then submit improved version for gate review
bash scripts/phase-gate-review.sh /tmp/arch-improved.md "Architecture Review"

Phase 4: Implementation

# Explain a code diff before code review
git diff HEAD~1 | fabric -p explain_code

# Summarize sprint status
cat docs/sprint-status.yaml | fabric -p create_summary

# Analyze test failures
npm test 2>&1 | fabric -p analyze_logs

# Create PR description from git log
git log --oneline origin/main..HEAD | fabric -p create_summary

# Security check on implementation
cat src/auth.ts | fabric -p ask_secure_by_design

Integration with TEA

# Analyze test coverage summary
cat docs/stories/*.md | fabric -p extract_wisdom | fabric -p create_summary

# Review acceptance criteria quality
cat docs/stories/*.feature | fabric -p analyze_claims

# Extract test insights for release gate
cat test-results/*.xml | fabric -p analyze_logs > /tmp/test-summary.md

---

Key Fabric Patterns for BMAD

---

Creating Custom BMAD Patterns

Create project-specific patterns in ~/.config/fabric/patterns/:

Pattern: bmad-prd-review

mkdir -p ~/.config/fabric/patterns/bmad-prd-review
cat > ~/.config/fabric/patterns/bmad-prd-review/system.md << 'EOF'
# IDENTITY AND PURPOSE

You are an expert product manager reviewing a PRD for completeness and clarity.

# STEPS

1. Check for: clear problem statement, target users, success metrics, acceptance criteria
2. Identify missing or ambiguous requirements
3. Rate each section: Complete / Needs Work / Missing
4. Provide specific improvement recommendations

# OUTPUT INSTRUCTIONS

- Output in Markdown
- Use ## sections: Summary, Missing Elements, Improvement Suggestions
- Be concise and actionable
EOF

Pattern: bmad-architecture-check

mkdir -p ~/.config/fabric/patterns/bmad-architecture-check
cat > ~/.config/fabric/patterns/bmad-architecture-check/system.md << 'EOF'
# IDENTITY AND PURPOSE

You are a senior architect reviewing a BMAD architecture document.

# STEPS

1. Verify: system overview, component design, API contracts, security, performance
2. Identify gaps vs requirements (assumes PRD context was provided)
3. Flag scalability, security, and operational risks

# OUTPUT INSTRUCTIONS

- Output in Markdown
- ## sections: Architecture Summary, Gaps, Risks, Recommendations
EOF

---

Pro Tips

# Stream output for long documents
cat docs/prd-*.md | fabric -p analyze_paper --stream

# Save analysis to file
cat docs/architecture-*.md | fabric -p extract_wisdom > docs/arch-insights.md

# Chain patterns for richer analysis
cat docs/prd-*.md | fabric -p extract_wisdom | fabric -p create_summary

# Per-pattern model routing (~/.config/fabric/.env)
FABRIC_MODEL_PATTERN_ANALYZE_PAPER=anthropic|claude-opus-4-5
FABRIC_MODEL_PATTERN_EXTRACT_WISDOM=openai|gpt-4o
FABRIC_MODEL_PATTERN_IMPROVE_WRITING=google|gemini-2.5-flash

TEA (Test Architect) — BMAD Integration Reference

TEA is an official BMAD v6 external module providing enterprise-grade test strategy. Agent persona: Murat — Master Test Architect focused on risk-based testing, fixture architecture, ATDD, and CI/CD governance.

Source: bmad-code-org/bmad-method-test-architecture-enterprise

---

TEA's 9 Workflows

---

TEA Per-Phase Integration

Phase 2: Planning

NFR Assessment (`/tea-nfr`)

• Elicits non-functional requirements (performance, security, reliability, scalability)
• Applies risk-based prioritization P0–P3
• Level 3+ required | Level 2 recommended | Level 0-1 optional
• Output: docs/nfr-assessment-{project}-{date}.md

# Run NFR assessment during planning phase
/tea-nfr

Phase 3: Solutioning

Test Design (`/tea-test-design`)

• Designs system-level test strategy based on architecture
• Identifies test boundaries, contract tests, integration points
• Output: docs/test-design-{project}-{date}.md

Framework Setup (`/tea-framework`)

• Configures Playwright, Cypress, Pact, or custom framework
• Sets up directory structure, config, CI integration hooks
• Supported: Playwright, Cypress, Jest, Pytest, Pact, MCP integrations

CI Integration (`/tea-ci`)

• Configures CI/CD pipeline with test gates
• Adds quality gates: coverage threshold, test pass rate, performance budget
• Output: Updated .github/workflows/ or equivalent

Phase 4: Implementation

Run TEA workflows per epic during sprint execution:

ATDD — Acceptance TDD (`/tea-atdd`)

• Writes Gherkin .feature files BEFORE implementation
• Links feature files to story acceptance criteria
• Enables BDD workflow: Red → Green → Refactor

Test Automation (`/tea-automate`)

• Automates acceptance tests for the current epic
• Generates test fixtures, mocks, and helpers
• Integrates with CI gate from Phase 3

Test Review (`/tea-review`)

• Reviews test quality, coverage, and completeness
• Checks for: missing edge cases, duplicate tests, brittle selectors
• Level 2+ required before story close

Requirements Tracing (`/tea-trace`)

• Maps every test to a requirement or acceptance criterion
• Generates traceability matrix
• Level 3+ required before sprint close

Release Gate

`/tea-release-gate`

• Final evidence-backed go/no-go decision before release
• Verifies: all P0-P1 tests pass, coverage thresholds met, NFR criteria satisfied
• Produces: Release Gate Report with explicit PASS/FAIL verdict
• Level 2+ required

---

Risk Prioritization (P0–P3)

Formula: Risk = Probability × Impact

---

Project Level Requirements

---

Supported Test Frameworks

---

Quick Reference

# Phase 2
/tea-nfr                    # NFR Assessment (Level 3+ required)

# Phase 3
/tea-test-design            # Test Design
/tea-framework              # Framework Setup
/tea-ci                     # CI Integration

# Phase 4 (per epic)
/tea-atdd                   # Write acceptance tests first
/tea-automate               # Automate tests
/tea-review                 # Review test quality
/tea-trace                  # Requirements tracing (Level 3+)

# Release
/tea-release-gate           # Final go/no-go

BMAD Workflow Phases Reference

Complete reference for all 4 BMAD phases, workflows, and project levels.

Phase 1: Analysis (Optional)

Purpose: Understand the problem space, research market/competitors, and define product vision.

When to use: Starting new products, major features, or when requirements are unclear.

When to skip: Bug fixes, well-defined features, or urgent implementations.

Phase 1 Workflows

Product Brief (/product-brief)

Purpose: Create comprehensive product vision and high-level requirements.

Output: Product brief document with:

• Problem statement
• Target users
• Value proposition
• Key features
• Success metrics
• Constraints

Duration: 1-2 hours

Recommended for: Level 1+ projects

Required for: Level 3+ projects

Brainstorm (/brainstorm)

Purpose: Structured ideation session for features and solutions.

Output: Brainstorming session notes with:

• Problem exploration
• Solution ideas
• Feature concepts
• Technical approaches

Duration: 30-60 minutes

Optional for: All levels

Research (/research)

Purpose: Market analysis, competitive research, technical investigation.

Output: Research report with:

• Market analysis
• Competitor comparison
• Technical feasibility
• Recommendations

Duration: 2-4 hours

Optional for: All levels (recommended for Level 2+)

---

Phase 2: Planning (Required)

Purpose: Define detailed requirements and technical specifications.

Critical: Every project must complete at least ONE planning workflow (PRD or Tech Spec).

Phase 2 Workflows

PRD - Product Requirements Document (/prd)

Purpose: Comprehensive product requirements for multi-feature projects.

Output: PRD document with:

• Executive summary
• User stories
• Functional requirements
• Non-functional requirements
• Success criteria
• Acceptance criteria

Duration: 2-4 hours

Required for: Level 2+ projects

Recommended for: Level 1 projects

Optional for: Level 0 projects

When to choose PRD over Tech Spec:

• Multiple features
• Stakeholder alignment needed
• Product perspective important
• Business requirements complex

Tech Spec - Technical Specification (/tech-spec)

Purpose: Technical design for single features or components.

Output: Tech spec document with:

• Technical overview
• Implementation approach
• API contracts
• Data models
• Testing strategy

Duration: 1-2 hours

Required for: Level 0-1 projects

Optional for: Level 2+ projects (supplement to PRD)

When to choose Tech Spec over PRD:

• Single feature
• Technical focus
• Limited scope
• Developer-centric work

UX Design (/create-ux-design)

Purpose: Design user interface and user experience.

Output: UX design document with:

• User flows
• Wireframes
• UI mockups
• Interaction patterns
• Design system references

Duration: 2-6 hours

Optional for: Projects with UI components

Recommended for: User-facing features

---

Phase 3: Solutioning (Conditional)

Purpose: Design system architecture for medium+ complexity projects.

Required for: Level 2+ projects

Skip for: Level 0-1 projects (unless significant architectural changes)

Phase 3 Workflows

Architecture (/architecture)

Purpose: Design system architecture, components, and integrations.

Output: Architecture document with:

• System overview
• Component design
• Data flow
• API contracts
• Integration points
• Technology decisions
• Security considerations
• Performance requirements

Duration: 2-6 hours

Required for: Level 2+ projects

Optional for: Level 0-1 with architectural impact

Content varies by level:

• Level 2: Component architecture, basic integrations
• Level 3: Comprehensive system design, multiple integrations
• Level 4: Enterprise architecture, platform design, infrastructure

Solutioning Gate Check (/solutioning-gate-check)

Purpose: Validate architecture against requirements before implementation.

Output: Gate check report with:

• Requirements coverage
• Risk assessment
• Technical debt analysis
• Readiness score

Duration: 30-60 minutes

Optional for: Level 2+ projects

Recommended for: Level 3+ projects

---

Phase 4: Implementation (Required)

Purpose: Execute development through sprints and stories.

Required for: All projects (even Level 0 creates at least 1 story)

Phase 4 Workflows

Sprint Planning (/sprint-planning)

Purpose: Break down requirements into epics and stories, plan sprints.

Output:

• Sprint plan with epics and stories
• sprint-status.yaml tracking file
• Story files in docs/stories/

Duration: 1-3 hours

Required for: Level 1+ projects

Simplified for: Level 0 (single story, no sprint)

Generates:

• Epics (Level 1+)
• User stories with acceptance criteria
• Story point estimates
• Sprint assignments

Create Story (/create-story)

Purpose: Create individual user story with details.

Output: Story file (docs/stories/story-{epic}-{id}.md) with:

• User story format
• Acceptance criteria
• Tasks breakdown
• Estimates
• Dependencies

Duration: 15-30 minutes per story

Required for: All projects

Used when: Adding stories to existing sprint

Dev Story (/dev-story)

Purpose: Implement a specific story with code generation.

Output:

• Code implementation
• Tests
• Documentation
• Story marked complete

Duration: 30 minutes - several hours

Required for: Story implementation

Process: 1. Read story file 2. Implement code 3. Write tests 4. Update documentation 5. Mark story complete

Code Review (/code-review)

Purpose: Review implemented code for quality and standards.

Output: Review findings and recommendations

Duration: 30-60 minutes

Optional for: All implementations

Recommended for: Level 2+ projects

---

Project Level Decision Matrix

Level 0: Single Atomic Change (1 story)

Typical flow: Tech Spec → Single Story → Implementation

Example projects:

• Bug fix
• Configuration change
• Small UI tweak
• Single function addition

---

Level 1: Small Feature (1-10 stories)

Typical flow: Product Brief → Tech Spec → Sprint Planning → Stories → Implementation

Example projects:

• New API endpoint
• User profile page
• Data export feature
• Email notifications

---

Level 2: Medium Feature Set (5-15 stories)

Typical flow: Product Brief → PRD → Architecture → Sprint Planning → Stories → Implementation

Example projects:

• User authentication system
• Payment integration
• Dashboard with multiple widgets
• Content management features

---

Level 3: Complex Integration (12-40 stories)

Typical flow: Product Brief → Research → PRD → Architecture → Gate Check → Multiple Sprints → Implementation

Example projects:

• Third-party API integration
• Multi-tenant system
• Real-time collaboration features
• Analytics platform

---

Level 4: Enterprise Expansion (40+ stories)

Typical flow: Product Brief → Research → PRD → UX Design → Architecture → Gate Check → Many Sprints → Implementation → Reviews

Example projects:

• Platform migration
• Microservices architecture
• Enterprise SaaS product
• Major system overhaul

---

Phase Transition Criteria

Phase 1 → Phase 2

Can transition when:

• Product brief completed (if created), OR
• User explicitly skips Phase 1

Blocking issues:

• None (Phase 1 is optional)

Recommendation: Complete product brief for Level 2+ projects

---

Phase 2 → Phase 3

Can transition when:

• PRD completed (Level 2+), OR
• Tech Spec completed (Level 0-1)

Blocking issues:

• No planning document created
• Planning document incomplete or invalid

Recommendation: Complete appropriate planning doc before proceeding

---

Phase 3 → Phase 4

Can transition when:

• Architecture completed (Level 2+), OR
• Project is Level 0-1 (skip Phase 3)

Blocking issues:

• Level 2+ project without architecture
• Architecture incomplete or not validated

Recommendation: Complete architecture for medium+ projects

---

Phase 4 Complete

Can transition when:

• All stories marked "done" in sprint-status.yaml
• Code reviewed (if required)
• Tests passing

Blocking issues:

• Incomplete stories
• Failing tests
• Unresolved blockers

Recommendation: Complete all stories before closing project

---

Workflow Dependencies

Must Complete Before

Product Brief → No dependencies (can be first)
Research → No dependencies (can be first)
Brainstorm → No dependencies (can be first)

PRD → Product Brief (recommended, not required)
Tech Spec → Product Brief (recommended, not required)
UX Design → Product Brief or PRD (recommended)

Architecture → PRD or Tech Spec (required)
Gate Check → Architecture (required)

Sprint Planning → PRD or Tech Spec (required), Architecture (if Level 2+)
Create Story → Sprint Planning (required)
Dev Story → Story created (required)
Code Review → Dev Story (required)

Can Work in Parallel

Product Brief + Research
PRD + UX Design (with coordination)
Multiple Dev Stories (different epics)

Sequential Requirements

Sprint Planning → Create Stories → Dev Stories → Code Review

---

Common Workflow Paths

Fast Track (Level 0-1)

Tech Spec → Sprint Planning → Story → Implementation → Done

Duration: Hours to days

Use when: Small, well-defined changes

---

Standard Feature (Level 1-2)

Product Brief → PRD or Tech Spec → Architecture (if Level 2) →
Sprint Planning → Stories → Implementation → Review → Done

Duration: Days to weeks

Use when: Normal feature development

---

Enterprise Project (Level 3-4)

Product Brief → Research → PRD → UX Design → Architecture →
Gate Check → Sprint Planning → Stories → Implementation →
Code Review → Iteration → Done

Duration: Weeks to months

Use when: Complex, multi-team projects

---

Selection Guidance

When unclear about level, ask:

1. How many files will change?

• 1-3 files: Level 0-1
• 3-20 files: Level 1-2
• 20-50 files: Level 2-3
• 50+ files: Level 3-4

2. How many stories estimated?

• 1 story: Level 0
• 1-10 stories: Level 1
• 5-15 stories: Level 2
• 12-40 stories: Level 3
• 40+ stories: Level 4

3. Is architecture design needed?

• No: Level 0-1
• Some: Level 2
• Significant: Level 3
• Extensive: Level 4

4. How long will development take?

• Hours-1 day: Level 0
• 1-5 days: Level 1
• 1-3 weeks: Level 2
• 3-8 weeks: Level 3
• 2+ months: Level 4

When unclear about workflow, ask:

1. Is this a new project or existing codebase?

• New: Start with Product Brief
• Existing: Start with Tech Spec or PRD

2. Do you need stakeholder approval?

• Yes: Use PRD
• No: Use Tech Spec

3. Is this primarily product or technical?

• Product: Use PRD
• Technical: Use Tech Spec

4. Do you have clear requirements?

• Yes: Skip to Planning
• No: Start with Analysis

---

Quick Reference Table

---

TEA Integration per Phase

fabric and TEA (Test Architect) integrate at each phase gate. See resources/tea-workflows.md for full TEA workflow reference and resources/fabric-patterns.md for fabric patterns.

Phase 1: Analysis — Foundation

TEA activities: None required (TEA engages from Phase 2) Fabric: cat docs/product-brief-*.md | fabric -p analyze_paper --stream

Phase 2: Planning — Strategy

TEA activities (Level 3+ required, 2+ recommended):

• /tea-nfr — NFR (Non-Functional Requirements) assessment → outputs test strategy doc
• Defines P0-P3 risk levels for all features

SSD (Level 2+):

• /spec-openapi → docs/spec-openapi-*.yaml
• /spec-schema → docs/spec-schema-*.json
• Run plannotator gate on spec before Phase 3

Fabric: cat docs/prd-*.md | fabric -p extract_wisdom --stream

Phase 3: Solutioning — Design

TEA activities (Level 2+ recommended):

• /tea-test-design — Design test strategy aligned with architecture
• /tea-framework — Select and configure test framework
• /tea-ci — CI/CD test pipeline integration

SSD:

• Architecture document must reference OpenAPI/Schema spec from Phase 2
• /spec-bdd scenarios drafted per component boundary

Fabric: cat docs/architecture-*.md | fabric -p create_summary

Phase 4: Implementation — Delivery

TEA activities (Level 2+ required):

• /tea-atdd — Acceptance Test-Driven Development per epic
• /tea-automate — Test automation implementation
• /tea-review — Test review (Level 2+ required)
• /tea-trace — Requirements tracing (Level 3+ required)

SSD:

• Each dev story implements against /spec-bdd scenarios
• Story blockedBy: spec file must be approved

Fabric: git diff HEAD~1 | fabric -p explain_code

Release Gate

TEA: /tea-release-gate — Go/No-Go decision based on P0/P1 test results

• P0 failures → No-Go (block release)
• P1 failures → Conditional (requires sign-off)
• P2/P3 failures → Go with known issues documented

Fabric: cat test-results/*.xml | fabric -p analyze_logs > docs/release-test-summary.md

Risk Prioritization Matrix

TEA + SSD + Fabric Combined Flow

Phase 2: PRD → /tea-nfr → /spec-openapi → fabric analyze → plannotator gate
Phase 3: Architecture (refs spec) → /tea-test-design → /tea-framework → /tea-ci
Phase 4: Per epic: /tea-atdd → implement → /tea-automate → /tea-review
Release: /tea-release-gate → fabric analyze_logs → Go/No-Go

BMAD Orchestrator — Setup Guide

BMAD Method v6 + plannotator integration

Structured AI-driven development with visual plan review at every phase gate.

---

What You Get

Your AI Agent
     │
     ▼
 /workflow-init          ← bootstrap project
     │
     ▼
 Phase 1: Analysis       ← /product-brief, /research
     │
     │  [plannotator review] ← approve before advancing
     ▼
 Phase 2: Planning       ← /prd or /tech-spec
     │
     │  [plannotator review]
     ▼
 Phase 3: Solutioning    ← /architecture  (Level 2+ only)
     │
     │  [plannotator review]
     ▼
 Phase 4: Implementation ← /sprint-planning → /dev-story

plannotator opens a visual browser UI after each phase document is created. You annotate, approve, or request changes — then your agent continues to the next phase. Use the same cross-platform control model as OMG: settings configure the platform, rules prevent invalid phase transitions, and hooks enforce them.

---

Quick Start (3 steps)

Step 1 — Install

bash scripts/install.sh

This installs plannotator CLI and configures the Claude Code ExitPlanMode hook. Restart Claude Code after running this.

Options:

bash scripts/install.sh --init-project       # Also initialize BMAD in current directory
bash scripts/install.sh --skip-plannotator   # BMAD scripts only, no plannotator
bash scripts/install.sh --dry-run            # Preview without making changes

Step 2 — Initialize your project

Run this inside your AI session (Claude Code, Gemini CLI, etc.):

/workflow-init

Your agent will ask three questions:

• Project name — e.g. my-app
• Project type — web-app, mobile-app, api, game, library, other
• Project level — 0 to 4 (see level guide below)

This creates:

bmad/config.yaml                    ← project configuration
docs/bmm-workflow-status.yaml       ← workflow tracking
docs/stories/                       ← story files will go here

Step 3 — Start working

/workflow-status

Your agent shows your current phase, what's done, and exactly what to run next.

---

Project Level Guide

Choose the level that matches your project size:

Quick decision:

• Bug fix or config change → Level 0
• New API endpoint or small UI feature → Level 1
• User auth system or payment integration → Level 2
• Third-party platform integration → Level 3
• Major system overhaul → Level 4

---

plannotator Phase Gate Review

After each phase document is created, submit it for review before moving on:

# After /prd creates docs/prd-myapp-2026-02-25.md
bash scripts/phase-gate-review.sh docs/prd-myapp-2026-02-25.md "PRD Review: myapp"

# After /architecture creates docs/architecture-myapp-2026-02-25.md
bash scripts/phase-gate-review.sh docs/architecture-myapp-2026-02-25.md

Or trigger it from inside your AI session:

planno — review the PRD before we proceed to Phase 3

What happens in the review UI

1. plannotator opens in your browser automatically

• unless the same document hash already has a terminal review result, in which case the gate is skipped

2. Read through the document 3. Annotate specific sections:

• delete — remove a risky or unnecessary element
• insert — add something missing
• replace — correct an approach
• comment — clarify constraints

4. Choose an outcome:

• Approve → your agent advances to the next phase; doc saved to your configured destination (Obsidian or Bear)
• Request Changes → annotations sent back; agent revises and re-submits

Phase gate reference

---

Common Commands

Check status anytime

/workflow-status

Output example:

Project: my-app (web-app, Level 2)

✓ Phase 1: Analysis
  ✓ product-brief (docs/product-brief-my-app-2026-02-25.md)

→ Phase 2: Planning [CURRENT]
  ⚠ prd (required - NOT STARTED)

  Phase 3: Solutioning
  - architecture (required)

  Phase 4: Implementation
  - sprint-planning (required)

Recommended next step: Run /prd to continue

Validate your config

bash scripts/validate-config.sh

Check BMAD + plannotator status

bash scripts/check-status.sh

---

Workflow by Project Level

Level 0–1 (Fast Track)

/workflow-init  →  /tech-spec
     ↓
planno review
     ↓
/sprint-planning  →  /dev-story

Level 2 (Standard Feature)

/workflow-init  →  /product-brief  →  /prd
                                        ↓
                               planno review (Phase 2 gate)
                                        ↓
                               /architecture
                                        ↓
                               planno review (Phase 3 gate)
                                        ↓
                               /sprint-planning  →  /dev-story

Level 3–4 (Enterprise)

/workflow-init  →  /product-brief  →  /research
                                        ↓
                                      /prd  →  /create-ux-design
                                        ↓
                               planno review (Phase 2 gate)
                                        ↓
                               /architecture  →  /solutioning-gate-check
                                        ↓
                               planno review (Phase 3 gate)
                                        ↓
                               /sprint-planning  →  /create-story  →  /dev-story
                                        ↓
                               /code-review  (per sprint)

---

Notes Auto-Save: Obsidian or Bear (Optional)

Approved phase documents can be auto-saved with YAML frontmatter and [[BMAD Plans]] backlinks.

Setup (choose one or both): 1. Open any plannotator review in your browser 2. Click ⚙️ Settings → Saving tab 3. Toggle ON Obsidian Integration and/or Bear Notes 4. For Obsidian: select your vault from the dropdown 5. For Bear: verify callback works first:

   open "bear://x-callback-url/create?title=Test&text=OK"

Each approved document saves as:

vault/plannotator/PRD Review myapp - Feb 25, 2026 10-30pm.md

With frontmatter:

---
created: 2026-02-25T22:30:00.000Z
source: plannotator
tags: [bmad, phase-2, prd, my-app]
---

[[BMAD Plans]]

# PRD: my-app
...

---

Scripts Reference

---

Troubleshooting

BMAD not detected:

# Check if config exists
ls bmad/config.yaml

# Re-initialize if missing
/workflow-init

plannotator doesn't open:

# Check installation
plannotator --version

# Re-install
curl -sSfL https://plannotator.ai/install.sh | sh

Hook not firing on plan exit:

# Re-run hook setup (from plannotator skill)
bash .agent-skills/plannotator/scripts/setup-hook.sh

# Restart Claude Code after this

Status file out of sync:

# Validate config
bash scripts/validate-config.sh

# Manually edit status
# File: docs/bmm-workflow-status.yaml

---

Related Skills

---

Source: BMAD Method · plannotator · skills-template