Brian
97d32405d0
* feat(installer): add plugin resolution strategies for custom URL installs When installing from a custom GitHub URL, the installer now analyzes marketplace.json plugin structures to determine how to locate module registration files (module.yaml, module-help.csv). Five strategies are tried in cascade: 1. Root module files at the common parent of listed skills 2. A -setup skill with registration files in its assets/ 3. Single standalone skill with registration files in assets/ 4. Multiple standalone skills, each with their own registration files 5. Fallback: synthesize registration from marketplace.json metadata and SKILL.md frontmatter Also changes the custom URL flow from confirm-all to multiselect, letting users pick which plugins to install. Already-installed modules are pre-checked for update; new modules are unchecked for opt-in. New file: tools/installer/modules/plugin-resolver.js Modified: custom-module-manager.js, official-modules.js, ui.js * fix(installer): address PR review findings for plugin resolver - Guard against path traversal in plugin-resolver.js: skill paths from unverified marketplace.json are now constrained to the repo root using path.resolve() + startsWith check - Skip npm install during browsing phase: cloneRepo() accepts skipInstall option, used in ui.js before user confirms selection, preventing arbitrary lifecycle script execution from untrusted repos - Add createModuleDirectories() call to installFromResolution() so modules with declarative directory config are fully set up - Fix ESLint: use replaceAll instead of replace with global regex * fix(installer): pass version and repoUrl to manifest for custom plugins installFromResolution was passing empty strings for version and repoUrl, which the manifest stores as null. Now threads the repo URL from ui.js through resolvePlugin into each ResolvedModule, and passes the plugin version and URL to the manifest correctly. * fix(installer): manifest-generator overwrites custom module version/repoUrl ManifestGenerator rebuilds the entire manifest via getModuleVersionInfo for every module. For custom modules, this returned null for version and repoUrl because it only checked _readMarketplaceVersion (which searches for marketplace.json on disk) and hardcoded repoUrl to null. Now checks the resolution cache first to get the correct version and repo URL. * fix(installer): resolve custom modules from disk cache on quick update When the resolution cache is empty (fresh CLI process, e.g. quick update), findModuleSourceByCode only matched plugin.name against the module code. This failed for modules like "sam" and "dw" where the code comes from module.yaml inside a setup/standalone skill, not from the plugin name in marketplace.json. Now runs the PluginResolver on cached repos when the direct name match fails, finding the correct module source and re-populating the cache for the install pipeline. * feat(installer): universal source support for custom modules Replace GitHub-only custom module installation with support for any Git host (GitHub, GitLab, Bitbucket, self-hosted) and local file paths. - Add parseSource() universal input parser (local paths, SSH, HTTPS with deep path/subdir extraction for GitHub, GitLab, Gitea) - Add resolveSource() coordinator: parse -> clone if URL -> detect discovery vs direct mode (marketplace.json present or not) - Clone-first approach eliminates host-specific raw URL fetching - 3-level cache structure (host/owner/repo) with .bmad-source.json metadata for URL reconstruction - Local paths install directly without caching; localPath persisted in manifest for quick-update source lookup - Direct mode scans target directory for SKILL.md when no marketplace.json - Fix version display bug where walk-up found parent repo marketplace.json and reported wrong version for custom modules * fix(installer): harden readMarketplaceJsonFromDisk and hoist require - Add try/catch to readMarketplaceJsonFromDisk so malformed JSON returns null instead of throwing an unhandled parse error - Hoist CustomModuleManager require outside the per-module loop in _installOfficialModules * fix(installer): restore validateGitHubUrl strictness and fix prettier - Restore original GitHub-only regex in deprecated validateGitHubUrl wrapper so existing tests pass (rejects non-GitHub URLs, trailing slashes) - Run prettier to fix formatting in custom-module-manager.js * feat(installer): add --custom-source CLI flag for non-interactive installs Allows installing custom modules from Git URLs or local paths directly from the command line without interactive prompts: npx bmad-method install --custom-source /path/to/module npx bmad-method install --custom-source https://gitlab.com/org/repo npx bmad-method install --custom-source /path/one,https://host/org/repo Works alongside --modules and --yes flags. All discovered modules from each source are auto-selected. * docs: add custom and community module installation guide New how-to page covering community module browsing, custom sources (any Git host, local paths), discovery vs direct mode, local development workflow, and the --custom-source CLI flag. Clarifies that .claude-plugin/ is a cross-tool convention, not Claude-specific. Also updates non-interactive installation docs with the new flag and examples, bumps sidebar ordering, and fixes --custom-source to install only core + custom modules when --modules is not specified.
4.4 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Established Projects | How to use BMad Method on existing codebases |
|
Use BMad Method effectively when working on existing projects and legacy codebases.
This guide covers the essential workflow for onboarding to existing projects with BMad Method.
:::note[Prerequisites]
- BMad Method installed (
npx bmad-method install) - An existing codebase you want to work on
- Access to an AI-powered IDE (Claude Code or Cursor) :::
Step 1: Clean Up Completed Planning Artifacts
If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
docs/_bmad-output/planning-artifacts/_bmad-output/implementation-artifacts/
Step 2: Create Project Context
:::tip[Recommended for Existing Projects]
Generate project-context.md to capture your existing codebase patterns and conventions. This ensures AI agents follow your established practices when implementing changes.
:::
Run the generate project context workflow:
bmad-generate-project-context
This scans your codebase to identify:
- Technology stack and versions
- Code organization patterns
- Naming conventions
- Testing approaches
- Framework-specific patterns
You can review and refine the generated file, or create it manually at _bmad-output/project-context.md if you prefer.
Learn more about project context
Step 3: Maintain Quality Project Documentation
Your docs/ folder should contain succinct, well-organized documentation that accurately represents your project:
- Intent and business rationale
- Business rules
- Architecture
- Any other relevant project information
For complex projects, consider using the bmad-document-project workflow. It offers runtime variants that will scan your entire project and document its actual current state.
Step 3: Get Help
BMad-Help: Your Starting Point
Run bmad-help anytime you're unsure what to do next. This intelligent guide:
- Inspects your project to see what's already been done
- Shows options based on your installed modules
- Understands natural language queries
bmad-help I have an existing Rails app, where should I start?
bmad-help What's the difference between quick-flow and full method?
bmad-help Show me what workflows are available
BMad-Help also automatically runs at the end of every workflow, providing clear guidance on exactly what to do next.
Choosing Your Approach
You have two primary options depending on the scope of changes:
| Scope | Recommended Approach |
|---|---|
| Small updates or additions | Run bmad-quick-dev to clarify intent, plan, implement, and review in a single workflow. The full four-phase BMad Method is likely overkill. |
| Major changes or additions | Start with the BMad Method, applying as much or as little rigor as needed. |
During PRD Creation
When creating a brief or jumping directly into the PRD, ensure the agent:
- Finds and analyzes your existing project documentation
- Reads the proper context about your current system
You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
UX Considerations
UX work is optional. The decision depends not on whether your project has a UX, but on:
- Whether you will be working on UX changes
- Whether significant new UX designs or patterns are needed
If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
Architecture Considerations
When doing architecture, ensure the architect:
- Uses the proper documented files
- Scans the existing codebase
Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
More Information
- Quick Fixes - Bug fixes and ad-hoc changes
- Established Projects FAQ - Common questions about working on established projects