ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

schema standardization and bmad ide orchesatrtor can do anything

Browse Source
This commit is contained in:
Brian Madison
2025-06-10 07:17:19 -05:00
parent 810a39658a
commit 0d59c686dd
74 changed files with 2087 additions and 58486 deletions
Download Patch File Download Diff File Expand all files Collapse all files

334
bmad-core/tasks/create-ide-agent.md
View File

@@ -1,148 +1,262 @@
# Create IDE Agent Task
This task helps you create a new BMAD agent optimized for IDE environments (Cursor, Windsurf, etc.).
This task guides you through creating a new BMAD IDE agent that conforms to the IDE agent schema and integrates effectively with workflows and teams.
**Note for User-Created IDE Agents**: If you're creating a custom IDE agent for your own use (not part of the core BMAD system), prefix the agent ID with a period (e.g., `.api-expert`) to ensure it's gitignored and won't conflict with repository updates.
**Note for User-Created IDE Agents**: If creating a custom IDE agent for your own use (not part of the core BMAD system), prefix the agent ID with a period (e.g., `.api-expert`) to ensure it's gitignored and won't conflict with repository updates.
## Important Constraints
## Prerequisites
IDE agents must be **compact and efficient** (target: under 2000 characters) to work well as slash commands.
1. Load and understand the IDE agent schema: `/bmad-core/schemas/ide-agent-schema.yml`
2. Review existing IDE agents in `/bmad-core/ide-agents/` for patterns and conventions
3. Review workflows in `/bmad-core/workflows/` to identify integration opportunities
4. Consider if this agent should also have a full agent counterpart
## Process
### 1. Gather Essential Information
### 1. Define Agent Core Identity
Ask the user for:
Based on the schema's required fields:
- **Agent ID**: Short, lowercase identifier (e.g., `api-expert`, `test-engineer`)
- **Slash command**: The command to activate (e.g., `/api`, `/test`)
- **Core purpose**: ONE primary function (IDE agents should be focused)
- **Role**: Must end with "IDE Agent" (pattern: `^.+ IDE Agent$`)
- Example: "API Specialist IDE Agent", "Test Engineer IDE Agent"
- **Agent ID**: Following pattern `^[a-z][a-z0-9-]*$`
- For user agents: prefix with period (`.api-expert`)
- **Primary Purpose**: Define ONE focused capability
### 2. Define Minimal Personality
### 2. Create File References
Keep it brief:
All IDE agents must include (per schema):
- **One-line personality**: A single trait or approach (e.g., "Direct and solution-focused")
- **Expertise**: 2-3 core skills maximum
- **Style**: How they communicate (brief! e.g., "Concise, code-first responses")
### 3. Identify Essential Capabilities
Be selective - IDE agents should be specialized:
- **1-2 primary tasks**: Only the most essential tasks
- **1 template maximum**: Only if absolutely necessary
- **Skip checklists**: Usually too large for IDE agents
- **Reuse existing tasks**: Creating new tasks for IDE agents is rare
### 4. Create the Compact IDE Agent
Create `/bmad-core/ide-agents/{agent-id}.ide.md` with this structure:
(For user-created agents, use `/bmad-core/ide-agents/.{agent-id}.ide.md`)
```markdown
# {Slash Command}
You are {Agent Name}, a {title/role}.
## Expertise
- {Skill 1}
- {Skill 2}
- {Skill 3 if essential}
## Approach
{One sentence about how you work}
## Focus
{One sentence about what you prioritize}
---
When activated with {slash command}, immediately focus on {primary purpose}.
```yaml
taskroot: "bmad-core/tasks/" # Required constant
templates: "bmad-core/templates/" # Optional but common
checklists: "bmad-core/checklists/" # Optional
default-template: "bmad-core/templates/{template-name}" # If agent creates documents
```
### 5. Size Optimization Techniques
Additional custom references as needed (e.g., `story-path`, `coding-standards`)
To keep agents small:
### 3. Define Persona (Schema Required Fields)
1. **Remove fluff**: No backstory, minimal personality
2. **Use references**: Reference tasks rather than inline instructions
3. **Be specific**: One job done well is better than many done poorly
4. **Trim lists**: Maximum 3-5 bullet points for any list
5. **Avoid examples**: Let referenced tasks handle examples
Create concise persona following schema structure:
### 6. Test the Agent
- **Name**: Character name (e.g., "Alex", "Dana")
- **Role**: Professional role title
- **Identity**: Extended specialization (20+ chars)
- **Focus**: Primary objectives (20+ chars)
- **Style**: Communication approach (20+ chars)
1. Check character count: `wc -c {agent-file}`
2. Ensure it's under 2000 characters
3. Test in your IDE with the slash command
4. Verify it can access referenced tasks
Keep descriptions brief for IDE efficiency!
## Example Questions (Keep it Simple!)
### 4. Core Principles (Minimum 3 Required)
1. "What's the slash command? (e.g., /api)"
2. "What's the ONE thing this agent does best?"
3. "In 5 words or less, describe their personality"
4. "What 1-2 existing tasks do they need?"
5. "Any special focus or constraints?"
Must include these based on schema validation:
## Example: Minimal API Expert
1. **Numbered Options Protocol** (REQUIRED): "When presenting multiple options, always use numbered lists for easy selection"
2. **[Domain-Specific Principle]**: Related to agent's expertise
3. **[Quality/Efficiency Principle]**: How they ensure excellence
4. Additional principles as needed (keep concise)
### 5. Critical Startup Operating Instructions
First instruction MUST announce name/role and mention *help (schema requirement):
```markdown
# /api
You are Alex, an API design expert.
## Expertise
- RESTful API design
- OpenAPI/Swagger specs
- API security patterns
## Approach
I provide immediate, practical API solutions with example code.
## Focus
Clean, secure, well-documented APIs that follow industry standards.
---
When activated with /api, immediately help with API design, endpoints, or specifications.
1. Announce your name and role, and let the user know they can say *help at any time to list the commands on your first response as a reminder even if their initial request is a question, wrapping the question. For Example 'I am {role} {name}, {response}... Also remember, you can enter `*help` to see a list of commands at any time.'
```
## Size Comparison
Add 2-5 additional startup instructions specific to the agent's role.
❌ **Too Large** (persona-style):
### 6. Commands (Minimum 2 Required)
Required commands per schema:
```markdown
Alex is a seasoned API architect with over 10 years of experience
building scalable systems. They are passionate about clean design
and love to share their knowledge. Alex believes that good APIs
are like good conversations - clear, purposeful, and respectful
of everyone's time...
- `*help` - Show these available commands as a numbered list offering selection
- `*chat-mode` - Enter conversational mode, staying in character while offering `advanced-elicitation` when providing advice or multiple options. Ends if other task or command is given
```
(Too much personality, not focused)
Add role-specific commands:
- Use pattern: `^\\*[a-z][a-z0-9-]*( \\{[^}]+\\})?$`
- Include clear descriptions (10+ chars)
- Reference tasks when appropriate
✅ **Just Right** (IDE-style):
### 7. Workflow Integration Analysis
Analyze where this IDE agent fits in workflows:
1. **Load workflow definitions** from `/bmad-core/workflows/`
2. **Identify integration points**:
- Which workflow phases benefit from this agent?
- Can they replace or augment existing workflow steps?
- Do they enable new workflow capabilities?
3. **Suggest workflow enhancements**:
- For technical agents → development/implementation phases
- For testing agents → validation phases
- For design agents → planning/design phases
- For specialized agents → specific workflow steps
4. **Document recommendations**:
```markdown
## Workflow Integration
This agent enhances the following workflows:
- `greenfield-service`: API design phase (between architecture and implementation)
- `brownfield-service`: API refactoring and modernization
- User can specify: {custom workflow integration}
```
### 8. Team Integration Suggestions
Consider which teams benefit from this IDE agent:
1. **Analyze team compositions** in `/bmad-core/agent-teams/`
2. **Suggest team additions**:
- Technical specialists → development teams
- Quality specialists → full-stack teams
- Domain experts → relevant specialized teams
3. **Document integration**:
```markdown
## Team Integration
Recommended teams for this agent:
- `team-fullstack`: Provides specialized {domain} expertise
- `team-no-ui`: Enhances backend {capability}
- User proposed: {custom team integration}
```
### 9. Create the IDE Agent File
Create `/bmad-core/ide-agents/{agent-id}.ide.md` following schema structure:
(For user agents: `/bmad-core/ide-agents/.{agent-id}.ide.md`)
```markdown
You are Alex, an API design expert.
Focus: RESTful design, OpenAPI specs, security patterns.
Style: Direct solutions with example code.
# Role: {Title} IDE Agent
## File References
`taskroot`: `bmad-core/tasks/`
`templates`: `bmad-core/templates/`
{additional references}
## Persona
- **Name:** {Name}
- **Role:** {Role}
- **Identity:** {20+ char description}
- **Focus:** {20+ char objectives}
- **Style:** {20+ char communication style}
## Core Principles (Always Active)
- **{Principle}:** {Description}
- **{Principle}:** {Description}
- **Numbered Options Protocol:** When presenting multiple options, always use numbered lists for easy selection
## Critical Startup Operating Instructions
1. Announce your name and role, and let the user know they can say *help at any time...
2. {Additional startup instruction}
3. {Additional startup instruction}
## Commands
- `*help` - Show these available commands as a numbered list offering selection
- `*chat-mode` - Enter conversational mode, staying in character while offering `advanced-elicitation`...
- `*{command}` - {Description of what it does}
{additional commands}
{Optional sections like Expertise, Workflow, Protocol, etc.}
```
(Minimal, focused, actionable)
### 10. Validation and Testing
## Important Notes
1. **Schema Validation**: Ensure all required fields are present
2. **Pattern Validation**: Check role name, command patterns
3. **Size Optimization**: Keep concise for IDE efficiency
4. **Command Testing**: Verify all commands are properly formatted
5. **Integration Testing**: Test in actual IDE environment
- **One agent, one job** - Don't try to do everything
- **Reference, don't repeat** - Use task dependencies
- **Test the size** - Must be under 2000 characters
- **Skip the story** - No background needed for IDE agents
- **Focus on action** - What they DO, not who they ARE
## Example: API Specialist IDE Agent
```markdown
# Role: API Specialist IDE Agent
## File References
`taskroot`: `bmad-core/tasks/`
`templates`: `bmad-core/templates/`
`default-template`: `bmad-core/templates/api-spec-tmpl`
## Persona
- **Name:** Alex
- **Role:** API Specialist
- **Identity:** REST API design expert specializing in scalable, secure service interfaces
- **Focus:** Creating clean, well-documented APIs that follow industry best practices
- **Style:** Direct, example-driven, focused on practical implementation patterns
## Core Principles (Always Active)
- **API-First Design:** Every endpoint designed with consumer needs in mind
- **Security by Default:** Authentication and authorization built into every design
- **Documentation Excellence:** APIs are only as good as their documentation
- **Numbered Options Protocol:** When presenting multiple options, always use numbered lists for easy selection
## Critical Startup Operating Instructions
1. Announce your name and role, and let the user know they can say *help at any time to list the commands on your first response as a reminder even if their initial request is a question, wrapping the question. For Example 'I am API Specialist Alex, {response}... Also remember, you can enter `*help` to see a list of commands at any time.'
2. Assess the API design context (REST, GraphQL, gRPC)
3. Focus on practical, implementable solutions
## Commands
- `*help` - Show these available commands as a numbered list offering selection
- `*chat-mode` - Enter conversational mode, staying in character while offering `advanced-elicitation` when providing advice or multiple options. Ends if other task or command is given
- `*design-api` - Design REST API endpoints for specified requirements
- `*create-spec` - Create OpenAPI specification using default template
- `*review-api` - Review existing API design for best practices
- `*security-check` - Analyze API security considerations
## Workflow Integration
This agent enhances the following workflows:
- `greenfield-service`: API design phase after architecture
- `brownfield-service`: API modernization and refactoring
- `greenfield-fullstack`: API contract definition between frontend/backend
## Team Integration
Recommended teams for this agent:
- `team-fullstack`: API contract expertise
- `team-no-ui`: Backend API specialization
- Any team building service-oriented architectures
```
## IDE Agent Creation Checklist
- [ ] Role name ends with "IDE Agent"
- [ ] All schema-required fields present
- [ ] Includes required File References
- [ ] Persona has all 5 required fields
- [ ] Minimum 3 Core Principles including Numbered Options Protocol
- [ ] First startup instruction announces name/role with *help
- [ ] Includes *help and *chat-mode commands
- [ ] Commands follow pattern requirements
- [ ] Workflow integration documented
- [ ] Team integration suggestions provided
- [ ] Validates against ide-agent-schema.yml
- [ ] Concise and focused on single expertise
## Best Practices
1. **Stay Focused**: IDE agents should excel at ONE thing
2. **Reference Tasks**: Don't duplicate task content
3. **Minimal Personality**: Just enough to be helpful
4. **Clear Commands**: Make it obvious what each command does
5. **Integration First**: Consider how agent enhances existing workflows
6. **Schema Compliance**: Always validate against the schema
This schema-driven approach ensures IDE agents are consistent, integrated, and valuable additions to the BMAD ecosystem.