bmad-fh 6.0.0-alpha.23.50b728f9 → 6.0.0-alpha.23.599980af

package/README.md

@@ -66,31 +66,134 @@ BMad supports running multiple workflows in parallel across different terminal s
 - **Multi-team projects** — Each team works in their own scope
 - **Parallel feature development** — Develop auth, payments, and catalog simultaneously
 - **Microservices** — One scope per service with shared contracts
+- **Experimentation** — Create isolated scopes for spikes and prototypes
+
+### Quick Start
 
 ```bash
 # Initialize scope system
-bmad scope init
+npx bmad-fh@multi-artifact scope init
 
 # Create scopes for different services
-bmad scope create auth --name "Authentication"
-bmad scope create payments --name "Payments"
+npx bmad-fh@multi-artifact scope create auth --name "Authentication Service"
+npx bmad-fh@multi-artifact scope create payments --name "Payment Processing" --deps auth
+
+# Set the active scope for your session
+npx bmad-fh@multi-artifact scope set auth
 
 # Run workflows in parallel (different terminals)
-bmad workflow create-prd --scope auth     # Terminal 1
-bmad workflow create-prd --scope payments # Terminal 2
+# Terminal 1: Set scope to auth, run agent workflows
+# Terminal 2: Set scope to payments, run agent workflows
 
 # Share artifacts between scopes
-bmad scope sync-up auth       # Promote to shared layer
-bmad scope sync-down payments # Pull shared updates
+npx bmad-fh@multi-artifact scope sync-up auth       # Promote to shared layer
+npx bmad-fh@multi-artifact scope sync-down payments # Pull shared updates
+```
+
+### CLI Reference
+
+| Command                                           | Description                                 |
+| ------------------------------------------------- | ------------------------------------------- |
+| `npx bmad-fh@multi-artifact scope init`           | Initialize the scope system in your project |
+| `npx bmad-fh@multi-artifact scope list`           | List all scopes (alias: `ls`)               |
+| `npx bmad-fh@multi-artifact scope create <id>`    | Create a new scope (alias: `new`)           |
+| `npx bmad-fh@multi-artifact scope info <id>`      | Show scope details (alias: `show`)          |
+| `npx bmad-fh@multi-artifact scope set [id]`       | Set active scope for session (alias: `use`) |
+| `npx bmad-fh@multi-artifact scope unset`          | Clear active scope (alias: `clear`)         |
+| `npx bmad-fh@multi-artifact scope remove <id>`    | Remove a scope (aliases: `rm`, `delete`)    |
+| `npx bmad-fh@multi-artifact scope archive <id>`   | Archive a completed scope                   |
+| `npx bmad-fh@multi-artifact scope activate <id>`  | Reactivate an archived scope                |
+| `npx bmad-fh@multi-artifact scope sync-up <id>`   | Promote artifacts to shared layer           |
+| `npx bmad-fh@multi-artifact scope sync-down <id>` | Pull shared updates into scope              |
+| `npx bmad-fh@multi-artifact scope help [cmd]`     | Show help (add command for detailed help)   |
+
+### Create Options
+
+```bash
+npx bmad-fh@multi-artifact scope create auth \
+  --name "Authentication Service" \
+  --description "User auth, SSO, and session management" \
+  --deps users,notifications \
+  --context  # Create scope-specific project-context.md
+```
+
+### Directory Structure
+
+After initialization and scope creation:
+
+```
+project-root/
+├── _bmad/
+│   ├── _config/
+│   │   └── scopes.yaml          # Scope registry and settings
+│   └── _events/
+│       ├── event-log.yaml       # Event history
+│       └── subscriptions.yaml   # Cross-scope subscriptions
+│
+├── _bmad-output/
+│   ├── _shared/                 # Shared knowledge layer
+│   │   ├── project-context.md   # Global project context
+│   │   ├── contracts/           # Integration contracts
+│   │   └── principles/          # Architecture principles
+│   │
+│   ├── auth/                    # Auth scope artifacts
+│   │   ├── planning-artifacts/
+│   │   ├── implementation-artifacts/
+│   │   └── tests/
+│   │
+│   └── payments/                # Payments scope artifacts
+│       └── ...
+│
+└── .bmad-scope                  # Session-sticky active scope (gitignored)
+```
+
+### Access Model
+
+Scopes follow a "read-any, write-own" isolation model:
+
+| Operation | Own Scope | Other Scopes | \_shared/   |
+| --------- | --------- | ------------ | ----------- |
+| **Read**  | Allowed   | Allowed      | Allowed     |
+| **Write** | Allowed   | Blocked      | via sync-up |
+
+### Workflow Integration
+
+Workflows (run via agent menus like `CP` for Create PRD, `DS` for Dev Story) automatically detect and use scope context. Resolution order:
+
+1. Session context from `.bmad-scope` file (set via `scope set`)
+2. `BMAD_SCOPE` environment variable
+3. Prompt user to select or create scope
+
+**Setting your active scope:**
+
+```bash
+# Set scope for your terminal session
+npx bmad-fh@multi-artifact scope set auth
+
+# Or use environment variable (useful for CI/CD)
+export BMAD_SCOPE=auth
 ```
 
