Comprehensive guide to Agent-First workflow including all 9 agents, 6 commands, best practices, and workflow examples
Provides comprehensive guide to Agent-First workflow with all agents, commands, and best practices
/plugin marketplace add musingfox/cc-plugins/plugin install omt@nick-personal-marketplaceclaude-haiku-4-5The Agent-First Workflow is a collaborative development system where:
/po, /techlead)/po (Define Requirements)
↓
/techlead (Architecture Decisions)
↓
@agent-planner (Task Breakdown + PRD)
↓
@agent-coder (TDD Implementation)
↓
@agent-reviewer (Code Review + Auto Commit)
↓
@agent-pm (Project Management)
↓
@agent-retro (Retrospective Analysis)
Error Path:
@agent-debugger → diagnoses issues → hands off to @agent-coderOptimization Path:
@agent-optimizer → optimizes code → hands off to @agent-reviewerIn your project root, run:
/init-agents
This creates:
.agents/ directory structure/po "Your feature description"
Example:
/po "Implement user authentication with JWT and refresh tokens"
You decide:
/techlead
You decide:
Result: Everything else happens automatically!
/po - Product OwnerWhen: Project start or new feature planning Input: Feature description and requirements Output: Automatically triggers task breakdown
Example:
/po "Implement OAuth2 social login integration"
/techlead - Technology DecisionsWhen: Major architectural or technology changes Input: Tech stack and architecture preferences Output: Architecture-informed task planning
/approve - Review Important ChangesWhen: API changes, schema modifications, security updates Input: Review and approve/reject changes Output: Automatic commit after approval
/git-commit - Manual Commit (Emergency)When: Manual intervention needed Input: Commit message Output: Direct git commit
/init-agents - Initialize WorkspaceWhen: New project setup Execution: Sets up complete agent infrastructure
Role: Task Breakdown & PRD Generation
Trigger: After /po and /techlead commands
Output: Detailed PRD with task breakdown
Handoff: → @agent-coder
Responsibilities:
Sample Output (planner.md):
# PRD: User Authentication
## Requirements
- JWT token generation
- Refresh token mechanism
- Rate limiting
## Task Breakdown
- [ ] Token service (3 points)
- [ ] Auth middleware (2 points)
- [ ] Rate limiting (2 points)
- [ ] Tests (1 point)
Total Complexity: 8 points
Role: TDD Implementation
Trigger: After planner completes
Output: Tested, working code
Handoff: → @agent-reviewer
Responsibilities:
Best For:
Sample Output (coder.md):
# Implementation Progress
## Completed Tasks
- ✅ Token service (2500 tokens)
- ✅ Auth middleware (1800 tokens)
- ✅ All tests passing
## Remaining
- [ ] Integration tests
Total tokens used: 4300
Role: Code Quality Review + Git Commit Authority
Trigger: After coder completes
Output: Approved code with commit
Handoff: → @agent-pm
Responsibilities:
Approval Criteria:
Role: Error Diagnosis & Troubleshooting
Trigger: Manual call when issues arise
Output: Identified root cause & fix
Handoff: → @agent-coder
Responsibilities:
Usage:
@agent-debugger "Fix login 500 error"
# → Diagnoses issue
# → Hands to @agent-coder for fix
# → @agent-reviewer reviews
# → Auto commit
Role: Performance Optimization
Trigger: Manual call for performance improvements
Output: Optimized code
Handoff: → @agent-reviewer
Responsibilities:
Optimization Targets:
Role: Documentation Generation Trigger: After code is reviewed Output: Complete documentation Handoff: Completes independently
Responsibilities:
Generates:
Role: Deployment Configuration Trigger: After code review Output: Deployment-ready config Handoff: Completes independently
Responsibilities:
Handles:
Role: Project Management & Completion
Trigger: After code review + commit
Output: Project status report
Handoff: → @agent-retro
Responsibilities:
Integration:
Role: Retrospective Analysis & Learning Trigger: After task completion Output: Insights and improvements Handoff: Updates PM with findings
Responsibilities:
Generates:
# Retrospective Analysis - LIN-123
## Estimation Accuracy
- Estimated: 8 points
- Actual: 10 points
- Accuracy: 80%
## Lessons Learned
- Auth implementation more complex than expected
- Token management requires more edge cases
## Recommendations
- Add 20% buffer for auth tasks in future
- Create auth helper library for reuse
# Step 1: Define Requirements
/po "Implement Stripe payment processing with webhook support"
# Step 2: Technology Decisions
/techlead
# → User selects: Node.js, Express, Stripe API, PostgreSQL
# Step 3-7: Fully Automated
# @agent-planner
# ↓ Creates PRD with 4-5 subtasks
# @agent-coder
# ↓ Implements payment service (TDD)
# @agent-reviewer
# ↓ Reviews and commits
# @agent-pm
# ↓ Updates Linear issue
# @agent-retro
# ↓ Analyzes and reports
# Result: Feature complete with commit history!
Local Files:
.agents/tasks/Linear:
GitHub Issues:
Jira:
During /init-agents, choose your system:
Choose task management:
A) Local files
B) Linear
C) GitHub Issues
D) Jira
After /init-agents, your project has:
.agents/
├── package.json # Dependencies (yaml)
├── config.yml # Configuration
├── states.yml # State definitions
├── lib.js # Helper library
├── tasks/ # Task data (gitignored)
│ ├── LIN-123.json # Task state
│ └── LIN-123/
│ ├── planner.md # Planner output
│ ├── coder.md # Coder output
│ └── reviewer.md # Review results
└── retro/ # Retrospectives (gitignored)
Tasks are estimated using token consumption, not human hours:
| Points | Tokens | Description |
|---|---|---|
| 1 | 1,000 | Trivial task |
| 2 | 2,000 | Simple feature |
| 3 | 3,000 | Basic feature |
| 5 | 5,000 | Medium feature |
| 8 | 8,000 | Complex feature |
| 13 | 13,000 | Very complex |
| 21 | 21,000 | Large feature set |
Key Principle: Let @agent-retro improve estimates based on actual usage.
When an agent encounters issues:
Example:
# Agent tries 3 times, then alerts:
🚨 Agent needs help: Test failures after 3 retries
Current state:
- Stashed changes: stash@{0}
- Diagnostic: .agents/tasks/LIN-123/coder.md
Options:
A) Review failure details
B) Manually fix issue
C) Adjust requirements
Use Agents for:
Use Commands for:
@agent-retro continuously improve# Check workspace size
du -sh .agents/
# View task status
cat .agents/tasks/LIN-123.json | jq
# View agent output
cat .agents/tasks/LIN-123/coder.md
# Clean old tasks (90+ days)
node -e "require('./.agents/lib').AgentTask.cleanup(90)"
Only 2 entities can commit:
@agent-reviewer - after review/git-commit - manual (emergency only)Commit Format:
feat(LIN-123): implement payment processing
Add Stripe integration with webhook support
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
/po "Feature: Add dark mode toggle"
# → Auto-completes in 1-2 passes
@agent-debugger "Fix: Memory leak in user session"
# → Diagnosis → Fix → Review → Commit
@agent-optimizer "Reduce API response time by 50%"
# → Analysis → Optimization → Testing → Commit
@agent-doc "Generate API docs for new endpoints"
# → Analyzes code → Generates docs
Inside this plugin:
docs/workflow.md - Complete workflow overviewdocs/agent-workspace-guide.md - Technical implementation guidecommands/ directory - Individual command detailsagents/ directory - Agent specificationsInitialize workspace:
/init-agents
View workspace guide:
See plugin's docs/agent-workspace-guide.md
Check agent status:
cat .agents/tasks/LIN-123.json | jq
Q: Do I need to run all commands?
A: No! Start with /po, optionally use /techlead, then agents handle the rest.
Q: Can I use this without task management?
A: Yes! Choose "Local files" during /init-agents setup.
Q: What if an agent fails? A: It escalates with full context. You can then manually fix or adjust requirements.
Q: How do I monitor progress?
A: Check .agents/tasks/ directory - each task shows all agent outputs.
Q: Can agents commit code?
A: Only @agent-reviewer can commit. Other agents create code, reviewer approves.
docs/ directoryagents/ directorycommands/ directory/init-agentsVersion: 1.0 Last Updated: 2025-10-16 Status: Production Ready
Need more details? Check the comprehensive guides in the docs/ directory!