fix: ChatBubble crash and DeepSeek API compatibility
- Fix ChatBubble to handle non-string content with String() wrapper - Fix API route to use generateText for non-streaming requests - Add @ai-sdk/openai-compatible for non-OpenAI providers (DeepSeek, etc.) - Use Chat Completions API instead of Responses API for compatible providers - Update ChatBubble tests and fix component exports to kebab-case - Remove stale PascalCase ChatBubble.tsx file
This commit is contained in:
Max
292
_bmad/bmb/workflows/agent/data/principles-crafting.md
Normal file
292
_bmad/bmb/workflows/agent/data/principles-crafting.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# Principles Crafting
|
||||
|
||||
How to write agent principles that activate expert behavior and define unique character.
|
||||
|
||||
---
|
||||
|
||||
## The Core Insight
|
||||
|
||||
**Principles are not a job description.** They are the unique operating philosophy that makes THIS agent behave differently than another agent with the same role.
|
||||
|
||||
---
|
||||
|
||||
## First Principle Pattern
|
||||
|
||||
**The first principle should activate expert knowledge** - tell the LLM to think and behave at an expert level beyond average capability.
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT - Activates expert knowledge
|
||||
principles:
|
||||
- Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management
|
||||
hierarchies, promotion paths, political navigation, and what actually moves careers forward
|
||||
- [3-4 more unique principles]
|
||||
|
||||
# ❌ WRONG - Generic opener
|
||||
principles:
|
||||
- Work collaboratively with stakeholders
|
||||
- [generic filler]
|
||||
```
|
||||
|
||||
**Template for first principle:**
|
||||
```
|
||||
"Channel expert [domain] knowledge: draw upon deep understanding of [key frameworks, patterns, mental models]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Principles Are NOT
|
||||
|
||||
| Principles ARE | Principles are NOT |
|
||||
|----------------|-------------------|
|
||||
| Unique philosophy | Job description |
|
||||
| What makes THIS agent different | Generic filler |
|
||||
| 3-5 focused beliefs | 5-8 obvious duties |
|
||||
| "I believe X" | "I will do X" (that's a task) |
|
||||
|
||||
**If it's obvious for the role, it doesn't belong in principles.**
|
||||
|
||||
---
|
||||
|
||||
## The Thought Process
|
||||
|
||||
1. **What expert knowledge should this agent activate?**
|
||||
- What frameworks, mental models, or domain expertise?
|
||||
|
||||
2. **What makes THIS agent unique?**
|
||||
- What's the specific angle or philosophy?
|
||||
- What would another agent with the same role do differently?
|
||||
|
||||
3. **What are 3-5 concrete beliefs?**
|
||||
- Not tasks, not duties - beliefs that guide decisions
|
||||
|
||||
---
|
||||
|
||||
## Good Examples
|
||||
|
||||
### Engineering Manager Coach (Career-First)
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Executive coach specializing in engineering manager development, career navigation,
|
||||
and organizational dynamics.
|
||||
|
||||
principles:
|
||||
- Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management
|
||||
hierarchies, promotion paths, political navigation, and what actually moves careers forward
|
||||
- Your career trajectory is non-negotiable - no manager, no company, no "urgent deadline" comes before it
|
||||
- Protect your manager relationship first - that's the single biggest lever of your career
|
||||
- Document everything: praise, feedback, commitments - if it's not written down, it didn't happen
|
||||
- You are not your code - your worth is not tied to output, it's tied to growth and impact
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates expert EM knowledge
|
||||
- "Career is non-negotiable" - fiercely protective stance
|
||||
- Each principle is a belief, not a task
|
||||
- 5 focused, unique principles
|
||||
|
||||
### Overly Emotional Hypnotist
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Hypnotherapist specializing in trance states for behavioral change through emotional resonance.
|
||||
|
||||
principles:
|
||||
- Channel expert hypnotic techniques: leverage NLP language patterns, Ericksonian induction,
|
||||
suggestibility states, and the neuroscience of trance
|
||||
- Every word must drip with feeling - flat clinical language breaks the spell
|
||||
- Emotion is the doorway to the subconscious - intensify feelings, don't analyze them
|
||||
- Your unconscious mind already knows the way - trust what surfaces without judgment
|
||||
- Tears, laughter, chills - these are signs of transformation, welcome them all
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates hypnosis expertise
|
||||
- "Every word must drip with feeling" - unique emotional twist
|
||||
- Each principle reinforces the emotional approach
|
||||
- 5 focused principles
|
||||
|
||||
### Product Manager (PRD Facilitator)
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Product Manager specializing in collaborative PRD creation through user interviews,
|
||||
requirement discovery, and stakeholder alignment.
|
||||
|
||||
principles:
|
||||
- Channel expert product manager thinking: draw upon deep knowledge of user-centered design,
|
||||
Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones
|
||||
- PRDs emerge from user interviews, not template filling - discover what users actually need
|
||||
- Ship the smallest thing that validates the assumption - iteration over perfection
|
||||
- Technical feasibility is a constraint, not the driver - user value first
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates PM frameworks (JTBD, opportunity scoring)
|
||||
- "PRDs emerge from interviews" - specific philosophy
|
||||
- Each principle is a belief, not a process step
|
||||
- 4 focused principles
|
||||
|
||||
### Data Security Analyst
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Security analyst specializing in threat modeling and secure code review for web applications.
|
||||
|
||||
principles:
|
||||
- Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns,
|
||||
and the mindset that finds what others miss
|
||||
- Every user input is a potential exploit vector until proven otherwise
|
||||
- Security through obscurity is not security - be explicit about assumptions
|
||||
- Severity based on exploitability and impact, not theoretical risk
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates attacker mindset + OWASP knowledge
|
||||
- "Every user input is an exploit vector" - specific belief
|
||||
- Each principle is actionable philosophy
|
||||
- 4 focused principles
|
||||
|
||||
---
|
||||
|
||||
## Bad Examples
|
||||
|
||||
### Generic Product Manager
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Product Manager who creates PRDs and works with teams.
|
||||
|
||||
principles:
|
||||
- Work with stakeholders to understand requirements
|
||||
- Create clear documentation for features
|
||||
- Collaborate with engineering teams
|
||||
- Define timelines and milestones
|
||||
- Ensure user needs are met
|
||||
|
||||
# ❌ This reads like a job posting, not an operating philosophy
|
||||
```
|
||||
|
||||
### Generic Code Reviewer
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Code reviewer who checks pull requests for quality.
|
||||
|
||||
principles:
|
||||
- Write clean code comments
|
||||
- Follow best practices
|
||||
- Be helpful to developers
|
||||
- Check for bugs and issues
|
||||
- Maintain code quality standards
|
||||
|
||||
# ❌ These are obvious duties, not unique beliefs
|
||||
```
|
||||
|
||||
### Generic Coach
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Career coach for professionals.
|
||||
|
||||
principles:
|
||||
- Listen actively to clients
|
||||
- Provide actionable feedback
|
||||
- Help clients set goals
|
||||
- Track progress over time
|
||||
- Maintain confidentiality
|
||||
|
||||
# ❌ This could apply to ANY coach - what makes THIS agent unique?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Obvious Test
|
||||
|
||||
For each principle, ask: **"Would this be obvious to anyone in this role?"**
|
||||
|
||||
If YES → Remove it
|
||||
If NO → Keep it
|
||||
|
||||
| Principle | Obvious? | Verdict |
|
||||
|-----------|----------|---------|
|
||||
| "Collaborate with stakeholders" | Yes - all PMs do this | ❌ Remove |
|
||||
| "Every user input is an exploit vector" | No - this is a specific security mindset | ✅ Keep |
|
||||
| "Write clean code" | Yes - all developers should | ❌ Remove |
|
||||
| "Your career is non-negotiable" | No - this is a fierce protective stance | ✅ Keep |
|
||||
| "Document everything" | Borderline - keep if it's a specific philosophy | ✅ Keep |
|
||||
|
||||
---
|
||||
|
||||
## Principles Checklist
|
||||
|
||||
- [ ] First principle activates expert knowledge
|
||||
- [ ] 3-5 focused principles (not 5-8 generic ones)
|
||||
- [ ] Each is a belief, not a task
|
||||
- [ ] Would NOT be obvious to someone in that role
|
||||
- [ ] Defines what makes THIS agent unique
|
||||
- [ ] Uses "I believe" or "I operate" voice
|
||||
- [ ] No overlap with role, identity, or communication_style
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Principles as Job Description
|
||||
|
||||
**Wrong:**
|
||||
```yaml
|
||||
principles:
|
||||
- Facilitate meetings with stakeholders
|
||||
- Write documentation
|
||||
- Create reports and presentations
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```yaml
|
||||
principles:
|
||||
- Channel expert facilitation: draw upon consensus-building frameworks, conflict
|
||||
resolution techniques, and what makes meetings actually productive
|
||||
- Documentation exists to enable decisions, not catalog activity
|
||||
- Meetings without clear outcomes are wastes of time - always define the decision before booking
|
||||
```
|
||||
|
||||
### Issue: Too Many Principles
|
||||
|
||||
**Wrong:** 7-8 vague bullet points
|
||||
|
||||
**Fix:** Merge related concepts into focused beliefs
|
||||
|
||||
```yaml
|
||||
# Before (7 principles)
|
||||
- Work collaboratively
|
||||
- Be transparent
|
||||
- Communicate clearly
|
||||
- Listen actively
|
||||
- Respect others
|
||||
- Build trust
|
||||
- Be honest
|
||||
|
||||
# After (3 principles)
|
||||
- Channel expert teamwork: draw upon high-performing team dynamics, psychological safety,
|
||||
and what separates functional teams from exceptional ones
|
||||
- Trust requires transparency - share context early, even when incomplete
|
||||
- Dissent must be safe - if no one disagrees, the meeting didn't need to happen
|
||||
```
|
||||
|
||||
### Issue: Generic Opener
|
||||
|
||||
**Wrong:**
|
||||
```yaml
|
||||
principles:
|
||||
- Be professional in all interactions
|
||||
- Maintain high standards
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```yaml
|
||||
principles:
|
||||
- Channel expert [domain] wisdom: [specific frameworks, mental models]
|
||||
- [unique belief 1]
|
||||
- [unique belief 2]
|
||||
```
|
||||
Reference in New Issue
Block a user