-**Key Features:**
-- Read-any, write-own isolation model
-- Shared knowledge layer (`_shared/`) for cross-scope artifacts
-- Event system for dependency notifications
-- Session-sticky scope context
+**Scope-aware path variables in workflows:**
+
+- `{scope}` → Scope ID (e.g., "auth")
+- `{scope_path}` → `_bmad-output/auth`
+- `{scope_planning}` → `_bmad-output/auth/planning-artifacts`
+- `{scope_implementation}` → `_bmad-output/auth/implementation-artifacts`
+- `{scope_tests}` → `_bmad-output/auth/tests`
+
+### Getting Help
+
+```bash
+# Show comprehensive help for all scope commands
+npx bmad-fh@multi-artifact scope help
+
+# Get detailed help for a specific command
+npx bmad-fh@multi-artifact scope help create
+npx bmad-fh@multi-artifact scope help sync-up
+```
 
-See [Multi-Scope Guide](docs/multi-scope-guide.md) for details.
+See [Multi-Scope Guide](docs/multi-scope-guide.md) for complete documentation.
 
 ## Community
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-fh",
-  "version": "6.0.0-alpha.23.50b728f9",
+  "version": "6.0.0-alpha.23.599980af",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/core/lib/scope/scope-manager.js

@@ -2,6 +2,7 @@ const path = require('node:path');
 const fs = require('fs-extra');
 const yaml = require('yaml');
 const { ScopeValidator } = require('./scope-validator');
+const { ScopeInitializer } = require('./scope-initializer');
 
 /**
  * Manages scope lifecycle and CRUD operations
@@ -25,6 +26,7 @@ class ScopeManager {
     this.scopesFilePath = options.scopesFilePath || path.join(this.configPath, 'scopes.yaml');
 
     this.validator = new ScopeValidator();
+    this.initializer = new ScopeInitializer({ projectRoot: this.projectRoot });
     this._config = null; // Cached configuration
   }
 
@@ -38,6 +40,7 @@ class ScopeManager {
     this.configPath = path.join(this.bmadPath, '_config');
     this.scopesFilePath = path.join(this.configPath, 'scopes.yaml');
     this._config = null; // Clear cache
+    this.initializer.setProjectRoot(projectRoot);
   }
 
   /**
@@ -59,6 +62,9 @@ class ScopeManager {
         await this.saveConfig(defaultConfig);
       }
 
+      // Initialize scope system directories (_shared, _events)
+      await this.initializer.initializeScopeSystem();
+
       // Load and validate configuration
       const config = await this.loadConfig();
       return config !== null;
@@ -239,6 +245,9 @@ class ScopeManager {
       // Save configuration
       await this.saveConfig(config);
 
+      // Create scope directory structure
+      await this.initializer.initializeScope(scopeId, options);
+
       return scope;
     } catch (error) {
       throw new Error(`Failed to create scope '${scopeId}': ${error.message}`);
@@ -311,7 +320,7 @@ class ScopeManager {
       }
 
       // Check if other scopes depend on this one
-      const dependentScopes = this.findDependentScopes(scopeId, config.scopes);
+      const dependentScopes = this.findDependentScopesSync(scopeId, config.scopes);
       if (dependentScopes.length > 0 && !options.force) {
         throw new Error(
           `Cannot remove scope '${scopeId}'. The following scopes depend on it: ${dependentScopes.join(', ')}. Use force option to remove anyway.`,
@@ -396,7 +405,7 @@ class ScopeManager {
       const tree = {
         scope: scopeId,
         dependencies: [],
-        dependents: this.findDependentScopes(scopeId, config.scopes),
+        dependents: this.findDependentScopesSync(scopeId, config.scopes),
       };
 
       // Build dependency tree recursively
@@ -422,10 +431,34 @@ class ScopeManager {
   /**
    * Find scopes that depend on a given scope
    * @param {string} scopeId - The scope ID
-   * @param {object} allScopes - All scopes object
+   * @param {object} allScopes - All scopes object (optional, will load if not provided)
+   * @returns {Promise<string[]>|string[]} Array of dependent scope IDs
+   */
+  async findDependentScopes(scopeId, allScopes = null) {
+    // If allScopes not provided, load from config
+    if (!allScopes) {
+      const config = await this.loadConfig();
+      allScopes = config.scopes || {};
+    }
+
+    const dependents = [];
+
+    for (const [sid, scope] of Object.entries(allScopes)) {
+      if (scope.dependencies && scope.dependencies.includes(scopeId)) {
+        dependents.push(sid);
+      }
+    }
+
+    return dependents;
+  }
+
+  /**
+   * Find scopes that depend on a given scope (synchronous version)
+   * @param {string} scopeId - The scope ID
+   * @param {object} allScopes - All scopes object (required)
    * @returns {string[]} Array of dependent scope IDs
    */
-  findDependentScopes(scopeId, allScopes) {
+  findDependentScopesSync(scopeId, allScopes) {
     const dependents = [];
 
     for (const [sid, scope] of Object.entries(allScopes)) {