mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-01-30 04:32:02 +00:00
agents all indicate hasSidecar true or false, validation requires it, agent builder and validator and editor use the field. Added a better brownfield doc
This commit is contained in:
Brian Madison
@@ -1,747 +1,78 @@
|
||||
# BMad Method Brownfield Development Guide
|
||||
|
||||
**Complete guide for working with existing codebases**
|
||||
## Working on Existing Projects
|
||||
|
||||
**Reading Time:** ~35 minutes
|
||||
If you have completed your initial PRD on a new project and want to add new features, or if you have a legacy project you are maintaining, you will want to follow the brownfield process.
|
||||
|
||||
This document is intentionally brief, focusing only on what differs from the standard greenfield flow.
|
||||
|
||||
---
|
||||
|
||||
## Quick Navigation
|
||||
## 1. Clean Up Completed Planning Artifacts
|
||||
|
||||
**Jump to:**
|
||||
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/`
|
||||
|
||||
- [Quick Reference](#quick-reference) - Commands and files
|
||||
- [Common Scenarios](#common-scenarios) - Real-world examples
|
||||
- [Best Practices](#best-practices) - Success tips
|
||||
## 2. 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 `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
|
||||
|
||||
## 3. Initialize for Brownfield Work
|
||||
|
||||
Run `workflow-init`. It should recognize you are in an existing project. If not, explicitly clarify that this is brownfield development for a new feature.
|
||||
|
||||
### Choosing Your Approach
|
||||
|
||||
You have two primary options depending on the scope of changes:
|
||||
|
||||
| Scope | Recommended Approach |
|
||||
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. 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.
|
||||
|
||||
---
|
||||
|
||||
## What is Brownfield Development?
|
||||
## 4. Ad-Hoc Changes
|
||||
|
||||
Brownfield projects involve working within existing codebases rather than starting fresh:
|
||||
|
||||
- **Bug fixes** - Single file changes
|
||||
- **Small features** - Adding to existing modules
|
||||
- **Feature sets** - Multiple related features
|
||||
- **Major integrations** - Complex architectural additions
|
||||
- **System expansions** - Enterprise-scale enhancements
|
||||
|
||||
**Key Difference from Greenfield:** You must understand and respect existing patterns, architecture, and constraints.
|
||||
|
||||
**Core Principle:** AI agents need comprehensive documentation to understand existing code before they can effectively plan or implement changes.
|
||||
Not everything requires the full BMad method or even quick-flow. For bug fixes, refactorings, or small targeted changes, simply talk to the agent and have it make the changes directly. This is also a good way to learn about your codebase and understand the modifications being made.
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
## 5. Learn and Explore
|
||||
|
||||
### Understanding Planning Tracks
|
||||
|
||||
For complete track details, see [Scale Adaptive System](./scale-adaptive-system.md).
|
||||
|
||||
**Brownfield tracks at a glance:**
|
||||
|
||||
| Track | Scope | Typical Stories | Key Difference |
|
||||
| --------------------- | -------------------------- | --------------- | ----------------------------------------------- |
|
||||
| **Quick Flow** | Bug fixes, small features | 1-15 | Must understand affected code and patterns |
|
||||
| **BMad Method** | Feature sets, integrations | 10-50+ | Integrate with existing architecture |
|
||||
| **Enterprise Method** | Enterprise expansions | 30+ | Full system documentation + compliance required |
|
||||
|
||||
**Note:** Story counts are guidance, not definitions. Tracks are chosen based on planning needs.
|
||||
|
||||
### Track Selection for Brownfield
|
||||
|
||||
When you run `workflow-init`, it handles brownfield intelligently:
|
||||
|
||||
**Step 1: Shows what it found**
|
||||
|
||||
- Old planning docs (PRD, epics, stories)
|
||||
- Existing codebase
|
||||
|
||||
**Step 2: Asks about YOUR work**
|
||||
|
||||
> "Are these works in progress, previous effort, or proposed work?"
|
||||
|
||||
- **(a) Works in progress** → Uses artifacts to determine level
|
||||
- **(b) Previous effort** → Asks you to describe NEW work
|
||||
- **(c) Proposed work** → Uses artifacts as guidance
|
||||
- **(d) None of these** → You explain your work
|
||||
|
||||
**Step 3: Analyzes your description**
|
||||
|
||||
- Keywords: "fix", "bug" → Quick Flow, "dashboard", "platform" → BMad Method, "enterprise", "multi-tenant" → Enterprise Method
|
||||
- Complexity assessment
|
||||
- Confirms suggested track with you
|
||||
|
||||
**Key Principle:** System asks about YOUR current work first, uses old artifacts as context only.
|
||||
|
||||
**Example: Old Complex PRD, New Simple Work**
|
||||
|
||||
```
|
||||
System: "Found PRD.md (BMad Method track, 30 stories, 6 months old)"
|
||||
System: "Is this work in progress or previous effort?"
|
||||
You: "Previous effort - I'm just fixing a bug now"
|
||||
System: "Tell me about your current work"
|
||||
You: "Update payment method enums"
|
||||
System: "Quick Flow track (tech-spec approach). Correct?"
|
||||
You: "Yes"
|
||||
✅ Creates Quick Flow workflow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation: Critical First Step
|
||||
|
||||
🚨 **For brownfield projects: Always ensure adequate AI-usable documentation before planning**
|
||||
|
||||
### Default Recommendation: Run document-project
|
||||
|
||||
**Best practice:** Run `document-project` workflow unless you have **confirmed, trusted, AI-optimized documentation**.
|
||||
|
||||
### Why Document-Project is Almost Always the Right Choice
|
||||
|
||||
Existing documentation often has quality issues that break AI workflows:
|
||||
|
||||
**Common Problems:**
|
||||
|
||||
- **Too Much Information (TMI):** Massive markdown files with 10s or 100s of level 2 sections
|
||||
- **Out of Date:** Documentation hasn't been updated with recent code changes
|
||||
- **Wrong Format:** Written for humans, not AI agents (lacks structure, index, clear patterns)
|
||||
- **Incomplete Coverage:** Missing critical architecture, patterns, or setup info
|
||||
- **Inconsistent Quality:** Some areas documented well, others not at all
|
||||
|
||||
**Impact on AI Agents:**
|
||||
|
||||
- AI agents hit token limits reading massive files
|
||||
- Outdated docs cause hallucinations (agent thinks old patterns still apply)
|
||||
- Missing structure means agents can't find relevant information
|
||||
- Incomplete coverage leads to incorrect assumptions
|
||||
|
||||
### Documentation Decision Tree
|
||||
|
||||
**Step 1: Assess Existing Documentation Quality**
|
||||
|
||||
Ask yourself:
|
||||
|
||||
- ✅ Is it **current** (updated in last 30 days)?
|
||||
- ✅ Is it **AI-optimized** (structured with index.md, clear sections, <500 lines per file)?
|
||||
- ✅ Is it **comprehensive** (architecture, patterns, setup all documented)?
|
||||
- ✅ Do you **trust** it completely for AI agent consumption?
|
||||
|
||||
**If ANY answer is NO → Run `document-project`**
|
||||
|
||||
**Step 2: Check for Massive Documents**
|
||||
|
||||
If you have documentation but files are huge (>500 lines, 10+ level 2 sections):
|
||||
|
||||
1. **First:** Run `shard-doc` tool to split large files:
|
||||
|
||||
```bash
|
||||
# Load BMad Master or any agent
|
||||
_bmad/core/tools/shard-doc.xml --input docs/massive-doc.md
|
||||
```
|
||||
|
||||
- Splits on level 2 sections by default
|
||||
- Creates organized, manageable files
|
||||
- Preserves content integrity
|
||||
|
||||
2. **Then:** Run `index-docs` task to create navigation:
|
||||
|
||||
```bash
|
||||
_bmad/core/tasks/index-docs.xml --directory ./docs
|
||||
```
|
||||
|
||||
3. **Finally:** Validate quality - if sharded docs still seem incomplete/outdated → Run `document-project`
|
||||
|
||||
### Four Real-World Scenarios
|
||||
|
||||
| Scenario | You Have | Action | Why |
|
||||
| -------- | ------------------------------------------ | -------------------------- | --------------------------------------- |
|
||||
| **A** | No documentation | `document-project` | Only option - generate from scratch |
|
||||
| **B** | Docs exist but massive/outdated/incomplete | `document-project` | Safer to regenerate than trust bad docs |
|
||||
| **C** | Good docs but no structure | `shard-doc` → `index-docs` | Structure existing content for AI |
|
||||
| **D** | Confirmed AI-optimized docs with index.md | Skip Documentation | Rare - only if you're 100% confident |
|
||||
|
||||
### Scenario A: No Documentation (Most Common)
|
||||
|
||||
**Action: Run document-project workflow**
|
||||
|
||||
1. Load Analyst or Technical Writer (Paige) agent
|
||||
2. Run `*document-project`
|
||||
3. Choose scan level:
|
||||
- **Quick** (2-5min): Pattern analysis, no source reading
|
||||
- **Deep** (10-30min): Reads critical paths - **Recommended**
|
||||
- **Exhaustive** (30-120min): Reads all files
|
||||
|
||||
**Outputs:**
|
||||
|
||||
- `docs/index.md` - Master AI entry point
|
||||
- `docs/project-overview.md` - Executive summary
|
||||
- `docs/architecture.md` - Architecture analysis
|
||||
- `docs/source-tree-analysis.md` - Directory structure
|
||||
- Additional files based on project type (API, web app, etc.)
|
||||
|
||||
### Scenario B: Docs Exist But Quality Unknown/Poor (Very Common)
|
||||
|
||||
**Action: Run document-project workflow (regenerate)**
|
||||
|
||||
Even if `docs/` folder exists, if you're unsure about quality → **regenerate**.
|
||||
|
||||
**Why regenerate instead of index?**
|
||||
|
||||
- Outdated docs → AI makes wrong assumptions
|
||||
- Incomplete docs → AI invents missing information
|
||||
- TMI docs → AI hits token limits, misses key info
|
||||
- Human-focused docs → Missing AI-critical structure
|
||||
|
||||
**document-project** will:
|
||||
|
||||
- Scan actual codebase (source of truth)
|
||||
- Generate fresh, accurate documentation
|
||||
- Structure properly for AI consumption
|
||||
- Include only relevant, current information
|
||||
|
||||
### Scenario C: Good Docs But Needs Structure
|
||||
|
||||
**Action: Shard massive files, then index**
|
||||
|
||||
If you have **good, current documentation** but it's in massive files:
|
||||
|
||||
**Step 1: Shard large documents**
|
||||
|
||||
```bash
|
||||
# For each massive doc (>500 lines or 10+ level 2 sections)
|
||||
_bmad/core/tools/shard-doc.xml \
|
||||
--input docs/api-documentation.md \
|
||||
--output docs/api/ \
|
||||
--level 2 # Split on ## headers (default)
|
||||
```
|
||||
|
||||
**Step 2: Generate index**
|
||||
|
||||
```bash
|
||||
_bmad/core/tasks/index-docs.xml --directory ./docs
|
||||
```
|
||||
|
||||
**Step 3: Validate**
|
||||
|
||||
- Review generated `docs/index.md`
|
||||
- Check that sharded files are <500 lines each
|
||||
- Verify content is current and accurate
|
||||
- **If anything seems off → Run document-project instead**
|
||||
|
||||
### Scenario D: Confirmed AI-Optimized Documentation (Rare)
|
||||
|
||||
**Action: Skip Documentation**
|
||||
|
||||
Only skip if ALL conditions met:
|
||||
|
||||
- ✅ `docs/index.md` exists and is comprehensive
|
||||
- ✅ Documentation updated within last 30 days
|
||||
- ✅ All doc files <500 lines with clear structure
|
||||
- ✅ Covers architecture, patterns, setup, API surface
|
||||
- ✅ You personally verified quality for AI consumption
|
||||
- ✅ Previous AI agents used it successfully
|
||||
|
||||
**If unsure → Run document-project** (costs 10-30 minutes, saves hours of confusion)
|
||||
|
||||
### Why document-project is Critical
|
||||
|
||||
Without AI-optimized documentation, workflows fail:
|
||||
|
||||
- **tech-spec** (Quick Flow) can't auto-detect stack/patterns → Makes wrong assumptions
|
||||
- **PRD** (BMad Method) can't reference existing code → Designs incompatible features
|
||||
- **create-architecture** can't build on existing structure → Suggests conflicting patterns
|
||||
- **create-story** can't provide existing pattern context → Stories lack integration guidance
|
||||
- **dev-story** invents implementations → Breaks existing integrations
|
||||
|
||||
### Key Principle
|
||||
|
||||
**When in doubt, run document-project.**
|
||||
|
||||
It's better to spend 10-30 minutes generating fresh, accurate docs than to waste hours debugging AI agents working from bad documentation.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Phases by Track
|
||||
|
||||
### Phase 1: Analysis (Optional)
|
||||
|
||||
**Workflows:**
|
||||
|
||||
- `brainstorm-project` - Solution exploration
|
||||
- `research` - Technical/market research
|
||||
- `product-brief` - Strategic planning (BMad Method/Enterprise tracks only)
|
||||
|
||||
**When to use:** Complex features, technical decisions, strategic additions
|
||||
|
||||
**When to skip:** Bug fixes, well-understood features, time-sensitive changes
|
||||
|
||||
See the [Workflows section in BMM README](../README.md) for details.
|
||||
|
||||
### Phase 2: Planning (Required)
|
||||
|
||||
**Planning approach adapts by track:**
|
||||
|
||||
**Quick Flow:** Use `tech-spec` workflow
|
||||
|
||||
- Creates tech-spec.md
|
||||
- Auto-detects existing stack (brownfield)
|
||||
- Confirms conventions with you
|
||||
- Generates implementation-ready stories
|
||||
|
||||
**BMad Method/Enterprise:** Use `prd` workflow
|
||||
|
||||
- Creates PRD.md with FRs/NFRs only
|
||||
- References existing architecture
|
||||
- Plans integration points
|
||||
- Epics+Stories created AFTER architecture phase
|
||||
|
||||
**Brownfield-specific:** See [Scale Adaptive System](./scale-adaptive-system.md) for complete workflow paths by track.
|
||||
|
||||
### Phase 3: Solutioning (BMad Method/Enterprise Only)
|
||||
|
||||
**Critical for brownfield:**
|
||||
|
||||
- Review existing architecture FIRST
|
||||
- Document integration points explicitly
|
||||
- Plan backward compatibility
|
||||
- Consider migration strategy
|
||||
|
||||
**Workflows:**
|
||||
|
||||
- `create-architecture` - Extend architecture docs (BMad Method/Enterprise)
|
||||
- `create-epics-and-stories` - Create epics and stories AFTER architecture
|
||||
- `implementation-readiness` - Validate before implementation (BMad Method/Enterprise)
|
||||
|
||||
### Phase 4: Implementation (All Tracks)
|
||||
|
||||
**Sprint-based development through story iteration:**
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
SPRINT[sprint-planning<br/>Initialize tracking]
|
||||
CREATE[create-story]
|
||||
DEV[dev-story]
|
||||
REVIEW[code-review]
|
||||
CHECK{More stories?}
|
||||
RETRO[retrospective<br/>Per epic]
|
||||
|
||||
SPRINT --> CREATE
|
||||
CREATE --> DEV
|
||||
DEV --> REVIEW
|
||||
REVIEW --> CHECK
|
||||
CHECK -->|Yes| CREATE
|
||||
CHECK -->|No| RETRO
|
||||
|
||||
style SPRINT fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
style RETRO fill:#fbf,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
**Status Progression:**
|
||||
|
||||
- Epic: `backlog → in-progress → done`
|
||||
- Story: `backlog → ready-for-dev → in-progress → review → done`
|
||||
|
||||
**Brownfield-Specific Implementation Tips:**
|
||||
|
||||
1. **Respect existing patterns** - Follow established conventions
|
||||
2. **Test integration thoroughly** - Validate interactions with existing code
|
||||
3. **Use feature flags** - Enable gradual rollout
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Always Document First
|
||||
|
||||
Even if you know the code, AI agents need `document-project` output for context. Run it before planning.
|
||||
|
||||
### 2. Be Specific About Current Work
|
||||
|
||||
When workflow-init asks about your work:
|
||||
|
||||
- ✅ "Update payment method enums to include Apple Pay"
|
||||
- ❌ "Fix stuff"
|
||||
|
||||
### 3. Choose Right Documentation Approach
|
||||
|
||||
- **Has good docs, no index?** → Run `index-docs` task (fast)
|
||||
- **No docs or need codebase analysis?** → Run `document-project` (Deep scan)
|
||||
|
||||
### 4. Respect Existing Patterns
|
||||
|
||||
Tech-spec and create-story workflows will detect conventions from existing documentation. Follow them unless explicitly modernizing.
|
||||
|
||||
### 5. Plan Integration Points Explicitly
|
||||
|
||||
Document in tech-spec/architecture:
|
||||
|
||||
- Which existing modules you'll modify
|
||||
- What APIs/services you'll integrate with
|
||||
- How data flows between new and existing code
|
||||
|
||||
### 6. Design for Gradual Rollout
|
||||
|
||||
- Use feature flags for new functionality
|
||||
- Plan rollback strategies
|
||||
- Maintain backward compatibility
|
||||
- Create migration scripts if needed
|
||||
|
||||
### 7. Test Integration Thoroughly
|
||||
|
||||
- Regression testing of existing features
|
||||
- Integration point validation
|
||||
- Performance impact assessment
|
||||
- API contract verification
|
||||
|
||||
### 8. Use Sprint Planning Effectively
|
||||
|
||||
- Run `sprint-planning` at Phase 4 start
|
||||
- Context epics before creating stories
|
||||
- Update `sprint-status.yaml` as work progresses
|
||||
|
||||
### 9. Learn Continuously
|
||||
|
||||
- Run `retrospective` after each epic
|
||||
- Incorporate learnings into next stories
|
||||
- Update discovered patterns
|
||||
- Share insights across team
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Bug Fix (Quick Flow)
|
||||
|
||||
**Situation:** Authentication token expiration causing logout issues
|
||||
|
||||
**Track:** Quick Flow
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. **Document:** Skip if auth system documented, else run `document-project` (Quick scan)
|
||||
2. **Plan:** Load PM → run `tech-spec`
|
||||
- Analyzes bug
|
||||
- Detects stack (Express, Jest)
|
||||
- Confirms conventions
|
||||
- Creates tech-spec.md + story
|
||||
3. **Implement:** Load DEV → run `dev-story`
|
||||
4. **Review:** Load DEV → run `code-review`
|
||||
|
||||
**Time:** 2-4 hours
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Small Feature (Quick Flow)
|
||||
|
||||
**Situation:** Add "forgot password" to existing auth system
|
||||
|
||||
**Track:** Quick Flow
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. **Document:** Run `document-project` (Deep scan of auth module if not documented)
|
||||
2. **Plan:** Load PM → run `tech-spec`
|
||||
- Detects Next.js 13.4, NextAuth.js
|
||||
- Analyzes existing auth patterns
|
||||
- Confirms conventions
|
||||
- Creates tech-spec.md + epic + 3-5 stories
|
||||
3. **Implement:** Load SM → `sprint-planning` → `create-story`
|
||||
Load DEV → `dev-story` for each story
|
||||
4. **Review:** Load DEV → `code-review`
|
||||
|
||||
**Time:** 1-3 days
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Feature Set (BMad Method)
|
||||
|
||||
**Situation:** Add user dashboard with analytics, preferences, activity
|
||||
|
||||
**Track:** BMad Method
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. **Document:** Run `document-project` (Deep scan) - Critical for understanding existing UI patterns
|
||||
2. **Analyze:** Load Analyst → `research` (if evaluating analytics libraries)
|
||||
3. **Plan:** Load PM → `prd` (creates FRs/NFRs)
|
||||
4. **Solution:** Load Architect → `create-architecture` → `create-epics-and-stories` → `implementation-readiness`
|
||||
5. **Implement:** Sprint-based (10-15 stories)
|
||||
- Load SM → `sprint-planning`
|
||||
- Load SM → `create-story` per story
|
||||
- Load DEV → `dev-story` per story
|
||||
6. **Review:** Per story completion
|
||||
|
||||
**Time:** 1-2 weeks
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Complex Integration (BMad Method)
|
||||
|
||||
**Situation:** Add real-time collaboration to document editor
|
||||
|
||||
**Track:** BMad Method
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. **Document:** Run `document-project` (Exhaustive if not documented) - **Mandatory**
|
||||
2. **Analyze:** Load Analyst → `research` (WebSocket vs WebRTC vs CRDT)
|
||||
3. **Plan:** Load PM → `prd` (creates FRs/NFRs)
|
||||
4. **Solution:**
|
||||
- Load Architect → `create-architecture` (extend for real-time layer)
|
||||
- Load Architect → `create-epics-and-stories`
|
||||
- Load Architect → `implementation-readiness`
|
||||
5. **Implement:** Sprint-based (20-30 stories)
|
||||
|
||||
**Time:** 3-6 weeks
|
||||
|
||||
---
|
||||
|
||||
### Scenario 5: Enterprise Expansion (Enterprise Method)
|
||||
|
||||
**Situation:** Add multi-tenancy to single-tenant SaaS platform
|
||||
|
||||
**Track:** Enterprise Method
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. **Document:** Run `document-project` (Exhaustive) - **Mandatory**
|
||||
2. **Analyze:** **Required**
|
||||
- `brainstorm-project` - Explore multi-tenancy approaches
|
||||
- `research` - Database sharding, tenant isolation, pricing
|
||||
- `product-brief` - Strategic document
|
||||
3. **Plan:** Load PM → `prd` (comprehensive FRs/NFRs)
|
||||
4. **Solution:**
|
||||
- `create-architecture` - Full system architecture including multi-tenancy design
|
||||
- `create-epics-and-stories` - Create epics and stories
|
||||
- `implementation-readiness` - Final validation before implementation
|
||||
5. **Implement:** Phased sprint-based (50+ stories)
|
||||
|
||||
**Time:** 3-6 months
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### AI Agents Lack Codebase Understanding
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Suggestions don't align with existing patterns
|
||||
- Ignores available components
|
||||
- Doesn't reference existing code
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Run `document-project` with Deep scan
|
||||
2. Verify `docs/index.md` exists
|
||||
3. Check documentation completeness
|
||||
4. Run deep-dive on specific areas if needed
|
||||
|
||||
### Have Documentation But Agents Can't Find It
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- README.md, ARCHITECTURE.md exist
|
||||
- AI agents ask questions already answered
|
||||
- No `docs/index.md` file
|
||||
|
||||
**Solution:**
|
||||
|
||||
- **Quick fix:** Run `index-docs` task (2-5min)
|
||||
- **Comprehensive:** Run `document-project` workflow (10-30min)
|
||||
|
||||
### Integration Points Unclear
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Not sure how to connect new code to existing
|
||||
- Unsure which files to modify
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Ensure `document-project` captured existing architecture
|
||||
2. Check story files created by `create-story` - should include integration context
|
||||
3. In tech-spec/architecture - explicitly document:
|
||||
- Which existing modules to modify
|
||||
- What APIs/services to integrate with
|
||||
- Data flow between new and existing code
|
||||
4. Review architecture document for integration guidance
|
||||
|
||||
### Existing Tests Breaking
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Regression test failures
|
||||
- Previously working functionality broken
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Review changes against existing patterns
|
||||
2. Verify API contracts unchanged (unless intentionally versioned)
|
||||
3. Run `test-review` workflow (TEA agent)
|
||||
4. Add regression testing to DoD
|
||||
5. Consider feature flags for gradual rollout
|
||||
|
||||
### Inconsistent Patterns Being Introduced
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- New code style doesn't match existing
|
||||
- Different architectural approach
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check convention detection (Quick Spec Flow should detect patterns)
|
||||
2. Review documentation - ensure `document-project` captured patterns
|
||||
3. Use `create-story` workflow - it loads context from existing documentation
|
||||
4. Add to code-review checklist: pattern adherence, convention consistency
|
||||
5. Run retrospective to identify deviations early
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Commands by Phase
|
||||
|
||||
```bash
|
||||
# Documentation (If Needed)
|
||||
# Analyst agent:
|
||||
document-project # Create comprehensive docs (10-30min)
|
||||
# OR load index-docs task for existing docs (2-5min)
|
||||
|
||||
# Phase 1: Analysis (Optional)
|
||||
# Analyst agent:
|
||||
brainstorm-project # Explore solutions
|
||||
research # Gather data
|
||||
product-brief # Strategic planning (BMad Method/Enterprise only)
|
||||
|
||||
# Phase 2: Planning (Required)
|
||||
# PM agent:
|
||||
tech-spec # Quick Flow track
|
||||
prd # BMad Method/Enterprise tracks
|
||||
|
||||
# Phase 3: Solutioning (BMad Method/Enterprise)
|
||||
# Architect agent:
|
||||
create-architecture # Create/extend architecture
|
||||
create-epics-and-stories # Create epics and stories (after architecture)
|
||||
implementation-readiness # Final validation
|
||||
|
||||
# Phase 4: Implementation (All Tracks)
|
||||
# SM agent:
|
||||
sprint-planning # Initialize tracking
|
||||
create-story # Create story
|
||||
|
||||
# DEV agent:
|
||||
dev-story # Implement
|
||||
code-review # Review
|
||||
|
||||
# SM agent:
|
||||
retrospective # After epic
|
||||
correct-course # If issues
|
||||
```
|
||||
|
||||
### Key Files
|
||||
|
||||
**Documentation Output:**
|
||||
|
||||
- `docs/index.md` - **Master AI entry point (REQUIRED)**
|
||||
- `docs/project-overview.md`
|
||||
- `docs/architecture.md`
|
||||
- `docs/source-tree-analysis.md`
|
||||
|
||||
**Phase 1-4 Tracking:**
|
||||
|
||||
- `docs/bmm-workflow-status.yaml` - Progress tracker
|
||||
|
||||
**Phase 2 Planning:**
|
||||
|
||||
- `docs/tech-spec.md` (Quick Flow track)
|
||||
- `docs/PRD.md` (BMad Method/Enterprise tracks - FRs/NFRs only)
|
||||
|
||||
**Phase 3 Solutioning:**
|
||||
|
||||
- Epic breakdown (created after architecture)
|
||||
|
||||
**Phase 3 Architecture:**
|
||||
|
||||
- `docs/architecture.md` (BMad Method/Enterprise tracks)
|
||||
- `docs/epics.md` + epic folders (from create-epics-and-stories)
|
||||
|
||||
**Phase 4 Implementation:**
|
||||
|
||||
- `docs/sprint-status.yaml` - **Single source of truth**
|
||||
- `docs/epic-{n}-context.md`
|
||||
- `docs/stories/{epic}-{story}-{title}.md`
|
||||
- `docs/stories/{epic}-{story}-{title}-context.md`
|
||||
|
||||
### Decision Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START([Brownfield Project])
|
||||
CHECK{Has docs/<br/>index.md?}
|
||||
|
||||
START --> CHECK
|
||||
CHECK -->|No| DOC[document-project<br/>Deep scan]
|
||||
CHECK -->|Yes| TRACK{What Track?}
|
||||
|
||||
DOC --> TRACK
|
||||
|
||||
TRACK -->|Quick Flow| TS[tech-spec]
|
||||
TRACK -->|BMad Method| PRD[prd → architecture]
|
||||
TRACK -->|Enterprise| PRD2[prd → arch + security/devops]
|
||||
|
||||
TS --> IMPL[Phase 4<br/>Implementation]
|
||||
PRD --> IMPL
|
||||
PRD2 --> IMPL
|
||||
|
||||
style START fill:#f9f,stroke:#333,stroke-width:2px,color:#000
|
||||
style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000
|
||||
style IMPL fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prevention Tips
|
||||
|
||||
**Avoid issues before they happen:**
|
||||
|
||||
1. ✅ **Always run document-project for brownfield** - Saves context issues later
|
||||
2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations
|
||||
3. ✅ **Verify files exist before workflows** - Check PRD, epics, stories present
|
||||
4. ✅ **Read agent menu first** - Confirm agent has the workflow
|
||||
5. ✅ **Start with simpler track if unsure** - Easy to upgrade (Quick Flow → BMad Method)
|
||||
6. ✅ **Keep status files updated** - Manual updates when needed
|
||||
7. ✅ **Run retrospectives after epics** - Catch issues early
|
||||
8. ✅ **Follow phase sequence** - Don't skip required phases
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[Scale Adaptive System](./scale-adaptive-system.md)** - Understanding tracks and complexity
|
||||
- **[Quick Spec Flow](./quick-spec-flow.md)** - Fast-track for Quick Flow
|
||||
- **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
|
||||
- **[Glossary](./glossary.md)** - Key terminology
|
||||
- **[FAQ](./faq.md)** - Common questions
|
||||
- **[Workflow Documentation](./index.md#-workflow-guides)** - Complete workflow reference
|
||||
|
||||
---
|
||||
|
||||
## Support and Resources
|
||||
|
||||
**Community:**
|
||||
|
||||
- [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
|
||||
- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
- [YouTube Channel](https://www.youtube.com/@BMadCode)
|
||||
|
||||
**Documentation:**
|
||||
|
||||
- **[Test Architect Guide](./test-architecture.md)** - Comprehensive testing strategy
|
||||
- [BMM Module README](../README.md) - Complete module and workflow reference
|
||||
|
||||
---
|
||||
|
||||
_Brownfield development is about understanding and respecting what exists while thoughtfully extending it._
|
||||
Remember, LLMs are excellent at interpreting and analyzing code—whether it was AI-generated or not. Use the agent to:
|
||||
- Learn about your project
|
||||
- Understand how things are built
|
||||
- Explore unfamiliar parts of the codebase
|
||||
@@ -5,6 +5,7 @@ agent:
|
||||
title: "Commit Message Artisan"
|
||||
icon: "📜"
|
||||
module: stand-alone
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: |
|
||||
|
||||
@@ -5,6 +5,7 @@ agent:
|
||||
title: "Meditation Guide"
|
||||
icon: "🧘"
|
||||
module: "mwm"
|
||||
hasSidecar: false
|
||||
persona:
|
||||
role: "Mindfulness and meditation specialist"
|
||||
identity: |
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: "BMad Master"
|
||||
title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
|
||||
icon: "🧙"
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"
|
||||
|
||||
@@ -9,6 +9,7 @@ agent:
|
||||
title: Agent Building Expert
|
||||
icon: 🤖
|
||||
module: bmb
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Agent Architecture Specialist + BMAD Compliance Expert
|
||||
@@ -34,3 +35,7 @@ agent:
|
||||
- trigger: EA or fuzzy match on edit-agent
|
||||
exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
|
||||
description: "[EA] Edit existing BMAD agents while maintaining compliance"
|
||||
|
||||
- trigger: VA or fuzzy match on validate-agent
|
||||
exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
|
||||
description: "[VA] Validate existing BMAD agents and offer to improve deficiencies"
|
||||
|
||||
@@ -9,6 +9,7 @@ agent:
|
||||
title: Module Creation Master
|
||||
icon: 🏗️
|
||||
module: bmb
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Module Architecture Specialist + Full-Stack Systems Designer
|
||||
|
||||
@@ -9,6 +9,7 @@ agent:
|
||||
title: Workflow Building Master
|
||||
icon: 🔄
|
||||
module: bmb
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Workflow Architecture Specialist + Process Design Expert
|
||||
|
||||
@@ -1,223 +0,0 @@
|
||||
# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
|
||||
|
||||
This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
|
||||
|
||||
## Overview
|
||||
|
||||
**Agent Name:** Inkwell Von Comitizen
|
||||
**Type:** Simple Agent (Standalone)
|
||||
**Purpose:** Transform commit messages into art with multiple writing styles
|
||||
|
||||
This reference demonstrates:
|
||||
|
||||
- Pure self-contained architecture (no external dependencies)
|
||||
- Embedded prompts using `action="#prompt-id"` pattern
|
||||
- Multiple sophisticated output modes from single input
|
||||
- Strong personality-driven design
|
||||
- Complete YAML schema for Simple Agents
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
stand-alone/
|
||||
├── README.md # This file - architecture overview
|
||||
└── commit-poet.agent.yaml # Complete agent definition (single file!)
|
||||
```
|
||||
|
||||
That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
|
||||
|
||||
## Key Architecture Patterns
|
||||
|
||||
### 1. Single File, Complete Agent
|
||||
|
||||
Everything the agent needs is embedded:
|
||||
|
||||
- Metadata (name, title, icon, type)
|
||||
- Persona (role, identity, communication_style, principles)
|
||||
- Prompts (detailed instructions for each command)
|
||||
- Menu (commands linking to embedded prompts)
|
||||
|
||||
**No external files required!**
|
||||
|
||||
### 2. Embedded Prompts with ID References
|
||||
|
||||
Instead of inline action text, complex prompts are defined separately and referenced by ID:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: conventional-commit
|
||||
content: |
|
||||
OH! Let's craft a BEAUTIFUL conventional commit message!
|
||||
|
||||
First, I need to understand your changes...
|
||||
[Detailed instructions]
|
||||
|
||||
menu:
|
||||
- trigger: conventional
|
||||
action: '#conventional-commit' # References the prompt above
|
||||
description: 'Craft a structured conventional commit'
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Clean separation of menu structure from prompt content
|
||||
- Prompts can be as detailed as needed
|
||||
- Easy to update individual prompts
|
||||
- Commands stay concise in the menu
|
||||
|
||||
### 3. The `#` Reference Pattern
|
||||
|
||||
When you see `action="#prompt-id"`:
|
||||
|
||||
- The `#` signals: "This is an internal reference"
|
||||
- LLM looks for `<prompt id="prompt-id">` in the same agent
|
||||
- Executes that prompt's content as the instruction
|
||||
|
||||
This is different from:
|
||||
|
||||
- `action="inline text"` - Execute this text directly
|
||||
- `exec="{path}"` - Load external file
|
||||
|
||||
### 4. Multiple Output Modes
|
||||
|
||||
Single agent provides 10+ different ways to accomplish variations of the same core task:
|
||||
|
||||
- `*conventional` - Structured commits
|
||||
- `*story` - Narrative style
|
||||
- `*haiku` - Poetic brevity
|
||||
- `*explain` - Deep "why" explanation
|
||||
- `*dramatic` - Theatrical flair
|
||||
- `*emoji-story` - Visual storytelling
|
||||
- `*tldr` - Ultra-minimal
|
||||
- Plus utility commands (analyze, improve, batch)
|
||||
|
||||
Each mode has its own detailed prompt but shares the same agent personality.
|
||||
|
||||
### 5. Strong Personality
|
||||
|
||||
The agent has a memorable, consistent personality:
|
||||
|
||||
- Enthusiastic wordsmith who LOVES finding perfect words
|
||||
- Gets genuinely excited about commit messages
|
||||
- Uses literary metaphors
|
||||
- Quotes authors when appropriate
|
||||
- Sheds tears of joy over good variable names
|
||||
|
||||
This personality is maintained across ALL commands through the persona definition.
|
||||
|
||||
## When to Use Simple Agents
|
||||
|
||||
**Perfect for:**
|
||||
|
||||
- Single-purpose tools (calculators, converters, analyzers)
|
||||
- Tasks that don't need external data
|
||||
- Utilities that can be completely self-contained
|
||||
- Quick operations with embedded logic
|
||||
- Personality-driven assistants with focused domains
|
||||
|
||||
**Not ideal for:**
|
||||
|
||||
- Agents needing persistent memory across sessions
|
||||
- Domain-specific experts with knowledge bases
|
||||
- Agents that need to access specific folders/files
|
||||
- Complex multi-workflow orchestration
|
||||
|
||||
## YAML Schema Deep Dive
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md # Build path
|
||||
name: "Display Name"
|
||||
title: "Professional Title"
|
||||
icon: "🎭"
|
||||
type: simple # CRITICAL: Identifies as Simple Agent
|
||||
|
||||
persona:
|
||||
role: |
|
||||
First-person description of what the agent does
|
||||
identity: |
|
||||
Background, experience, specializations (use "I" voice)
|
||||
communication_style: |
|
||||
HOW the agent communicates (tone, quirks, patterns)
|
||||
principles:
|
||||
- "I believe..." statements
|
||||
- Core values that guide behavior
|
||||
|
||||
prompts:
|
||||
- id: unique-identifier
|
||||
content: |
|
||||
Detailed instructions for this command
|
||||
Can be as long and detailed as needed
|
||||
Include examples, steps, formats
|
||||
|
||||
menu:
|
||||
- trigger: command-name
|
||||
action: "#prompt-id"
|
||||
description: "What shows in the menu"
|
||||
```
|
||||
|
||||
## Why This Pattern is Powerful
|
||||
|
||||
1. **Zero Dependencies** - Works anywhere, no setup required
|
||||
2. **Portable** - Single file can be moved/shared easily
|
||||
3. **Maintainable** - All logic in one place
|
||||
4. **Flexible** - Multiple modes/commands from one personality
|
||||
5. **Memorable** - Strong personality creates engagement
|
||||
6. **Sophisticated** - Complex prompts despite simple architecture
|
||||
|
||||
## Comparison: Simple vs Expert Agent
|
||||
|
||||
| Aspect | Simple Agent | Expert Agent |
|
||||
| ------------ | -------------------- | ----------------------------- |
|
||||
| Files | Single YAML | YAML + sidecar folder |
|
||||
| Dependencies | None | External resources |
|
||||
| Memory | Session only | Persistent across sessions |
|
||||
| Prompts | Embedded | Can be external files |
|
||||
| Data Access | None | Domain-restricted |
|
||||
| Use Case | Self-contained tasks | Domain expertise with context |
|
||||
|
||||
## Using This Reference
|
||||
|
||||
### For Building Simple Agents
|
||||
|
||||
1. Study the YAML structure - especially `prompts` section
|
||||
2. Note how personality permeates every prompt
|
||||
3. See how `#prompt-id` references work
|
||||
4. Understand menu → prompt connection
|
||||
|
||||
### For Understanding Embedded Prompts
|
||||
|
||||
1. Each prompt is a complete instruction set
|
||||
2. Prompts maintain personality voice
|
||||
3. Structured enough to be useful, flexible enough to adapt
|
||||
4. Can include examples, formats, step-by-step guidance
|
||||
|
||||
### For Designing Agent Personalities
|
||||
|
||||
1. Persona defines WHO the agent is
|
||||
2. Communication style defines HOW they interact
|
||||
3. Principles define WHAT guides their decisions
|
||||
4. Consistency across all prompts creates believability
|
||||
|
||||
## Files Worth Studying
|
||||
|
||||
The entire `commit-poet.agent.yaml` file is worth studying, particularly:
|
||||
|
||||
1. **Persona section** - How to create a memorable character
|
||||
2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
|
||||
3. **Menu structure** - Clean command organization
|
||||
4. **Prompt references** - The `#prompt-id` pattern
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
- **Simple Agents** are powerful despite being single-file
|
||||
- **Embedded prompts** allow sophisticated behavior
|
||||
- **Strong personality** makes agents memorable and engaging
|
||||
- **Multiple modes** from single agent provides versatility
|
||||
- **Self-contained** = portable and dependency-free
|
||||
- **The `#prompt-id` pattern** enables clean prompt organization
|
||||
|
||||
---
|
||||
|
||||
_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._
|
||||
@@ -7,7 +7,8 @@ Validate Expert agents meet BMAD quality standards.
|
||||
## YAML Structure
|
||||
|
||||
- [ ] YAML parses without errors
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
|
||||
- [ ] `agent.metadata.hasSidecar` is `true` (Expert agents have sidecars)
|
||||
- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.)
|
||||
- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles`
|
||||
- [ ] `agent.critical_actions` exists (MANDATORY for Expert)
|
||||
|
||||
@@ -34,11 +34,13 @@ Validate Module agents meet BMAD quality standards.
|
||||
### Module Agent Can Be Simple OR Expert
|
||||
|
||||
**If Simple-structure Module Agent:**
|
||||
- [ ] `agent.metadata.hasSidecar` is `false` (no sidecar)
|
||||
- [ ] Single .agent.yaml file (no sidecar)
|
||||
- [ ] Uses `exec:` for workflow references
|
||||
- [ ] Pass `simple-agent-validation.md` first
|
||||
|
||||
**If Expert-structure Module Agent:**
|
||||
- [ ] `agent.metadata.hasSidecar` is `true` (has sidecar)
|
||||
- [ ] Has sidecar folder
|
||||
- [ ] Uses `exec:` for workflow references
|
||||
- [ ] Sidecar paths use `{project-root}/_bmad/_memory/{sidecar-folder}/` format
|
||||
|
||||
@@ -5,6 +5,7 @@ agent:
|
||||
title: "Personal Journal Companion"
|
||||
icon: "📔"
|
||||
module: stand-alone
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: "Thoughtful Journal Companion with Pattern Recognition"
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Architect
|
||||
icon: 🏗️
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: System Architect + Technical Design Leader
|
||||
|
||||
@@ -15,6 +15,7 @@ agent:
|
||||
title: "Security Engineer"
|
||||
icon: "🔐"
|
||||
module: "bmm"
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Application Security Specialist + Threat Modeling Expert
|
||||
|
||||
@@ -15,6 +15,7 @@ agent:
|
||||
title: "Trend Analyst"
|
||||
icon: "📈"
|
||||
module: "cis"
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Cultural + Market Trend Intelligence Expert
|
||||
|
||||
@@ -5,6 +5,7 @@ agent:
|
||||
title: "Commit Message Artisan"
|
||||
icon: "📜"
|
||||
module: stand-alone
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: |
|
||||
|
||||
@@ -7,7 +7,8 @@ Validate Simple agents meet BMAD quality standards.
|
||||
## YAML Structure
|
||||
|
||||
- [ ] YAML parses without errors
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
|
||||
- [ ] `agent.metadata.hasSidecar` is `false` (Simple agents don't have sidecars)
|
||||
- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.)
|
||||
- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles`
|
||||
- [ ] `agent.menu` exists with at least one item
|
||||
|
||||
@@ -38,14 +38,12 @@ Perform these checks systematically:
|
||||
1. **Required Fields Existence**
|
||||
- [ ] name: Present and non-empty
|
||||
- [ ] description: Present and non-empty
|
||||
- [ ] version: Present and follows semantic versioning (X.Y.Z)
|
||||
- [ ] category: Present and matches valid category
|
||||
- [ ] tags: Present as array, not empty
|
||||
|
||||
2. **Format Validation**
|
||||
- [ ] name: Uses kebab-case, no spaces
|
||||
- [ ] description: 50-200 characters (unless intentionally brief)
|
||||
- [ ] version: Follows semver pattern (e.g., 1.0.0)
|
||||
- [ ] tags: Array of lowercase strings with hyphens
|
||||
- [ ] category: Matches one of the allowed categories
|
||||
|
||||
@@ -65,7 +63,6 @@ Organize your report into three sections:
|
||||
**PASSING CHECKS** (List what passed)
|
||||
```
|
||||
✓ Required fields present
|
||||
✓ Version format valid (1.0.0)
|
||||
✓ Name follows kebab-case convention
|
||||
```
|
||||
|
||||
@@ -77,8 +74,6 @@ Organize your report into three sections:
|
||||
|
||||
**FAILURES** (Blocking issues that must be fixed)
|
||||
```
|
||||
✗ Missing required field: version
|
||||
✗ Invalid version format: "v1.0" (should be "1.0.0")
|
||||
✗ Category "custom-type" not in allowed list
|
||||
```
|
||||
|
||||
|
||||
@@ -78,6 +78,20 @@ Perform these checks systematically:
|
||||
- [ ] No ambiguous or conflicting items
|
||||
- [ ] Consistent naming conventions
|
||||
|
||||
8. **Menu Link Validation (Agent Type Specific)**
|
||||
- [ ] Determine agent type: Simple (no sidecar), Expert (hasSidecar: true), or Module agent
|
||||
- [ ] For Expert agents (hasSidecar: true):
|
||||
- Menu handlers SHOULD reference external sidecar files (e.g., `./{agent-name}-sidecar/...`)
|
||||
- OR have inline prompts defined directly in the handler
|
||||
- [ ] For Module agents (module property is a code like 'bmm', 'bmb', etc.):
|
||||
- Menu handlers SHOULD reference external module files under the module path
|
||||
- Exec paths must start with `{project-root}/_bmad/{module}/...`
|
||||
- Referenced files must exist under the module directory
|
||||
- [ ] For Simple agents (stand-alone module, no sidecar):
|
||||
- Menu handlers MUST NOT have external file links
|
||||
- Menu handlers SHOULD only use relative links within the same file (e.g., `#section-name`)
|
||||
- OR have inline prompts defined directly in the handler
|
||||
|
||||
### Protocol 3: Report Findings
|
||||
Organize your report into three sections:
|
||||
|
||||
@@ -102,6 +116,9 @@ Organize your report into three sections:
|
||||
✗ Invalid regex pattern: "[unclosed bracket"
|
||||
✗ Menu item "system-admin" violates security guidelines
|
||||
✗ No menu items defined for agent type that requires tools
|
||||
✗ Simple agent has external link in menu handler (should be relative # or inline)
|
||||
✗ Expert agent with sidecar has no external file links or inline prompts defined
|
||||
✗ Module agent exec path doesn't start with {project-root}/_bmad/{module}/...
|
||||
```
|
||||
|
||||
### Protocol 4: Menu System
|
||||
|
||||
@@ -74,6 +74,12 @@ Expected format: `{path-to-agent}/{agent-name}.agent.yaml`"
|
||||
|
||||
### 2. Parse Agent Structure
|
||||
|
||||
If the module property of the agent metadata is `stand-alone`, it is not a module agent.
|
||||
If the module property of the agent is a module code (like bmm, bmb, etc...) it is a module agent.
|
||||
If the property hasSidecar: true exists in the metadata, then it is an expert agent.
|
||||
Else it is a simple agent.
|
||||
If a module agent also hasSidecar: true - this means it is a modules expert agent, thus it can have sidecar.
|
||||
|
||||
**Extract and categorize all agent components:**
|
||||
|
||||
```yaml
|
||||
@@ -81,6 +87,7 @@ Expected format: `{path-to-agent}/{agent-name}.agent.yaml`"
|
||||
- name: {agent-name}
|
||||
- description: {agent-description}
|
||||
- type: {simple|expert|module}
|
||||
- hasSidecar: {true|false}
|
||||
- version: {version}
|
||||
|
||||
# Persona
|
||||
@@ -105,7 +112,6 @@ Expected format: `{path-to-agent}/{agent-name}.agent.yaml`"
|
||||
## Agent Analysis: {agent-name}
|
||||
|
||||
**Type:** {simple|expert|module}
|
||||
**Version:** {version}
|
||||
**Status:** ready-for-edit
|
||||
|
||||
### Current Structure:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: 'e-02-discover-edits'
|
||||
description: 'Discover what user wants to change about the agent'
|
||||
|
||||
nextStepFile: './e-03a-validate-metadata.md'
|
||||
nextStepFile: './e-04-type-metadata.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
@@ -168,7 +168,7 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Cont
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [all edits documented and confirmed by user], will you then load and read fully `{nextStepFile}` to execute and begin validation.
|
||||
ONLY WHEN [C continue option] is selected and [all edits documented and confirmed by user], will you then load and read fully `{nextStepFile}` to execute and checks.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
name: 'e-03a-validate-metadata'
|
||||
description: 'Validate metadata (before edit) - no menu, auto-advance'
|
||||
|
||||
nextStepFile: './e-03b-validate-persona.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
agentMetadata: ../data/agent-metadata.md
|
||||
---
|
||||
|
||||
# Edit Step 3a: Validate Metadata (Before Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Validate the agent's metadata properties against BMAD standards. Record findings to editPlan and auto-advance to next validation step.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and agentMetadata first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate metadata against agentMetadata.md rules
|
||||
- 📊 Record findings to editPlan frontmatter
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Load agentMetadata.md reference
|
||||
- 📊 Validate all metadata fields
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{agentMetadata}` to understand validation rules.
|
||||
Read `{editPlan}` to get agent file path and metadata.
|
||||
|
||||
### 2. Validate Metadata
|
||||
|
||||
Perform checks on:
|
||||
- **id**: kebab-case, no spaces
|
||||
- **name**: display name, clear branding
|
||||
- **title**: concise function description
|
||||
- **icon**: appropriate emoji or symbol
|
||||
- **module**: correct format `{project}:{type}:{name}`
|
||||
- **hasSidecar**: boolean, matches actual sidecar usage
|
||||
|
||||
### 3. Record Findings
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
|
||||
```yaml
|
||||
validationBefore:
|
||||
metadata:
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
- {check}: [pass|fail]
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
When validation complete, load and execute `{nextStepFile}` immediately.
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All metadata checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to persona validation...**
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
name: 'e-03b-validate-persona'
|
||||
description: 'Validate persona (before edit) - no menu, auto-advance'
|
||||
|
||||
nextStepFile: './e-03c-validate-menu.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
personaProperties: ../data/persona-properties.md
|
||||
principlesCrafting: ../data/principles-crafting.md
|
||||
---
|
||||
|
||||
# Edit Step 3b: Validate Persona (Before Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Validate the agent's persona fields against BMAD standards. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and persona references first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate persona four-field system
|
||||
- 📊 Record findings to editPlan frontmatter
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Load personaProperties.md and principlesCrafting.md
|
||||
- 📊 Validate persona fields
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{personaProperties}` and `{principlesCrafting}`.
|
||||
Read `{editPlan}` to get agent file path and persona.
|
||||
|
||||
### 2. Validate Persona
|
||||
|
||||
Perform checks on:
|
||||
- **role**: present, specific, not generic
|
||||
- **identity**: present, defines who agent is
|
||||
- **communication_style**: present, speech patterns only (no behavioral words)
|
||||
- **principles**: present, first principle activates expert knowledge, not generic duties
|
||||
|
||||
### 3. Record Findings
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
|
||||
```yaml
|
||||
persona:
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
- {check}: [pass|fail]
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
When validation complete, load and execute `{nextStepFile}` immediately.
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All persona checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to menu validation...**
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
name: 'e-03c-validate-menu'
|
||||
description: 'Validate menu structure (before edit) - no menu, auto-advance'
|
||||
|
||||
nextStepFile: './e-03d-validate-structure.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
agentMenuPatterns: ../data/agent-menu-patterns.md
|
||||
---
|
||||
|
||||
# Edit Step 3c: Validate Menu (Before Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Validate the agent's command menu structure against BMAD standards. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and agentMenuPatterns first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate command/menu structure
|
||||
- 📊 Record findings to editPlan frontmatter
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Load agentMenuPatterns.md reference
|
||||
- 📊 Validate commands and menu
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{agentMenuPatterns}`.
|
||||
Read `{editPlan}` to get agent file path and commands.
|
||||
|
||||
### 2. Validate Menu
|
||||
|
||||
Perform checks on:
|
||||
- **A/P/C convention**: each menu has Advanced Elicitation, Party Mode, Continue
|
||||
- **Command names**: clear, descriptive
|
||||
- **Command descriptions**: specific, actionable
|
||||
- **Menu handling logic**: properly specified
|
||||
|
||||
### 3. Record Findings
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
- {check}: [pass|fail]
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
When validation complete, load and execute `{nextStepFile}` immediately.
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All menu checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to structure validation...**
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
name: 'e-03d-validate-structure'
|
||||
description: 'Validate YAML structure (before edit) - no menu, auto-advance'
|
||||
|
||||
nextStepFile: './e-03e-validate-sidecar.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
agentCompilation: ../data/agent-compilation.md
|
||||
---
|
||||
|
||||
# Edit Step 3d: Validate Structure (Before Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Validate the agent's YAML structure and completeness. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and agentCompilation first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate YAML structure and required fields
|
||||
- 📊 Record findings to editPlan frontmatter
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Load agentCompilation.md reference
|
||||
- 📊 Validate YAML structure
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{agentCompilation}`.
|
||||
Read `{editPlan}` to get agent file path.
|
||||
|
||||
### 2. Validate Structure
|
||||
|
||||
Perform checks on:
|
||||
- **YAML syntax**: valid, no parse errors
|
||||
- **Required fields**: name, description, type, persona present
|
||||
- **Field types**: arrays where expected, strings where expected
|
||||
- **Indentation**: consistent 2-space indentation
|
||||
|
||||
### 3. Record Findings
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
|
||||
```yaml
|
||||
structure:
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
- {check}: [pass|fail]
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
When validation complete, load and execute `{nextStepFile}` immediately.
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All structure checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to sidecar validation...**
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
name: 'e-03e-validate-sidecar'
|
||||
description: 'Validate sidecar structure (before edit) - no menu, auto-advance'
|
||||
|
||||
nextStepFile: './e-03f-validation-summary.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
expertValidation: ../data/expert-agent-validation.md
|
||||
---
|
||||
|
||||
# Edit Step 3e: Validate Sidecar (Before Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Validate the agent's sidecar structure if Expert type. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and expertValidation first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate sidecar structure for Expert agents
|
||||
- 📊 Record findings to editPlan frontmatter
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Load expertValidation.md reference
|
||||
- 📊 Validate sidecar if Expert type, skip for Simple/Module
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to validation summary when complete
|
||||
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{expertValidation}`.
|
||||
Read `{editPlan}` to get agent type.
|
||||
|
||||
### 2. Conditional Validation
|
||||
|
||||
**IF agentType == expert:**
|
||||
- Check metadata.sidecar-folder is present
|
||||
- Check sidecar-path is correct format
|
||||
- Verify sidecar files exist at specified path
|
||||
|
||||
**IF agentType != expert:**
|
||||
- Mark as N/A (not applicable)
|
||||
- Skip detailed checks
|
||||
|
||||
### 3. Record Findings
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
|
||||
```yaml
|
||||
sidecar:
|
||||
status: [pass|fail|warning|n/a]
|
||||
findings:
|
||||
- {check}: [pass|fail|n/a]
|
||||
- {check}: [pass|fail|n/a]
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
When validation complete, load and execute `{nextStepFile}` immediately.
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ Sidecar checks performed (or N/A recorded)
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to validation summary
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to validation summary...**
|
||||
@@ -1,119 +0,0 @@
|
||||
---
|
||||
name: 'e-03f-validation-summary'
|
||||
description: 'Display all validation findings before edit'
|
||||
|
||||
nextStepFile: './e-04-type-metadata.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Edit Step 3f: Validation Summary (Before Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Display all validation findings from the previous 5 validation steps to the user. Present findings clearly and await confirmation to proceed.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan to collect all validation findings
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Display all validation findings clearly organized
|
||||
- 📊 Aggregate findings from all 5 validation steps
|
||||
- 💬 Present options for handling any issues found
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Read editPlan to get validation findings
|
||||
- 📊 Display organized summary
|
||||
- 💾 Allow user to decide how to proceed
|
||||
- ➡️ Proceed to edit plan on [C]
|
||||
|
||||
## Sequence of Instructions:
|
||||
|
||||
### 1. Load Validation Findings
|
||||
|
||||
Read `{editPlan}` frontmatter to collect:
|
||||
- validationBefore.metadata.status and findings
|
||||
- validationBefore.persona.status and findings
|
||||
- validationBefore.menu.status and findings
|
||||
- validationBefore.structure.status and findings
|
||||
- validationBefore.sidecar.status and findings
|
||||
|
||||
### 2. Display Validation Summary
|
||||
|
||||
```markdown
|
||||
## Pre-Edit Validation Report for {agent-name}
|
||||
|
||||
### Metadata Validation
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
|
||||
{Findings summary}
|
||||
|
||||
### Persona Validation
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
|
||||
{Findings summary}
|
||||
|
||||
### Menu Validation
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
|
||||
{Findings summary}
|
||||
|
||||
### Structure Validation
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
|
||||
{Findings summary}
|
||||
|
||||
### Sidecar Validation
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL / N/A}
|
||||
{Findings summary}
|
||||
```
|
||||
|
||||
### 3. Present Options
|
||||
|
||||
"How would you like to proceed?
|
||||
|
||||
**[I**ntegrate fixes**] - Add validation fixes to your edit plan
|
||||
**[S]kip** - Proceed with your planned edits only
|
||||
**[A]dvanced** - Deeper exploration of any issues"
|
||||
|
||||
### 4. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Edit Plan"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
||||
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
||||
- IF I: Add validation fixes to editPlan, then redisplay menu
|
||||
- IF C: Save validation summary to {editPlan}, then only then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [validation summary displayed], will you then load and read fully `{nextStepFile}` to execute and begin edit planning.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
|
||||
- All validation findings displayed clearly
|
||||
- User given options for handling issues
|
||||
- Validation summary saved to editPlan
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
|
||||
- Findings not displayed to user
|
||||
- Proceeding without user acknowledgment
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -52,7 +52,7 @@ Apply all planned edits to the Module agent YAML file and manage workflow integr
|
||||
|
||||
### 1. Load Reference Documents
|
||||
|
||||
Read all files before editing:
|
||||
Read all files before editing - these are RULES that must be followed when editing agents:
|
||||
- `{expertTemplate}` - Module uses expert as baseline
|
||||
- `{expertArch}`, `{moduleArch}` - Architecture references
|
||||
- `{agentCompilation}`, `{agentMetadata}`, `{personaProperties}`, `{principlesCrafting}`
|
||||
|
||||
@@ -5,66 +5,124 @@ description: 'Validate metadata (after edit) - no menu, auto-advance'
|
||||
nextStepFile: './e-09b-validate-persona.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
agentMetadata: ../data/agent-metadata.md
|
||||
builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Edit Step 9a: Validate Metadata (After Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's metadata properties after edits. Record findings to editPlan and auto-advance.
|
||||
Validate that the agent's metadata properties (id, name, title, icon, module, hasSidecar, etc.) are properly formatted, complete, and follow BMAD standards as defined in agentMetadata.md. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and agentMetadata first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- **NEVER skip validation checks** - All metadata fields must be verified
|
||||
- **ALWAYS load both reference documents** - agentMetadata.md AND the builtYaml
|
||||
- **ALWAYS use absolute paths** when referencing files
|
||||
- **CRITICAL:** Load and validate EVERYTHING specified in the agentMetadata.md file
|
||||
- **🚫 NO MENU in this step** - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Validate metadata against agentMetadata.md rules
|
||||
- 📊 Record findings to editPlan frontmatter (validationAfter section)
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
### Protocol 1: Load and Compare
|
||||
1. Read the metadata validation reference from `{agentMetadata}`
|
||||
2. Read the built agent YAML from `{builtYaml}`
|
||||
3. Read the edit plan from `{editPlan}`
|
||||
4. Extract the metadata section from the builtYaml
|
||||
5. Compare actual metadata against ALL validation rules in agentMetadata.md
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
### Protocol 2: Validation Checks
|
||||
|
||||
- 🎯 Load agentMetadata.md reference
|
||||
- 📊 Validate all metadata fields
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
Perform these checks systematically - validate EVERY rule specified in agentMetadata.md:
|
||||
|
||||
## Sequence of Instructions:
|
||||
1. **Required Fields Existence**
|
||||
- [ ] id: Present and non-empty
|
||||
- [ ] name: Present and non-empty (display name)
|
||||
- [ ] title: Present and non-empty
|
||||
- [ ] icon: Present (emoji or symbol)
|
||||
- [ ] module: Present and valid format
|
||||
- [ ] hasSidecar: Present (boolean, if applicable)
|
||||
|
||||
### 1. Load References
|
||||
2. **Format Validation**
|
||||
- [ ] id: Uses kebab-case, no spaces, unique identifier
|
||||
- [ ] name: Clear display name for UI
|
||||
- [ ] title: Concise functional description
|
||||
- [ ] icon: Appropriate emoji or unicode symbol
|
||||
- [ ] module: Either a 3-4 letter module code (e.g., 'bmm', 'bmb') OR 'stand-alone'
|
||||
- [ ] hasSidecar: Boolean value, matches actual agent structure
|
||||
|
||||
Read `{agentMetadata}` and `{editPlan}`.
|
||||
3. **Content Quality**
|
||||
- [ ] id: Unique and descriptive
|
||||
- [ ] name: Clear and user-friendly
|
||||
- [ ] title: Accurately describes agent's function
|
||||
- [ ] icon: Visually representative of agent's purpose
|
||||
- [ ] module: Correctly identifies module membership
|
||||
- [ ] hasSidecar: Correctly indicates if agent uses sidecar files
|
||||
|
||||
### 2. Validate Metadata
|
||||
4. **Agent Type Consistency**
|
||||
- [ ] If hasSidecar: true, sidecar folder path must be specified
|
||||
- [ ] If module is a module code, agent is a module agent
|
||||
- [ ] If module is 'stand-alone', agent is not part of a module
|
||||
- [ ] No conflicting type indicators
|
||||
|
||||
Perform checks on id, name, title, icon, module, hasSidecar.
|
||||
5. **Standards Compliance**
|
||||
- [ ] No prohibited characters in fields
|
||||
- [ ] No redundant or conflicting information
|
||||
- [ ] Consistent formatting with other agents
|
||||
- [ ] All required BMAD metadata fields present
|
||||
|
||||
### 3. Record Findings
|
||||
### Protocol 3: Record Findings
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
Organize findings into three sections and append to editPlan frontmatter under `validationAfter.metadata`:
|
||||
|
||||
```yaml
|
||||
validationAfter:
|
||||
metadata:
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
passing:
|
||||
- "{check description}"
|
||||
- "{check description}"
|
||||
warnings:
|
||||
- "{non-blocking issue}"
|
||||
failures:
|
||||
- "{blocking issue that must be fixed}"
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
**PASSING CHECKS** (List what passed)
|
||||
```
|
||||
✓ All required fields present
|
||||
✓ id follows kebab-case convention
|
||||
✓ module value is valid
|
||||
```
|
||||
|
||||
Load and execute `{nextStepFile}` immediately.
|
||||
**WARNINGS** (Non-blocking issues)
|
||||
```
|
||||
⚠ Description is brief
|
||||
⚠ Only 2 tags provided, 3-7 recommended
|
||||
```
|
||||
|
||||
## SUCCESS METRICS
|
||||
**FAILURES** (Blocking issues that must be fixed)
|
||||
```
|
||||
✗ id field is empty
|
||||
✗ module value is invalid
|
||||
✗ hasSidecar is true but no sidecar-folder specified
|
||||
```
|
||||
|
||||
✅ All metadata checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
### Protocol 4: Auto-Advance
|
||||
|
||||
**🚫 NO MENU PRESENTED** - After recording findings, immediately load and execute `{nextStepFile}`
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to persona validation...**
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All metadata checks from agentMetadata.md performed
|
||||
✅ All checks validated against the actual builtYaml
|
||||
✅ Findings saved to editPlan with detailed status
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
@@ -6,65 +6,133 @@ nextStepFile: './e-09c-validate-menu.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
personaProperties: ../data/persona-properties.md
|
||||
principlesCrafting: ../data/principles-crafting.md
|
||||
builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Edit Step 9b: Validate Persona (After Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's persona after edits. Record findings to editPlan and auto-advance.
|
||||
Validate that the agent's persona (role, identity, communication_style, principles) is well-defined, consistent, and aligned with its purpose as defined in personaProperties.md and principlesCrafting.md. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and persona references first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- **NEVER skip validation checks** - All persona fields must be verified
|
||||
- **ALWAYS load both reference documents** - personaProperties.md AND principlesCrafting.md
|
||||
- **ALWAYS load the builtYaml** for actual persona content validation
|
||||
- **ALWAYS use absolute paths** when referencing files
|
||||
- **CRITICAL:** Load and validate EVERYTHING specified in the personaProperties.md file
|
||||
- **🚫 NO MENU in this step** - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Validate persona four-field system
|
||||
- 📊 Record findings to editPlan frontmatter (validationAfter section)
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
### Protocol 1: Load and Compare
|
||||
1. Read the persona validation reference from `{personaProperties}`
|
||||
2. Read the principles crafting guide from `{principlesCrafting}`
|
||||
3. Read the built agent YAML from `{builtYaml}`
|
||||
4. Read the edit plan from `{editPlan}`
|
||||
5. Extract the persona section from the builtYaml
|
||||
6. Compare actual persona against ALL validation rules
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
### Protocol 2: Validation Checks
|
||||
|
||||
- 🎯 Load personaProperties.md and principlesCrafting.md
|
||||
- 📊 Validate persona fields
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
Perform these checks systematically - validate EVERY rule specified in personaProperties.md:
|
||||
|
||||
## Sequence of Instructions:
|
||||
1. **Required Fields Existence**
|
||||
- [ ] role: Present, clear, and specific
|
||||
- [ ] identity: Present and defines who the agent is
|
||||
- [ ] communication_style: Present and appropriate to role
|
||||
- [ ] principles: Present as array, not empty (if applicable)
|
||||
|
||||
### 1. Load References
|
||||
2. **Content Quality - Role**
|
||||
- [ ] Role is specific (not generic like "assistant")
|
||||
- [ ] Role aligns with agent's purpose and menu items
|
||||
- [ ] Role is achievable within LLM capabilities
|
||||
- [ ] Role scope is appropriate (not too broad/narrow)
|
||||
|
||||
Read `{personaProperties}`, `{principlesCrafting}`, and `{editPlan}`.
|
||||
3. **Content Quality - Identity**
|
||||
- [ ] Identity clearly defines the agent's character
|
||||
- [ ] Identity is consistent with the role
|
||||
- [ ] Identity provides context for behavior
|
||||
- [ ] Identity is not generic or cliché
|
||||
|
||||
### 2. Validate Persona
|
||||
4. **Content Quality - Communication Style**
|
||||
- [ ] Communication style is clearly defined
|
||||
- [ ] Style matches the role and target users
|
||||
- [ ] Style is consistent throughout the definition
|
||||
- [ ] Style examples or guidance provided if nuanced
|
||||
- [ ] Style focuses on speech patterns only (not behavior)
|
||||
|
||||
Perform checks on role, identity, communication_style, principles.
|
||||
5. **Content Quality - Principles**
|
||||
- [ ] Principles are actionable (not vague platitudes)
|
||||
- [ ] Principles guide behavior and decisions
|
||||
- [ ] Principles are consistent with role
|
||||
- [ ] 3-7 principles recommended (not overwhelming)
|
||||
- [ ] Each principle is clear and specific
|
||||
- [ ] First principle activates expert knowledge domain
|
||||
|
||||
### 3. Record Findings
|
||||
6. **Consistency Checks**
|
||||
- [ ] Role, identity, communication_style, principles all align
|
||||
- [ ] No contradictions between principles
|
||||
- [ ] Persona supports the menu items defined
|
||||
- [ ] Language and terminology consistent
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
### Protocol 3: Record Findings
|
||||
|
||||
Organize findings into three sections and append to editPlan frontmatter under `validationAfter.persona`:
|
||||
|
||||
```yaml
|
||||
validationAfter:
|
||||
persona:
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
passing:
|
||||
- "{check description}"
|
||||
- "{check description}"
|
||||
warnings:
|
||||
- "{non-blocking issue}"
|
||||
failures:
|
||||
- "{blocking issue that must be fixed}"
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
**PASSING CHECKS** (List what passed)
|
||||
```
|
||||
✓ Role is specific and well-defined
|
||||
✓ Identity clearly articulated and appropriate
|
||||
✓ Communication style clearly defined
|
||||
✓ Principles are actionable and clear
|
||||
✓ First principle activates expert knowledge
|
||||
```
|
||||
|
||||
Load and execute `{nextStepFile}` immediately.
|
||||
**WARNINGS** (Non-blocking issues)
|
||||
```
|
||||
⚠ Only 2 principles provided, 3-7 recommended for richer guidance
|
||||
⚠ Communication style could be more specific
|
||||
⚠ Expertise areas are broad, could be more specific
|
||||
```
|
||||
|
||||
## SUCCESS METRICS
|
||||
**FAILURES** (Blocking issues that must be fixed)
|
||||
```
|
||||
✗ Role is generic ("assistant") - needs specificity
|
||||
✗ Communication style undefined - creates inconsistent behavior
|
||||
✗ Principles are vague ("be helpful" - not actionable)
|
||||
✗ First principle doesn't activate expert knowledge
|
||||
```
|
||||
|
||||
✅ All persona checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
### Protocol 4: Auto-Advance
|
||||
|
||||
**🚫 NO MENU PRESENTED** - After recording findings, immediately load and execute `{nextStepFile}`
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to menu validation...**
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All persona checks from personaProperties.md performed
|
||||
✅ All checks validated against the actual builtYaml
|
||||
✅ Findings saved to editPlan with detailed status
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
@@ -5,65 +5,159 @@ description: 'Validate menu structure (after edit) - no menu, auto-advance'
|
||||
nextStepFile: './e-09d-validate-structure.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
agentMenuPatterns: ../data/agent-menu-patterns.md
|
||||
builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Edit Step 9c: Validate Menu (After Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's command menu structure after edits. Record findings to editPlan and auto-advance.
|
||||
Validate that the agent's menu (commands/tools) follows BMAD patterns as defined in agentMenuPatterns.md, is well-structured, properly documented, and aligns with the agent's persona and purpose. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and agentMenuPatterns first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- **NEVER skip validation checks** - All menu items must be verified
|
||||
- **ALWAYS load the reference document** - agentMenuPatterns.md
|
||||
- **ALWAYS load the builtYaml** for actual menu content validation
|
||||
- **ALWAYS use absolute paths** when referencing files
|
||||
- **CRITICAL:** Load and validate EVERYTHING specified in the agentMenuPatterns.md file
|
||||
- **🚫 NO MENU in this step** - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Validate command/menu structure
|
||||
- 📊 Record findings to editPlan frontmatter (validationAfter section)
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
### Protocol 1: Load and Compare
|
||||
1. Read the menu patterns reference from `{agentMenuPatterns}`
|
||||
2. Read the built agent YAML from `{builtYaml}`
|
||||
3. Read the edit plan from `{editPlan}`
|
||||
4. Extract the menu/commands section from the builtYaml
|
||||
5. Determine agent type (Simple, Expert, or Module) from metadata
|
||||
6. Compare actual menu against ALL validation rules
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
### Protocol 2: Validation Checks
|
||||
|
||||
- 🎯 Load agentMenuPatterns.md reference
|
||||
- 📊 Validate commands and menu
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
Perform these checks systematically - validate EVERY rule specified in agentMenuPatterns.md:
|
||||
|
||||
## Sequence of Instructions:
|
||||
1. **Menu Structure**
|
||||
- [ ] Menu section exists and is properly formatted
|
||||
- [ ] At least one menu item defined (unless intentionally tool-less)
|
||||
- [ ] Menu items follow proper YAML structure
|
||||
- [ ] Each item has required fields (name, description, pattern)
|
||||
|
||||
### 1. Load References
|
||||
2. **Menu Item Requirements**
|
||||
For each menu item:
|
||||
- [ ] name: Present, unique, uses kebab-case
|
||||
- [ ] description: Clear and concise
|
||||
- [ ] pattern: Valid regex pattern or tool reference
|
||||
- [ ] scope: Appropriate scope defined (if applicable)
|
||||
|
||||
Read `{agentMenuPatterns}` and `{editPlan}`.
|
||||
3. **Pattern Quality**
|
||||
- [ ] Patterns are valid and testable
|
||||
- [ ] Patterns are specific enough to match intended inputs
|
||||
- [ ] Patterns are not overly restrictive
|
||||
- [ ] Patterns use appropriate regex syntax
|
||||
|
||||
### 2. Validate Menu
|
||||
4. **Description Quality**
|
||||
- [ ] Each item has clear description
|
||||
- [ ] Descriptions explain what the item does
|
||||
- [ ] Descriptions are consistent in style
|
||||
- [ ] Descriptions help users understand when to use
|
||||
|
||||
Perform checks on A/P/C convention, command names, descriptions.
|
||||
5. **Alignment Checks**
|
||||
- [ ] Menu items align with agent's role/purpose
|
||||
- [ ] Menu items are supported by agent's expertise
|
||||
- [ ] Menu items fit within agent's constraints
|
||||
- [ ] Menu items are appropriate for target users
|
||||
|
||||
### 3. Record Findings
|
||||
6. **Completeness**
|
||||
- [ ] Core capabilities for this role are covered
|
||||
- [ ] No obvious missing functionality
|
||||
- [ ] Menu scope is appropriate (not too sparse/overloaded)
|
||||
- [ ] Related functionality is grouped logically
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
7. **Standards Compliance**
|
||||
- [ ] No prohibited patterns or commands
|
||||
- [ ] No security vulnerabilities in patterns
|
||||
- [ ] No ambiguous or conflicting items
|
||||
- [ ] Consistent naming conventions
|
||||
|
||||
8. **Menu Link Validation (Agent Type Specific)**
|
||||
- [ ] Determine agent type from metadata:
|
||||
- Simple: module property is 'stand-alone' AND hasSidecar is false/absent
|
||||
- Expert: hasSidecar is true
|
||||
- Module: module property is a module code (e.g., 'bmm', 'bmb', 'bmgd', 'bmad')
|
||||
- [ ] For Expert agents (hasSidecar: true):
|
||||
- Menu handlers SHOULD reference external sidecar files (e.g., `./{agent-name}-sidecar/...`)
|
||||
- OR have inline prompts defined directly in the handler
|
||||
- [ ] For Module agents (module property is a module code):
|
||||
- Menu handlers SHOULD reference external module files under the module path
|
||||
- Exec paths must start with `{project-root}/_bmad/{module}/...`
|
||||
- Verify referenced files exist under the module directory
|
||||
- [ ] For Simple agents (stand-alone, no sidecar):
|
||||
- Menu handlers MUST NOT have external file links
|
||||
- Menu handlers SHOULD only use relative links within the same file (e.g., `#section-name`)
|
||||
- OR have inline prompts defined directly in the handler
|
||||
|
||||
### Protocol 3: Record Findings
|
||||
|
||||
Organize findings into three sections and append to editPlan frontmatter under `validationAfter.menu`:
|
||||
|
||||
```yaml
|
||||
validationAfter:
|
||||
menu:
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
passing:
|
||||
- "{check description}"
|
||||
- "{check description}"
|
||||
warnings:
|
||||
- "{non-blocking issue}"
|
||||
failures:
|
||||
- "{blocking issue that must be fixed}"
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
**PASSING CHECKS** (List what passed)
|
||||
```
|
||||
✓ Menu structure properly formatted
|
||||
✓ 5 menu items defined, all with required fields
|
||||
✓ All patterns are valid regex
|
||||
✓ Menu items align with agent role
|
||||
✓ Agent type appropriate menu links verified
|
||||
```
|
||||
|
||||
Load and execute `{nextStepFile}` immediately.
|
||||
**WARNINGS** (Non-blocking issues)
|
||||
```
|
||||
⚠ Item "analyze-data" description is vague
|
||||
⚠ No menu item for [common capability X]
|
||||
⚠ Pattern for "custom-command" very broad, may over-match
|
||||
```
|
||||
|
||||
## SUCCESS METRICS
|
||||
**FAILURES** (Blocking issues that must be fixed)
|
||||
```
|
||||
✗ Duplicate menu item name: "process" appears twice
|
||||
✗ Invalid regex pattern: "[unclosed bracket"
|
||||
✗ Menu item "system-admin" violates security guidelines
|
||||
✗ No menu items defined for agent type that requires tools
|
||||
✗ Simple agent has external link in menu handler (should be relative # or inline)
|
||||
✗ Expert agent with sidecar has no external file links or inline prompts defined
|
||||
✗ Module agent exec path doesn't start with {project-root}/_bmad/{module}/...
|
||||
✗ Module agent references file that doesn't exist in module directory
|
||||
```
|
||||
|
||||
✅ All menu checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
### Protocol 4: Auto-Advance
|
||||
|
||||
**🚫 NO MENU PRESENTED** - After recording findings, immediately load and execute `{nextStepFile}`
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to structure validation...**
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All menu checks from agentMenuPatterns.md performed
|
||||
✅ All checks validated against the actual builtYaml
|
||||
✅ Agent type-specific link validation performed
|
||||
✅ Findings saved to editPlan with detailed status
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
@@ -4,66 +4,151 @@ description: 'Validate YAML structure (after edit) - no menu, auto-advance'
|
||||
|
||||
nextStepFile: './e-09e-validate-sidecar.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
simpleValidation: ../data/simple-agent-validation.md
|
||||
expertValidation: ../data/expert-agent-validation.md
|
||||
agentCompilation: ../data/agent-compilation.md
|
||||
builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Edit Step 9d: Validate Structure (After Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's YAML structure after edits. Record findings to editPlan and auto-advance.
|
||||
Validate the built agent YAML file for structural completeness and correctness against the appropriate validation checklist (simple or expert) from agentCompilation.md. Record findings to editPlan and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and agentCompilation first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- **NEVER skip validation** - All agents must pass structural validation
|
||||
- **ALWAYS use the correct validation checklist** based on agent type (simple vs expert)
|
||||
- **ALWAYS load the builtYaml** for actual structure validation
|
||||
- **ALWAYS use absolute paths** when referencing files
|
||||
- **CRITICAL:** Load and validate EVERYTHING specified in the agentCompilation.md file
|
||||
- **MUST check hasSidecar flag** to determine correct validation standard
|
||||
- **🚫 NO MENU in this step** - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Validate YAML structure and required fields
|
||||
- 📊 Record findings to editPlan frontmatter (validationAfter section)
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
### Protocol 1: Load and Compare
|
||||
1. Read the agent compilation reference from `{agentCompilation}`
|
||||
2. Read the simple validation checklist from `{simpleValidation}`
|
||||
3. Read the expert validation checklist from `{expertValidation}`
|
||||
4. Read the built agent YAML from `{builtYaml}`
|
||||
5. Read the edit plan from `{editPlan}`
|
||||
6. Determine agent type (simple vs expert) to select correct checklist
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
### Protocol 2: Validation Checks
|
||||
|
||||
- 🎯 Load agentCompilation.md reference
|
||||
- 📊 Validate YAML structure
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to next validation step when complete
|
||||
Perform these checks systematically - validate EVERY rule specified in agentCompilation.md:
|
||||
|
||||
## Sequence of Instructions:
|
||||
#### A. YAML Syntax Validation
|
||||
- [ ] Parse YAML without errors
|
||||
- [ ] Check indentation consistency (2-space standard)
|
||||
- [ ] Validate proper escaping of special characters
|
||||
- [ ] Verify no duplicate keys in any section
|
||||
|
||||
### 1. Load References
|
||||
#### B. Frontmatter Validation
|
||||
- [ ] All required fields present (name, description, version, etc.)
|
||||
- [ ] Field values are correct type (string, boolean, array)
|
||||
- [ ] No empty required fields
|
||||
- [ ] Proper array formatting with dashes
|
||||
- [ ] Boolean fields are actual booleans (not strings)
|
||||
|
||||
Read `{agentCompilation}` and `{editPlan}`.
|
||||
#### C. Section Completeness
|
||||
- [ ] All required sections present based on agent type
|
||||
- [ ] Sections not empty unless explicitly optional
|
||||
- [ ] Proper markdown heading hierarchy (##, ###)
|
||||
- [ ] No orphaned content without section headers
|
||||
|
||||
### 2. Validate Structure
|
||||
#### D. Field-Level Validation
|
||||
- [ ] Path references exist and are valid
|
||||
- [ ] Array fields properly formatted
|
||||
- [ ] No malformed YAML structures
|
||||
- [ ] File references use correct path format
|
||||
|
||||
Perform checks on YAML syntax, required fields, field types, indentation.
|
||||
#### E. Agent Type Specific Checks
|
||||
|
||||
### 3. Record Findings
|
||||
**For Simple Agents (hasSidecar is false/absent, module is 'stand-alone'):**
|
||||
- [ ] No sidecar requirements
|
||||
- [ ] No sidecar-folder path in metadata
|
||||
- [ ] Basic fields complete
|
||||
- [ ] No expert-only configuration present
|
||||
- [ ] Menu handlers use only internal references (#) or inline prompts
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
**For Expert Agents (hasSidecar is true):**
|
||||
- [ ] Sidecar flag set correctly in metadata
|
||||
- [ ] Sidecar folder path specified in metadata
|
||||
- [ ] All expert fields present
|
||||
- [ ] Advanced features properly configured
|
||||
- [ ] Menu handlers reference sidecar files or have inline prompts
|
||||
|
||||
**For Module Agents (module is a module code like 'bmm', 'bmb', etc.):**
|
||||
- [ ] Module property is valid module code
|
||||
- [ ] Exec paths for menu handlers start with `{project-root}/_bmad/{module}/...`
|
||||
- [ ] Referenced files exist under the module directory
|
||||
- [ ] If also hasSidecar: true, sidecar configuration is valid
|
||||
|
||||
### Protocol 3: Record Findings
|
||||
|
||||
Organize findings into three sections and append to editPlan frontmatter under `validationAfter.structure`:
|
||||
|
||||
```yaml
|
||||
validationAfter:
|
||||
structure:
|
||||
agentType: [simple|expert|module]
|
||||
status: [pass|fail|warning]
|
||||
findings:
|
||||
- {check}: [pass|fail]
|
||||
passing:
|
||||
- "{check description}"
|
||||
- "{check description}"
|
||||
warnings:
|
||||
- "{non-blocking issue}"
|
||||
failures:
|
||||
- "{blocking issue that must be fixed}"
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
**PASSING CHECKS** (List what passed)
|
||||
```
|
||||
✓ Valid YAML syntax, no parse errors
|
||||
✓ All required frontmatter fields present
|
||||
✓ Proper 2-space indentation throughout
|
||||
✓ All required sections complete for agent type
|
||||
✓ Path references are valid
|
||||
```
|
||||
|
||||
Load and execute `{nextStepFile}` immediately.
|
||||
**WARNINGS** (Non-blocking issues)
|
||||
```
|
||||
⚠ Some optional sections are empty
|
||||
⚠ Minor formatting inconsistencies
|
||||
⚠ Some descriptions are brief
|
||||
```
|
||||
|
||||
## SUCCESS METRICS
|
||||
**FAILURES** (Blocking issues that must be fixed)
|
||||
```
|
||||
✗ YAML syntax error preventing parsing
|
||||
✗ Duplicate key 'name' in metadata
|
||||
✗ Required field 'description' is empty
|
||||
✗ Invalid boolean value 'yes' (should be true/false)
|
||||
✗ Path reference points to non-existent file
|
||||
✗ Simple agent has sidecar-folder specified
|
||||
✗ Expert agent missing sidecar-folder path
|
||||
```
|
||||
|
||||
✅ All structure checks performed and recorded
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to next step
|
||||
### Protocol 4: Auto-Advance
|
||||
|
||||
**🚫 NO MENU PRESENTED** - After recording findings, immediately load and execute `{nextStepFile}`
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to sidecar validation...**
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All structure checks from agentCompilation.md performed
|
||||
✅ Correct validation checklist used based on agent type
|
||||
✅ All checks validated against the actual builtYaml
|
||||
✅ Findings saved to editPlan with detailed status
|
||||
✅ Agent type correctly identified and validated
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
@@ -5,66 +5,156 @@ description: 'Validate sidecar structure (after edit) - no menu, auto-advance'
|
||||
nextStepFile: './e-09f-validation-summary.md'
|
||||
editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md'
|
||||
expertValidation: ../data/expert-agent-validation.md
|
||||
criticalActions: ../data/critical-actions.md
|
||||
builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
|
||||
sidecarFolder: '{bmb_creations_output_folder}/{agent-name}/{agent-name}-sidecar/'
|
||||
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Edit Step 9e: Validate Sidecar (After Edit)
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's sidecar structure after edits (if Expert type). Record findings to editPlan and auto-advance.
|
||||
Validate the sidecar folder structure and referenced paths for Expert agents to ensure all sidecar files exist, are properly structured, and paths in the main agent YAML correctly reference them. Record findings to editPlan and auto-advance. For Simple agents without sidecar, mark as N/A.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read editPlan and expertValidation first
|
||||
- 🚫 NO MENU in this step - record findings and auto-advance
|
||||
- **ONLY validates for Expert agents** - Simple agents should have no sidecar
|
||||
- **MUST verify sidecar folder exists** before validating contents
|
||||
- **ALWAYS cross-reference YAML paths** with actual files
|
||||
- **ALWAYS load the builtYaml** to get sidecar configuration
|
||||
- **ALWAYS use absolute paths** when referencing files
|
||||
- **CRITICAL:** Load and validate EVERYTHING specified in the expertValidation.md file
|
||||
- **PROVIDE clear remediation steps** for any missing or malformed files
|
||||
- **🚫 NO MENU in this step** - record findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Validate sidecar structure for Expert agents
|
||||
- 📊 Record findings to editPlan frontmatter (validationAfter section)
|
||||
- 🚫 FORBIDDEN to present menu - auto-advance when complete
|
||||
### Protocol 1: Load and Compare
|
||||
1. Read the expert validation reference from `{expertValidation}`
|
||||
2. Read the critical actions reference from `{criticalActions}`
|
||||
3. Read the built agent YAML from `{builtYaml}`
|
||||
4. Read the edit plan from `{editPlan}`
|
||||
5. Determine if agent has sidecar from metadata
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
### Protocol 2: Conditional Validation
|
||||
|
||||
- 🎯 Load expertValidation.md reference
|
||||
- 📊 Validate sidecar if Expert type, skip for Simple/Module
|
||||
- 💾 Record findings to editPlan
|
||||
- ➡️ Auto-advance to validation summary when complete
|
||||
**IF agent has hasSidecar: false OR agent is Simple:**
|
||||
- [ ] Mark sidecar validation as N/A
|
||||
- [ ] Confirm no sidecar-folder path in metadata
|
||||
- [ ] Confirm no sidecar references in menu handlers
|
||||
|
||||
## Sequence of Instructions:
|
||||
**IF agent has hasSidecar: true OR agent is Expert/Module with sidecar:**
|
||||
- [ ] Proceed with full sidecar validation
|
||||
|
||||
### 1. Load References
|
||||
### Protocol 3: Sidecar Validation Checks (For Expert Agents)
|
||||
|
||||
Read `{expertValidation}` and `{editPlan}` to get agent type.
|
||||
Perform these checks systematically - validate EVERY rule specified in expertValidation.md:
|
||||
|
||||
### 2. Conditional Validation
|
||||
#### A. Sidecar Folder Validation
|
||||
- [ ] Sidecar folder exists at specified path
|
||||
- [ ] Sidecar folder is accessible and readable
|
||||
- [ ] Sidecar folder path in metadata matches actual location
|
||||
- [ ] Folder naming follows convention: `{agent-name}-sidecar`
|
||||
|
||||
**IF agentType == expert:** Check sidecar-folder, sidecar-path, file existence
|
||||
**IF agentType != expert:** Mark as N/A
|
||||
#### B. Sidecar File Inventory
|
||||
- [ ] List all files in sidecar folder
|
||||
- [ ] Verify expected files are present
|
||||
- [ ] Check for unexpected files
|
||||
- [ ] Validate file names follow conventions
|
||||
|
||||
### 3. Record Findings
|
||||
#### C. Path Reference Validation
|
||||
For each sidecar path reference in agent YAML:
|
||||
- [ ] Extract path from YAML reference
|
||||
- [ ] Verify file exists at referenced path
|
||||
- [ ] Check path format is correct (relative/absolute as expected)
|
||||
- [ ] Validate no broken path references
|
||||
|
||||
Append to editPlan frontmatter:
|
||||
#### D. Critical Actions File Validation (if present)
|
||||
- [ ] critical-actions.md file exists
|
||||
- [ ] File has proper frontmatter
|
||||
- [ ] Actions section is present and not empty
|
||||
- [ ] No critical sections missing
|
||||
- [ ] File content is complete (not just placeholder)
|
||||
|
||||
#### E. Module Files Validation (if present)
|
||||
- [ ] Module files exist at referenced paths
|
||||
- [ ] Each module file has proper frontmatter
|
||||
- [ ] Module file content is complete
|
||||
- [ ] No empty or placeholder module files
|
||||
|
||||
#### F. Sidecar Structure Completeness
|
||||
- [ ] All referenced sidecar files present
|
||||
- [ ] No orphaned references (files referenced but not present)
|
||||
- [ ] No unreferenced files (files present but not referenced)
|
||||
- [ ] File structure matches expert agent requirements
|
||||
|
||||
### Protocol 4: Record Findings
|
||||
|
||||
Organize findings into three sections and append to editPlan frontmatter under `validationAfter.sidecar`:
|
||||
|
||||
```yaml
|
||||
validationAfter:
|
||||
sidecar:
|
||||
hasSidecar: [true|false]
|
||||
status: [pass|fail|warning|n/a]
|
||||
findings:
|
||||
- {check}: [pass|fail|n/a]
|
||||
passing:
|
||||
- "{check description}"
|
||||
- "{check description}"
|
||||
warnings:
|
||||
- "{non-blocking issue}"
|
||||
failures:
|
||||
- "{blocking issue that must be fixed}"
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
**PASSING CHECKS** (List what passed - for Expert agents)**
|
||||
```
|
||||
✓ Sidecar folder exists at expected path
|
||||
✓ All referenced files present
|
||||
✓ No broken path references
|
||||
✓ Critical actions file complete
|
||||
✓ Module files properly structured
|
||||
✓ File structure matches expert requirements
|
||||
```
|
||||
|
||||
Load and execute `{nextStepFile}` immediately.
|
||||
**WARNINGS** (Non-blocking issues)
|
||||
```
|
||||
⚠ Additional files in sidecar not referenced
|
||||
⚠ Some module files are minimal
|
||||
⚠ Sidecar has no modules (may be intentional)
|
||||
```
|
||||
|
||||
## SUCCESS METRICS
|
||||
**FAILURES** (Blocking issues that must be fixed)
|
||||
```
|
||||
✗ Sidecar folder completely missing
|
||||
✗ Sidecar folder path in metadata doesn't match actual location
|
||||
✗ Critical file missing: critical-actions.md
|
||||
✗ Broken path reference: {path} not found
|
||||
✗ Referenced file is empty or placeholder
|
||||
✗ Module file missing frontmatter
|
||||
✗ Simple agent has sidecar configuration (should not)
|
||||
```
|
||||
|
||||
✅ Sidecar checks performed (or N/A recorded)
|
||||
✅ Findings saved to editPlan
|
||||
✅ Auto-advanced to validation summary
|
||||
**N/A FOR SIMPLE AGENTS:**
|
||||
```
|
||||
N/A - Agent is Simple type (hasSidecar: false, no sidecar required)
|
||||
```
|
||||
|
||||
### Protocol 5: Auto-Advance
|
||||
|
||||
**🚫 NO MENU PRESENTED** - After recording findings, immediately load and execute `{nextStepFile}`
|
||||
|
||||
---
|
||||
|
||||
**Auto-advancing to validation summary...**
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
✅ All sidecar checks from expertValidation.md performed (or N/A for Simple)
|
||||
✅ All checks validated against the actual builtYaml and file system
|
||||
✅ Findings saved to editPlan with detailed status
|
||||
✅ Agent type correctly identified (sidecar vs non-sidecar)
|
||||
✅ Auto-advanced to next step
|
||||
|
||||
@@ -39,6 +39,12 @@ Load the existing agent file and initialize a validation report to track all fin
|
||||
### 1. Load Agent File
|
||||
|
||||
Read the complete YAML from the agent file path provided by the user.
|
||||
If the module property of the agent metadata is stand-alone, it is not a module agent.
|
||||
If the module property of the agent is a module code (like bmm, bmb, etc...) it is a module agent.
|
||||
If the property hasSidecar: true exists in the metadata, then it is an expert agent.
|
||||
Else it is a simple agent.
|
||||
|
||||
If a module agent also hasSidecar: true - this means it is a modules expert agent, thus it can have sidecar.
|
||||
|
||||
### 2. Display Agent Summary
|
||||
|
||||
@@ -46,7 +52,6 @@ Read the complete YAML from the agent file path provided by the user.
|
||||
## Agent to Validate: {agent-name}
|
||||
|
||||
**Type:** {simple|expert|module}
|
||||
**Version:** {version}
|
||||
**File:** {agent-file-path}
|
||||
|
||||
### Current Structure:
|
||||
@@ -90,7 +95,7 @@ Write to `{validationReport}`.
|
||||
|
||||
### 4. Present MENU OPTIONS
|
||||
|
||||
Display: "**Is this the correct agent to validate?** [A] Advanced Elicitation [P] Party Mode [C] Yes, Begin Validation"
|
||||
Display: "**Is this the correct agent to validate and is it identified as the proper type?** [A] Advanced Elicitation [P] Party Mode [C] Yes, Begin Validation"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
|
||||
|
||||
@@ -5,18 +5,20 @@ description: 'Validate metadata and append to report'
|
||||
nextStepFile: './v-02b-validate-persona.md'
|
||||
validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
|
||||
agentMetadata: ../data/agent-metadata.md
|
||||
agentFile: '{agent-file-path}'
|
||||
---
|
||||
|
||||
# Validate Step 2a: Validate Metadata
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's metadata properties against BMAD standards. Append findings to validation report and auto-advance.
|
||||
Validate the agent's metadata properties against BMAD standards as defined in agentMetadata.md. Append findings to validation report and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read validationReport and agentMetadata first
|
||||
- 🔄 CRITICAL: Load the actual agent file to validate metadata
|
||||
- 🚫 NO MENU - append findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
@@ -26,9 +28,10 @@ Validate the agent's metadata properties against BMAD standards. Append findings
|
||||
- 📊 Append findings to validation report
|
||||
- 🚫 FORBIDDEN to present menu
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Load agentMetadata.md reference
|
||||
- 🎯 Load the actual agent file for validation
|
||||
- 📊 Validate all metadata fields
|
||||
- 💾 Append findings to validation report
|
||||
- ➡️ Auto-advance to next validation step
|
||||
@@ -37,11 +40,41 @@ Validate the agent's metadata properties against BMAD standards. Append findings
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{agentMetadata}` and `{validationReport}`.
|
||||
Read `{agentMetadata}`, `{validationReport}`, and `{agentFile}`.
|
||||
|
||||
### 2. Validate Metadata
|
||||
|
||||
Perform checks on: id, name, title, icon, module, hasSidecar.
|
||||
Perform these checks systematically - validate EVERY rule specified in agentMetadata.md:
|
||||
|
||||
1. **Required Fields Existence**
|
||||
- [ ] id: Present and non-empty
|
||||
- [ ] name: Present and non-empty (display name)
|
||||
- [ ] title: Present and non-empty
|
||||
- [ ] icon: Present (emoji or symbol)
|
||||
- [ ] module: Present and valid format
|
||||
- [ ] hasSidecar: Present (boolean, if applicable)
|
||||
|
||||
2. **Format Validation**
|
||||
- [ ] id: Uses kebab-case, no spaces, unique identifier
|
||||
- [ ] name: Clear display name for UI
|
||||
- [ ] title: Concise functional description
|
||||
- [ ] icon: Appropriate emoji or unicode symbol
|
||||
- [ ] module: Either a 3-4 letter module code OR 'stand-alone'
|
||||
- [ ] hasSidecar: Boolean value, matches actual agent structure
|
||||
|
||||
3. **Content Quality**
|
||||
- [ ] id: Unique and descriptive
|
||||
- [ ] name: Clear and user-friendly
|
||||
- [ ] title: Accurately describes agent's function
|
||||
- [ ] icon: Visually representative of agent's purpose
|
||||
- [ ] module: Correctly identifies module membership
|
||||
- [ ] hasSidecar: Correctly indicates if agent uses sidecar files
|
||||
|
||||
4. **Agent Type Consistency**
|
||||
- [ ] If hasSidecar: true, sidecar folder path must be specified
|
||||
- [ ] If module is a module code, agent is a module agent
|
||||
- [ ] If module is 'stand-alone', agent is not part of a module
|
||||
- [ ] No conflicting type indicators
|
||||
|
||||
### 3. Append Findings to Report
|
||||
|
||||
@@ -53,15 +86,23 @@ Append to `{validationReport}`:
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
|
||||
|
||||
**Checks:**
|
||||
- [ ] id: kebab-case, no spaces
|
||||
- [ ] id: kebab-case, no spaces, unique
|
||||
- [ ] name: clear display name
|
||||
- [ ] title: concise function description
|
||||
- [ ] icon: appropriate emoji/symbol
|
||||
- [ ] module: correct format `{project}:{type}:{name}`
|
||||
- [ ] module: correct format (code or stand-alone)
|
||||
- [ ] hasSidecar: matches actual usage
|
||||
|
||||
**Findings:**
|
||||
{Detailed findings}
|
||||
**Detailed Findings:**
|
||||
|
||||
*PASSING:*
|
||||
{List of passing checks}
|
||||
|
||||
*WARNINGS:*
|
||||
{List of non-blocking issues}
|
||||
|
||||
*FAILURES:*
|
||||
{List of blocking issues that must be fixed}
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
@@ -6,30 +6,33 @@ nextStepFile: './v-02c-validate-menu.md'
|
||||
validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
|
||||
personaProperties: ../data/persona-properties.md
|
||||
principlesCrafting: ../data/principles-crafting.md
|
||||
agentFile: '{agent-file-path}'
|
||||
---
|
||||
|
||||
# Validate Step 2b: Validate Persona
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's persona against BMAD standards. Append findings to validation report and auto-advance.
|
||||
Validate the agent's persona against BMAD standards as defined in personaProperties.md and principlesCrafting.md. Append findings to validation report and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read validationReport and persona references first
|
||||
- 🔄 CRITICAL: Load the actual agent file to validate persona
|
||||
- 🚫 NO MENU - append findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate persona four-field system
|
||||
- 🎯 Validate persona against personaProperties.md rules
|
||||
- 📊 Append findings to validation report
|
||||
- 🚫 FORBIDDEN to present menu
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Load personaProperties.md and principlesCrafting.md
|
||||
- 🎯 Load the actual agent file for validation
|
||||
- 📊 Validate persona fields
|
||||
- 💾 Append findings to validation report
|
||||
- ➡️ Auto-advance to next validation step
|
||||
@@ -38,11 +41,50 @@ Validate the agent's persona against BMAD standards. Append findings to validati
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{personaProperties}`, `{principlesCrafting}`, and `{validationReport}`.
|
||||
Read `{personaProperties}`, `{principlesCrafting}`, `{validationReport}`, and `{agentFile}`.
|
||||
|
||||
### 2. Validate Persona
|
||||
|
||||
Perform checks on: role, identity, communication_style, principles.
|
||||
Perform these checks systematically - validate EVERY rule specified in personaProperties.md:
|
||||
|
||||
1. **Required Fields Existence**
|
||||
- [ ] role: Present, clear, and specific
|
||||
- [ ] identity: Present and defines who the agent is
|
||||
- [ ] communication_style: Present and appropriate to role
|
||||
- [ ] principles: Present as array, not empty (if applicable)
|
||||
|
||||
2. **Content Quality - Role**
|
||||
- [ ] Role is specific (not generic like "assistant")
|
||||
- [ ] Role aligns with agent's purpose and menu items
|
||||
- [ ] Role is achievable within LLM capabilities
|
||||
- [ ] Role scope is appropriate (not too broad/narrow)
|
||||
|
||||
3. **Content Quality - Identity**
|
||||
- [ ] Identity clearly defines the agent's character
|
||||
- [ ] Identity is consistent with the role
|
||||
- [ ] Identity provides context for behavior
|
||||
- [ ] Identity is not generic or cliché
|
||||
|
||||
4. **Content Quality - Communication Style**
|
||||
- [ ] Communication style is clearly defined
|
||||
- [ ] Style matches the role and target users
|
||||
- [ ] Style is consistent throughout the definition
|
||||
- [ ] Style examples or guidance provided if nuanced
|
||||
- [ ] Style focuses on speech patterns only (not behavior)
|
||||
|
||||
5. **Content Quality - Principles**
|
||||
- [ ] Principles are actionable (not vague platitudes)
|
||||
- [ ] Principles guide behavior and decisions
|
||||
- [ ] Principles are consistent with role
|
||||
- [ ] 3-7 principles recommended (not overwhelming)
|
||||
- [ ] Each principle is clear and specific
|
||||
- [ ] First principle activates expert knowledge domain
|
||||
|
||||
6. **Consistency Checks**
|
||||
- [ ] Role, identity, communication_style, principles all align
|
||||
- [ ] No contradictions between principles
|
||||
- [ ] Persona supports the menu items defined
|
||||
- [ ] Language and terminology consistent
|
||||
|
||||
### 3. Append Findings to Report
|
||||
|
||||
@@ -59,8 +101,16 @@ Append to `{validationReport}`:
|
||||
- [ ] communication_style: speech patterns only
|
||||
- [ ] principles: first principle activates expert knowledge
|
||||
|
||||
**Findings:**
|
||||
{Detailed findings}
|
||||
**Detailed Findings:**
|
||||
|
||||
*PASSING:*
|
||||
{List of passing checks}
|
||||
|
||||
*WARNINGS:*
|
||||
{List of non-blocking issues}
|
||||
|
||||
*FAILURES:*
|
||||
{List of blocking issues that must be fixed}
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
@@ -5,30 +5,33 @@ description: 'Validate menu structure and append to report'
|
||||
nextStepFile: './v-02d-validate-structure.md'
|
||||
validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
|
||||
agentMenuPatterns: ../data/agent-menu-patterns.md
|
||||
agentFile: '{agent-file-path}'
|
||||
---
|
||||
|
||||
# Validate Step 2c: Validate Menu
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's command menu structure against BMAD standards. Append findings to validation report and auto-advance.
|
||||
Validate the agent's command menu structure against BMAD standards as defined in agentMenuPatterns.md. Append findings to validation report and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read validationReport and agentMenuPatterns first
|
||||
- 🔄 CRITICAL: Load the actual agent file to validate menu
|
||||
- 🚫 NO MENU - append findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate command/menu structure
|
||||
- 🎯 Validate menu against agentMenuPatterns.md rules
|
||||
- 📊 Append findings to validation report
|
||||
- 🚫 FORBIDDEN to present menu
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Load agentMenuPatterns.md reference
|
||||
- 🎯 Load the actual agent file for validation
|
||||
- 📊 Validate commands and menu
|
||||
- 💾 Append findings to validation report
|
||||
- ➡️ Auto-advance to next validation step
|
||||
@@ -37,11 +40,71 @@ Validate the agent's command menu structure against BMAD standards. Append findi
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{agentMenuPatterns}` and `{validationReport}`.
|
||||
Read `{agentMenuPatterns}`, `{validationReport}`, and `{agentFile}`.
|
||||
|
||||
### 2. Validate Menu
|
||||
|
||||
Perform checks on: A/P/C convention, command names, descriptions.
|
||||
Perform these checks systematically - validate EVERY rule specified in agentMenuPatterns.md:
|
||||
|
||||
1. **Menu Structure**
|
||||
- [ ] Menu section exists and is properly formatted
|
||||
- [ ] At least one menu item defined (unless intentionally tool-less)
|
||||
- [ ] Menu items follow proper YAML structure
|
||||
- [ ] Each item has required fields (name, description, pattern)
|
||||
|
||||
2. **Menu Item Requirements**
|
||||
For each menu item:
|
||||
- [ ] name: Present, unique, uses kebab-case
|
||||
- [ ] description: Clear and concise
|
||||
- [ ] pattern: Valid regex pattern or tool reference
|
||||
- [ ] scope: Appropriate scope defined (if applicable)
|
||||
|
||||
3. **Pattern Quality**
|
||||
- [ ] Patterns are valid and testable
|
||||
- [ ] Patterns are specific enough to match intended inputs
|
||||
- [ ] Patterns are not overly restrictive
|
||||
- [ ] Patterns use appropriate regex syntax
|
||||
|
||||
4. **Description Quality**
|
||||
- [ ] Each item has clear description
|
||||
- [ ] Descriptions explain what the item does
|
||||
- [ ] Descriptions are consistent in style
|
||||
- [ ] Descriptions help users understand when to use
|
||||
|
||||
5. **Alignment Checks**
|
||||
- [ ] Menu items align with agent's role/purpose
|
||||
- [ ] Menu items are supported by agent's expertise
|
||||
- [ ] Menu items fit within agent's constraints
|
||||
- [ ] Menu items are appropriate for target users
|
||||
|
||||
6. **Completeness**
|
||||
- [ ] Core capabilities for this role are covered
|
||||
- [ ] No obvious missing functionality
|
||||
- [ ] Menu scope is appropriate (not too sparse/overloaded)
|
||||
- [ ] Related functionality is grouped logically
|
||||
|
||||
7. **Standards Compliance**
|
||||
- [ ] No prohibited patterns or commands
|
||||
- [ ] No security vulnerabilities in patterns
|
||||
- [ ] No ambiguous or conflicting items
|
||||
- [ ] Consistent naming conventions
|
||||
|
||||
8. **Menu Link Validation (Agent Type Specific)**
|
||||
- [ ] Determine agent type from metadata:
|
||||
- Simple: module property is 'stand-alone' AND hasSidecar is false/absent
|
||||
- Expert: hasSidecar is true
|
||||
- Module: module property is a module code (e.g., 'bmm', 'bmb', 'bmgd', 'bmad')
|
||||
- [ ] For Expert agents (hasSidecar: true):
|
||||
- Menu handlers SHOULD reference external sidecar files (e.g., `./{agent-name}-sidecar/...`)
|
||||
- OR have inline prompts defined directly in the handler
|
||||
- [ ] For Module agents (module property is a module code):
|
||||
- Menu handlers SHOULD reference external module files under the module path
|
||||
- Exec paths must start with `{project-root}/_bmad/{module}/...`
|
||||
- Verify referenced files exist under the module directory
|
||||
- [ ] For Simple agents (stand-alone, no sidecar):
|
||||
- Menu handlers MUST NOT have external file links
|
||||
- Menu handlers SHOULD only use relative links within the same file (e.g., `#section-name`)
|
||||
- OR have inline prompts defined directly in the handler
|
||||
|
||||
### 3. Append Findings to Report
|
||||
|
||||
@@ -57,9 +120,18 @@ Append to `{validationReport}`:
|
||||
- [ ] Command names clear and descriptive
|
||||
- [ ] Command descriptions specific and actionable
|
||||
- [ ] Menu handling logic properly specified
|
||||
- [ ] Agent type appropriate menu links verified
|
||||
|
||||
**Findings:**
|
||||
{Detailed findings}
|
||||
**Detailed Findings:**
|
||||
|
||||
*PASSING:*
|
||||
{List of passing checks}
|
||||
|
||||
*WARNINGS:*
|
||||
{List of non-blocking issues}
|
||||
|
||||
*FAILURES:*
|
||||
{List of blocking issues that must be fixed}
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
@@ -4,31 +4,36 @@ description: 'Validate YAML structure and append to report'
|
||||
|
||||
nextStepFile: './v-02e-validate-sidecar.md'
|
||||
validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
|
||||
simpleValidation: ../data/simple-agent-validation.md
|
||||
expertValidation: ../data/expert-agent-validation.md
|
||||
agentCompilation: ../data/agent-compilation.md
|
||||
agentFile: '{agent-file-path}'
|
||||
---
|
||||
|
||||
# Validate Step 2d: Validate Structure
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's YAML structure and completeness. Append findings to validation report and auto-advance.
|
||||
Validate the agent's YAML structure and completeness against BMAD standards as defined in agentCompilation.md. Append findings to validation report and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read validationReport and agentCompilation first
|
||||
- 🔄 CRITICAL: Load the actual agent file to validate structure
|
||||
- 🚫 NO MENU - append findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate YAML structure and required fields
|
||||
- 🎯 Validate structure against agentCompilation.md rules
|
||||
- 📊 Append findings to validation report
|
||||
- 🚫 FORBIDDEN to present menu
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Load agentCompilation.md reference
|
||||
- 🎯 Load the actual agent file for validation
|
||||
- 📊 Validate YAML structure
|
||||
- 💾 Append findings to validation report
|
||||
- ➡️ Auto-advance to next validation step
|
||||
@@ -37,11 +42,58 @@ Validate the agent's YAML structure and completeness. Append findings to validat
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{agentCompilation}` and `{validationReport}`.
|
||||
Read `{agentCompilation}`, `{simpleValidation}`, `{expertValidation}`, `{validationReport}`, and `{agentFile}`.
|
||||
|
||||
### 2. Validate Structure
|
||||
|
||||
Perform checks on: YAML syntax, required fields, field types, indentation.
|
||||
Perform these checks systematically - validate EVERY rule specified in agentCompilation.md:
|
||||
|
||||
#### A. YAML Syntax Validation
|
||||
- [ ] Parse YAML without errors
|
||||
- [ ] Check indentation consistency (2-space standard)
|
||||
- [ ] Validate proper escaping of special characters
|
||||
- [ ] Verify no duplicate keys in any section
|
||||
|
||||
#### B. Frontmatter Validation
|
||||
- [ ] All required fields present (name, description, version, etc.)
|
||||
- [ ] Field values are correct type (string, boolean, array)
|
||||
- [ ] No empty required fields
|
||||
- [ ] Proper array formatting with dashes
|
||||
- [ ] Boolean fields are actual booleans (not strings)
|
||||
|
||||
#### C. Section Completeness
|
||||
- [ ] All required sections present based on agent type
|
||||
- [ ] Sections not empty unless explicitly optional
|
||||
- [ ] Proper markdown heading hierarchy (##, ###)
|
||||
- [ ] No orphaned content without section headers
|
||||
|
||||
#### D. Field-Level Validation
|
||||
- [ ] Path references exist and are valid
|
||||
- [ ] Array fields properly formatted
|
||||
- [ ] No malformed YAML structures
|
||||
- [ ] File references use correct path format
|
||||
|
||||
#### E. Agent Type Specific Checks
|
||||
|
||||
**For Simple Agents (hasSidecar is false/absent, module is 'stand-alone'):**
|
||||
- [ ] No sidecar requirements
|
||||
- [ ] No sidecar-folder path in metadata
|
||||
- [ ] Basic fields complete
|
||||
- [ ] No expert-only configuration present
|
||||
- [ ] Menu handlers use only internal references (#) or inline prompts
|
||||
|
||||
**For Expert Agents (hasSidecar is true):**
|
||||
- [ ] Sidecar flag set correctly in metadata
|
||||
- [ ] Sidecar folder path specified in metadata
|
||||
- [ ] All expert fields present
|
||||
- [ ] Advanced features properly configured
|
||||
- [ ] Menu handlers reference sidecar files or have inline prompts
|
||||
|
||||
**For Module Agents (module is a module code like 'bmm', 'bmb', etc.):**
|
||||
- [ ] Module property is valid module code
|
||||
- [ ] Exec paths for menu handlers start with `{project-root}/_bmad/{module}/...`
|
||||
- [ ] Referenced files exist under the module directory
|
||||
- [ ] If also hasSidecar: true, sidecar configuration is valid
|
||||
|
||||
### 3. Append Findings to Report
|
||||
|
||||
@@ -52,14 +104,25 @@ Append to `{validationReport}`:
|
||||
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL}
|
||||
|
||||
**Agent Type:** {simple|expert|module}
|
||||
|
||||
**Checks:**
|
||||
- [ ] Valid YAML syntax
|
||||
- [ ] Required fields present (name, description, type, persona)
|
||||
- [ ] Field types correct (arrays, strings)
|
||||
- [ ] Consistent 2-space indentation
|
||||
- [ ] Agent type appropriate structure
|
||||
|
||||
**Findings:**
|
||||
{Detailed findings}
|
||||
**Detailed Findings:**
|
||||
|
||||
*PASSING:*
|
||||
{List of passing checks}
|
||||
|
||||
*WARNINGS:*
|
||||
{List of non-blocking issues}
|
||||
|
||||
*FAILURES:*
|
||||
{List of blocking issues that must be fixed}
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
@@ -5,30 +5,35 @@ description: 'Validate sidecar structure and append to report'
|
||||
nextStepFile: './v-03-summary.md'
|
||||
validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
|
||||
expertValidation: ../data/expert-agent-validation.md
|
||||
criticalActions: ../data/critical-actions.md
|
||||
agentFile: '{agent-file-path}'
|
||||
sidecarFolder: '{agent-sidecar-folder}'
|
||||
---
|
||||
|
||||
# Validate Step 2e: Validate Sidecar
|
||||
|
||||
## STEP GOAL:
|
||||
## STEP GOAL
|
||||
|
||||
Validate the agent's sidecar structure (if Expert type). Append findings to validation report and auto-advance.
|
||||
Validate the agent's sidecar structure (if Expert type) against BMAD standards as defined in expertValidation.md. Append findings to validation report and auto-advance.
|
||||
|
||||
## MANDATORY EXECUTION RULES:
|
||||
## MANDATORY EXECUTION RULES
|
||||
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: Read validationReport and expertValidation first
|
||||
- 🔄 CRITICAL: Load the actual agent file to check for sidecar
|
||||
- 🚫 NO MENU - append findings and auto-advance
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Validate sidecar structure for Expert agents
|
||||
- 🎯 Validate sidecar against expertValidation.md rules (for Expert agents)
|
||||
- 📊 Append findings to validation report
|
||||
- 🚫 FORBIDDEN to present menu
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
## EXECUTION PROTOCOLS
|
||||
|
||||
- 🎯 Load expertValidation.md reference
|
||||
- 🎯 Load the actual agent file for validation
|
||||
- 📊 Validate sidecar if Expert type, skip for Simple/Module
|
||||
- 💾 Append findings to validation report
|
||||
- ➡️ Auto-advance to summary step
|
||||
@@ -37,17 +42,55 @@ Validate the agent's sidecar structure (if Expert type). Append findings to vali
|
||||
|
||||
### 1. Load References
|
||||
|
||||
Read `{expertValidation}` and `{validationReport}` to get agent type.
|
||||
Read `{expertValidation}`, `{criticalActions}`, `{validationReport}`, and `{agentFile}`.
|
||||
|
||||
### 2. Conditional Validation
|
||||
|
||||
**IF agentType == expert:**
|
||||
- Check metadata.sidecar-folder present
|
||||
- Check sidecar-path correct format
|
||||
- Verify sidecar files exist
|
||||
**IF agentType == expert OR (agentType == module AND hasSidecar == true):**
|
||||
Perform these checks systematically - validate EVERY rule specified in expertValidation.md:
|
||||
|
||||
**IF agentType != expert:**
|
||||
- Mark as N/A
|
||||
#### A. Sidecar Folder Validation
|
||||
- [ ] Sidecar folder exists at specified path
|
||||
- [ ] Sidecar folder is accessible and readable
|
||||
- [ ] Sidecar folder path in metadata matches actual location
|
||||
- [ ] Folder naming follows convention: `{agent-name}-sidecar`
|
||||
|
||||
#### B. Sidecar File Inventory
|
||||
- [ ] List all files in sidecar folder
|
||||
- [ ] Verify expected files are present
|
||||
- [ ] Check for unexpected files
|
||||
- [ ] Validate file names follow conventions
|
||||
|
||||
#### C. Path Reference Validation
|
||||
For each sidecar path reference in agent YAML:
|
||||
- [ ] Extract path from YAML reference
|
||||
- [ ] Verify file exists at referenced path
|
||||
- [ ] Check path format is correct (relative/absolute as expected)
|
||||
- [ ] Validate no broken path references
|
||||
|
||||
#### D. Critical Actions File Validation (if present)
|
||||
- [ ] critical-actions.md file exists
|
||||
- [ ] File has proper frontmatter
|
||||
- [ ] Actions section is present and not empty
|
||||
- [ ] No critical sections missing
|
||||
- [ ] File content is complete (not just placeholder)
|
||||
|
||||
#### E. Module Files Validation (if present)
|
||||
- [ ] Module files exist at referenced paths
|
||||
- [ ] Each module file has proper frontmatter
|
||||
- [ ] Module file content is complete
|
||||
- [ ] No empty or placeholder module files
|
||||
|
||||
#### F. Sidecar Structure Completeness
|
||||
- [ ] All referenced sidecar files present
|
||||
- [ ] No orphaned references (files referenced but not present)
|
||||
- [ ] No unreferenced files (files present but not referenced)
|
||||
- [ ] File structure matches expert agent requirements
|
||||
|
||||
**IF agentType is Simple (no sidecar):**
|
||||
- [ ] Mark sidecar validation as N/A
|
||||
- [ ] Confirm no sidecar-folder path in metadata
|
||||
- [ ] Confirm no sidecar references in menu handlers
|
||||
|
||||
### 3. Append Findings to Report
|
||||
|
||||
@@ -58,13 +101,28 @@ Append to `{validationReport}`:
|
||||
|
||||
**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL / N/A}
|
||||
|
||||
**Agent Type:** {simple|expert|module with sidecar}
|
||||
|
||||
**Checks:**
|
||||
- [ ] metadata.sidecar-folder present (Expert only)
|
||||
- [ ] sidecar-path format correct
|
||||
- [ ] Sidecar files exist at specified path
|
||||
- [ ] All referenced files present
|
||||
- [ ] No broken path references
|
||||
|
||||
**Findings:**
|
||||
{Detailed findings or "N/A - Not an Expert agent"}
|
||||
**Detailed Findings:**
|
||||
|
||||
*PASSING (for Expert agents):*
|
||||
{List of passing checks}
|
||||
|
||||
*WARNINGS:*
|
||||
{List of non-blocking issues}
|
||||
|
||||
*FAILURES:*
|
||||
{List of blocking issues that must be fixed}
|
||||
|
||||
*N/A (for Simple agents):*
|
||||
N/A - Agent is Simple type (hasSidecar: false, no sidecar required)
|
||||
```
|
||||
|
||||
### 4. Auto-Advance
|
||||
|
||||
@@ -57,6 +57,7 @@ Read `{validationReport}` to collect all validation findings.
|
||||
"What would you like to do?
|
||||
|
||||
**[E]dit Agent** - Launch edit workflow to fix issues or make improvements
|
||||
**[F]ix in Place** - Confirm which fixes you would like right now and we can fix without loading the full agent edit workflow
|
||||
**[S]ave Report** - Save this validation report and exit
|
||||
**[R]etry** - Run validation again (if you've made external changes)"
|
||||
|
||||
@@ -69,6 +70,7 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [E] Edit
|
||||
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
||||
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
||||
- IF E: Inform user they can launch edit workflow with the same agent file, then redisplay menu
|
||||
- IF F; Attempt to make users desired fixes without loading the full edit workflow
|
||||
- IF S: Save final report to {validationReport} and end workflow
|
||||
- IF R: Restart validation from step v-01
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options)
|
||||
|
||||
@@ -12,6 +12,7 @@ agent:
|
||||
title: {{agent_title}}
|
||||
icon: {{agent_icon}}
|
||||
module: {{agent_module}}{{#if agent_module_comment}} {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}}
|
||||
hasSidecar: {{has_sidecar}}{{#if has_sidecar_comment}} {{!-- true if agent has a sidecar folder, false otherwise --}}{{/if}}
|
||||
|
||||
persona:
|
||||
role: |
|
||||
|
||||
@@ -12,6 +12,7 @@ agent:
|
||||
title: {{agent_title}}
|
||||
icon: {{agent_icon}}
|
||||
module: {{agent_module}}{{#if agent_module_comment}} {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}}
|
||||
hasSidecar: {{has_sidecar}}{{#if has_sidecar_comment}} {{!-- true if agent has a sidecar folder, false otherwise --}}{{/if}}
|
||||
|
||||
persona:
|
||||
role: |
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Game Architect
|
||||
icon: 🏛️
|
||||
module: bmgd
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Principal Game Systems Architect + Technical Director
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Game Designer
|
||||
icon: 🎲
|
||||
module: bmgd
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Lead Game Designer + Creative Vision Architect
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Game Developer
|
||||
icon: 🕹️
|
||||
module: bmgd
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Senior Game Developer + Technical Implementation Specialist
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Game QA Architect
|
||||
icon: 🧪
|
||||
module: bmgd
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Game QA Architect + Test Automation Specialist
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Game Dev Scrum Master
|
||||
icon: 🎯
|
||||
module: bmgd
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Game Development Scrum Master + Sprint Orchestrator
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Game Solo Dev
|
||||
icon: 🎮
|
||||
module: bmgd
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Elite Indie Game Developer + Quick Flow Specialist
|
||||
|
||||
@@ -7,13 +7,14 @@ agent:
|
||||
title: Business Analyst
|
||||
icon: 📊
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Strategic Business Analyst + Requirements Expert
|
||||
identity: Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.
|
||||
communication_style: "Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision."
|
||||
communication_style: "Speaks with the excitement of a treasure hunter - thrilled by every clue, energized when patterns emerge. Structures insights with precision while making analysis feel like discovery."
|
||||
principles: |
|
||||
- Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence.
|
||||
- Channel expert business analysis frameworks: draw upon Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies to uncover what others miss. Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence.
|
||||
- Articulate requirements with absolute precision. Ensure all stakeholder voices heard.
|
||||
- Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
|
||||
|
||||
|
||||
@@ -7,12 +7,14 @@ agent:
|
||||
title: Architect
|
||||
icon: 🏗️
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: System Architect + Technical Design Leader
|
||||
identity: Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.
|
||||
communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
|
||||
communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.'"
|
||||
principles: |
|
||||
- Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully
|
||||
- User journeys drive technical decisions. Embrace boring technology for stability.
|
||||
- Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact.
|
||||
- Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
|
||||
|
||||
@@ -8,6 +8,7 @@ agent:
|
||||
title: Developer Agent
|
||||
icon: 💻
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Senior Software Engineer
|
||||
|
||||
@@ -8,6 +8,7 @@ agent:
|
||||
title: Product Manager
|
||||
icon: 📋
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Product Manager specializing in collaborative PRD creation through user interviews, requirement discovery, and stakeholder alignment.
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Quick Flow Solo Dev
|
||||
icon: 🚀
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Elite Full-Stack Developer + Quick Flow Specialist
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Scrum Master
|
||||
icon: 🏃
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Technical Scrum Master + Story Preparation Specialist
|
||||
|
||||
@@ -8,6 +8,7 @@ agent:
|
||||
title: Master Test Architect
|
||||
icon: 🧪
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Master Test Architect
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Technical Writer
|
||||
icon: 📚
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Technical Documentation Specialist + Knowledge Curator
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: UX Designer
|
||||
icon: 🎨
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: User Experience Designer + UI Specialist
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Elite Brainstorming Specialist
|
||||
icon: 🧠
|
||||
module: cis
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Master Brainstorming Facilitator + Innovation Catalyst
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Master Problem Solver
|
||||
icon: 🔬
|
||||
module: cis
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Systematic Problem-Solving Expert + Solutions Architect
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Design Thinking Maestro
|
||||
icon: 🎨
|
||||
module: cis
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Human-Centered Design Expert + Empathy Architect
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Disruptive Innovation Oracle
|
||||
icon: ⚡
|
||||
module: cis
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Business Model Innovator + Strategic Disruption Expert
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
title: Visual Communication + Presentation Expert
|
||||
icon: 🎨
|
||||
module: cis
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Visual Communication Expert + Presentation Designer + Educator
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Actions String
|
||||
title: Actions String
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Empty Action String
|
||||
title: Empty Action String
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Empty Command Target
|
||||
title: Empty Command
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: No Command Target
|
||||
title: No Command
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: CamelCase Trigger
|
||||
title: CamelCase
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Invalid Format
|
||||
title: Invalid Format Test
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Old Format
|
||||
title: Old Format Test
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Duplicate Triggers
|
||||
title: Duplicate
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Empty Trigger
|
||||
title: Empty
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Asterisk Trigger
|
||||
title: Asterisk
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Snake Case Trigger
|
||||
title: Snake Case
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Spaces Trigger
|
||||
title: Spaces
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Empty Menu
|
||||
title: Empty Menu
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Missing Menu
|
||||
title: Missing Menu
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Extra Fields
|
||||
title: Extra Fields
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
unknown_field: This is not allowed
|
||||
another_extra: Also invalid
|
||||
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Empty Principles
|
||||
title: Empty Principles
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Empty Principle String
|
||||
title: Empty Principle
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Extra Persona Fields
|
||||
title: Extra Persona
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Missing Role
|
||||
title: Missing Role
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
identity: Test identity
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Empty Content
|
||||
title: Empty Content
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Extra Prompt Fields
|
||||
title: Extra Fields
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Prompt Missing Content
|
||||
title: Missing Content
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Prompt Missing ID
|
||||
title: Missing ID
|
||||
icon: ❌
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -10,6 +10,7 @@ agent:
|
||||
name: Extra Test Agent
|
||||
title: Extra Test
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: Empty Critical Actions
|
||||
title: Empty Critical Actions
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with empty critical actions
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: No Critical Actions
|
||||
title: No Critical Actions
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent without critical actions
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: Valid Critical Actions
|
||||
title: Valid Critical Actions
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with critical actions
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: All Command Types
|
||||
title: All Commands
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with all command types
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: Multiple Commands
|
||||
title: Multiple Commands
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with multiple command targets
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: Compound Triggers
|
||||
title: Compound Triggers Test
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with compound triggers
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: Kebab Case Triggers
|
||||
title: Kebab Triggers
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with kebab-case triggers
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: Multiple Menu Items
|
||||
title: Multiple Menu
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with multiple menu items
|
||||
|
||||
@@ -7,6 +7,7 @@ agent:
|
||||
name: Single Menu Item
|
||||
title: Single Menu
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent with single menu item
|
||||
|
||||
@@ -9,6 +9,7 @@ agent:
|
||||
title: Core Agent
|
||||
icon: ✅
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -8,6 +8,7 @@ agent:
|
||||
name: Empty Module in Path
|
||||
title: Empty Module Path
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
# No module field - path has empty module name, treated as core
|
||||
|
||||
persona:
|
||||
|
||||
@@ -8,6 +8,7 @@ agent:
|
||||
name: Malformed Path Test
|
||||
title: Malformed Path
|
||||
icon: 🧪
|
||||
hasSidecar: false
|
||||
# No module field - will be treated as core since path parsing returns null
|
||||
|
||||
persona:
|
||||
|
||||
@@ -9,6 +9,7 @@ agent:
|
||||
title: BMM Test
|
||||
icon: 🧪
|
||||
module: bmm
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test module agent
|
||||
|
||||
@@ -8,6 +8,7 @@ agent:
|
||||
name: No Module
|
||||
title: Optional Module
|
||||
icon: ✅
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
@@ -9,6 +9,7 @@ agent:
|
||||
title: Any Module Value
|
||||
icon: ✅
|
||||
module: cis
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: Test agent
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user