bmad-fh 6.0.0-alpha.23 → 6.0.0-alpha.23.3b00cb36

package/.github/workflows/publish.yaml

@@ -0,0 +1,68 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - feat/multi-artifact-support
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Set version with commit hash
+        id: version
+        run: |
+          BASE_VERSION=$(node -p "require('./package.json').version")
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          NEW_VERSION="${BASE_VERSION}.${SHORT_SHA}"
+          npm version "${NEW_VERSION}" --no-git-tag-version
+          echo "version=${NEW_VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Publish to NPM
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          echo "Checking if bmad-fh@${VERSION} already exists..."
+
+          # Check if version already exists on npm
+          if npm view "bmad-fh@${VERSION}" version 2>/dev/null; then
+            echo "Version ${VERSION} already exists on npm, skipping publish"
+            echo "SKIPPED=true" >> $GITHUB_ENV
+          else
+            echo "Publishing bmad-fh@${VERSION}"
+            npm publish --ignore-scripts
+            echo "SKIPPED=false" >> $GITHUB_ENV
+          fi
+
+      - name: Summary
+        run: |
+          if [ "$SKIPPED" = "true" ]; then
+            echo "## Skipped - bmad-fh@${{ steps.version.outputs.version }} already exists" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "## Published bmad-fh@${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Installation" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "npx bmad-fh install" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

package/.husky/pre-commit

@@ -1,5 +1,20 @@
 #!/usr/bin/env sh
 
+# =============================================================================
+# Call .githooks/pre-commit first (if exists)
+# =============================================================================
+if [ -x ".githooks/pre-commit" ]; then
+  .githooks/pre-commit "$@"
+  GITHOOKS_EXIT=$?
+  if [ $GITHOOKS_EXIT -ne 0 ]; then
+    exit $GITHOOKS_EXIT
+  fi
+fi
+
+# =============================================================================
+# Husky-specific: lint-staged and tests
+# =============================================================================
+
 # Auto-fix changed files and stage them
 npx --no-install lint-staged
 
@@ -10,11 +25,11 @@ npm test
 if command -v rg >/dev/null 2>&1; then
   if git diff --cached --name-only | rg -q '^docs/'; then
     npm run docs:validate-links
-		npm run docs:build
+    npm run docs:build
   fi
 else
   if git diff --cached --name-only | grep -Eq '^docs/'; then
     npm run docs:validate-links
-		npm run docs:build
+    npm run docs:build
   fi
 fi

package/.husky/pre-push

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+
+# Delegate to .githooks/pre-push for comprehensive checks
+# (upstream sync, rebase check, single-commit enforcement)
+
+if [ -x ".githooks/pre-push" ]; then
+  .githooks/pre-push "$@"
+else
+  echo "Warning: .githooks/pre-push not found, skipping custom checks"
+fi

package/README.md

@@ -23,7 +23,7 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 **Prerequisites**: [Node.js](https://nodejs.org) v20+
 
 ```bash
-npx bmad-fh@multi-artifact install
+npx bmad-fh install
 ```
 
 Follow the installer prompts to configure your project. Then run:
@@ -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 scope init
 
 # Create scopes for different services
-bmad scope create auth --name "Authentication"
-bmad scope create payments --name "Payments"
+npx bmad-fh scope create auth --name "Authentication Service"
+npx bmad-fh scope create payments --name "Payment Processing" --deps auth
+
+# Set the active scope for your session
+npx bmad-fh 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 scope sync-up auth       # Promote to shared layer
+npx bmad-fh scope sync-down payments # Pull shared updates
+```
+
+### CLI Reference
+
+| Command                            | Description                                 |
+| ---------------------------------- | ------------------------------------------- |
+| `npx bmad-fh scope init`           | Initialize the scope system in your project |
+| `npx bmad-fh scope list`           | List all scopes (alias: `ls`)               |
+| `npx bmad-fh scope create <id>`    | Create a new scope (alias: `new`)           |
+| `npx bmad-fh scope info <id>`      | Show scope details (alias: `show`)          |
+| `npx bmad-fh scope set [id]`       | Set active scope for session (alias: `use`) |
+| `npx bmad-fh scope unset`          | Clear active scope (alias: `clear`)         |
+| `npx bmad-fh scope remove <id>`    | Remove a scope (aliases: `rm`, `delete`)    |
+| `npx bmad-fh scope archive <id>`   | Archive a completed scope                   |
+| `npx bmad-fh scope activate <id>`  | Reactivate an archived scope                |
+| `npx bmad-fh scope sync-up <id>`   | Promote artifacts to shared layer           |
+| `npx bmad-fh scope sync-down <id>` | Pull shared updates into scope              |
+| `npx bmad-fh scope help [cmd]`     | Show help (add command for detailed help)   |
+
+### Create Options
+
+```bash
+npx bmad-fh 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 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 scope help
+
+# Get detailed help for a specific command
+npx bmad-fh scope help create
+npx bmad-fh 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/eslint.config.mjs

@@ -81,9 +81,9 @@ export default [
     },
   },
 
