bmad-fh 6.0.0-alpha.23.6390fcb0 → 6.0.0-alpha.23.6874ced1

package/.github/workflows/publish.yaml

@@ -41,12 +41,26 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          echo "Publishing bmad-fh@${{ steps.version.outputs.version }}"
-          npm publish
+          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: |
-          echo "## Published bmad-fh@${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          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

package/.husky/post-checkout

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+
+# =============================================================================
+# Call .githooks/post-checkout first (if exists)
+# =============================================================================
+if [ -x ".githooks/post-checkout" ]; then
+  .githooks/post-checkout "$@"
+fi
+
+# =============================================================================
+# Husky-specific post-checkout logic can be added below
+# =============================================================================

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

@@ -74,22 +74,28 @@ BMad supports running multiple workflows in parallel across different terminal s
 # Initialize scope system
 npx bmad-fh scope init
 
-# Create scopes for different services
+# Create a scope (you'll be prompted to activate it)
 npx bmad-fh scope create auth --name "Authentication Service"
-npx bmad-fh scope create payments --name "Payment Processing" --deps auth
+# ✓ Scope 'auth' created successfully!
+# ? Set 'auth' as your active scope for this session? (Y/n)
 
-# Set the active scope for your session
-npx bmad-fh scope set auth
+# Run workflows - artifacts now go to _bmad-output/auth/
+# The active scope is stored in .bmad-scope file
 
-# Run workflows in parallel (different terminals)
-# Terminal 1: Set scope to auth, run agent workflows
-# Terminal 2: Set scope to payments, run agent workflows
+# For parallel development in different terminals:
+# Terminal 1:
+npx bmad-fh scope set auth     # Activate auth scope
+# Terminal 2:
+npx bmad-fh scope set payments # Activate payments scope
 
 # Share artifacts between scopes
 npx bmad-fh scope sync-up auth       # Promote to shared layer
 npx bmad-fh scope sync-down payments # Pull shared updates
 ```
 
+> **Important:** Workflows only use scoped directories when a scope is active.
+> After creating a scope, accept the prompt to activate it, or run `scope set <id>` manually.
+
 ### CLI Reference
 
 | Command                            | Description                                 |

package/docs/migration-guide.md

@@ -1,3 +1,8 @@
+---
+title: 'Migration Guide: Multi-Scope Parallel Artifacts'
+description: 'Guide for migrating existing BMAD installations to the multi-scope system'
+---
+
 # Migration Guide: Multi-Scope Parallel Artifacts
 
 > Guide for migrating existing BMAD installations to the multi-scope system.
@@ -23,11 +28,13 @@ The multi-scope system introduces isolated artifact workspaces while maintaining
 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
@@ -49,6 +56,7 @@ bmad scope info default
 ```
 
 **What happens:**
+
 - Creates backup at `_bmad-output/_backup_migration_<timestamp>/`
 - Initializes scope system
 - Creates `default` scope
@@ -89,6 +97,7 @@ bmad scope migrate --analyze
 ```
 
 **Example output:**
+
 ```
 Migration Analysis
 ==================
@@ -128,6 +137,7 @@ bmad scope migrate
 ```
 
 **Interactive prompts:**
+
 ```
 ? Ready to migrate existing artifacts to 'default' scope? (Y/n)
 ? Create scope-specific project-context.md? (y/N)
@@ -147,6 +157,7 @@ bmad scope info default
 ```
 
 **Expected structure after migration:**
+
 ```
 _bmad-output/
 ├── _shared/
@@ -172,13 +183,15 @@ _bmad-output/
 If you have custom workflow configurations, update paths:
 
 **Before:**
+
 ```yaml
-output_dir: "{output_folder}/planning-artifacts"
+output_dir: '{output_folder}/planning-artifacts'
 ```
 
 **After:**
+
 ```yaml
-output_dir: "{scope_planning}"
+output_dir: '{scope_planning}'
 # Or: "{output_folder}/{scope}/planning-artifacts"
 ```
 
@@ -261,7 +274,7 @@ subscriptions:
   frontend:
     watch:
       - scope: api
-        patterns: ["contracts/*"]
+        patterns: ['contracts/*']
     notify: true
 ```
 
@@ -272,6 +285,7 @@ subscriptions:
 **Cause:** Migration path resolution issue.
 
 **Solution:**
+
 ```bash
 # Check backup location
 ls _bmad-output/_backup_migration_*/
