dance-lessons-coach/documentation/AGENT_USAGE_GUIDE.md

# DanceLessonsCoach Agent Usage Guide

## 🚀 Quick Start

### Launch Programmer Agent
```bash
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
vibe start --agent dancelessonscoachprogrammer
```

### Launch Product Owner Agent
```bash
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
vibe start --agent dancelessonscoach-product-owner
```

## 📚 Agent Reference

### Available Agents

| Agent | Configuration File | Purpose |
|-------|-------------------|---------|
| **Programmer** | `.mistral/dancelessonscoachprogrammer-agent.toml` | Code implementation, testing, CI/CD |
| **Product Owner** | `.mistral/dancelessonscoach-product-owner-agent.toml` | Requirements, interviews, documentation |

### Agent Skills

**Programmer Agent Skills (8):**
- `bdd-testing` - BDD test execution and validation
- `gitea-client` - Gitea API integration
- `commit-message` - Commit message conventions
- `documentation` - Markdown/wiki formatting
- `skill-creator` - Skill creation and management
- `changelog-manager` - Changelog maintenance

**Product Owner Agent Skills (9):**
- `product-owner-assistant` - Epic and user story management
- `interview-facilitator` - Structured stakeholder interviews
- `feedback-analyzer` - Feedback categorization and analysis
- `decision-documenter` - Decision and meeting documentation
- `prioritization-expert` - Feature prioritization (WSJF, MoSCoW)
- `bdd-testing` - BDD test generation
- `gitea-client` - Gitea API integration
- `documentation` - Markdown/wiki formatting
- `changelog-manager` - Changelog maintenance

## 🎯 Agent Selection Guide

### Use Programmer Agent When:
- ✅ Writing or modifying code
- ✅ Running tests (unit, integration, BDD)
- ✅ Fixing bugs and issues
- ✅ Implementing new features
- ✅ Working with Git and CI/CD pipelines
- ✅ Following commit conventions

### Use Product Owner Agent When:
- ✅ Gathering requirements from stakeholders
- ✅ Conducting structured interviews
- ✅ Analyzing feedback and issues
- ✅ Prioritizing features and epics
- ✅ Creating user stories and acceptance criteria
- ✅ Generating BDD test scenarios
- ✅ Documenting decisions and meetings
- ✅ Maintaining project documentation

## 📋 Common Workflows

### Programmer Workflow Example

```bash
# Start programmer agent session
vibe start --agent dancelessonscoachprogrammer

# Implement feature with BDD
agent implement-feature --name "User Authentication" --bdd-first

# Run tests
agent run-tests --feature authentication --bdd

# Commit changes
agent commit-changes --message "feat: implement OAuth authentication"

# Update changelog
skill changelog-manager add-entry \
  --description "Implement OAuth authentication" \
  --status "completed" \
  --what "- Added OAuth 2.0 provider\n- Implemented JWT tokens\n- Added session management" \
  --why "Enables social login\nImproves security" \
  --how "Used golang/oauth2 library\nImplemented middleware pattern" \
  --references "#42,adr/0004.md"
```

### Product Owner Workflow Example

```bash
# Start product owner agent session
vibe start --agent dancelessonscoach-product-owner

# Conduct stakeholder interview
agent conduct-interview \
  --template requirements-elicitation \
  --topic "Payment System" \
  --participants "Product Manager, Business Analyst, Security Team" \
  --output payment-interview-2026-04-06.md

# Analyze feedback
agent analyze-feedback \
  --source gitea-issues.json \
  --source payment-interview-2026-04-06.md \
  --categories "bug,feature,question,praise" \
  --output payment-feedback-analysis.md

# Prioritize features
agent prioritize-features \
  --method wsjf \
  --features payment-features.yaml \
  --output payment-prioritization.md

# Generate BDD tests
agent generate-bdd-tests \
  --requirements payment-requirements.md \
  --feature "Payment Processing" \
  --output features/payment.feature

# Update changelog
skill changelog-manager add-entry \
  --description "Add payment system requirements" \
  --status "completed" \
  --what "- Conducted 3 stakeholder interviews\n- Analyzed 15 feedback items\n- Prioritized 8 features\n- Created 12 BDD scenarios" \
  --why "Clear requirements for Q2 development\nReduced ambiguity by 60%" \
  --how "Used WSJF prioritization\nApplied BDD best practices" \
  --references "#45,adr/0008.md"
```

