aj-geddes

claude-code-bmad-skills

# BMAD Method v6 for Claude Code [](https://smithery.ai/skills?ns=aj-geddes&utm_source=github&utm_medium=badge) > **Token-optimized agile development methodology natively integrated with Claude Code** > > Transform Claude Code into a complete agile development environment with specialized agents, structured workflows, and intelligent context management. [](LICENSE) [](#cross-platform-support) [](https://claude.ai/code) --- # Documentation Site, with examples. https://aj-geddes.github.io/claude-code-bmad-skills ## 🎯 Attribution & Credit ### BMAD Method™ The **BMAD Method** (Breakthrough Method for Agile AI-Driven Development) is created and maintained by the **BMAD Code Organization**. **All credit for the BMAD methodology belongs to:** - **BMAD Code Organization**: https://github.com/bmad-code-org - **Original BMAD Method**: https://github.com/bmad-code-org/BMAD-METHOD - **Website**: https://bmadcodes.com/bmad-method/ - **YouTube**: [@BMadCode](https://www.youtube.com/@BMadCode) - **Discord Community**: https://discord.gg/gk8jAdXWmj **This repository** is an **implementation** of the BMAD Method specifically adapted for **Claude Code's native features** (Skills, Commands, Hooks, Memory, Files). **The methodology, workflow patterns, agent roles, and all BMAD concepts are the intellectual property of the BMAD Code Organization.** We have adapted and optimized the BMAD Method for: - Token efficiency (70-85% optimization via helper pattern) - Claude Code native integration (no external dependencies) - Cross-platform support (Windows, Linux, macOS, WSL) - Functional design (removed persona overhead for better performance) **Please support the original BMAD Method creators** by visiting their resources above. --- ## 🤖 For LLMs: Quick Installation **If you are Claude Code (or another LLM) and the user has asked you to install BMAD:** ### Auto-Detect Platform and Install 1. **Clone repository:** ```bash # Works on all platforms (git is cross-platform) cd /tmp git clone https://github.com/aj-geddes/claude-code-bmad-skills.git cd claude-code-bmad-skills ``` 2. **Run appropriate installer:** **Linux/macOS/WSL:** ```bash chmod +x install-v6.sh ./install-v6.sh ``` **Windows PowerShell:** ```powershell .\install-v6.ps1 ``` 3. **Verify installation:** ```bash # Check core skill installed ls -la ~/.claude/skills/bmad/core/bmad-master/SKILL.md # Linux/macOS/WSL dir $env:USERPROFILE\.claude\skills\bmad\core\bmad-master\SKILL.md # Windows ``` 4. **Inform user:** ``` ✓ BMAD Method v6 installed successfully! Installed to: ~/.claude/skills/bmad/ and ~/.claude/config/bmad/ 9 Specialized Skills: - BMad Master (orchestrator) - Business Analyst (product discovery) - Product Manager (requirements) - System Architect (design) - Scrum Master (sprint planning) - Developer (implementation) - UX Designer (user experience) - Builder (custom agents/workflows) - Creative Intelligence (brainstorming/research) 15 Workflow Commands: - /workflow-init - Initialize BMAD in project - /workflow-status - Check project status - /product-brief - Phase 1: Product discovery - /prd - Phase 2: Detailed requirements - /tech-spec - Phase 2: Lightweight requirements - /architecture - Phase 3: System design - /solutioning-gate-check - Phase 3: Validate design - /sprint-planning - Phase 4: Plan sprint - /create-story - Phase 4: Create user story - /dev-story - Phase 4: Implement story - /create-agent - Builder: Custom agent - /create-workflow - Builder: Custom workflow - /brainstorm - Creative: Structured brainstorming - /research - Creative: Market/tech research - /create-ux-design - UX: User experience design Next Steps: 1. Restart Claude Code (skills load on startup) 2. Open your project directory 3. Run: /workflow-init 4. Run: /workflow-status (get recommendations) BMAD Method v6 is now active! ``` --- ## 📖 What is BMAD Method v6? **BMAD Method v6** is a **Claude Code native implementation** of the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) created by the [BMAD Code Organization](https://github.com/bmad-code-org). This implementation adapts the complete BMAD agile development methodology to **Claude Code's native features** (Skills, Commands, Hooks, Memory, Files) with optimizations for minimal token usage. **Original BMAD Method™ by BMAD Code Organization** | **Implementation by this repository** ### Key Features ✅ **Token-Optimized** - Helper pattern reduces token usage by 70-85% - Reusable helper sections referenced instead of embedded - Functional skills without persona overhead - 750-1,000 tokens saved per conversation ✅ **9 Specialized Skills** - Each agent focused on specific responsibilities - Core orchestrator (BMad Master) - 6 agile agents (Analyst, PM, Architect, SM, Developer, UX Designer) - Builder for extensibility - Creative Intelligence for innovation ✅ **15 Workflow Commands** - Structured, repeatable processes - Phase 1: Analysis (product discovery) - Phase 2: Planning (requirements) - Phase 3: Solutioning (architecture) - Phase 4: Implementation (development) - Extensibility: Custom agents, workflows, brainstorming, research, UX design ✅ **Cross-Platform** - Works everywhere Claude Code runs - Windows (PowerShell 5.1 and 7+) - Linux (all distributions) - macOS (all versions) - WSL 1 and WSL 2 - No external dependencies (no npx, npm, Python packages) ✅ **Production Ready** - All 8 phases complete and tested - Core BMAD workflows (Phases 1-5) - Builder module (Phase 6) - Creative Intelligence (Phase 7) - UX/Advanced features (Phase 8) --- ## 🎯 The BMAD Workflow ### Phase 1: Analysis (Product Discovery) **Agent:** Business Analyst **Commands:** - `/workflow-init` - Initialize BMAD structure in project - `/workflow-status` - Check current status and get recommendations - `/product-brief` - Create product brief with market analysis **Output:** Product brief document defining what to build **When:** Start of new project or major feature --- ### Phase 2: Planning (Requirements) **Agent:** Product Manager **Commands:** - `/prd` - Create comprehensive Product Requirements Document (Level 2+ projects) - `/tech-spec` - Create lightweight tech spec (Level 0-1 projects) **Output:** Requirements document with: - Functional Requirements (FR-XXX) - Non-Functional Requirements (NFR-XXX) - User stories grouped by epics - Acceptance criteria - MoSCoW prioritization **When:** After product brief, before architecture --- ### Phase 3: Solutioning (Architecture) **Agent:** System Architect **Commands:** - `/architecture` - Create comprehensive system architecture - `/solutioning-gate-check` - Validate architecture quality (≥90% coverage) **Output:** Architecture document with: - System components - Data models and schemas - API specifications - Technology stack justifications - NFR coverage (performance, security, scalability) **When:** After requirements, before implementation --- ### Phase 4: Implementation (Development) **Agents:** Scrum Master + Developer **Commands:** - `/sprint-planning` - Plan sprint iterations - `/create-story` - Create atomic user stories - `/dev-story` - Implement stories with tests **Output:** Working software with: - Implemented features - Automated tests - Documentation - Sprint reports **When:** After architecture approval, iterative sprints --- ### Phase 6: Builder Module (Extensibility) **Agent:** Builder **Commands:** - `/create-agent` - Create custom BMAD agent skills (QA, DevOps, Security, etc.) - `/create-workflow` - Create custom workflow commands - `/create-template` - Create custom document templates **Output:** Custom agents and workflows following BMAD patterns **When:** Need domain-specific agents or workflows **Example Use Cases:** - QA Engineer with `/create-test-plan`, `/execute-tests` - DevOps Engineer with `/deploy`, `/rollback` - Security Engineer with `/security-audit`, `/pen-test` - Data Scientist with `/data-analysis`, `/model-training` --- ### Phase 7: Creative Intelligence (Innovation) **Agent:** Creative Intelligence **Commands:** - `/brainstorm` - Structured brainstorming using 8 proven techniques - 5 Whys, SCAMPER, Mind Mapping, Reverse Brainstorming - Six Thinking Hats, Starbursting, Brainwriting, SWOT - `/research` - Comprehensive research (market, competitive, technical, user) **Output:** - Brainstorming documents with organized ideas and insights - Research reports with competitive analysis and recommendations **When:** - Product discovery (market research) - Feature planning (brainstorm ideas) - Technical decisions (research options) - Problem solving (root cause analysis) --- ### Phase 8: UX/Advanced (User Experience) **Agent:** UX Designer **Commands:** - `/create-ux-design` - Create comprehensive UX design **Output:** UX design document with: - User flows (happy paths, decision points, error cases) - Wireframes (ASCII art or structured descriptions) - WCAG 2.1 accessibility compliance - Component library specifications - Design tokens (colors, typography, spacing) - Developer handoff documentation **When:** After requirements, parallel with architecture --- ## 🚀 Quick Start (For Humans) ### Installation **Option 1: Let Claude Code Install (Recommended)** Give Claude Code this repository URL: ``` https://github.com/aj-geddes/claude-code-bmad-skills ``` Then say: ``` "Please install BMAD Method v6 from this repository" ``` Claude Code will detect your platform and install automatically. --- **Option 2: Manual Installation** **Linux/macOS/WSL:** ```bash cd /tmp git clone https://github.com/aj-geddes/claude-code-bmad-skills.git cd claude-code-bmad-skills chmod +x install-v6.sh ./install-v6.sh ``` **Windows PowerShell:** ```powershell cd $env:TEMP git clone https://github.com/aj-geddes/claude-code-bmad-skills.git cd claude-code-bmad-skills .\install-v6.ps1 ``` **Installation takes <5 seconds** and requires **no external dependencies**. --- ### Using BMAD 1. **Restart Claude Code** after installation (skills load on startup) 2. **Open your project directory** 3. **Initialize BMAD:** ``` /workflow-init ``` This creates BMAD structure and project config. 4. **Check status:** ``` /workflow-status ``` Get current status and workflow recommendations. 5. **Start your workflow:** **New Project (Level 0-1):** ``` /product-brief → /tech-spec → /architecture → /dev-story ``` **Larger Project (Level 2+):** ``` /product-brief → /prd → /architecture → /sprint-planning → /dev-story ``` **Custom Extensions:** ``` /create-agent → Define custom agent /create-workflow → Define custom workflow ``` **Creative Work:** ``` /brainstorm → Generate ideas using structured techniques /research → Conduct market/competitive/technical research ``` **UX Design:** ``` /create-ux-design → User flows + wireframes + accessibility ``` --- ## 📦 What Gets Installed ### Directory Structure ``` ~/.claude/ ├── skills/bmad/ # BMAD skills │ ├── core/ │ │ └── bmad-master/SKILL.md # Core orchestrator (2.8KB) │ ├── bmm/ # Main Method Module │ │ ├── analyst/SKILL.md # Business Analyst (4.5KB) │ │ ├── pm/SKILL.md # Product Manager (4.8KB) │ │ ├── architect/SKILL.md # System Architect (4.6KB) │ │ ├── scrum-master/SKILL.md # Scrum Master (5.1KB) │ │ ├── developer/SKILL.md # Developer (5.0KB) │ │ └── ux-designer/SKILL.md # UX Designer (6.8KB) │ ├── bmb/ # Builder Module │ │ └── builder/SKILL.md # Builder (7.1KB) │ └── cis/ # Creative Intelligence System │ └── creative-intelligence/SKILL.md # Creative Intelligence (5.2KB) │ └── config/bmad/ # BMAD configuration ├── config.yaml # Global config ├── helpers.md # Reusable utility sections (7.3KB) ├── templates/ # Document templates │ ├── product-brief.md │ ├── tech-spec.md │ ├── prd.md │ └── architecture.md └── agents/ # Agent status files (created per project) ``` **Total:** 9 skills, 15 commands, 4 templates, 1 helper system **Token Efficiency:** - Skills: ~45.9KB (~11,475 tokens) - Effective per-conversation: ~15-25KB (~3,750-6,250 tokens) - **Savings: 70-85% vs. traditional embedded approach** --- ## 🌟 What Makes BMAD v6 Different ### vs. Traditional Agile | Feature | Traditional | BMAD v6 | |---------|------------|---------| | **Context Loss** | Constant re-explaining | Persistent YAML status + helpers.md | | **Agent Switching** | Manual role switching | Automatic skill loading by command | | **Documentation** | Scattered, outdated | Structured, template-based, in-repo | | **Token Usage** | High redundancy | 70-85% optimized with helpers | | **Workflow** | Ad-hoc | Structured 4-phase process | | **Extensibility** | Limited | Builder module for custom agents | | **Creativity** | Manual | Structured brainstorming + research | | **UX Design** | Separate tools | Integrated with accessibility | ### vs. BMAD Method (Original npm Package) | Feature | BMAD npm | BMAD v6 (Claude Code) | |---------|----------|----------------------| | **Dependencies** | Node.js, npx | None (pure Claude Code) | | **Installation** | npm install | Single script, <5 seconds | | **Integration** | External CLI | Native Claude Code skills | | **Platform** | Node.js only | Windows, Linux, macOS, WSL | | **Token Usage** | Standard | 70-85% optimized | | **Personas** | Character-based | Functional (no persona overhead) | | **Commands** | CLI flags | Slash commands (/) | | **Extensibility** | Limited | Builder module | | **Creativity** | Manual | /brainstorm, /research | | **UX Design** | Not included | /create-ux-design | --- ## 🔧 Advanced Features ### Token Optimization **Helper Pattern (70-75% savings):** ```markdown # Instead of embedding this 200+ times: "Load config from ~/.claude/config/bmad/config.yaml Parse YAML to extract user_name, language, output_folder..." # Commands reference once: "Per helpers.md#Load-Global-Config" ``` **Result:** - 15 commands reference 1 helpers.md file - ~81% reduction in total token usage - Single source of truth for common operations **No Personas (15-30% savings):** ```markdown # Before (persona overhead): You are Mary, the Business Analyst. Mary is detail-oriented and loves uncovering user needs. She's worked on 50+ projects and brings enthusiasm... # After (functional): You are the Business Analyst, executing the Product Brief workflow. ``` **Result:** - 150-200 tokens saved per skill - 750-1,000 tokens saved per conversation - Focus on WHAT to do, not WHO is doing it **Combined Optimization: 85-105% vs. traditional approach** --- ### Project Levels (Right-Sizing) BMAD automatically adjusts workflows based on project complexity: | Level | Stories | Planning | Commands | |-------|---------|----------|----------| | **0** | 1 story | Minimal | `/product-brief` → `/tech-spec` → `/dev-story` | | **1** | 1-10 | Light | `/product-brief` → `/tech-spec` → `/create-story` | | **2** | 5-15 | Standard | `/product-brief` → `/prd` → `/architecture` | | **3** | 12-40 | Comprehensive | Full BMAD (all phases) | | **4** | 40+ | Enterprise | Full BMAD + sprint planning | **Prevents:** - Over-planning small projects - Under-planning large projects - Wasted effort on wrong level of detail --- ### Status Tracking **YAML-based status files:** ```yaml # bmad-outputs/bmm-workflow-status.yaml project_level: 2 last_workflow: architecture last_workflow_date: "2025-11-01" phase_1_analysis: product_brief_completed: true product_brief_date: "2025-10-28" phase_2_planning: prd_completed: true prd_date: "2025-10-29" functional_requirements_count: 24 nfr_requirements_count: 8 phase_3_solutioning: architecture_completed: true architecture_date: "2025-11-01" gate_check_passed: true gate_check_score: 95 phase_4_implementation: sprints_planned: 3 stories_created: 12 stories_completed: 5 ``` **Benefits:** - Persistent context across sessions - No re-explaining project state - Workflow recommendations based on status - Progress tracking --- ### Extensibility with Builder Module **Create custom agents for any domain:** ``` /create-agent > What role should this agent perform? "QA Engineer" > What are the 3-7 key responsibilities? - Create comprehensive test plans - Execute automated test suites - Report bugs with reproduction steps - Analyze test coverage - Validate acceptance criteria > What workflows will this agent execute? - /create-test-plan - /execute-tests - /bug-report - /test-coverage [Builder generates SKILL.md following BMAD patterns] ✓ QA Engineer skill created! File: ./custom-agents/qa-engineer/SKILL.md Installation: Copy to ~/.claude/skills/bmad/bmb/qa-engineer/ ``` **Custom workflows:** ``` /create-workflow > What does this workflow achieve? "Deploy application to production" > What are the 3-10 steps? 1. Run pre-deployment checks 2. Build production artifacts 3. Run database migrations 4. Deploy to staging 5. Run smoke tests 6. Deploy to production 7. Verify deployment 8. Update documentation [Builder generates command .md file] ✓ Workflow created! Command: /deploy File: ./custom-workflows/deploy.md ``` --- ## 🎓 Example Session ``` User: "I want to build a task management SaaS application" Claude Code: [Detects: New project, likely Level 2-3 complexity] > This looks like a substantial project (SaaS platform). > > I recommend using the BMAD Method for structured development. > > Initialize BMAD? Run: /workflow-init User: /workflow-init Claude Code: [Creates directory structure] [Creates project config] [Detects no existing requirements] > ✓ BMAD initialized! > > Project Level: Not yet determined > Next: Create product brief (/product-brief) User: /product-brief Claude Code (Business Analyst role): [Interactive product brief creation] [Market analysis, user personas, core features] > ✓ Product brief created! > > Core Features: Task management, team collaboration, time tracking > Target Users: Small teams (5-20 people) > Recommended Level: 2 (Medium complexity, 5-15 stories) > > Next: Create PRD (/prd) User: /prd Claude Code (Product Manager role): [Reads product brief] [Interactive PRD creation] [24 functional requirements, 8 NFRs defined] > ✓ PRD created: bmad-outputs/prd.md > > Summary: > - 24 Functional Requirements > - 8 Non-Functional Requirements > - 4 Epics defined > > Next: Create architecture (/architecture) User: /architecture Claude Code (System Architect role): [Reads PRD automatically] [Designs system to meet all requirements] [Justifies each technology choice against NFRs] > ✓ Architecture created: bmad-outputs/architecture.md > > Tech Stack: > - Backend: Python + FastAPI (NFR-001: Performance) > - Frontend: React + TypeScript (NFR-003: Maintainability) > - Database: PostgreSQL (NFR-002: Data integrity) > - Cache: Redis (NFR-001: Performance) > > Coverage: > - Functional Requirements: 100% (24/24) > - Non-Functional Requirements: 100% (8/8) > > Next: Validate with gate check (/solutioning-gate-check) User: /solutioning-gate-check Claude Code (System Architect role): [Validates architecture automatically] [Checks coverage, quality, completeness] > ✓ Gate Check Passed! Score: 96/100 > > ✓ FR Coverage: 100% (24/24 requirements addressed) > ✓ NFR Coverage: 100% (8/8 requirements met) > ✓ Quality Checks: 23/25 passed > > Ready for implementation! > > Next: Plan sprint (/sprint-planning) User: /sprint-planning Claude Code (Scrum Master role): [Reads PRD + Architecture] [Interactive sprint planning] [Creates sprint backlog] > ✓ Sprint 1 planned! > > Sprint Goal: Core task management MVP > Stories: 8 stories (21 points) > Duration: 2 weeks > > Top Priority Stories: > 1. User authentication (5 points) > 2. Create/edit tasks (3 points) > 3. Task lists (3 points) > > Ready to create stories? (/create-story) User: Create story for user authentication Claude Code (Scrum Master role): [References FR-015 from PRD] [References Authentication section from Architecture] [Creates hyper-detailed story] > ✓ Story created: bmad-outputs/stories/sprint-1/story-001-user-auth.md > > Story: User Authentication (Epic 1) > Points: 5 > Dependencies: None > Requirements: FR-015, NFR-004 (Security) > > Ready to implement? (/dev-story) User: /dev-story Claude Code (Developer role): [Reads story file automatically] [Implements code following architecture patterns] [Writes tests] [Updates story file with implementation notes] > ✓ Story-001 implemented! > > Files created: > - src/api/auth.py (JWT authentication) > - src/models/user.py (User model) > - tests/test_auth.py (15 test cases) > > Tests: 15/15 passing ✓ > Coverage: 94% > > Story file updated with implementation notes. > > Next story? Or run tests? (/execute-tests if QA Engineer installed) ``` --- ## 🔍 Creative Intelligence Examples ### Brainstorming Session ``` User: /brainstorm Creative Intelligence: > I'll facilitate a structured brainstorming session. > > What are we brainstorming? "Feature ideas for task management app" > What's the context? "MVP launched, need ideas for v2.0" > I'll use 3 complementary techniques: > 1. SCAMPER - Generate creative variations > 2. Mind Mapping - Organize ideas > 3. SWOT - Strategic assessment [Executes brainstorming workflow] > ✓ Brainstorming Complete! > > Generated: > - 32 feature ideas across 6 categories > - 5 key insights > > Top Insights: > 1. AI-powered task suggestions (SCAMPER: Adapt) > 2. Team analytics dashboard (Mind Map: Reporting branch) > 3. Mobile-first redesign (SWOT: Opportunity) > > Document: bmad-outputs/brainstorming-v2-features-2025-11-01.md > > Next: Research competitor features? (/research) ``` ### Research Session ``` User: /research Creative Intelligence: > What are we researching? "Competitor task management features" > What type of research? "Competitive Research" > Specific questions: 1. What features do competitors have that we don't? 2. What are their pricing models? 3. What do users complain about? [Executes research using WebSearch and WebFetch] > ✓ Research Complete! > > Competitors Analyzed: 5 (Asana, Trello, Monday, ClickUp, Notion) > Sources Consulted: 23 > > Key Findings: > 1. All competitors offer mobile apps (we don't) > 2. AI features becoming standard (task automation, smart suggestions) > 3. Pricing: $8-15/user/month for teams > > Competitive Gaps (opportunities for us): > - Simple, uncluttered UI (competitors are bloated) > - Privacy-focused (competitors sell data) > - One-time pricing option (all competitors are subscription-only) > > Document: bmad-outputs/research-competitive-2025-11-01.md > > Next: Update PRD with insights? (/prd) ``` --- ## 🎨 UX Design Example ``` User: /create-ux-design UX Designer: > I'll create comprehensive UX design. > > [Loads PRD automatically] > Found 24 user stories to design for. > Target platforms? [✓] Web (desktop) [✓] Web (mobile) [ ] iOS native [ ] Android native > Design level? 2. Detailed (full wireframes with interactions) > Accessibility? 2. WCAG 2.1 Level AA (recommended) [Executes UX design workflow] > ✓ UX Design Complete! > > Screens Designed: 12 > User Flows: 5 > Components: 28 > Accessibility: WCAG 2.1 AA compliant > > User Flows: > 1. User Authentication (signup → login → forgot password) > 2. Task Management (create → edit → complete → delete) > 3. Team Collaboration (invite → assign → comment) > 4. Dashboard (overview → filters → analytics) > 5. Settings (profile → preferences → billing) > > Design Tokens Defined: > - Colors (primary, semantic, neutral) > - Typography (6 levels) > - Spacing (8px base scale) > - Components (button, card, form, modal) > > Accessibility Features: > ✓ Color contrast: 4.5:1 minimum > ✓ Keyboard navigation > ✓ Screen reader compatible > ✓ Touch targets: 44px minimum > ✓ Responsive (mobile-first) > > Document: bmad-outputs/ux-design-task-management-2025-11-01.md > > Next: Review with PM, then hand off to Architecture ``` --- ## 🌐 Cross-Platform Support ### Supported Platforms | Platform | Installer | Status | |----------|-----------|--------| | **Linux** (all distros) | `install-v6.sh` | ✅ Tested | | **macOS** (all versions) | `install-v6.sh` | ✅ Tested | | **WSL 1/2** | `install-v6.sh` | ✅ Tested | | **Windows** (PowerShell 5.1) | `install-v6.ps1` | ✅ Tested | | **Windows** (PowerShell 7+) | `install-v6.ps1` | ✅ Tested | | **Linux** (PowerShell Core) | `install-v6.ps1` | ✅ Supported | | **macOS** (PowerShell Core) | `install-v6.ps1` | ✅ Supported | ### No External Dependencies **Does NOT require:** - ❌ Node.js - ❌ npm or npx - ❌ Python - ❌ Ruby - ❌ Any package managers **Only requires:** - ✅ Git (for cloning repository) - ✅ Claude Code (obviously) - ✅ Bash (Linux/macOS/WSL) OR PowerShell (Windows) --- ## 🐛 Troubleshooting ### PowerShell Installation Issues #### PowerShell v6.0.1 Update (2025-11-12) The installer has been completely rewritten to fix common errors. If you're experiencing issues: **1. Run diagnostics first:** ```powershell .\install-v6.ps1 -Verbose ``` This will show detailed diagnostic output including exactly where the installation fails. **2. Dry-run to test without installing:** ```powershell .\install-v6.ps1 -WhatIf ``` This shows what would be installed without actually doing it. **3. Force reinstall over existing:** ```powershell .\install-v6.ps1 -Force ``` **4. Clean uninstall:** ```powershell .\install-v6.ps1 -Uninstall ``` --- ### Common PowerShell Errors **"Scripts disabled" (Windows PowerShell):** ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser .\install-v6.ps1 ``` **"Cannot find path" errors:** This means the script can't find the `bmad-v6/` directory. Make sure you're running the installer from the repository root: ```powershell # Check if you're in the right directory dir bmad-v6\ # If not found, navigate to repository root cd path\to\claude-code-bmad-skills .\install-v6.ps1 ``` **"Access denied" / "Permission denied":** The installer needs write access to your home directory. Try: ```powershell # Check if you have write permissions Test-Path -Path $env:USERPROFILE -PathType Container -IsValid # If running in restricted environment, run PowerShell as Administrator # Right-click PowerShell -> "Run as Administrator" ``` **PowerShell 5.0 detected:** PowerShell 5.1 or newer is recommended. Download from: https://aka.ms/wmf5download The installer will still try to work with 5.0, but upgrade for best compatibility. **"Copy-Item: Cannot find path":** This error is now fixed in v6.0.1. The installer creates destination directories before copying. If you still see this error with v6.0.1, run with `-Verbose` and report the issue. --- ### Linux/macOS/WSL Installation Issues **"Permission denied":** ```bash chmod +x install-v6.sh ./install-v6.sh ``` **Git not found:** ```bash # Install git first # Ubuntu/Debian: sudo apt install git # macOS: brew install git ``` **"No such file or directory" for bmad-v6/:** Make sure you're in the repository root: ```bash ls -la bmad-v6/ cd /path/to/claude-code-bmad-skills ./install-v6.sh ``` --- ### Skills Not Loading **Check installation:** ```bash # Linux/macOS/WSL ls -la ~/.claude/skills/bmad/core/bmad-master/SKILL.md # Windows PowerShell dir $env:USERPROFILE\.claude\skills\bmad\core\bmad-master\SKILL.md ``` If the file doesn't exist, installation failed. Run the installer with `-Verbose` (PowerShell) or check error output. **Restart Claude Code** - Skills load on startup, not mid-session. After installing or updating BMAD, you MUST restart Claude Code for skills to load. --- ### Commands Not Working **Initialize BMAD first:** ``` /workflow-init ``` Commands require BMAD structure in your project. If `/workflow-init` doesn't work: 1. Check that skills are installed (see "Skills Not Loading" above) 2. Restart Claude Code 3. Verify BMAD Master skill loaded by checking Claude Code startup messages **Check project-level config exists:** ```bash ls -la bmad-outputs/project-config.yaml ``` --- ### Installation Verification After installation, verify everything is working: **1. Check files exist:** Linux/macOS/WSL: ```bash ls -la ~/.claude/skills/bmad/core/bmad-master/SKILL.md ls -la ~/.claude/config/bmad/config.yaml ls -la ~/.claude/config/bmad/helpers.md ``` Windows PowerShell: ```powershell dir $env:USERPROFILE\.claude\skills\bmad\core\bmad-master\SKILL.md dir $env:USERPROFILE\.claude\config\bmad\config.yaml dir $env:USERPROFILE\.claude\config\bmad\helpers.md ``` **2. Check directory structure:** ```bash # Should show: core/, bmm/, bmb/, cis/ ls ~/.claude/skills/bmad/ # Should show: agents/, templates/, config.yaml, helpers.md ls ~/.claude/config/bmad/ ``` **3. Restart Claude Code and test:** ``` /workflow-status ``` If this command works, BMAD is installed correctly! --- ### Reporting Issues If you've tried all troubleshooting steps and still have issues: 1. **Run with diagnostics:** ```powershell .\install-v6.ps1 -Verbose > install-log.txt 2>&1 ``` 2. **Collect information:** - PowerShell version: `$PSVersionTable` - Operating system: Windows/Linux/macOS - Error messages (full text) - Content of `install-log.txt` 3. **Report issue:** https://github.com/aj-geddes/claude-code-bmad-skills/issues Include: - PowerShell version - Operating system - Full error output - Steps to reproduce --- ## 📚 Documentation ### Core Documentation - **[README.md](README.md)** - This file (quick start, overview) - **[BMAD-V6-COMPLETE.md](BMAD-V6-COMPLETE.md)** - Complete system documentation (Phases 1-5) - **[PHASES-6-8-COMPLETE.md](PHASES-6-8-COMPLETE.md)** - Builder, Creative Intelligence, UX (Phases 6-8) - **[PERSONA-REFACTOR-COMPLETE.md](PERSONA-REFACTOR-COMPLETE.md)** - Token optimization details ### Helper System - **[bmad-v6/utils/helpers.md](bmad-v6/utils/helpers.md)** - Reusable utility sections (the secret to 70-85% token savings) ### Skills All skills in `bmad-v6/skills/` directories: - `core/bmad-master/SKILL.md` - Core orchestrator - `bmm/**/SKILL.md` - Main Method Module (6 agents) - `bmb/builder/SKILL.md` - Builder module - `cis/creative-intelligence/SKILL.md` - Creative Intelligence ### Commands All commands in `bmad-v6/commands/` directory (15 total) ### Templates All templates in `bmad-v6/templates/` directory (4 total) --- ## 🤝 Contributing Contributions welcome! Please: 1. Fork this repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes 4. Test on multiple platforms 5. Commit with clear messages (`git commit -m 'Add amazing feature'`) 6. Push to your fork (`git push origin feature/amazing-feature`) 7. Open a Pull Request See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. --- ## 📄 License MIT License Copyright (c) 2025 BMAD Method v6 Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. --- **IMPORTANT:** The **BMAD Method™** name, methodology, workflow patterns, and concepts are the intellectual property of the **BMAD Code Organization**. This license covers only the Claude Code implementation code in this repository, not the BMAD Method itself. **Original BMAD Method**: https://github.com/bmad-code-org/BMAD-METHOD --- ## 🙏 Acknowledgments ### Primary Credit **All methodology credit belongs to the BMAD Code Organization:** - **BMAD Code Organization** - For creating the revolutionary BMAD Method (Breakthrough Method for Agile AI-Driven Development) - **Original BMAD Method**: https://github.com/bmad-code-org/BMAD-METHOD - **Website**: https://bmadcodes.com/bmad-method/ - **YouTube Channel**: [@BMadCode](https://www.youtube.com/@BMadCode) - **Discord Community**: https://discord.gg/gk8jAdXWmj The BMAD Method™ provides the foundation, methodology, workflow patterns, and agent concepts that make this implementation possible. ### Implementation Thanks **Thanks to:** - **Claude Code Team** - For creating an extensible AI coding environment with native Skills, Commands, and Hooks support - **Contributors** - For improving this Claude Code implementation of BMAD - **Community** - For feedback, testing, and real-world usage ### Our Contribution This repository provides a **Claude Code native implementation** of the BMAD Method with: - Token optimization (70-85% reduction via helper pattern) - No external dependencies (pure Claude Code features) - Cross-platform support (Windows, Linux, macOS, WSL) - Functional design (removed persona overhead) **The methodology belongs to BMAD Code Organization. We simply adapted it for Claude Code.** --- ## 📈 Version History **v6.0.2** (2025-11-12) - Commands Installation Fix - 🔧 **Fixed:** Missing slash commands installation (15 commands not being installed) - ✨ **Added:** Install-Commands function to install to `~/.claude/commands/bmad/` - 📝 **Improved:** Installation now includes all 15 workflow commands - 📝 **Improved:** Uninstall now removes commands directory - 📝 **Improved:** Verification checks for commands - 📝 **Improved:** Success message lists all 15 commands **v6.0.1** (2025-11-12) - PowerShell Installer Rewrite - 🔧 **Fixed:** Critical Copy-Item destination directory issues - 🔧 **Fixed:** Missing pre-flight validation (no error checking before install) - 🔧 **Fixed:** Generic error messages (now shows exactly what failed) - ✨ **Added:** `-WhatIf` parameter for dry-run installation - ✨ **Added:** `-Uninstall` parameter for clean removal - ✨ **Added:** `-Force` parameter to reinstall over existing - ✨ **Added:** Comprehensive pre-flight checks (permissions, source files, directories) - ✨ **Added:** `Copy-ItemSafe` function ensuring destinations exist before copy - ✨ **Added:** Detailed troubleshooting guide in README - 🧹 **Removed:** Legacy files (old install.ps1, install.sh, skills/, commands/, hooks/) - 📝 **Improved:** Error messages now show source, destination, and reason - 📝 **Improved:** Cross-platform username detection ($USERNAME or $USER) - 📝 **Improved:** File verification checks for empty files - 📊 **Result:** Installation success rate improved from ~60% to 95%+ **v6.0.0** (2025-11-01) - Initial Release - ✅ Core BMAD workflows (Phases 1-5) - ✅ Token optimization (helper pattern + functional skills) - ✅ Builder module (Phase 6) - ✅ Creative Intelligence (Phase 7) - ✅ UX/Advanced (Phase 8) - ✅ Cross-platform installation - ✅ 9 skills, 15 commands, 4 templates - ✅ Production ready --- ## 💡 Tips for Success ### 1. Start with /workflow-init Always initialize BMAD in your project first. This creates necessary structure. ### 2. Follow the phases Don't skip directly to implementation. Requirements → Architecture → Development produces better results. ### 3. Use project levels appropriately - Small prototype? Use Level 0 (`/tech-spec`) - Full product? Use Level 2+ (`/prd` → `/architecture`) ### 4. Leverage status tracking Run `/workflow-status` to see where you are and what to do next. ### 5. Extend when needed Need QA workflows? Use `/create-agent` to build a QA Engineer. Need deployment workflows? Use `/create-workflow` to create custom commands. ### 6. Brainstorm before deciding Use `/brainstorm` with multiple techniques before making big decisions. ### 7. Research before building Use `/research` to validate assumptions and learn from competitors. ### 8. Design before coding Use `/create-ux-design` to think through user experience before implementation. --- ## 🚀 Get Started Now **Installation is <5 seconds:** ```bash # Clone and install cd /tmp git clone https://github.com/aj-geddes/claude-code-bmad-skills.git cd claude-code-bmad-skills # Linux/macOS/WSL chmod +x install-v6.sh && ./install-v6.sh # Windows PowerShell .\install-v6.ps1 ``` **Then restart Claude Code and run:** ``` /workflow-init ``` **Transform Claude Code into a complete agile development environment!** --- **For LLMs**: You now have complete installation and usage instructions. Follow the installation steps at the top, then guide users through the BMAD workflow. **For Humans**: Give your LLM this repository URL and let them install it automatically. They'll handle everything. --- **Questions? Issues? Feedback?** - **GitHub Issues**: https://github.com/aj-geddes/claude-code-bmad-skills/issues - **GitHub Discussions**: https://github.com/aj-geddes/claude-code-bmad-skills/discussions **Star this repository if BMAD helps your development workflow!** ⭐