@@ -285,6 +299,7 @@ mv _bmad-output/_backup_migration_*/planning-artifacts/* _bmad-output/default/pl
 **Cause:** Scope system not initialized.
 
 **Solution:**
+
 ```bash
 bmad scope init
 ```
@@ -294,6 +309,7 @@ bmad scope init
 **Cause:** Cross-scope write protection.
 
 **Solution:**
+
 ```bash
 # Either switch scope
 bmad workflow --scope default
@@ -308,6 +324,7 @@ bmad scope sync-down default
 **Cause:** References not updated during migration.
 
 **Solution:**
+
 ```bash
 # Re-run migration with force update
 bmad scope migrate --force --update-refs
@@ -330,6 +347,7 @@ bmad scope migrate --force --update-refs
 ### 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/
@@ -343,6 +361,7 @@ bmad scope remove old-name --force
 ### 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
@@ -353,13 +372,14 @@ 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 |
+| 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)

package/docs/multi-scope-guide.md

@@ -1,3 +1,8 @@
+---
+title: 'Multi-Scope Parallel Artifacts Guide'
+description: '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.
@@ -16,10 +21,11 @@ The multi-scope system enables parallel development by isolating artifacts into
 ### Initialize Scope System
 
 ```bash
-bmad scope init
+npx bmad-fh scope init
 ```
 
 This creates:
+
 - `_bmad/_config/scopes.yaml` - Scope registry
 - `_bmad-output/_shared/` - Shared knowledge layer
 - `_bmad/_events/` - Event system
@@ -27,22 +33,41 @@ This creates:
 ### Create Your First Scope
 
 ```bash
-bmad scope create auth --name "Authentication Service"
+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
 
 ```bash
-bmad scope list
+npx bmad-fh scope list
 ```
 
-### Run Workflow with Scope
+### Activate a Scope
 
 ```bash
-# Workflows automatically use scope context
-bmad workflow --scope auth
+# 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
 
 ```
@@ -74,26 +99,30 @@ project-root/
 
 ### Scope Management
 
-| Command | Description |
-|---------|-------------|
-| `bmad scope init` | Initialize scope system |
-| `bmad scope list` | List all scopes |
-| `bmad scope create <id>` | Create new scope |
-| `bmad scope info <id>` | Show scope details |
-| `bmad scope remove <id>` | Remove a scope |
-| `bmad scope archive <id>` | Archive a scope |
-| `bmad scope activate <id>` | Activate archived scope |
+| 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
 
 ```bash
-bmad scope create auth \
+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
 
 ```bash
@@ -114,6 +143,7 @@ bmad scope sync-up auth
 ```
 
 Promotes:
+
 - `architecture/*.md`
 - `contracts/*.md`
 - `principles/*.md`
@@ -128,10 +158,10 @@ 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 |
+| Operation | Scope: auth | Scope: payments | \_shared    |
+| --------- | ----------- | --------------- | ----------- |
+| **Read**  | Any scope   | Any scope       | Yes         |
+| **Write** | auth only   | payments only   | Use sync-up |
 
 ### Isolation Modes
 
@@ -139,7 +169,7 @@ Configure in `_bmad/_config/scopes.yaml`:
 
 ```yaml
 settings:
-  isolation_mode: strict  # strict | warn | permissive
+  isolation_mode: strict # strict | warn | permissive
 ```
 
 - **strict**: Block cross-scope writes (default)
@@ -155,18 +185,18 @@ Workflows use `{scope}` variable:
 ```yaml
 # workflow.yaml
 variables:
-  test_dir: "{scope_tests}"  # Resolves to _bmad-output/auth/tests
+  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 |
+| 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
 
@@ -175,7 +205,7 @@ The `.bmad-scope` file in project root stores active scope:
 ```yaml
 # .bmad-scope (gitignored)
 active_scope: auth
-set_at: "2026-01-21T10:00:00Z"
+set_at: '2026-01-21T10:00:00Z'
 ```
 
 Workflows automatically use this scope when no `--scope` flag provided.
@@ -192,7 +222,7 @@ subscriptions:
   payments:
     watch:
       - scope: auth
-        patterns: ["contracts/*", "architecture.md"]
+        patterns: ['contracts/*', 'architecture.md']
     notify: true
 ```
 
@@ -250,6 +280,7 @@ bmad scope migrate
 ```
 
 This:
+
 1. Creates backup
 2. Creates `default` scope
 3. Moves artifacts to `_bmad-output/default/`
@@ -260,6 +291,7 @@ This:
 ### Naming Scopes
 
 Use clear, descriptive IDs:
+
 - `auth` - Authentication service
 - `payments` - Payment processing
 - `user-service` - User management
@@ -268,6 +300,7 @@ Use clear, descriptive IDs:
 ### Scope Granularity
 
 Choose based on:
+
 - **Team boundaries** - One scope per team
 - **Deployment units** - One scope per service
 - **Feature sets** - One scope per major feature
@@ -282,11 +315,13 @@ Choose based on:
 ### Dependencies
 
 Declare dependencies explicitly:
+
 ```bash
 bmad scope create payments --deps auth,users
 ```
 
 This helps:
+
 - Track relationships
 - Get notifications on dependency changes
 - Plan integration work
@@ -310,6 +345,7 @@ 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)
@@ -320,7 +356,7 @@ Solutions:
 # Keep local version
 bmad scope sync-down payments --resolution keep-local
 
-# Keep shared version  
+# Keep shared version
 bmad scope sync-down payments --resolution keep-shared
 
 # Backup and update
@@ -366,7 +402,7 @@ const { ArtifactResolver } = require('./src/core/lib/scope');
 
 const resolver = new ArtifactResolver({
   currentScope: 'auth',
-  basePath: '_bmad-output'
+  basePath: '_bmad-output',
 });
 
 // Check access