From 9bf5e576a694c02a00c7f81ab64131ea91568c2c Mon Sep 17 00:00:00 2001 From: Lukasz Wyszynski Date: Sun, 28 Dec 2025 11:25:48 +1030 Subject: [PATCH] docs: update linked projects list (31 total) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Converted 21 standalone BMAD installations to symlinks: - All projects now use central BMAD-METHOD installation - ~65MB disk space saved - Party mode works instantly across all projects Also added BMAD symlink protection: - Section 12 in ~/.claude/CLAUDE.md prevents empty placeholder creation - Pre-commit hook at ~/.claude/hooks/prevent-empty-bmad.sh 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- LINKED-PROJECTS.md | 192 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 LINKED-PROJECTS.md diff --git a/LINKED-PROJECTS.md b/LINKED-PROJECTS.md new file mode 100644 index 00000000..729e9bee --- /dev/null +++ b/LINKED-PROJECTS.md @@ -0,0 +1,192 @@ +# 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: + +```bash +cd /Users/hbl/Documents/BMAD-METHOD +./link-project.sh /path/to/your/project +``` + +### Method 2: Manual Linking + +```bash +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 + +```bash +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: + +```bash +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`: + +```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: + +```bash +ls -la /Users/hbl/Documents/BMAD-METHOD/bmad +``` + +### Want to switch from linked to standalone + +1. Unlink: `rm bmad .claude .bmad-linked` +2. 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: + +1. Restore BMAD-METHOD from git or backups +2. Or unlink all projects and reinstall BMAD independently in each + +## Best Practices + +1. **Keep BMAD-METHOD as a git repository** - Allows version control and easy restoration +2. **Don't modify files in linked directories** - Changes affect all linked projects +3. **Use project-specific configs** - Store project-specific settings outside `bmad/` and `.claude/` +4. **Backup before updates** - Run `git commit` in BMAD-METHOD before major updates +5. **Document linked projects** - Keep the "Currently Linked Projects" section updated + +## Advanced: Project-Specific Overrides + +If a linked project needs custom agents or configurations: + +```bash +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`