-  // CLI scripts under tools/** and test/**
+  // CLI scripts under tools/**, test/**, and src/core/lib/**
   {
-    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js'],
+    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js', 'src/core/lib/**/*.js'],
     rules: {
       // Allow CommonJS patterns for Node CLI scripts
       'unicorn/prefer-module': 'off',

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-fh",
-  "version": "6.0.0-alpha.23",
+  "version": "6.0.0-alpha.23.3b00cb36",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -24,7 +24,6 @@
   },
   "scripts": {
     "bmad:install": "node tools/cli/bmad-cli.js install",
-    "publish:multi-artifact": "npm publish --tag multi-artifact",
     "bundle": "node tools/cli/bundlers/bundle-web.js all",
     "docs:build": "node tools/build-docs.js",
     "docs:dev": "astro dev --root website",

package/src/bmm/module.yaml

@@ -34,13 +34,13 @@ user_skill_level:
 scope:
   default: ""
   result: "{value}"
-  runtime: true  # Indicates this is resolved at runtime, not during install
+  runtime: true # Indicates this is resolved at runtime, not during install
 
 # Scope-aware path helper - resolves to output_folder/scope or just output_folder
 scope_path:
   default: "{output_folder}"
   result: "{value}"
-  runtime: true  # Updated at runtime when scope is active
+  runtime: true # Updated at runtime when scope is active
 
 planning_artifacts: # Phase 1-3 artifacts
   prompt: "Where should planning artifacts be stored? (Brainstorming, Briefs, PRDs, UX Designs, Architecture, Epics)"

package/src/core/lib/scope/artifact-resolver.js

@@ -3,15 +3,15 @@ const path = require('node:path');
 /**
  * Resolves and enforces scope-based artifact access
  * Implements read-any/write-own access model
- * 
+ *
  * @class ArtifactResolver
- * 
+ *
  * @example
  * const resolver = new ArtifactResolver({
  *   currentScope: 'auth',
  *   basePath: '/path/to/_bmad-output'
  * });
- * 
+ *
  * if (resolver.canWrite('/path/to/_bmad-output/auth/file.md')) {
  *   // Write operation allowed
  * }
@@ -52,7 +52,7 @@ class ArtifactResolver {
   extractScopeFromPath(filePath) {
     // Normalize path
     const normalizedPath = path.normalize(filePath);
-    
+
     // Find the base path in the file path
     const baseIndex = normalizedPath.indexOf(this.basePath);
     if (baseIndex === -1) {
@@ -61,16 +61,16 @@ class ArtifactResolver {
 
     // Get the relative path from base
     const relativePath = normalizedPath.slice(Math.max(0, baseIndex + this.basePath.length + 1));
-    
+
     // Split to get the first segment (scope name)
     const segments = relativePath.split(path.sep).filter(Boolean);
-    
+
     if (segments.length === 0) {
       return null;
     }
 
     const firstSegment = segments[0];
-    
+
     // Check if it's a reserved path
     if (this.reservedPaths.includes(firstSegment)) {
       return firstSegment; // Return the reserved path name
@@ -109,7 +109,7 @@ class ArtifactResolver {
     // Read is always allowed for all paths
     return {
       allowed: true,
-      reason: 'Read access is always allowed in read-any model'
+      reason: 'Read access is always allowed in read-any model',
     };
   }
 
@@ -124,7 +124,7 @@ class ArtifactResolver {
       return {
         allowed: true,
         reason: 'No scope active, operating in legacy mode',
-        warning: null
+        warning: null,
       };
     }
 
@@ -135,7 +135,7 @@ class ArtifactResolver {
       return {
         allowed: false,
         reason: `Cannot write directly to '${this.sharedPath}'. Use: bmad scope sync-up`,
-        warning: null
+        warning: null,
       };
     }
 
@@ -144,7 +144,7 @@ class ArtifactResolver {
       return {
         allowed: false,
         reason: `Cannot write to reserved path '${targetScope}'`,
-        warning: null
+        warning: null,
       };
     }
 
@@ -153,7 +153,7 @@ class ArtifactResolver {
       return {
         allowed: true,
         reason: `Write allowed to current scope '${this.currentScope}'`,
-        warning: null
+        warning: null,
       };
     }
 
@@ -164,31 +164,31 @@ class ArtifactResolver {
           return {
             allowed: false,
             reason: `Cannot write to scope '${targetScope}' while in scope '${this.currentScope}'`,
-            warning: null
+            warning: null,
           };
         }
-        
+
         case 'warn': {
           return {
             allowed: true,
             reason: 'Write allowed with warning in warn mode',
-            warning: `Warning: Writing to scope '${targetScope}' from scope '${this.currentScope}'`
+            warning: `Warning: Writing to scope '${targetScope}' from scope '${this.currentScope}'`,
           };
         }
-        
+
         case 'permissive': {
           return {
             allowed: true,
             reason: 'Write allowed in permissive mode',
-            warning: null
+            warning: null,
           };
         }
-        
+
         default: {
           return {
             allowed: false,
             reason: 'Unknown isolation mode',
-            warning: null
+            warning: null,
           };
         }
       }
@@ -198,7 +198,7 @@ class ArtifactResolver {
     return {
       allowed: true,
       reason: 'Path is outside scope system',
-      warning: null
+      warning: null,
     };
   }
 
@@ -209,11 +209,11 @@ class ArtifactResolver {
    */
   validateWrite(filePath) {
     const result = this.canWrite(filePath);
-    
+
     if (!result.allowed) {
       throw new Error(result.reason);
     }
-    
+
     if (result.warning) {
       console.warn(result.warning);
     }
@@ -227,7 +227,7 @@ class ArtifactResolver {
    */
   resolveScopePath(relativePath, scopeId = null) {
     const scope = scopeId || this.currentScope;
-    
+
     if (!scope) {
       // No scope - return path relative to base
       return path.join(this.basePath, relativePath);
@@ -254,7 +254,7 @@ class ArtifactResolver {
       currentScope: this.currentScope ? path.join(this.basePath, this.currentScope) : null,
       shared: path.join(this.basePath, this.sharedPath),
       allScopes: `${this.basePath}/*`,
-      description: 'Read access is allowed to all scopes and shared directories'
+      description: 'Read access is allowed to all scopes and shared directories',
     };
   }
 
@@ -266,13 +266,13 @@ class ArtifactResolver {
     if (!this.currentScope) {
       return {
         all: this.basePath,
-        description: 'No scope active - all paths writable (legacy mode)'
+        description: 'No scope active - all paths writable (legacy mode)',
       };
     }
 
     return {
       currentScope: path.join(this.basePath, this.currentScope),
-      description: `Write access limited to scope '${this.currentScope}'`
+      description: `Write access limited to scope '${this.currentScope}'`,
     };
   }