bmad-fh 6.0.0-alpha.052779ef

package/docs/how-to/workflows/setup-party-mode.md

@@ -0,0 +1,89 @@
+---
+title: "How to Set Up Party Mode"
+description: How to set up and use Party Mode for multi-agent collaboration
+---
+
+Use Party Mode to orchestrate dynamic multi-agent conversations with your entire BMad team.
+
+## When to Use This
+
+- Exploring complex topics that benefit from diverse expert perspectives
+- Brainstorming with agents who can build on each other's ideas
+- Getting comprehensive views across multiple domains
+- Strategic decisions with trade-offs
+
+:::note[Prerequisites]
+- BMad Method installed with multiple agents
+- Any agent loaded that supports party mode
+:::
+
+## Steps
+
+### 1. Load Any Agent
+
+Start with any agent that supports party mode (most do).
+
+### 2. Start Party Mode
+
+```
+*party-mode
+```
+
+Or use the full path:
+```
+/bmad:core:workflows:party-mode
+```
+
+### 3. Introduce Your Topic
+
+Present a topic or question for the group to discuss:
+
+```
+I'm trying to decide between a monolithic architecture
+and microservices for our new platform.
+```
+
+### 4. Engage with the Discussion
+
+The facilitator will:
+- Select 2-3 most relevant agents based on expertise
+- Let agents respond in character
+- Enable natural cross-talk and debate
+- Continue until you choose to exit
+
+### 5. Exit When Ready
+
+Type "exit" or "done" to conclude the session. Participating agents will say personalized farewells.
+
+## What Happens
+
+1. **Agent Roster** — Party Mode loads your complete agent roster
+2. **Introduction** — Available team members are introduced
+3. **Topic Analysis** — The facilitator analyzes your topic
+4. **Agent Selection** — 2-3 most relevant agents are selected
+5. **Discussion** — Agents respond, reference each other, engage in cross-talk
+6. **Exit** — Session concludes with farewells
+
+## Example Party Compositions
+
+| Topic                  | Typical Agents                                        |
+| ---------------------- | ----------------------------------------------------- |
+| **Product Strategy**   | PM + Innovation Strategist + Analyst                  |
+| **Technical Design**   | Architect + Creative Problem Solver  + Game Architect |
+| **User Experience**    | UX Designer + Design Thinking Coach  + Storyteller    |
+| **Quality Assessment** | TEA + DEV + Architect                                 |
+
+## Key Features
+
+- **Intelligent agent selection** — Selects based on expertise needed
+- **Authentic personalities** — Each agent maintains their unique voice
+- **Natural cross-talk** — Agents reference and build on each other
+- **Graceful exit** — Personalized farewells
+
+## Tips
+
+- **Be specific about your topic** — Better agent selection
+- **Let the conversation flow** — Don't over-direct
+- **Ask follow-up questions** — Go deeper on interesting points
+- **Take notes on key insights** — Capture valuable perspectives
+- **Use for strategic decisions** — Not routine tasks

package/docs/how-to/workflows/setup-test-framework.md

