BMAD-METHOD/docs/multi-scope-guide.md

title	description
Multi-Scope Parallel Artifacts Guide	Run multiple workflows in parallel across different terminal sessions with isolated artifacts

Multi-Scope Parallel Artifacts Guide

Run multiple workflows in parallel across different terminal sessions with isolated artifacts.

Overview

The multi-scope system enables parallel development by isolating artifacts into separate "scopes". Each scope is an independent workspace with its own:

• Planning artifacts (PRDs, architecture, epics)
• Implementation artifacts (sprint status, stories)
• Test directories
• Optional scope-specific project context

Quick Start

Initialize Scope System

npx bmad-fh scope init

This creates:

• _bmad/_config/scopes.yaml - Scope registry
• _bmad-output/_shared/ - Shared knowledge layer
• _bmad/_events/ - Event system

Create Your First Scope

npx bmad-fh scope create auth --name "Authentication Service"

Important: After creation, you'll be prompted to activate the scope:

✓ Scope 'auth' created successfully!
? Set 'auth' as your active scope for this session? (Y/n)

Accept this prompt (or run npx bmad-fh scope set auth later) to ensure workflows use the scoped directories.

List Scopes

npx bmad-fh scope list

Activate a Scope

# Set the active scope for your terminal session
npx bmad-fh scope set auth

# Or use environment variable (useful for CI/CD)
export BMAD_SCOPE=auth

Workflows automatically detect the active scope from:

1. .bmad-scope file (set by scope set command)
2. BMAD_SCOPE environment variable

Warning: If no scope is active, artifacts go to root _bmad-output/ directory (legacy mode).

Directory Structure

project-root/
├── _bmad/
│   ├── _config/
│   │   └── scopes.yaml              # Scope registry
│   └── _events/
│       ├── event-log.yaml           # Event tracking
│       └── subscriptions.yaml       # Event subscriptions
│
└── _bmad-output/
    ├── _shared/                     # Shared knowledge layer
    │   ├── project-context.md       # Global "bible"
    │   ├── contracts/               # Integration contracts
    │   └── principles/              # Architecture principles
    │
    ├── auth/                        # Auth scope
    │   ├── planning-artifacts/
    │   ├── implementation-artifacts/
    │   ├── tests/
    │   └── project-context.md       # Scope-specific context
    │
    └── payments/                    # Payments scope
        └── ...

CLI Commands

Scope Management

Command	Description
npx bmad-fh scope init	Initialize scope system
npx bmad-fh scope create <id>	Create new scope (prompts to activate)
npx bmad-fh scope set <id>	Set active scope (required!)
npx bmad-fh scope list	List all scopes
npx bmad-fh scope info <id>	Show scope details
npx bmad-fh scope remove <id>	Remove a scope
npx bmad-fh scope archive <id>	Archive a scope
npx bmad-fh scope activate <id>	Activate archived scope

Create Options

npx bmad-fh scope create auth \
  --name "Authentication" \
  --description "User auth and SSO" \
  --deps payments,users \
  --context  # Create scope-specific project-context.md

Note: After creation, you'll be prompted to set this as your active scope. Accept the prompt to ensure workflows use the scoped directories.

Remove with Backup

# Creates backup in _bmad-output/_backup_auth_<timestamp>
bmad scope remove auth

# Force remove without backup
bmad scope remove auth --force --no-backup

Syncing Between Scopes

Promote to Shared Layer

# Promote artifacts to shared
bmad scope sync-up auth

Promotes:

