5.3 KiB

Raw Blame History

BMAD Linked Projects Strategy

Overview

This BMAD installation serves as the primary BMAD hub for all your projects. Instead of installing BMAD v6 separately into each project, external projects can be symbolically linked to this central installation.

Benefits

✅ Single Source of Truth - One BMAD installation to maintain ✅ Instant Updates - Update BMAD once, all linked projects benefit ✅ Disk Space Savings - No duplicate BMAD installations ✅ Consistent Tooling - Same agents and workflows across all projects ✅ Easy Management - Centralized configuration and updates

Architecture

/Users/hbl/Documents/BMAD-METHOD/          ← Primary BMAD Installation
├── bmad/                                   ← BMAD Core
├── .claude/                                ← Claude Code agents
├── src/                                    ← BMAD source code
└── link-project.sh                         ← Project linker script

/Users/hbl/Documents/hbl-documents/         ← Linked Project #1
├── bmad -> /Users/.../BMAD-METHOD/bmad     ← Symlink
├── .claude -> /Users/.../BMAD-METHOD/.claude
└── .bmad-linked                            ← Marker file

/Users/hbl/Documents/other-project/         ← Linked Project #2
├── bmad -> /Users/.../BMAD-METHOD/bmad     ← Symlink
├── .claude -> /Users/.../BMAD-METHOD/.claude
└── .bmad-linked                            ← Marker file

How to Link a New Project

Method 1: Using the Link Script (Recommended)

From the BMAD-METHOD directory:

cd /Users/hbl/Documents/BMAD-METHOD
./link-project.sh /path/to/your/project

Method 2: Manual Linking

cd /path/to/your/project

# Create symlinks
ln -s /Users/hbl/Documents/BMAD-METHOD/bmad bmad
ln -s /Users/hbl/Documents/BMAD-METHOD/.claude .claude

# Add to .gitignore
echo "bmad" >> .gitignore
echo ".claude" >> .gitignore
echo ".bmad-linked" >> .gitignore

How to Unlink a Project

cd /path/to/your/project
rm bmad .claude .bmad-linked

To restore a standalone BMAD installation after unlinking, run the BMAD installer from that project's directory.

Updating BMAD for All Linked Projects

Since all projects reference the same BMAD installation, you only need to update once:

cd /Users/hbl/Documents/BMAD-METHOD
npm run update:bmad

This will immediately update BMAD for all linked projects.

Currently Linked Projects (31 total)

Project	Status
ahmci	✅
aip-connect	✅
aja-app-2026	✅
bailey-legal-bloom	✅
banking-app-2026	✅
black-dashboard-ui	✅
caffeinate	✅
call-app	✅
council-ledger	✅
cyrvra	✅
dpc-bank	✅
e-sign-nextjs16	✅
exportwhatsapp	✅
hbl-documents	✅
hbl-documents/signright-au	✅
hbl-lawyer/lexicon	✅
hbl-nextjs16	✅
JurisMark	✅
LexFocus-Rust	✅
lexmail	✅
loco-app-early-july	✅
loco-nextjs16	✅
original-chadcn-ui	✅
pages-health-nextjs16	✅
press	✅
veenability	✅
VerityDocs	✅
visa-ai	✅
wyszynski-qcat	✅

Last updated: 2025-12-28

Git Considerations

The linker script automatically adds these entries to .gitignore:

# BMAD symlinks (linked to /Users/hbl/Documents/BMAD-METHOD)
bmad
.claude
.bmad-linked

This ensures:

Symlinks are not committed to version control
Each developer can maintain their own BMAD setup
Project repository stays clean and portable

Troubleshooting

Symlink appears broken

Check if the BMAD-METHOD installation still exists:

ls -la /Users/hbl/Documents/BMAD-METHOD/bmad

Want to switch from linked to standalone

Unlink: rm bmad .claude .bmad-linked
Install: node /Users/hbl/Documents/BMAD-METHOD/tools/cli/bmad-cli.js install

Accidentally deleted BMAD-METHOD

If you delete the primary installation, all linked projects will have broken symlinks. To recover:

Restore BMAD-METHOD from git or backups
Or unlink all projects and reinstall BMAD independently in each

Best Practices

Keep BMAD-METHOD as a git repository - Allows version control and easy restoration
Don't modify files in linked directories - Changes affect all linked projects
Use project-specific configs - Store project-specific settings outside bmad/ and .claude/
Backup before updates - Run git commit in BMAD-METHOD before major updates
Document linked projects - Keep the "Currently Linked Projects" section updated

Advanced: Project-Specific Overrides

If a linked project needs custom agents or configurations:

cd /path/to/your/project

# Create project-specific agent directory
mkdir -p .claude-local/agents

# Add to your project's documentation
# that .claude-local/ contains project-specific configs

Then configure Claude Code to read from both directories (check Claude Code docs for multi-path configuration).

Support

For issues with:

Linking/unlinking: Check this document or run ./link-project.sh without arguments
BMAD updates: See BMAD-METHOD documentation
Claude Code integration: See .claude/agents/ documentation

Last Updated: 2025-10-19 BMAD Version: 6.0.0-alpha.0 Primary Installation: /Users/hbl/Documents/BMAD-METHOD

5.3 KiB Raw Blame History