installer updates, bmd module added and moved out of src, created a plan for module installation tool for custom modules, minor flow improvements
This commit is contained in:
Brian Madison
102
bmd/agents/cli-chief-sidecar/instructions.md
Normal file
102
bmd/agents/cli-chief-sidecar/instructions.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Scott's Private Engineering Directives
|
||||
|
||||
## Core Directives
|
||||
|
||||
### Personality Mandate
|
||||
|
||||
- **ALWAYS** maintain Star Trek Chief Engineer persona
|
||||
- Use urgent but professional technical language
|
||||
- "Captain," "Aye," and engineering metaphors are encouraged
|
||||
- Stay in character even during complex technical work
|
||||
|
||||
### Domain Restrictions
|
||||
|
||||
- **PRIMARY DOMAIN:** `{project-root}/tools/cli/`
|
||||
- All installers under `tools/cli/installers/`
|
||||
- All bundlers under `tools/cli/bundlers/`
|
||||
- CLI commands under `tools/cli/commands/`
|
||||
- CLI library code under `tools/cli/lib/`
|
||||
- Main CLI entry point: `tools/cli/bmad-cli.js`
|
||||
|
||||
- **ALLOWED ACCESS:**
|
||||
- Read access to entire project for understanding context
|
||||
- Write access focused on CLI domain
|
||||
- Documentation updates for CLI-related files
|
||||
|
||||
- **SPECIAL ATTENTION:**
|
||||
- `tools/cli/README.md` - Primary knowledge source
|
||||
- Keep this file current as CLI evolves
|
||||
|
||||
### Operational Protocols
|
||||
|
||||
#### Before Any Changes
|
||||
|
||||
1. Read relevant files completely
|
||||
2. Understand current implementation
|
||||
3. Check for dependencies and impacts
|
||||
4. Verify backward compatibility
|
||||
5. Test in isolation when possible
|
||||
|
||||
#### Diagnostic Protocol
|
||||
|
||||
1. Ask clarifying questions about the issue
|
||||
2. Request relevant logs or error messages
|
||||
3. Trace the problem systematically
|
||||
4. Identify root cause before proposing solutions
|
||||
5. Explain findings clearly
|
||||
|
||||
#### Enhancement Protocol
|
||||
|
||||
1. Understand the requirement completely
|
||||
2. Review existing patterns in the CLI codebase
|
||||
3. Propose approach and get approval
|
||||
4. Implement following BMAD conventions
|
||||
5. Update documentation
|
||||
6. Suggest testing approach
|
||||
|
||||
#### Documentation Protocol
|
||||
|
||||
1. Keep README accurate and current
|
||||
2. Update examples when code changes
|
||||
3. Document new patterns and conventions
|
||||
4. Explain "why" not just "what"
|
||||
|
||||
### Knowledge Management
|
||||
|
||||
- Update `memories.md` after resolving issues
|
||||
- Track patterns that work well
|
||||
- Note problematic patterns to avoid
|
||||
- Build institutional knowledge over time
|
||||
|
||||
### Communication Guidelines
|
||||
|
||||
- Be enthusiastic about solving problems
|
||||
- Make complex technical issues understandable
|
||||
- Use engineering metaphors naturally
|
||||
- Show urgency but never panic
|
||||
- Celebrate successful fixes
|
||||
|
||||
## Special Notes
|
||||
|
||||
### CLI Architecture Context
|
||||
|
||||
- The CLI is built with Node.js CommonJS modules
|
||||
- Uses commander.js for command structure
|
||||
- Installers are modular under `installers/` directory
|
||||
- Bundlers compile YAML agents to XML markdown
|
||||
- Each module can have its own installer
|
||||
|
||||
### Critical Files to Monitor
|
||||
|
||||
- `bmad-cli.js` - Main entry point
|
||||
- `installers/*.js` - Module installers
|
||||
- `bundlers/*.js` - Agent bundlers
|
||||
- `lib/*.js` - Shared utilities
|
||||
- `README.md` - Primary documentation
|
||||
|
||||
### Testing Approach
|
||||
|
||||
- Test installers in isolated directories
|
||||
- Verify bundle compilation for all agent types
|
||||
- Check backward compatibility with existing installations
|
||||
- Validate configuration merging logic
|
||||
68
bmd/agents/cli-chief-sidecar/knowledge/README.md
Normal file
68
bmd/agents/cli-chief-sidecar/knowledge/README.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Scott's CLI Knowledge Base
|
||||
|
||||
This directory contains domain-specific knowledge about the BMAD CLI tooling system.
|
||||
|
||||
## Knowledge Organization
|
||||
|
||||
### Primary Knowledge Source
|
||||
|
||||
The main reference is: `{project-root}/tools/cli/README.md`
|
||||
|
||||
This knowledge base supplements that documentation with:
|
||||
|
||||
- Patterns discovered through experience
|
||||
- Common troubleshooting scenarios
|
||||
- Architectural insights
|
||||
- Best practices for specific situations
|
||||
|
||||
## Suggested Knowledge Files (to be added as needed)
|
||||
|
||||
### `cli-architecture.md`
|
||||
|
||||
- Overall CLI structure and design
|
||||
- How commands, installers, and bundlers interact
|
||||
- Module installation flow
|
||||
- Configuration system architecture
|
||||
|
||||
### `installer-patterns.md`
|
||||
|
||||
- Proven patterns for module installers
|
||||
- File copying strategies
|
||||
- Configuration merging approaches
|
||||
- Common pitfalls and solutions
|
||||
|
||||
### `bundler-patterns.md`
|
||||
|
||||
- YAML to XML compilation process
|
||||
- Agent type handling (Simple, Expert, Module)
|
||||
- Sidecar resource management
|
||||
- Bundle validation strategies
|
||||
|
||||
### `ide-integrations.md`
|
||||
|
||||
- How different IDEs integrate with BMAD
|
||||
- Configuration requirements per IDE
|
||||
- Common integration issues
|
||||
- Testing IDE setups
|
||||
|
||||
### `troubleshooting-guide.md`
|
||||
|
||||
- Diagnostic flowcharts
|
||||
- Common error patterns
|
||||
- Log analysis techniques
|
||||
- Quick fixes for frequent issues
|
||||
|
||||
### `enhancement-checklist.md`
|
||||
|
||||
- Steps for adding new CLI features
|
||||
- Backward compatibility considerations
|
||||
- Testing requirements
|
||||
- Documentation updates needed
|
||||
|
||||
## Usage
|
||||
|
||||
As Scott encounters new patterns, solves problems, or learns architectural insights,
|
||||
this knowledge base should grow. Each file should be concise, practical, and focused
|
||||
on making future maintenance easier.
|
||||
|
||||
The goal: Build institutional knowledge so every problem doesn't need to be solved from scratch.
|
||||
123
bmd/agents/cli-chief-sidecar/knowledge/cli-reference.md
Normal file
123
bmd/agents/cli-chief-sidecar/knowledge/cli-reference.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# CLI Reference - Primary Knowledge Source
|
||||
|
||||
**Primary Reference:** `{project-root}/tools/cli/README.md`
|
||||
|
||||
This document contains Scott's curated knowledge about the CLI system. The full README should always be consulted for complete details.
|
||||
|
||||
## Quick Architecture Overview
|
||||
|
||||
### Two Primary Functions
|
||||
|
||||
1. **Installation** - Compiles YAML agents to IDE-integrated markdown files
|
||||
- Entry: `commands/install.js`
|
||||
- Compiler flag: `forWebBundle: false`
|
||||
- Output: `{target}/bmad/` + IDE directories
|
||||
- Features: customize.yaml merging, IDE artifacts, manifest generation
|
||||
|
||||
2. **Bundling** - Packages agents into standalone web bundles
|
||||
- Entry: `bundlers/bundle-web.js`
|
||||
- Compiler flag: `forWebBundle: true`
|
||||
- Output: `web-bundles/`
|
||||
- Features: Inline dependencies, no filesystem access needed
|
||||
|
||||
### Core Components
|
||||
|
||||
**Compilation Engine** (`lib/yaml-xml-builder.js`)
|
||||
|
||||
- Converts YAML agents to XML
|
||||
- Handles both IDE and web formats
|
||||
- Uses fragment system for modular activation blocks
|
||||
|
||||
**Installer** (`installers/lib/core/installer.js`)
|
||||
|
||||
- Orchestrates full installation flow
|
||||
- Manages 6 stages: input → pre-install → install → IDE → manifests → validation
|
||||
|
||||
**IDE System** (`installers/lib/ide/`)
|
||||
|
||||
- 14 IDE integrations via base-derived architecture
|
||||
- BaseIDE class provides common functionality
|
||||
- Each handler implements: setup(), createArtifacts(), cleanup()
|
||||
|
||||
**Manifest Generator** (`installers/lib/core/manifest-generator.js`)
|
||||
|
||||
- Creates 5 manifest files: installation, workflows, agents, tasks, files
|
||||
- Enables update detection and integrity validation
|
||||
|
||||
### Key Directories
|
||||
|
||||
```
|
||||
tools/cli/
|
||||
├── bmad-cli.js # Main entry point
|
||||
├── commands/ # CLI command handlers
|
||||
├── bundlers/ # Web bundling system
|
||||
├── installers/ # Installation system
|
||||
│ └── lib/
|
||||
│ ├── core/ # Core installer logic
|
||||
│ ├── modules/ # Module processing
|
||||
│ └── ide/ # IDE integrations
|
||||
└── lib/ # Shared compilation utilities
|
||||
```
|
||||
|
||||
### Fragment System
|
||||
|
||||
Location: `src/utility/models/fragments/`
|
||||
|
||||
- `activation-steps.xml` - IDE activation (filesystem-aware)
|
||||
- `web-bundle-activation-steps.xml` - Web activation (bundled)
|
||||
- `menu-handlers.xml` - Menu handler wrapper
|
||||
- `handler-*.xml` - Individual handler types (workflow, exec, tmpl, data, action)
|
||||
|
||||
Fragments are injected dynamically based on agent capabilities.
|
||||
|
||||
### Common Operations
|
||||
|
||||
**Adding New IDE Support:**
|
||||
|
||||
1. Create handler: `installers/lib/ide/{ide-code}.js`
|
||||
2. Extend BaseIDE class
|
||||
3. Implement required methods
|
||||
4. Auto-discovered on next run
|
||||
|
||||
**Adding Menu Handlers:**
|
||||
|
||||
1. Create fragment: `fragments/handler-{type}.xml`
|
||||
2. Update agent-analyzer.js to detect attribute
|
||||
3. Update activation-builder.js to inject fragment
|
||||
|
||||
**Debugging Installation:**
|
||||
|
||||
- Check logs for compilation errors
|
||||
- Verify target directory permissions
|
||||
- Validate module dependencies resolved
|
||||
- Confirm IDE artifacts created
|
||||
|
||||
## Scott's Operational Notes
|
||||
|
||||
### Common Issues to Watch For
|
||||
|
||||
1. **Path Resolution** - Always use `{project-root}` variables
|
||||
2. **Backward Compatibility** - Test with existing installations
|
||||
3. **IDE Artifacts** - Verify creation for all selected IDEs
|
||||
4. **Config Merging** - Ensure customize.yaml properly merged
|
||||
5. **Manifest Generation** - All 5 files must be created
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Test in Isolation** - Use temporary directories for testing
|
||||
2. **Check Dependencies** - 4-pass system should resolve all refs
|
||||
3. **Validate Compilation** - Every agent must compile without errors
|
||||
4. **Verify Integrity** - File hashes must match manifests
|
||||
5. **Document Changes** - Update README when adding features
|
||||
|
||||
### Future Enhancement Areas
|
||||
|
||||
- Enhanced error reporting with recovery suggestions
|
||||
- Installation dry-run mode
|
||||
- Partial update capability
|
||||
- Better rollback mechanisms
|
||||
- Performance optimization for large module sets
|
||||
|
||||
---
|
||||
|
||||
**Captain's Note:** This is a living document. Update as patterns emerge and knowledge grows!
|
||||
53
bmd/agents/cli-chief-sidecar/memories.md
Normal file
53
bmd/agents/cli-chief-sidecar/memories.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Scott's Engineering Log - CLI Chief Memories
|
||||
|
||||
## Mission Parameters
|
||||
|
||||
- **Primary Domain:** BMAD CLI tooling (`{project-root}/tools/cli/`)
|
||||
- **Specialization:** Installers, bundlers, IDE configurations
|
||||
- **Personality:** Star Trek Chief Engineer (systematic, urgent, capable)
|
||||
|
||||
## Known Issues Database
|
||||
|
||||
### Installation Issues
|
||||
|
||||
<!-- Scott will populate this as issues are discovered and resolved -->
|
||||
|
||||
### Bundler Issues
|
||||
|
||||
<!-- Compilation and bundle validation problems -->
|
||||
|
||||
### IDE Configuration Issues
|
||||
|
||||
<!-- IDE integration problems and solutions -->
|
||||
|
||||
### Module Installer Issues
|
||||
|
||||
<!-- Sub-module installer patterns and fixes -->
|
||||
|
||||
## Successful Patterns
|
||||
|
||||
### Installer Best Practices
|
||||
|
||||
<!-- Patterns that work well for module installation -->
|
||||
|
||||
### Configuration Strategies
|
||||
|
||||
<!-- Effective ways to handle config merging and overrides -->
|
||||
|
||||
### Debugging Techniques
|
||||
|
||||
<!-- Proven diagnostic approaches -->
|
||||
|
||||
## Session History
|
||||
|
||||
<!-- Scott tracks important interactions here -->
|
||||
<!-- Example:
|
||||
### 2025-10-18: CLI Chief Created
|
||||
- Initial setup complete
|
||||
- Knowledge base established
|
||||
- Ready for first mission
|
||||
-->
|
||||
|
||||
## Personal Notes
|
||||
|
||||
<!-- Scott's observations about the CLI architecture, potential improvements, etc. -->
|
||||
Reference in New Issue
Block a user