diff --git a/README.md b/README.md index a3949f8..909bbf1 100644 --- a/README.md +++ b/README.md @@ -321,6 +321,31 @@ The Gitea client skill enables AI agents to: **Documentation:** See [.vibe/skills/gitea-client/README.md](.vibe/skills/gitea-client/README.md) for complete setup and usage guide. +## 🤖 AI Agent Usage + +### Quick Launch Commands + +**Programmer Agent** (for code implementation, testing, CI/CD): +```bash +vibe start --agent dancelessonscoachprogrammer +``` + +**Product Owner Agent** (for requirements, interviews, documentation): +```bash +vibe start --agent dancelessonscoach-product-owner +``` + +### Full Documentation + +For complete agent usage guide including: +- Agent selection guidance +- Common workflow examples +- Configuration reference +- Best practices +- Troubleshooting tips + +See: [AGENT_USAGE_GUIDE.md](documentation/AGENT_USAGE_GUIDE.md) + ## License MIT diff --git a/documentation/AGENT_USAGE_GUIDE.md b/documentation/AGENT_USAGE_GUIDE.md new file mode 100644 index 0000000..0bac1e1 --- /dev/null +++ b/documentation/AGENT_USAGE_GUIDE.md @@ -0,0 +1,245 @@ +# 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!** 🚀 \ No newline at end of file