• architecture/*.md
• contracts/*.md
• principles/*.md
• project-context.md

Pull from Shared Layer

# Pull shared updates to scope
bmad scope sync-down payments

Access Model

Operation	Scope: auth	Scope: payments	_shared
Read	Any scope	Any scope	Yes
Write	auth only	payments only	Use sync-up

Isolation Modes

Configure in _bmad/_config/scopes.yaml:

settings:
  isolation_mode: strict # strict | warn | permissive

• strict: Block cross-scope writes (default)
• warn: Allow with warnings
• permissive: Allow all (not recommended)

Workflow Integration

Scope Variable

Workflows use {scope} variable:

# workflow.yaml
variables:
  test_dir: '{scope_tests}' # Resolves to _bmad-output/auth/tests

Scope-Aware Paths

Variable	Non-scoped	Scoped (auth)
{scope}	(empty)	auth
{scope_path}	_bmad-output	_bmad-output/auth
{scope_planning}	_bmad-output/planning-artifacts	_bmad-output/auth/planning-artifacts
{scope_implementation}	_bmad-output/implementation-artifacts	_bmad-output/auth/implementation-artifacts
{scope_tests}	_bmad-output/tests	_bmad-output/auth/tests

Session-Sticky Scope

The .bmad-scope file in project root stores active scope:

# .bmad-scope (gitignored)
active_scope: auth
set_at: '2026-01-21T10:00:00Z'

Workflows automatically use this scope when no --scope flag provided.

Event System

Subscribing to Updates

Scopes can subscribe to events from other scopes:

# _bmad/_events/subscriptions.yaml
subscriptions:
  payments:
    watch:
      - scope: auth
        patterns: ['contracts/*', 'architecture.md']
    notify: true

Event Types

• artifact_created - New artifact created
• artifact_updated - Artifact modified
• artifact_promoted - Promoted to shared
• sync_up / sync_down - Sync operations
• scope_created / scope_archived - Scope lifecycle

Parallel Development Example

Terminal 1: Auth Scope

# Set scope for session
bmad scope create auth --name "Authentication"

# Run workflows - all output goes to auth scope
bmad workflow create-prd --scope auth
bmad workflow create-epic --scope auth

Terminal 2: Payments Scope

# Different scope, isolated artifacts
bmad scope create payments --name "Payment Processing"

bmad workflow create-prd --scope payments
bmad workflow create-epic --scope payments

Sharing Work

# Terminal 1: Promote auth architecture to shared
bmad scope sync-up auth

# Terminal 2: Pull shared updates to payments
bmad scope sync-down payments

Migration from Non-Scoped

Existing projects can migrate:

# Analyze existing artifacts
bmad scope migrate --analyze

# Migrate to 'default' scope
bmad scope migrate

This:

1. Creates backup
2. Creates default scope
3. Moves artifacts to _bmad-output/default/
4. Updates references

Best Practices

Naming Scopes

Use clear, descriptive IDs:

• auth - Authentication service
• payments - Payment processing
• user-service - User management
• api-gateway - API gateway

Scope Granularity

Choose based on:

• Team boundaries - One scope per team
• Deployment units - One scope per service
• Feature sets - One scope per major feature

Shared Layer Usage

• Keep project-context.md as the global "bible"
• Put integration contracts in _shared/contracts/
• Document architecture principles in _shared/principles/
• Promote mature, stable artifacts only

Dependencies

Declare dependencies explicitly:

bmad scope create payments --deps auth,users

This helps:

• Track relationships
• Get notifications on dependency changes
• Plan integration work

Troubleshooting

"No scope set" Error

# Option 1: Specify scope explicitly
bmad workflow --scope auth

# Option 2: Set session scope
bmad scope create auth

Cross-Scope Write Blocked

Error: Cannot write to scope 'payments' while in scope 'auth'

Solutions:

1. Switch to correct scope
2. Use sync-up to promote to shared
3. Change isolation mode (not recommended)

Conflict During Sync

# Keep local version
bmad scope sync-down payments --resolution keep-local

# Keep shared version
bmad scope sync-down payments --resolution keep-shared

# Backup and update
bmad scope sync-down payments --resolution backup-and-update

API Reference

ScopeManager

const { ScopeManager } = require('./src/core/lib/scope');

const manager = new ScopeManager({ projectRoot: '/path/to/project' });
await manager.initialize();

// CRUD operations
const scope = await manager.createScope('auth', { name: 'Auth' });
const scopes = await manager.listScopes();
await manager.archiveScope('auth');
await manager.removeScope('auth', { force: true });

ScopeContext

const { ScopeContext } = require('./src/core/lib/scope');

const context = new ScopeContext({ projectRoot: '/path/to/project' });

// Session management
await context.setScope('auth');
const current = await context.getCurrentScope();

// Load merged context
const projectContext = await context.loadProjectContext('auth');

ArtifactResolver

const { ArtifactResolver } = require('./src/core/lib/scope');

const resolver = new ArtifactResolver({
  currentScope: 'auth',
  basePath: '_bmad-output',
});

// Check access
const canWrite = resolver.canWrite('/path/to/file.md');
resolver.validateWrite('/path/to/file.md'); // Throws if not allowed

---

For more details, see the Implementation Plan.