Initial commit

2025-11-30 08:41:39 +08:00
commit 2652dfae0d
18 changed files with 5608 additions and 0 deletions
--- a/commands/help.md
+++ b/commands/help.md
@@ -0,0 +1,613 @@
+---
+name: help
+description: Comprehensive guide to Agent-First workflow including all 9 agents, 6 commands, best practices, and workflow examples
+model: claude-haiku-4-5
+---
+
+# Agent-First Workflow - Complete Guide
+
+## 🎯 Quick Overview
+
+The **Agent-First Workflow** is a collaborative development system where:
+- **Humans** make critical decisions via 2 commands (`/po`, `/techlead`)
+- **Agents** autonomously execute complex work
+- **Quality** is built-in with automated code review and git commits
+
+## 📊 Workflow Diagram
+
+```
+/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-coder`
+
+**Optimization Path**:
+- `@agent-optimizer` → optimizes code → hands off to `@agent-reviewer`
+
+---
+
+## 🚀 Getting Started (3 Steps)
+
+### Step 1: Initialize Agent Workspace
+
+In your project root, run:
+```bash
+/init-agents
+```
+
+This creates:
+- `.agents/` directory structure
+- Task management configuration (Linear/GitHub/Jira/Local)
+- Helper library and state definitions
+
+### Step 2: Define Your Requirements
+
+```bash
+/po "Your feature description"
+```
+
+Example:
+```bash
+/po "Implement user authentication with JWT and refresh tokens"
+```
+
+**You decide**:
+- Feature scope and acceptance criteria
+- Priority and timeline
+- Success metrics
+
+### Step 3: Architecture Decisions (Optional but Recommended)
+
+```bash
+/techlead
+```
+
+**You decide**:
+- Technology stack
+- Architecture patterns
+- Integration points
+- Risk assessment
+
+**Result**: Everything else happens automatically!
+
+---
+
+## 🎮 Commands (Critical Decision Points)
+
+### `/po` - Product Owner
+**When**: Project start or new feature planning
+**Input**: Feature description and requirements
+**Output**: Automatically triggers task breakdown
+
+Example:
+```bash
+/po "Implement OAuth2 social login integration"
+```
+
+### `/techlead` - Technology Decisions
+**When**: Major architectural or technology changes
+**Input**: Tech stack and architecture preferences
+**Output**: Architecture-informed task planning
+
+### `/approve` - Review Important Changes
+**When**: 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 Workspace
+**When**: New project setup
+**Execution**: Sets up complete agent infrastructure
+
+---
+
+## 🤖 Agents (Autonomous Execution)
+
+### 1. @agent-planner
+**Role**: Task Breakdown & PRD Generation
+**Trigger**: After `/po` and `/techlead` commands
+**Output**: Detailed PRD with task breakdown
+**Handoff**: → `@agent-coder`
+
+**Responsibilities**:
+- Analyze requirements
+- Create detailed PRD (Product Requirements Document)
+- Break down into subtasks
+- Estimate complexity (Fibonacci scale)
+
+**Sample Output** (planner.md):
+```markdown
+# 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
+```
+
+### 2. @agent-coder
+**Role**: TDD Implementation
+**Trigger**: After planner completes
+**Output**: Tested, working code
+**Handoff**: → `@agent-reviewer`
+
+**Responsibilities**:
+- Write tests first (TDD approach)
+- Implement features
+- Ensure tests pass
+- Document code inline
+
+**Best For**:
+- Feature implementation
+- Bug fixes
+- Refactoring
+
+**Sample Output** (coder.md):
+```markdown
+# Implementation Progress
+
+## Completed Tasks
+- ✅ Token service (2500 tokens)
+- ✅ Auth middleware (1800 tokens)
+- ✅ All tests passing
+
+## Remaining
+- [ ] Integration tests
+
+Total tokens used: 4300
+```
+
+### 3. @agent-reviewer
+**Role**: Code Quality Review + Git Commit Authority
+**Trigger**: After coder completes
+**Output**: Approved code with commit
+**Handoff**: → `@agent-pm`
+
+**Responsibilities**:
+- Review code quality
+- Verify test coverage
+- Check documentation
+- **Auto commit** approved code
+- Enforce coding standards
+
+**Approval Criteria**:
+- All tests passing
+- Code quality standards met
+- Documentation complete
+- Security review passed
+
+### 4. @agent-debugger
+**Role**: Error Diagnosis & Troubleshooting
+**Trigger**: Manual call when issues arise
+**Output**: Identified root cause & fix
+**Handoff**: → `@agent-coder`
+
+**Responsibilities**:
+- Diagnose errors systematically
+- Identify root causes
+- Suggest fixes
+- Prevent recurring issues
+
+**Usage**:
+```bash
+@agent-debugger "Fix login 500 error"
+# → Diagnoses issue
+# → Hands to @agent-coder for fix
+# → @agent-reviewer reviews
+# → Auto commit
+```
+
+### 5. @agent-optimizer
+**Role**: Performance Optimization
+**Trigger**: Manual call for performance improvements
+**Output**: Optimized code
+**Handoff**: → `@agent-reviewer`
+
+**Responsibilities**:
+- Identify performance bottlenecks
+- Optimize algorithms
+- Reduce resource usage
+- Maintain functionality
+
+**Optimization Targets**:
+- Response time
+- Memory usage
+- Database queries
+- Code complexity
+
+### 6. @agent-doc
+**Role**: Documentation Generation
+**Trigger**: After code is reviewed
+**Output**: Complete documentation
+**Handoff**: Completes independently
+
+**Responsibilities**:
+- Generate API documentation
+- Create user guides
+- Update README
+- Add code comments
+
+**Generates**:
+- API reference
+- Usage examples
+- Architecture diagrams
+- Troubleshooting guides
+
+### 7. @agent-devops
+**Role**: Deployment Configuration
+**Trigger**: After code review
+**Output**: Deployment-ready config
+**Handoff**: Completes independently
+
+**Responsibilities**:
+- Prepare deployment configurations
+- Set up CI/CD pipelines
+- Configure environment variables
+- Create deployment scripts
+
+**Handles**:
+- Docker/container setup
+- Infrastructure as Code
+- Deployment automation
+- Environment management
+
+### 8. @agent-pm
+**Role**: Project Management & Completion
+**Trigger**: After code review + commit
+**Output**: Project status report
+**Handoff**: → `@agent-retro`
+
+**Responsibilities**:
+- Update task management system
+- Track project progress
+- Coordinate agent handoffs
+- Trigger retrospective analysis
+
+**Integration**:
+- Linear issue updates
+- GitHub milestone tracking
+- Progress reporting
+- Capacity planning
+
+### 9. @agent-retro
+**Role**: Retrospective Analysis & Learning
+**Trigger**: After task completion
+**Output**: Insights and improvements
+**Handoff**: Updates PM with findings
+
+**Responsibilities**:
+- Analyze estimation accuracy
+- Calculate actual complexity
+- Identify lessons learned
+- Improve future predictions
+
+**Generates**:
+```markdown
+# 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
+```
+
+---
+
+## 🔄 Complete Workflow Example
+
+### Scenario: Implement Payment Processing
+
+```bash
+# 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!
+```
+
+---
+
+## 📚 Task Management Integration
+
+### Supported Systems
+
+**Local Files**:
+- Tasks in `.agents/tasks/`
+- No external dependency
+- Best for solo projects
+
+**Linear**:
+- Full MCP integration
+- Status synchronization
+- Team collaboration
+
+**GitHub Issues**:
+- Native integration
+- Automatic linking
+- Built-in CI/CD
+
+**Jira**:
+- API-based sync
+- Enterprise support
+- Sprint tracking
+
+### Configuration
+
+During `/init-agents`, choose your system:
+```
+Choose task management:
+A) Local files
+B) Linear
+C) GitHub Issues
+D) Jira
+```
+
+---
+
+## 🏗️ Workspace Structure
+
+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)
+```
+
+---
+
+## 📊 Complexity Estimation (Fibonacci Scale)
+
+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.
+
+---
+
+## 🛡️ Error Handling & Protection
+
+### Automatic Escalation
+
+When an agent encounters issues:
+
+1. **Retry up to 3 times** for transient errors
+2. **Fallback strategy** for known issues
+3. **Escalate to human** if unresolvable
+
+Example:
+```bash
+# 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
+```
+
+### State Preservation
+
+- Git stashes are created before risky operations
+- Checkpoints saved between agent handoffs
+- Complete audit trail in task JSON
+
+---
+
+## 🎓 Best Practices
+
+### 1. Agent-First Priority
+
+**Use Agents for**:
+- ✅ Complex multi-step tasks
+- ✅ Automation and repetition
+- ✅ Consistent quality
+
+**Use Commands for**:
+- ✅ Critical decisions only
+- ✅ Direction-setting
+- ✅ Approval gates
+
+### 2. Complexity Estimation
+
+- Based on token consumption, not guesses
+- Let `@agent-retro` continuously improve
+- Use historical data for better predictions
+
+### 3. Workspace Maintenance
+
+```bash
+# 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)"
+```
+
+### 4. Git Workflow
+
+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>
+```
+
+---
+
+## 🚦 Workflow Variations
+
+### Quick Feature Development
+
+```bash
+/po "Feature: Add dark mode toggle"
+# → Auto-completes in 1-2 passes
+```
+
+### Bug Fix with Investigation
+
+```bash
+@agent-debugger "Fix: Memory leak in user session"
+# → Diagnosis → Fix → Review → Commit
+```
+
+### Performance Optimization
+
+```bash
+@agent-optimizer "Reduce API response time by 50%"
+# → Analysis → Optimization → Testing → Commit
+```
+
+### Documentation Update
+
+```bash
+@agent-doc "Generate API docs for new endpoints"
+# → Analyzes code → Generates docs
+```
+
+---
+
+## 📖 Learning Resources
+
+### Documentation
+
+Inside this plugin:
+- `docs/workflow.md` - Complete workflow overview
+- `docs/agent-workspace-guide.md` - Technical implementation guide
+- `commands/` directory - Individual command details
+- `agents/` directory - Agent specifications
+
+### Quick References
+
+**Initialize workspace**:
+```bash
+/init-agents
+```
+
+**View workspace guide**:
+See plugin's `docs/agent-workspace-guide.md`
+
+**Check agent status**:
+```bash
+cat .agents/tasks/LIN-123.json | jq
+```
+
+---
+
+## ❓ FAQ
+
+**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.
+
+---
+
+## 🔗 Related Resources
+
+- Full documentation: See `docs/` directory
+- Individual agents: See `agents/` directory
+- Command details: See `commands/` directory
+- Workspace setup: Run `/init-agents`
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2025-10-16
+**Status**: Production Ready
+
+Need more details? Check the comprehensive guides in the `docs/` directory!