BMad Git Commit Extension

Adds *commit command to BMAD Dev agent for automatic Conventional Commits.

Install

Option 1: Install via npm (Recommended)

npm install bmad-git-commit

What happens:

• If BMAD is already installed: Extension installs automatically ✅
• If BMAD is not installed yet: Installation is deferred (no errors) ⏸️

Option 2: Manual Installation

If you installed the package before BMAD, trigger installation manually:

npx bmad-git-commit install

Or directly:

node node_modules/bmad-git-commit/install.js

Installation Scenarios

The installer automatically detects whether BMAD is installed and handles both scenarios gracefully.

Scenario 1: Installing AFTER BMAD is Installed ✅

When this happens:

• You run npm install bmad-git-commit in a project that already has BMAD
• The postinstall script runs automatically after npm install

What happens:

1. ✅ Package is installed to node_modules/bmad-git-commit
2. ✅ postinstall script runs automatically
3. ✅ Script detects .bmad-core exists
4. ✅ Script detects dev.md exists
5. ✅ Installation proceeds immediately:
   • Copies documentation to .bmad-core/docs/
   • Backs up dev.md
   • Merges commit command into dev.md
   • Updates install-manifest.yaml
6. ✅ Installation completes successfully

User workflow:

# 1. Install BMAD first
npx bmad-method install

# 2. Install this package
npm install bmad-git-commit

# ✅ Extension is immediately available!
# You can now use @dev *commit

Result:

• ✅ Extension is immediately available
• ✅ You can use @dev *commit right away
• ✅ No manual steps required

Scenario 2: Installing BEFORE BMAD is Installed ⏸️

When this happens:

• You run npm install bmad-git-commit in a project that doesn't have BMAD yet
• The postinstall script runs automatically after npm install

What happens:

1. ✅ Package is installed to node_modules/bmad-git-commit
2. ✅ postinstall script runs automatically
3. ⚠️ Script detects .bmad-core doesn't exist
4. ✅ Script exits gracefully (no error)
5. 📝 Installation is deferred until BMAD is installed

User workflow:

# Step 1: Install the package
npm install bmad-git-commit
# (Installation is deferred - no errors)

# Step 2: Install BMAD (later)
npx bmad-method install

# Step 3: Run the installer manually
npx bmad-git-commit install
# OR
node node_modules/bmad-git-commit/install.js

# ✅ Extension is now available!

Why this approach:

• ✅ No errors during npm install
• ✅ Package is ready when BMAD is installed
• ✅ You can install BMAD at any time
• ✅ Manual trigger ensures installation happens at the right time

Installation Flow

┌─────────────────────────────────────────────────────────────┐
│                    npm install bmad-git-commit               │
└───────────────────────────┬───────────────────────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │  postinstall  │
                    │     hook      │
                    └───────┬───────┘
                            │
                            ▼
              ┌─────────────────────────┐
              │  Check .bmad-core       │
              │  exists?                │
              └─────┬───────────┬───────┘
                    │           │
          ┌─────────┘           └─────────┐
          │                                 │
          ▼                                 ▼
    ┌──────────┐                    ┌──────────┐
    │   NO     │                    │   YES    │
    │          │                    │          │
    └────┬─────┘                    └────┬─────┘
         │                                │
         ▼                                ▼
  ┌──────────────┐              ┌─────────────────┐
  │ Exit Gracefully│              │ Check dev.md    │
  │ (Deferred)     │              │ exists?         │
  └───────────────┘              └────┬──────┬─────┘
                                       │      │
                              ┌────────┘      └────────┐
                              │                         │
                              ▼                         ▼
                        ┌──────────┐            ┌──────────┐
                        │   NO     │            │   YES    │
                        │          │            │          │
                        └────┬─────┘            └────┬─────┘
                             │                      │
                             ▼                      ▼
                    ┌──────────────┐      ┌──────────────────┐
                    │ Exit Gracefully│      │ Install Extension│
                    │ (Deferred)     │      │                  │
                    └───────────────┘      │ 1. Copy docs      │
                                           │ 2. Backup dev.md  │
                                           │ 3. Merge command  │
                                           │ 4. Update manifest│
                                           └─────────┬─────────┘
                                                     │
                                                     ▼
                                            ┌────────────────┐
                                            │ ✅ Complete!   │
                                            └────────────────┘

Requirements

• Node.js >= 14.0.0
• BMAD installed in your project (can be installed before or after this package)

