docs: document dual publishing strategy and automated promotion
- Add comprehensive documentation for dual publishing workflow - Document GitHub Actions promotion process - Clarify user experience for stable vs beta installations - Include step-by-step promotion instructions
This commit is contained in:
Brian Madison
196
CLAUDE.md
Normal file
196
CLAUDE.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# CLAUDE.md
|
||||
|
||||
Don't be an ass kisser, don't glaze my donut, keep it to the point. Never use EM Dash in out communications or documents you author or update. Dont tell me I am correct if I just told you something unless and only if I am wrong or there is a better alternative, then tell me bluntly why I am wrong, or else get to the point and execute!
|
||||
|
||||
## Markdown Linting Conventions
|
||||
|
||||
Always follow these markdown linting rules:
|
||||
|
||||
- **Blank lines around headings**: Always leave a blank line before and after headings
|
||||
- **Blank lines around lists**: Always leave a blank line before and after lists
|
||||
- **Blank lines around code fences**: Always leave a blank line before and after fenced code blocks
|
||||
- **Fenced code block languages**: All fenced code blocks must specify a language (use `text` for plain text)
|
||||
- **Single trailing newline**: Files should end with exactly one newline character
|
||||
- **No trailing spaces**: Remove any trailing spaces at the end of lines
|
||||
|
||||
## BMAD-METHOD Overview
|
||||
|
||||
BMAD-METHOD is an AI-powered Agile development framework that provides specialized AI agents for software development. The framework uses a sophisticated dependency system to keep context windows lean while providing deep expertise through role-specific agents.
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Build and Validation
|
||||
|
||||
```bash
|
||||
npm run build # Build all web bundles (agents and teams)
|
||||
npm run build:agents # Build agent bundles only
|
||||
npm run build:teams # Build team bundles only
|
||||
npm run validate # Validate all configurations
|
||||
npm run format # Format all markdown files with prettier
|
||||
```
|
||||
|
||||
### Development and Testing
|
||||
|
||||
```bash
|
||||
npx bmad-build build # Alternative build command via CLI
|
||||
npx bmad-build list:agents # List all available agents
|
||||
npx bmad-build validate # Validate agent configurations
|
||||
```
|
||||
|
||||
### Installation Commands
|
||||
|
||||
```bash
|
||||
npx bmad-method install # Install stable release (recommended)
|
||||
npx bmad-method@beta install # Install bleeding edge version
|
||||
npx bmad-method@latest install # Explicit stable installation
|
||||
npx bmad-method@latest update # Update stable installation
|
||||
npx bmad-method@beta update # Update bleeding edge installation
|
||||
```
|
||||
|
||||
### Dual Publishing Strategy
|
||||
|
||||
The project uses a dual publishing strategy with automated promotion:
|
||||
|
||||
**Branch Strategy:**
|
||||
- `main` branch: Bleeding edge development, auto-publishes to `@beta` tag
|
||||
- `stable` branch: Production releases, auto-publishes to `@latest` tag
|
||||
|
||||
**Release Promotion:**
|
||||
1. **Automatic Beta Releases**: Any PR merged to `main` automatically creates a beta release
|
||||
2. **Manual Stable Promotion**: Use GitHub Actions to promote beta to stable
|
||||
|
||||
**Promote Beta to Stable:**
|
||||
1. Go to GitHub Actions tab in the repository
|
||||
2. Select "Promote to Stable" workflow
|
||||
3. Click "Run workflow"
|
||||
4. Choose version bump type (patch/minor/major)
|
||||
5. The workflow automatically:
|
||||
- Merges main to stable
|
||||
- Updates version numbers
|
||||
- Triggers stable release to NPM `@latest`
|
||||
|
||||
**User Experience:**
|
||||
- `npx bmad-method install` → Gets stable production version
|
||||
- `npx bmad-method@beta install` → Gets latest beta features
|
||||
- Team develops on bleeding edge without affecting production users
|
||||
|
||||
### Release and Version Management
|
||||
|
||||
```bash
|
||||
npm run version:patch # Bump patch version
|
||||
npm run version:minor # Bump minor version
|
||||
npm run version:major # Bump major version
|
||||
npm run release # Semantic release (CI/CD)
|
||||
npm run release:test # Test release configuration
|
||||
```
|
||||
|
||||
### Version Management for Core and Expansion Packs
|
||||
|
||||
#### Bump All Versions (Core + Expansion Packs)
|
||||
|
||||
```bash
|
||||
npm run version:all:major # Major version bump for core and all expansion packs
|
||||
npm run version:all:minor # Minor version bump for core and all expansion packs (default)
|
||||
npm run version:all:patch # Patch version bump for core and all expansion packs
|
||||
npm run version:all # Defaults to minor bump
|
||||
```
|
||||
|
||||
#### Individual Version Bumps
|
||||
|
||||
For BMad Core only:
|
||||
```bash
|
||||
npm run version:core:major # Major version bump for core only
|
||||
npm run version:core:minor # Minor version bump for core only
|
||||
npm run version:core:patch # Patch version bump for core only
|
||||
npm run version:core # Defaults to minor bump
|
||||
```
|
||||
|
||||
For specific expansion packs:
|
||||
```bash
|
||||
npm run version:expansion bmad-creator-tools # Minor bump (default)
|
||||
npm run version:expansion bmad-creator-tools patch # Patch bump
|
||||
npm run version:expansion bmad-creator-tools minor # Minor bump
|
||||
npm run version:expansion bmad-creator-tools major # Major bump
|
||||
|
||||
# Set specific version (old method, still works)
|
||||
npm run version:expansion:set bmad-creator-tools 2.0.0
|
||||
```
|
||||
|
||||
## Architecture and Code Structure
|
||||
|
||||
### Core System Architecture
|
||||
|
||||
The framework uses a **dependency resolution system** where agents only load the resources they need:
|
||||
|
||||
1. **Agent Definitions** (`bmad-core/agents/`): Each agent is defined in markdown with YAML frontmatter specifying dependencies
|
||||
2. **Dynamic Loading**: The build system (`tools/lib/dependency-resolver.js`) resolves and includes only required resources
|
||||
3. **Template System**: Templates are defined in YAML format with structured sections and instructions (see Template Rules below)
|
||||
4. **Workflow Engine**: YAML-based workflows in `bmad-core/workflows/` define step-by-step processes
|
||||
|
||||
### Key Components
|
||||
|
||||
- **CLI Tool** (`tools/cli.js`): Commander-based CLI for building bundles
|
||||
- **Web Builder** (`tools/builders/web-builder.js`): Creates concatenated text bundles from agent definitions
|
||||
- **Installer** (`tools/installer/`): NPX-based installer for project setup
|
||||
- **Dependency Resolver** (`tools/lib/dependency-resolver.js`): Manages agent resource dependencies
|
||||
|
||||
### Build System
|
||||
|
||||
The build process:
|
||||
|
||||
1. Reads agent/team definitions from `bmad-core/`
|
||||
2. Resolves dependencies using the dependency resolver
|
||||
3. Creates concatenated text bundles in `dist/`
|
||||
4. Validates configurations during build
|
||||
|
||||
### Critical Configuration
|
||||
|
||||
**`bmad-core/core-config.yaml`** is the heart of the framework configuration:
|
||||
|
||||
- Defines document locations and expected structure
|
||||
- Specifies which files developers should always load
|
||||
- Enables compatibility with different project structures (V3/V4)
|
||||
- Controls debug logging
|
||||
|
||||
## Development Practices
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. **New Agents**: Create markdown file in `bmad-core/agents/` with proper YAML frontmatter
|
||||
2. **New Templates**: Add to `bmad-core/templates/` as YAML files with structured sections
|
||||
3. **New Workflows**: Create YAML in `bmad-core/workflows/`
|
||||
4. **Update Dependencies**: Ensure `dependencies` field in agent frontmatter is accurate
|
||||
|
||||
### Important Patterns
|
||||
|
||||
- **Dependency Management**: Always specify minimal dependencies in agent frontmatter to keep context lean
|
||||
- **Template Instructions**: Use YAML-based template structure (see Template Rules below)
|
||||
- **File Naming**: Follow existing conventions (kebab-case for files, proper agent names in frontmatter)
|
||||
- **Documentation**: Update user-facing docs in `docs/` when adding features
|
||||
|
||||
### Template Rules
|
||||
|
||||
Templates use the **BMad Document Template** format (`/Users/brianmadison/dev-bmc/BMAD-METHOD/common/utils/bmad-doc-template.md`) with YAML structure:
|
||||
|
||||
1. **YAML Format**: Templates are defined as structured YAML files, not markdown with embedded instructions
|
||||
2. **Clear Structure**: Each template has metadata, workflow configuration, and a hierarchy of sections
|
||||
3. **Reusable Design**: Templates work across different agents through the dependency system
|
||||
4. **Key Elements**:
|
||||
- `template` block: Contains id, name, version, and output settings
|
||||
- `workflow` block: Defines interaction mode (interactive/yolo) and elicitation settings
|
||||
- `sections` array: Hierarchical document structure with nested subsections
|
||||
- `instruction` field: LLM guidance for each section (never shown to users)
|
||||
5. **Advanced Features**:
|
||||
- Variable substitution: `{{variable_name}}` syntax for dynamic content
|
||||
- Conditional sections: `condition` field for optional content
|
||||
- Repeatable sections: `repeatable: true` for multiple instances
|
||||
- Agent permissions: `owner` and `editors` fields for access control
|
||||
6. **Clean Output**: All processing instructions are in YAML fields, ensuring clean document generation
|
||||
|
||||
## Notes for Claude Code
|
||||
|
||||
- The project uses semantic versioning with automated releases via GitHub Actions
|
||||
- All markdown is formatted with Prettier (run `npm run format`)
|
||||
- Expansion packs in `expansion-packs/` provide domain-specific capabilities
|
||||
- NEVER automatically commit or push changes unless explicitly asked by the user
|
||||
- NEVER include Claude Code attribution or co-authorship in commit messages
|
||||
Reference in New Issue
Block a user