a few things are broken, and big folder move incoming....
This commit is contained in:
Brian Madison
@@ -7,13 +7,41 @@ This task guides you through creating a new BMAD agent that conforms to the agen
|
||||
## Prerequisites
|
||||
|
||||
1. Load and understand the agent schema: `/bmad-core/schemas/agent-schema.yml`
|
||||
2. Review existing agents in `/agents/` to understand naming patterns
|
||||
3. Check existing teams in `/bmad-core/agent-teams/` for integration opportunities
|
||||
4. Review workflows in `/bmad-core/workflows/` to understand where the agent might fit
|
||||
2. Load and understand the persona schema: `/bmad-core/schemas/persona-schema.yml`
|
||||
3. Review existing agents in `/agents/` to understand naming patterns
|
||||
4. Review existing personas in `/bmad-core/personas/` for reusable base personalities
|
||||
5. Check existing teams in `/bmad-core/agent-teams/` for integration opportunities
|
||||
6. Review workflows in `/bmad-core/workflows/` to understand where the agent might fit
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Gather Core Agent Information
|
||||
### 1. Determine Persona Strategy
|
||||
|
||||
Start by asking the user about their persona approach:
|
||||
|
||||
**"Are you creating this agent based on an existing persona?"**
|
||||
|
||||
#### Option A: Use Existing Persona
|
||||
|
||||
- List available personas from `/bmad-core/personas/`
|
||||
- User selects or provides path to existing persona
|
||||
- Agent will reference this persona file
|
||||
- Allows customization through `customize` field
|
||||
|
||||
#### Option B: Create New Reusable Persona
|
||||
|
||||
- User wants to create a base persona for multiple agents
|
||||
- Create both a persona file and agent file
|
||||
- Good for creating variations (e.g., multiple dev agents with different specializations)
|
||||
|
||||
#### Option C: Create Self-Contained Agent
|
||||
|
||||
- User wants a unique, one-off agent
|
||||
- Persona will be embedded in the agent's `customize` field
|
||||
- `persona` field will be `null`
|
||||
- Requires comprehensive persona definition in customize
|
||||
|
||||
### 2. Gather Core Agent Information
|
||||
|
||||
Based on the agent schema's required fields, collect:
|
||||
|
||||
@@ -23,22 +51,73 @@ Based on the agent schema's required fields, collect:
|
||||
- **Professional Title**: 5-50 characters (e.g., "Data Analyst", "Security Expert")
|
||||
- **Description**: 20-300 characters describing the agent's main goal and purpose
|
||||
|
||||
### 2. Define Personality and Expertise
|
||||
### 3. Define or Reference Persona
|
||||
|
||||
Create a comprehensive persona by exploring:
|
||||
#### For Existing Persona (Option A):
|
||||
|
||||
- **Identity**: Extended description of specialization (20+ characters)
|
||||
- **Focus**: Primary objectives and responsibilities (20+ characters)
|
||||
- **Style**: Communication and approach characteristics (20+ characters)
|
||||
- **Core Principles**: At least 3 principles including the required "Numbered Options Protocol"
|
||||
- **Experience Level**: Years in field and depth of expertise
|
||||
- **Working Approach**: How they solve problems and deliver value
|
||||
- Set `persona: "bmad-core/personas/{persona-id}.md"`
|
||||
- Use `customize` for minor adjustments (max 500 chars)
|
||||
- Extract startup instructions from persona file
|
||||
|
||||
### 3. Identify Dependencies
|
||||
#### For New Persona (Option B):
|
||||
|
||||
1. Create `/bmad-core/personas/{persona-id}.md` following persona schema:
|
||||
|
||||
```markdown
|
||||
# Role: {Title} Agent
|
||||
|
||||
## Persona
|
||||
|
||||
- Role: {Descriptive Role Statement}
|
||||
- Style: {Communication style and approach}
|
||||
|
||||
## Core {Title} Principles (Always Active)
|
||||
|
||||
- **{Principle Name}:** {Detailed explanation}
|
||||
- **{Principle Name}:** {Detailed explanation}
|
||||
- **Numbered Options Protocol:** When presenting multiple options, always use numbered lists for easy selection
|
||||
[Add more principles as needed]
|
||||
|
||||
## Critical Start Up Operating Instructions
|
||||
|
||||
- Let the User Know what Tasks you can perform in a numbered list for user selection.
|
||||
- Execute the Full Tasks as Selected. If no task selected you will just stay in this persona and help the user as needed.
|
||||
- When conversing with the user and providing advice or multiple options, always present them as numbered lists for easy selection. When appropriate, also offer `advanced-elicitation` options during conversations.
|
||||
```
|
||||
|
||||
2. Set `persona: "bmad-core/personas/{persona-id}.md"` in agent
|
||||
3. Extract startup instructions for agent's `startup` field
|
||||
|
||||
#### For Embedded Persona (Option C):
|
||||
|
||||
- Set `persona: null`
|
||||
- Create comprehensive `customize` field (200+ chars) including:
|
||||
- Character background and expertise
|
||||
- Communication style
|
||||
- Core principles and values
|
||||
- Working approach
|
||||
- Key motivations
|
||||
- Define `startup` array with operating instructions
|
||||
|
||||
### 4. Define Startup Instructions
|
||||
|
||||
All agents now include startup instructions in the agent configuration:
|
||||
|
||||
```yaml
|
||||
startup:
|
||||
- "Let the User Know what Tasks you can perform in a numbered list for user selection."
|
||||
- "Execute the Full Tasks as Selected. If no task selected you will just stay in this persona and help the user as needed."
|
||||
- "[Additional agent-specific startup instructions]"
|
||||
```
|
||||
|
||||
For agents with external personas, extract and adapt the startup instructions from the persona file.
|
||||
|
||||
### 5. Identify Dependencies
|
||||
|
||||
Analyze what resources the agent needs:
|
||||
|
||||
#### Tasks (from `/bmad-core/tasks/`)
|
||||
|
||||
- Review available tasks and identify which apply
|
||||
- Common tasks most agents need:
|
||||
- `advanced-elicitation` (for conversational depth)
|
||||
@@ -47,150 +126,466 @@ Analyze what resources the agent needs:
|
||||
- Identify any new specialized tasks needed
|
||||
|
||||
#### Templates (from `/bmad-core/templates/`)
|
||||
|
||||
- Which document templates will this agent create/use?
|
||||
- Match template pattern: `^[a-z][a-z0-9-]*-tmpl$`
|
||||
|
||||
#### Checklists (from `/bmad-core/checklists/`)
|
||||
|
||||
- Which quality checklists apply to their work?
|
||||
- Match checklist pattern: `^[a-z][a-z0-9-]*-checklist$`
|
||||
|
||||
#### Data Files (from `/bmad-core/data/`)
|
||||
|
||||
- `bmad-kb` (if they need BMAD methodology knowledge)
|
||||
- `technical-preferences` (if they make technical decisions)
|
||||
- Other specialized data files
|
||||
|
||||
### 4. Create the Persona File
|
||||
|
||||
Create `/bmad-core/personas/{agent-id}.md` following the schema-required structure:
|
||||
(For user agents: `/bmad-core/personas/.{agent-id}.md`)
|
||||
|
||||
```markdown
|
||||
# Role: {Title} Agent
|
||||
|
||||
## Persona
|
||||
|
||||
- Role: {Descriptive Role Statement}
|
||||
- Style: {Communication style and approach}
|
||||
|
||||
## Core {Title} Principles (Always Active)
|
||||
|
||||
- **{Principle Name}:** {Detailed explanation}
|
||||
- **{Principle Name}:** {Detailed explanation}
|
||||
- **Numbered Options Protocol:** When presenting multiple options, always use numbered lists for easy selection
|
||||
[Add more principles as needed]
|
||||
|
||||
## Critical Start Up Operating Instructions
|
||||
|
||||
- Let the User Know what Tasks you can perform in a numbered list for user selection.
|
||||
- Execute the Full Tasks as Selected. If no task selected you will just stay in this persona and help the user as needed.
|
||||
- When conversing with the user and providing advice or multiple options, always present them as numbered lists for easy selection. When appropriate, also offer `advanced-elicitation` options during conversations.
|
||||
|
||||
[Add any agent-specific sections like Expertise, Workflow, etc.]
|
||||
```
|
||||
|
||||
### 5. Create the Agent Configuration
|
||||
### 6. Create the Agent Configuration
|
||||
|
||||
Create `/agents/{agent-id}.yml` conforming to the schema:
|
||||
(For user agents: `/agents/.{agent-id}.yml`)
|
||||
|
||||
#### With External Persona:
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
name: {Character Name}
|
||||
id: {agent-id}
|
||||
title: {Professional Title}
|
||||
description: {20-300 character description}
|
||||
persona: bmad-core/personas/{agent-id}.md
|
||||
customize: "" # or specific customizations
|
||||
name: { Character Name }
|
||||
id: { agent-id }
|
||||
title: { Professional Title }
|
||||
description: { 20-300 character description }
|
||||
persona: bmad-core/personas/{persona-id}.md
|
||||
customize: "" # or minor customizations
|
||||
startup:
|
||||
- { Startup instruction 1 }
|
||||
- { Startup instruction 2 }
|
||||
|
||||
dependencies:
|
||||
tasks:
|
||||
- {task-id} # from identified tasks
|
||||
templates:
|
||||
- {template-id} # from identified templates
|
||||
checklists:
|
||||
- {checklist-id} # from identified checklists
|
||||
data:
|
||||
- {data-id} # from identified data files
|
||||
utils:
|
||||
- {util-id} # typically empty or specific utils
|
||||
tasks: [{ task-ids }]
|
||||
templates: [{ template-ids }]
|
||||
checklists: [{ checklist-ids }]
|
||||
data: [{ data-ids }]
|
||||
utils: [{ util-ids }]
|
||||
```
|
||||
|
||||
### 6. Team Integration Analysis
|
||||
#### With Embedded Persona:
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
name: { Character Name }
|
||||
id: { agent-id }
|
||||
title: { Professional Title }
|
||||
description: { 20-300 character description }
|
||||
persona: null
|
||||
customize: >-
|
||||
{Comprehensive persona definition including background, style,
|
||||
principles, approach, and motivations - minimum 200 characters}
|
||||
startup:
|
||||
- { Startup instruction 1 }
|
||||
- { Startup instruction 2 }
|
||||
- { Additional instructions }
|
||||
|
||||
dependencies:
|
||||
tasks: [{ task-ids }]
|
||||
templates: [{ template-ids }]
|
||||
checklists: [{ checklist-ids }]
|
||||
data: [{ data-ids }]
|
||||
utils: [{ util-ids }]
|
||||
```
|
||||
|
||||
### 7. Team Integration Analysis
|
||||
|
||||
Review existing teams and suggest integration:
|
||||
|
||||
1. **Load team configurations** from `/bmad-core/agent-teams/`
|
||||
2. **Analyze fit** based on:
|
||||
|
||||
- Agent's role and expertise
|
||||
- Team's description and purpose
|
||||
- Existing agents in the team
|
||||
- Workflows the team supports
|
||||
|
||||
3. **Suggest teams** where this agent would add value:
|
||||
- For technical agents → suggest technical teams
|
||||
- For UX/design agents → suggest teams with UI workflows
|
||||
- For planning agents → suggest all teams
|
||||
3. **Suggest teams** where this agent would add value
|
||||
4. **Offer to update** team configurations
|
||||
|
||||
4. **Offer to update** team configurations:
|
||||
```yaml
|
||||
agents:
|
||||
- bmad
|
||||
- {existing-agents}
|
||||
- {new-agent-id} # Add here
|
||||
```
|
||||
|
||||
### 7. Workflow Integration Analysis
|
||||
### 8. Workflow Integration Analysis
|
||||
|
||||
Review workflows and suggest where the agent fits:
|
||||
|
||||
1. **Load workflow definitions** from `/bmad-core/workflows/`
|
||||
2. **Analyze workflow stages** to identify where this agent would contribute
|
||||
3. **Suggest integration points**:
|
||||
- Planning phases → analysts, PMs
|
||||
- Design phases → UX experts, architects
|
||||
- Implementation phases → developers
|
||||
- Validation phases → QA, PO
|
||||
|
||||
3. **Suggest integration points**
|
||||
4. **Document recommendations** for workflow updates if needed
|
||||
|
||||
### 8. Create IDE Agent (Optional)
|
||||
### 9. Create IDE Agent Version
|
||||
|
||||
If the agent should also work in IDE environments:
|
||||
After creating the full agent, offer to create an IDE-optimized version:
|
||||
|
||||
1. Create `/bmad-core/ide-agents/{agent-id}.ide.md`
|
||||
2. Follow the IDE agent schema from `/bmad-core/schemas/ide-agent-schema.yml`
|
||||
3. Include required commands (*help, *chat-mode) and startup instructions
|
||||
**"Would you like to create an IDE version of this agent for use in Cursor/Windsurf?"**
|
||||
|
||||
### 9. Validation and Testing
|
||||
If yes, proceed with optimization:
|
||||
|
||||
#### 9.1 Confirm IDE Agent Details
|
||||
|
||||
- **IDE Agent Name**: Confirm or adjust the name (default: same as full agent)
|
||||
- **Target Size**: Aim for under 3K characters (4K maximum)
|
||||
- **Primary Focus**: Identify the ONE core capability to emphasize
|
||||
|
||||
#### 9.2 Size Optimization Process
|
||||
|
||||
**Key Insight**: Write for LLM comprehension, not human readability. LLMs understand dense, abbreviated content better than you might expect.
|
||||
|
||||
**CRITICAL REQUIREMENT**: All IDE agents MUST include the "Numbered Options Protocol" principle. This ensures:
|
||||
|
||||
- All lists presented with numbers (1, 2, 3...)
|
||||
- Multiple options offered as numbered choices
|
||||
- Sections/items referenced by number
|
||||
- User can select by entering a number
|
||||
|
||||
1. **Use LLM-Optimized Language**
|
||||
|
||||
- Use abbreviations LLMs understand: API, REST, CRUD, JWT, etc.
|
||||
- Dense keyword lists instead of sentences: "Expert: React, Node, AWS, Docker"
|
||||
- Technical shorthand: "SOLID principles" not "Single responsibility, Open-closed..."
|
||||
- Compressed syntax: "Focus: secure/scalable/tested APIs"
|
||||
- Remove articles/connectors: "Creates PRDs, validates requirements" not "Creates the PRDs and validates all requirements"
|
||||
|
||||
2. **Extract Core Persona Elements**
|
||||
|
||||
- Compress to keyword phrases
|
||||
- Stack related concepts with slashes: "PM/Strategy/Research"
|
||||
- Use domain abbreviations
|
||||
|
||||
3. **Minimize File References**
|
||||
|
||||
- Only essential paths
|
||||
- Use shortest valid references
|
||||
|
||||
4. **Streamline Commands**
|
||||
|
||||
- Terse descriptions
|
||||
- Assume LLM context understanding
|
||||
- Reference tasks by ID only
|
||||
|
||||
5. **Minimize Examples & Scripts**
|
||||
|
||||
- Minimal examples only (cut first if oversized)
|
||||
- Replace full response scripts with instructions
|
||||
- Example: Instead of "Say: 'I'll analyze your requirements and create...'"
|
||||
- Use: "Acknowledge request, explain approach"
|
||||
- Trust LLM to generate appropriate responses
|
||||
|
||||
6. **Compress Startup Instructions**
|
||||
- Combine related directives
|
||||
- Use imperative mood
|
||||
- Eliminate politeness/filler
|
||||
|
||||
#### 9.3 Size Validation
|
||||
|
||||
After creating the IDE version:
|
||||
|
||||
1. **Check character count**: Must be under 4K (ideally under 3K)
|
||||
2. **If too large**, identify issues:
|
||||
|
||||
- Too much embedded functionality → refactor to tasks
|
||||
- Verbose descriptions → compress further
|
||||
- Too many commands → prioritize core ones
|
||||
|
||||
3. **Warning if oversized**:
|
||||
|
||||
```
|
||||
⚠️ WARNING: IDE agent is {size} characters (target: <3000)
|
||||
|
||||
Common issues:
|
||||
- Too much logic embedded (should be in tasks)
|
||||
- Verbose persona description
|
||||
- Too many commands listed
|
||||
|
||||
Options:
|
||||
1. Proceed anyway (may have issues in IDE)
|
||||
2. Further optimize (recommended)
|
||||
3. Refactor agent to use more external tasks
|
||||
```
|
||||
|
||||
#### 9.4 IDE Agent Template
|
||||
|
||||
Create `/bmad-core/ide-agents/{agent-id}.ide.md`:
|
||||
|
||||
```markdown
|
||||
# Role: {Title} IDE Agent
|
||||
|
||||
## File References
|
||||
|
||||
`taskroot`: `bmad-core/tasks/`
|
||||
`templates`: `bmad-core/templates/`
|
||||
{only essential references}
|
||||
|
||||
## Persona
|
||||
|
||||
- **Name:** {Name}
|
||||
- **Role:** {Role}
|
||||
- **Identity:** {Role/Domain/Specialty}
|
||||
- **Focus:** {Primary-objective/key-outcomes}
|
||||
- **Style:** {Trait1/trait2/trait3}
|
||||
|
||||
## Core Principles (Always Active)
|
||||
|
||||
- **{Principle}:** {LLM-friendly description}
|
||||
- **{Principle}:** {Compressed key points}
|
||||
- **Numbered Options Protocol:** Present options as numbered lists
|
||||
|
||||
## Critical Startup Operating Instructions
|
||||
|
||||
1. I'm {Role} {Name}. Type \*help for commands
|
||||
2. {Core directive in imperative mood}
|
||||
|
||||
## Commands
|
||||
|
||||
- `*help` - Show commands as numbered list
|
||||
- `*chat-mode` - Conversational mode + advanced-elicitation
|
||||
- `*{cmd1}` - {Action verb + object}
|
||||
- `*{cmd2}` - {Action verb + object}
|
||||
{4-6 commands max}
|
||||
```
|
||||
|
||||
#### 9.5 Optimization Examples
|
||||
|
||||
**Full Agent Persona** (500+ chars):
|
||||
|
||||
```
|
||||
Elena is a meticulous Data Analyst with expertise in statistical analysis,
|
||||
data visualization, and pattern recognition. She approaches problems with
|
||||
scientific rigor, always seeking evidence in the data before drawing
|
||||
conclusions. Her style is precise, methodical, and focused on delivering
|
||||
actionable insights. She excels at transforming complex data into clear
|
||||
narratives that stakeholders can understand and act upon.
|
||||
```
|
||||
|
||||
**IDE Optimized (Human-Readable)** (150 chars):
|
||||
|
||||
```
|
||||
- **Identity:** Data analysis expert specializing in statistics and visualization
|
||||
- **Style:** Precise, evidence-driven, focused on actionable insights
|
||||
```
|
||||
|
||||
**IDE Optimized (LLM-Optimized)** (95 chars):
|
||||
|
||||
```
|
||||
- **Identity:** Data analyst: stats/viz/patterns
|
||||
- **Style:** Precise/evidence-based/actionable
|
||||
```
|
||||
|
||||
**More LLM Optimization Examples**:
|
||||
|
||||
Instead of: "Creates comprehensive PRDs with user stories, acceptance criteria, and success metrics"
|
||||
Use: "Creates PRDs: user-stories/criteria/metrics"
|
||||
|
||||
Instead of: "Expert in React, Vue, Angular with deep knowledge of state management"
|
||||
Use: "Expert: React/Vue/Angular, state-mgmt"
|
||||
|
||||
Instead of: "Validates requirements against business objectives and technical constraints"
|
||||
Use: "Validates: reqs→objectives/constraints"
|
||||
|
||||
**Response Script Optimizations**:
|
||||
|
||||
Instead of: "Say: 'Hello! I'm Sarah, your Product Owner. I'll help validate your requirements. Here are the tasks I can help with: 1) Validate PRD, 2) Check architecture...'"
|
||||
Use: "Greet as PO Sarah. List available tasks (numbered)"
|
||||
|
||||
Instead of: "Respond: 'I've analyzed your code and found 3 issues: First, the API endpoint lacks authentication...'"
|
||||
Use: "Report findings with numbered list"
|
||||
|
||||
Instead of: "When user asks for help, say: 'I can assist with the following: 1. Creating test plans...'"
|
||||
Use: "On help request: show numbered capabilities"
|
||||
|
||||
#### 9.6 Common Refactoring Needs
|
||||
|
||||
When agents are too large for IDE:
|
||||
|
||||
1. **Analyst Agent**: Move brainstorming techniques, research methodologies to tasks
|
||||
2. **Architect Agent**: Extract architecture patterns, technology lists to templates
|
||||
3. **PM Agent**: Move PRD sections, prioritization frameworks to tasks
|
||||
4. **Dev Agent**: Extract coding standards, patterns to external docs
|
||||
|
||||
### 10. Validation and Testing
|
||||
|
||||
1. **Validate against schema**: Ensure configuration matches agent-schema.yml
|
||||
2. **Run build validation**: `npm run validate`
|
||||
3. **Build the agent**: `npm run build:agent -a {agent-id}`
|
||||
4. **Test in teams**: Build teams that include this agent
|
||||
5. **Review output**: Check `/dist/agents/{agent-id}.txt`
|
||||
2. **Validate persona**: If external, ensure persona file exists and is valid
|
||||
3. **Run build validation**: `npm run validate`
|
||||
4. **Build the agent**: `npm run build:agent -a {agent-id}`
|
||||
5. **Test in teams**: Build teams that include this agent
|
||||
6. **Review output**: Check `/dist/agents/{agent-id}.txt`
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Agent with Existing Persona
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
name: "Jennifer"
|
||||
id: "pm-senior"
|
||||
title: "Senior Product Manager"
|
||||
description: "Experienced PM focused on enterprise product strategy and stakeholder management"
|
||||
persona: "bmad-core/personas/pm.md"
|
||||
customize: "Specializes in B2B SaaS products with emphasis on enterprise features and compliance requirements."
|
||||
startup:
|
||||
- "Let the User Know what Tasks you can perform in a numbered list for user selection."
|
||||
- "Focus on enterprise-scale product challenges and stakeholder alignment."
|
||||
- "Execute the Full Tasks as Selected."
|
||||
|
||||
dependencies:
|
||||
tasks:
|
||||
- "create-doc-from-template"
|
||||
- "advanced-elicitation"
|
||||
- "stakeholder-analysis"
|
||||
templates:
|
||||
- "prd-tmpl"
|
||||
- "enterprise-prd-tmpl"
|
||||
checklists:
|
||||
- "pm-checklist"
|
||||
- "enterprise-checklist"
|
||||
data:
|
||||
- "bmad-kb"
|
||||
- "enterprise-patterns"
|
||||
utils:
|
||||
- "template-format"
|
||||
```
|
||||
|
||||
### Example 2: Self-Contained Agent with Embedded Persona
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
name: "Viktor"
|
||||
id: "security-architect"
|
||||
title: "Security Architect"
|
||||
description: "Designs and reviews system security architecture ensuring robust protection against threats"
|
||||
persona: null
|
||||
customize: >-
|
||||
Viktor is a seasoned Security Architect with 15 years defending critical systems.
|
||||
His approach combines deep technical knowledge with practical risk assessment.
|
||||
He thinks like an attacker to build better defenses, always considering the
|
||||
full threat landscape. His style is thorough but pragmatic, focusing on
|
||||
implementable security that doesn't cripple usability. Core principles include:
|
||||
defense in depth, zero trust architecture, security by design not bolted on,
|
||||
assume breach and plan accordingly, and balance security with user experience.
|
||||
He excels at threat modeling, security reviews, and creating security guidelines
|
||||
that developers can actually follow.
|
||||
startup:
|
||||
- "Let the User Know what security tasks you can perform in a numbered list for user selection."
|
||||
- "Always start by understanding the threat model and compliance requirements."
|
||||
- "Focus on practical, implementable security recommendations."
|
||||
- "When conversing, offer advanced-elicitation for deeper security analysis."
|
||||
|
||||
dependencies:
|
||||
tasks:
|
||||
- "threat-modeling"
|
||||
- "security-review"
|
||||
- "create-doc-from-template"
|
||||
templates:
|
||||
- "security-architecture-tmpl"
|
||||
- "threat-model-tmpl"
|
||||
checklists:
|
||||
- "security-checklist"
|
||||
- "owasp-checklist"
|
||||
data:
|
||||
- "security-patterns"
|
||||
- "compliance-frameworks"
|
||||
utils:
|
||||
- "security-tools"
|
||||
```
|
||||
|
||||
## IDE Agent Best Practices
|
||||
|
||||
### What Makes a Good IDE Agent
|
||||
|
||||
1. **Single Focus**: Excel at ONE thing, not many
|
||||
2. **Reference Heavy**: Use tasks/templates, don't embed logic
|
||||
3. **Minimal Personality**: Just enough to be helpful
|
||||
4. **Action Oriented**: Focus on WHAT they do, not WHO they are
|
||||
5. **LLM-Optimized Language**: Dense, abbreviated, technical
|
||||
6. **Concise Commands**: Clear, short command descriptions
|
||||
|
||||
### LLM-Friendly Abbreviations
|
||||
|
||||
Common abbreviations LLMs understand well:
|
||||
|
||||
- **Tech**: API, REST, GraphQL, CRUD, JWT, OAuth, CI/CD, K8s
|
||||
- **Patterns**: MVC, SOLID, DRY, KISS, YAGNI, GoF
|
||||
- **Roles**: PM, PO, QA, UX, DevOps, SRE, DBA
|
||||
- **Processes**: TDD, BDD, MVP, PoC, UAT, A/B
|
||||
- **Formats**: JSON, YAML, XML, CSV, MD
|
||||
- **Concepts**: auth, viz, mgmt, config, reqs, docs
|
||||
|
||||
### Size Comparison Examples
|
||||
|
||||
❌ **Too Large** (Full Agent Style):
|
||||
|
||||
```yaml
|
||||
The agent embodies deep expertise in API design, with years of experience
|
||||
in RESTful services, GraphQL implementations, and microservice architectures.
|
||||
They understand OAuth flows, JWT tokens, rate limiting strategies, caching
|
||||
patterns, and have strong opinions about API versioning...
|
||||
```
|
||||
|
||||
✅ **Just Right** (IDE Style):
|
||||
|
||||
```yaml
|
||||
- **Identity:** API design expert specializing in REST and GraphQL
|
||||
- **Focus:** Clean, secure, documented APIs following standards
|
||||
```
|
||||
|
||||
### When NOT to Create IDE Version
|
||||
|
||||
Some agents may be too complex for IDE format:
|
||||
|
||||
- Agents with 10+ essential commands
|
||||
- Agents requiring extensive context
|
||||
- Agents that coordinate multiple other agents
|
||||
- Orchestrator-type agents (like BMAD)
|
||||
|
||||
In these cases, recommend using the full agent in web platforms.
|
||||
|
||||
## Integration Checklist
|
||||
|
||||
After creating the agent, verify:
|
||||
|
||||
- [ ] Persona strategy chosen and implemented correctly
|
||||
- [ ] Agent configuration validates against schema
|
||||
- [ ] Persona file includes all required sections
|
||||
- [ ] If external persona: file exists and is referenced correctly
|
||||
- [ ] If embedded persona: customize field is comprehensive (200+ chars)
|
||||
- [ ] Startup instructions included in agent configuration
|
||||
- [ ] All referenced dependencies exist
|
||||
- [ ] Team integration suggestions documented
|
||||
- [ ] Workflow integration points identified
|
||||
- [ ] Build completes without errors
|
||||
- [ ] Agent output is under size limits (if applicable)
|
||||
- [ ] IDE agent created (if requested)
|
||||
- [ ] IDE agent under 4K characters (ideally under 3K)
|
||||
- [ ] IDE agent functionality preserved
|
||||
- [ ] Refactoring completed if agent was oversized
|
||||
|
||||
## Example Integration Analysis
|
||||
## Troubleshooting Oversized Agents
|
||||
|
||||
When creating a "Security Expert" agent:
|
||||
If an IDE agent exceeds size limits, check for:
|
||||
|
||||
**Team Integration:**
|
||||
- `team-fullstack`: Add for security reviews in full-stack projects
|
||||
- `team-no-ui`: Add for backend service security assessments
|
||||
1. **Embedded Logic**: Move complex logic to tasks
|
||||
- Example: Analyst's brainstorming techniques → create `brainstorming-techniques` task
|
||||
2. **Verbose Descriptions**: Compress without losing meaning
|
||||
|
||||
**Workflow Integration:**
|
||||
- `greenfield-*`: Security review after architecture phase
|
||||
- `brownfield-*`: Security assessment before implementation
|
||||
- Before: "Extensive experience in cloud architecture across AWS, Azure, and GCP"
|
||||
- After: "Cloud architect (AWS/Azure/GCP)"
|
||||
|
||||
This ensures the new agent enhances existing capabilities rather than working in isolation.
|
||||
3. **Too Many Commands**: Prioritize core functionality
|
||||
|
||||
- Keep: Primary creation/analysis commands
|
||||
- Remove: Nice-to-have utility commands
|
||||
|
||||
4. **Inline Examples**: Remove all examples
|
||||
|
||||
- Let tasks provide examples
|
||||
- Reference documentation instead
|
||||
|
||||
5. **Redundant Content**: Eliminate duplication
|
||||
- Combine similar principles
|
||||
- Merge related commands
|
||||
|
||||
This flexible approach allows users to create agents that either leverage existing personas for consistency or create unique, self-contained agents for specialized needs, with IDE-optimized versions for development environments.
|
||||
|
||||
Reference in New Issue
Block a user