@@ -0,0 +1,98 @@
+---
+title: "How to Set Up a Test Framework with TEA"
+description: How to set up a production-ready test framework using TEA
+---
+
+Use TEA's `*framework` workflow to scaffold a production-ready test framework for your project.
+
+## When to Use This
+
+- No existing test framework in your project
+- Current test setup isn't production-ready
+- Starting a new project that needs testing infrastructure
+- Phase 3 (Solutioning) after architecture is complete
+
+:::note[Prerequisites]
+- BMad Method installed
+- Architecture completed (or at least tech stack decided)
+- TEA agent available
+:::
+
+## Steps
+
+### 1. Load the TEA Agent
+
+Start a fresh chat and load the TEA (Test Architect) agent.
+
+### 2. Run the Framework Workflow
+
+```
+*framework
+```
+
+### 3. Answer TEA's Questions
+
+TEA will ask about:
+
+- Your tech stack (React, Node, etc.)
+- Preferred test framework (Playwright, Cypress, Jest)
+- Testing scope (E2E, integration, unit)
+- CI/CD platform (GitHub Actions, etc.)
+
+### 4. Review Generated Output
+
+TEA generates:
+
+- **Test scaffold** — Directory structure and config files
+- **Sample specs** — Example tests following best practices
+- **`.env.example`** — Environment variable template
+- **`.nvmrc`** — Node version specification
+- **README updates** — Testing documentation
+
+## What You Get
+
+```
+tests/
+├── e2e/
+│   ├── example.spec.ts
+│   └── fixtures/
+├── integration/
+├── unit/
+├── playwright.config.ts  # or cypress.config.ts
+└── README.md
+```
+
+## Optional: Playwright Utils Integration
+
+TEA can integrate with `@seontechnologies/playwright-utils` for advanced fixtures:
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+Enable during BMad installation or set `tea_use_playwright_utils: true` in config.
+
+**Utilities available:** api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor
+
+## Optional: MCP Enhancements
+
+TEA can use Playwright MCP servers for enhanced capabilities:
+
+- `playwright` — Browser automation
+- `playwright-test` — Test runner with failure analysis
+
+Configure in your IDE's MCP settings.
+
+## Tips
+
+- **Run only once per repository** — Framework setup is a one-time operation
+- **Run after architecture is complete** — Framework aligns with tech stack
+- **Follow up with CI setup** — Run `*ci` to configure CI/CD pipeline
+
+## Next Steps
+
+After test framework setup:
+
+1. **Test Design** — Create test plans for system or epics
+2. **CI Configuration** — Set up automated test runs
+3. **Story Implementation** — Tests are ready for development

package/docs/index.md