Usage

After completing a story:

@dev *commit

The agent will:

1. Read your story's File List
2. Generate a conventional commit message
3. Ask for approval (Yes/No/Edit)
4. Execute the commit

What It Does

• ✅ Adds *commit command to Dev agent
• ✅ Generates Conventional Commit messages (feat/fix/refactor/etc.)
• ✅ Uses story File List automatically
• ✅ Interactive approval workflow

Verify Installation

# Check if commit command was added
grep "commit:" .bmad-core/agents/dev.md

# Should show the command definition

Then test in Cursor: @dev *help (should show *commit)

Manual Installation Options

If installation was deferred (Scenario 2), you can manually trigger installation:

Option 1: Using npx (Recommended)

npx bmad-git-commit install

Option 2: Direct Node execution

node node_modules/bmad-git-commit/install.js

Option 3: Using npm script

Add to your package.json:

{
  "scripts": {
    "bmad:install-commit": "node node_modules/bmad-git-commit/install.js"
  }
}

Then run:

npm run bmad:install-commit

Re-installation / Update

If the extension is already installed and you update the package:

What happens:

• ✅ Script detects - commit: already exists in dev.md
• ✅ In non-interactive mode (postinstall): Skips installation (already installed)
• ✅ In interactive mode: Prompts to overwrite

To force re-installation:

# Remove the commit command manually from dev.md first, then:
npx bmad-git-commit install

Troubleshooting

Extension not working after install?

1. Check if BMAD is installed:

   ls .bmad-core/agents/dev.md

   If missing, run: npx bmad-method install

2. Check if extension is installed:

   grep "commit:" .bmad-core/agents/dev.md

   If missing, run: npx bmad-git-commit install

3. Reinstall manually:

   npx bmad-git-commit install

Error Handling

Missing BMAD

• Detection: .bmad-core doesn't exist
• Action: Exit gracefully, installation deferred
• Solution: Install BMAD first (npx bmad-method install), then run installer manually

Missing dev.md

• Detection: .bmad-core/agents/dev.md doesn't exist
• Action: Exit gracefully, installation deferred
• Solution: Run npx bmad-method install first

File Permission Errors

• Detection: Cannot write to .bmad-core/ directory
• Action: Exit with error code
• Solution: Check file permissions on .bmad-core/ directory

Already Installed

• Detection: - commit: found in dev.md
• Action: Skip installation (in postinstall) or prompt (in interactive)
• Solution: None needed - extension is already installed

How It Works

postinstall Hook

• Runs automatically after npm install
• Detects installation context via process.env.npm_lifecycle_event
• Runs silently unless DEBUG env var is set
• Exits gracefully if BMAD not found (deferred installation)

Manual Installation

• Can be triggered via npx bmad-git-commit install
• Runs in interactive mode
• Shows full output and prompts
• Can overwrite existing installation if needed

File Operations

• Backup: Creates timestamped backup of dev.md before modification
• Merge: Intelligently merges commit command before dependencies: section
• Manifest: Updates install-manifest.yaml to track installation
• Docs: Copies documentation to .bmad-core/docs/

Benefits

1. ✅ No Breaking Changes: Works whether BMAD is installed or not
2. ✅ User-Friendly: Automatic installation when possible
3. ✅ Flexible: Manual trigger available when needed
4. ✅ Safe: Creates backups before modifying files
5. ✅ Idempotent: Can be run multiple times safely
6. ✅ CI/CD Friendly: Non-interactive mode for automated environments

Testing Installation

Test Scenario 1 (Before BMAD)

# Create a new project
mkdir test-project && cd test-project
npm init -y

# Install package (BMAD not installed yet)
npm install bmad-git-commit

# Verify: Should exit gracefully, no errors
# Check: .bmad-core should not exist

# Now install BMAD
npx bmad-method install

# Manually trigger installation
npx bmad-git-commit install

# Verify: dev.md should have commit command
grep "commit:" .bmad-core/agents/dev.md

Test Scenario 2 (After BMAD)

# Create a new project
mkdir test-project && cd test-project
npm init -y

# Install BMAD first
npx bmad-method install

# Install package (BMAD already installed)
npm install bmad-git-commit

# Verify: Installation should complete automatically
# Check: dev.md should have commit command
grep "commit:" .bmad-core/agents/dev.md

More Information

• See docs/commit-changes-usage.md for detailed usage guide