## 🔧 Configuration

### Agent Configuration Files

**Programmer Agent:**
```toml
# .mistral/dancelessonscoachprogrammer-agent.toml
name: dancelessonscoachprogrammer
role: DanceLessonsCoachProgrammer
goals: ["Follow BDD practices", "Use Gitmoji commits", "Respect ADR process"]
```

**Product Owner Agent:**
```toml
# .mistral/dancelessonscoach-product-owner-agent.toml
name: dancelessonscoach-product-owner
role: DanceLessonsCoachProductOwner
goals: ["Facilitate stakeholder interviews", "Generate BDD tests", "Maintain documentation"]
```

### Customizing Agents

To modify agent behavior:

```bash
# Edit programmer agent configuration
nano /Users/gabrielradureau/Work/Vibe/.mistral/dancelessonscoachprogrammer-agent.toml

# Edit product owner agent configuration
nano /Users/gabrielradureau/Work/Vibe/.mistral/dancelessonscoach-product-owner-agent.toml

# Validate configuration
vibe validate --agent dancelessonscoachprogrammer
vibe validate --agent dancelessonscoach-product-owner
```

## 📚 Best Practices

### General
- **Start each session** with the appropriate agent
- **Use the right agent** for the task type
- **Follow the workflow** for your agent
- **Update changelog** after significant work
- **Commit changes** with clear, conventional messages

### Programmer Agent
- ✅ **BDD First**: Always create failing tests before implementation
- ✅ **Small Commits**: Atomic changes with clear messages
- ✅ **Test Coverage**: Maintain >80% coverage
- ✅ **Document Decisions**: Use ADRs for architecture choices
- ✅ **Follow Conventions**: Gitmoji, semantic commits

### Product Owner Agent
- ✅ **Stakeholder Focus**: Document all interviews and feedback
- ✅ **Outcome Oriented**: Focus on what was achieved, not tasks
- ✅ **Link References**: Always reference issues, ADRs, commits
- ✅ **Keep Compact**: Bullet points, not paragraphs
- ✅ **Update Regularly**: After each significant session

## 🔍 Troubleshooting

### Agent Not Found

```bash
# List available agents
ls /Users/gabrielradureau/Work/Vibe/.mistral/*-agent.toml

# Verify agent configuration
vibe validate --agent dancelessonscoachprogrammer
vibe validate --agent dancelessonscoach-product-owner
```

### Skills Not Working

```bash
# List available skills
ls /Users/gabrielradureau/Work/Vibe/.mistral/skills/
ls /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach/.vibe/skills/

# Validate skill
skill skill-creator validate .vibe/skills/product-owner-assistant
skill skill-creator validate .mistral/skills/interview-facilitator
```

### Permission Issues

```bash
# Check file permissions
chmod +x /Users/gabrielradureau/Work/Vibe/.mistral/skills/*/scripts/*
chmod +x /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach/.vibe/skills/*/scripts/*
```

## 📖 Related Documentation

- [AGENT_CHANGELOG.md](../AGENT_CHANGELOG.md) - Agent contributions and decisions
- [AGENTS.md](../AGENTS.md) - Complete agent documentation
- [adr/](../adr/) - Architecture Decision Records
- [.vibe/skills/*/SKILL.md](../.vibe/skills/*/SKILL.md) - Individual skill documentation

## 🎉 Summary

This guide provides:
- ✅ Quick launch commands for both agents
- ✅ Agent selection guidance
- ✅ Common workflow examples
- ✅ Configuration reference
- ✅ Best practices
- ✅ Troubleshooting tips

**Use the right agent for the task and follow the established workflows!** 🚀