@@ -0,0 +1,63 @@
+---
+title: Welcome to the BMad Method
+---
+
+The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework that helps you build software faster and smarter. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity—whether you're fixing a bug or building an enterprise platform.
+
+If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
+
+---
+
+## New Here? Start with a Tutorial
+
+The fastest way to understand BMad is to try it. Choose a tutorial to walk through your first project in about 10 minutes.
+
+- **[Get Started with BMad](/docs/tutorials/getting-started/getting-started-bmadv6.md)** — Latest features, still in active development
+
+:::tip[Already familiar with AI-assisted development?]
+Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](/docs/explanation/core-concepts/what-are-agents.md) to understand how BMad organizes its AI personas.
+:::
+
+---
+
+## How to Use These Docs
+
+These docs are organized into four sections based on what you're trying to do:
+
+| Section           | Purpose                                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Tutorials**     | Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new. |
+| **How-To Guides** | Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here.  |
+| **Explanation**   | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*.       |
+| **Reference**     | Information-oriented. Technical specifications for agents, workflows, and configuration.                   |
+
+---
+
+## What You'll Need
+
+BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
+
+- **[Claude Code](https://code.claude.com)** — Anthropic's CLI tool (recommended)
+- **[Cursor](https://cursor.sh)** — AI-first code editor
+- **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
+- **[Roo Code](https://roocode.com)** — VS Code extension
+
+You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMad-style agent systems is required—that's what these docs are for.
+
+---
+
+## Join the Community
+
+Get help, share what you're building, or contribute to BMad:
+
+- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chat with other BMad users, ask questions, share ideas
+- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Source code, issues, and contributions
+- **[YouTube](https://www.youtube.com/@BMadCode)** — Video tutorials and walkthroughs
+
+---
+
+## Next Step
+
+Ready to dive in? Pick a tutorial and start building.
+
+- **[Get Started with BMad](/docs/tutorials/getting-started/getting-started-bmadv6.md)** — Explore the latest features

package/docs/migration-guide.md

@@ -0,0 +1,365 @@
+# Migration Guide: Multi-Scope Parallel Artifacts
+
+> Guide for migrating existing BMAD installations to the multi-scope system.
+
+## Overview
+
+The multi-scope system introduces isolated artifact workspaces while maintaining full backward compatibility. Existing installations can:
+
+1. Continue working without any changes (legacy mode)
+2. Migrate existing artifacts to a `default` scope
+3. Create new scopes for parallel development
+
+## Prerequisites
+
+- BMAD v6+ installed
+- Node.js 20+
+- Backup of your `_bmad-output/` directory (recommended)
+
+## Migration Paths
+
+### Path 1: Continue Without Migration (Recommended for Simple Projects)
+
+If you have a single-team, single-product workflow, you can continue using BMAD without migration. The scope system is entirely opt-in.
+
+**When to choose this path:**
+- Small to medium projects
+- Single developer or tightly coordinated team
+- No need for parallel feature development
+
+**What happens:**
+- Workflows continue to use `_bmad-output/` directly
+- No scope variable in paths
+- All existing commands work unchanged
+
+### Path 2: Migrate to Default Scope (Recommended for Growing Projects)
+
+Migrate existing artifacts to a `default` scope, enabling future parallel development.
+
+```bash
+# 1. Analyze current state
+bmad scope migrate --analyze
+
+# 2. Run migration (creates backup automatically)
+bmad scope migrate
+
+# 3. Verify migration
+bmad scope list
+bmad scope info default
+```
+
+**What happens:**
+- Creates backup at `_bmad-output/_backup_migration_<timestamp>/`
+- Initializes scope system
+- Creates `default` scope
+- Moves artifacts from `_bmad-output/` to `_bmad-output/default/`
+- Updates references in state files
+- Creates shared layer at `_bmad-output/_shared/`
+
+### Path 3: Fresh Start with Scopes
+
+For new projects or major rewrites, start fresh with the scope system.
+
+```bash
+# Initialize scope system
+bmad scope init
+
+# Create your first scope
+bmad scope create main --name "Main Product"
+
+# Run workflows with scope
+bmad workflow create-prd --scope main
+```
+
+## Step-by-Step Migration
+
+### Step 1: Backup (Automatic but Verify)
+
+The migration creates an automatic backup, but we recommend creating your own:
+
+```bash
+# Manual backup
+cp -r _bmad-output/ _bmad-output-backup-$(date +%Y%m%d)/
+```
+
+### Step 2: Analyze Current State
+
+```bash
+bmad scope migrate --analyze
+```
+
+**Example output:**
+```
+Migration Analysis
+==================
+
+Current Structure:
+  _bmad-output/
+  ├── planning-artifacts/
+  │   ├── prd.md
+  │   ├── architecture.md
+  │   └── epics-stories.md
+  ├── implementation-artifacts/
+  │   ├── sprint-status.yaml
+  │   └── stories/
+  └── tests/
+      └── ...
+
+Detected Artifacts:
+  Planning: 3 files
+  Implementation: 15 files
+  Tests: 8 files
+
+Migration Plan:
+  1. Create backup
+  2. Initialize scope system
+  3. Create 'default' scope
+  4. Move all artifacts to default/
+  5. Create shared layer
+  6. Update state references
+
+Estimated time: < 30 seconds
+```
+
+### Step 3: Run Migration
+
+```bash
+bmad scope migrate
+```
+
+**Interactive prompts:**
+```
+? Ready to migrate existing artifacts to 'default' scope? (Y/n)
+? Create scope-specific project-context.md? (y/N)
+```
+
+### Step 4: Verify Migration
+
+```bash
+# Check scope list
+bmad scope list
+
+# Verify directory structure
+ls -la _bmad-output/
+
+# Check default scope
+bmad scope info default
+```
+
+**Expected structure after migration:**
+```
+_bmad-output/
+├── _shared/
+│   ├── project-context.md
+│   ├── contracts/
+│   └── principles/
+├── default/
+│   ├── planning-artifacts/
+│   │   ├── prd.md
+│   │   ├── architecture.md
+│   │   └── epics-stories.md
+│   ├── implementation-artifacts/
+│   │   ├── sprint-status.yaml
+│   │   └── stories/
+│   ├── tests/
+│   └── .scope-meta.yaml
+└── _backup_migration_<timestamp>/
+    └── (original files)
+```
+
+### Step 5: Update Workflows (Optional)
+
+If you have custom workflow configurations, update paths:
+
+**Before:**
+```yaml
+output_dir: "{output_folder}/planning-artifacts"
+```
+
+**After:**
+```yaml
+output_dir: "{scope_planning}"
+# Or: "{output_folder}/{scope}/planning-artifacts"
+```
+
+The migration script can update workflows automatically:
+
+```bash
+node tools/cli/scripts/migrate-workflows.js --dry-run --verbose
+node tools/cli/scripts/migrate-workflows.js
+```
+
+## Rollback Procedure
+
+If migration fails or you need to revert:
+
+### Automatic Rollback
+
+```bash
+bmad scope migrate --rollback
+```
+
+### Manual Rollback
+
+```bash
+# Remove migrated structure
+rm -rf _bmad-output/default/
+rm -rf _bmad-output/_shared/
+rm -rf _bmad/_config/scopes.yaml
+rm -rf _bmad/_events/
+
+# Restore from backup
+cp -r _bmad-output/_backup_migration_<timestamp>/* _bmad-output/
+rm -rf _bmad-output/_backup_migration_<timestamp>/
+```
+
+## Post-Migration Steps
+
+### 1. Update .gitignore
+
+Add scope-related files to ignore:
+
+```gitignore
+# Scope session file (user-specific)
+.bmad-scope
+
+# Lock files
+*.lock
+
+# Backup directories (optional)
+_bmad-output/_backup_*/
+```
+
+### 2. Update Team Documentation
+
+Inform your team about the new scope system:
+
+- How to create scopes
+- How to run workflows with scopes
+- How to use sync-up/sync-down
+
+### 3. Configure Scope Dependencies (Optional)
+
+If your scopes have dependencies:
+
+```bash
+# Update scope with dependencies
+bmad scope update default --deps shared-lib,core-api
+```
+
+### 4. Set Up Event Subscriptions (Optional)
+
+For multi-scope projects:
+
+```bash
+# Edit subscriptions manually
+# _bmad/_events/subscriptions.yaml
+```
+
+```yaml
+subscriptions:
+  frontend:
+    watch:
+      - scope: api
+        patterns: ["contracts/*"]
+    notify: true
+```
+
+## Troubleshooting
+
+### Error: "Artifacts not found after migration"
+
+**Cause:** Migration path resolution issue.
+
+**Solution:**
+```bash
+# Check backup location
+ls _bmad-output/_backup_migration_*/
+
+# Manually move if needed
+mv _bmad-output/_backup_migration_*/planning-artifacts/* _bmad-output/default/planning-artifacts/
+```
+
+### Error: "Scope not found"
+
+**Cause:** Scope system not initialized.
+
+**Solution:**
+```bash
+bmad scope init
+```
+
+### Error: "Cannot write to scope 'default' while in scope 'other'"
+
+**Cause:** Cross-scope write protection.
+
+**Solution:**
+```bash
+# Either switch scope
+bmad workflow --scope default
+
+# Or use sync to share
+bmad scope sync-up other
+bmad scope sync-down default
+```
+
+### State Files Show Old Paths
+
+**Cause:** References not updated during migration.
+
+**Solution:**
+```bash
+# Re-run migration with force update
+bmad scope migrate --force --update-refs
+```
+
+## FAQ
+
+### Q: Will my existing workflows break?
+
+**A:** No. The scope system is backward compatible. Workflows without `{scope}` variables continue to work. Only workflows with scope variables require an active scope.
+
+### Q: Can I have both scoped and non-scoped artifacts?
+
+**A:** Yes, but not recommended. The `_shared/` layer is for cross-scope artifacts. Keep everything in scopes for consistency.
+
+### Q: How do I share artifacts between team members?
+
+**A:** Use git as usual. The `_bmad-output/` directory structure (including scopes) can be committed. Add `.bmad-scope` to `.gitignore` (session-specific).
+
+### Q: Can I rename scopes?
+
+**A:** Not directly. Create new scope, copy artifacts, remove old scope:
+```bash
+bmad scope create new-name --name "New Name"
+cp -r _bmad-output/old-name/* _bmad-output/new-name/
+bmad scope remove old-name --force
+```
+
+### Q: What happens to sprint-status.yaml?
+
+**A:** Each scope gets its own `sprint-status.yaml` at `_bmad-output/{scope}/implementation-artifacts/sprint-status.yaml`. This enables parallel sprint planning.
+
+### Q: Do I need to update my CI/CD?
+
+**A:** Only if your CI/CD references specific artifact paths. Update paths to include scope:
+```bash
+# Before
+cat _bmad-output/planning-artifacts/prd.md
+
+# After
+cat _bmad-output/default/planning-artifacts/prd.md
+```
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| 6.1.0 | Multi-scope system introduced |
+| 6.0.0 | Initial v6 release |
+
+---
+
+For more details, see:
+- [Multi-Scope Guide](multi-scope-guide.md)
+- [Implementation Plan](plans/multi-scope-parallel-artifacts-plan.md)