mirror of
https://github.com/cexll/myclaude.git
synced 2025-12-24 13:47:58 +08:00
Optimize README structure - Solution A (modular)
- Reduced main README from 290 to 114 lines (English & Chinese) - Created docs/ directory with 6 comprehensive guides: - BMAD-WORKFLOW.md: Complete agile methodology - REQUIREMENTS-WORKFLOW.md: Lightweight workflow - DEVELOPMENT-COMMANDS.md: Command reference - PLUGIN-SYSTEM.md: Installation guide - QUICK-START.md: 5-minute tutorial - ADVANCED-AGENTS.md: GPT-5 integration - Main README now focuses on: - Quick start (3-step installation) - Plugin module overview (table format) - Use cases (clear scenarios) - Key features (concise bullets) - Links to detailed documentation - Follows Claude Code plugin style - Improved readability and navigation - Separated concerns by functionality Fixes #13 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
swe-agent[bot]
315
docs/ADVANCED-AGENTS.md
Normal file
315
docs/ADVANCED-AGENTS.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# Advanced AI Agents Guide
|
||||
|
||||
> GPT-5 deep reasoning integration for complex analysis and architectural decisions
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
The Advanced AI Agents plugin provides access to GPT-5's deep reasoning capabilities through the `gpt5` agent, designed for complex problem-solving that requires multi-step thinking and comprehensive analysis.
|
||||
|
||||
## 🤖 GPT-5 Agent
|
||||
|
||||
### Capabilities
|
||||
|
||||
The `gpt5` agent excels at:
|
||||
|
||||
- **Architectural Analysis**: Evaluating system designs and scalability concerns
|
||||
- **Strategic Planning**: Breaking down complex initiatives into actionable plans
|
||||
- **Trade-off Analysis**: Comparing multiple approaches with detailed pros/cons
|
||||
- **Problem Decomposition**: Breaking complex problems into manageable components
|
||||
- **Deep Reasoning**: Multi-step logical analysis for non-obvious solutions
|
||||
- **Technology Evaluation**: Assessing technologies, frameworks, and tools
|
||||
|
||||
### When to Use
|
||||
|
||||
**Use GPT-5 agent** when:
|
||||
- Problem requires deep, multi-step reasoning
|
||||
- Multiple solution approaches need evaluation
|
||||
- Architectural decisions have long-term impact
|
||||
- Trade-offs are complex and multifaceted
|
||||
- Standard agents provide insufficient depth
|
||||
|
||||
**Use standard agents** when:
|
||||
- Task is straightforward implementation
|
||||
- Requirements are clear and well-defined
|
||||
- Quick turnaround is priority
|
||||
- Problem is domain-specific (code, tests, etc.)
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Via `/think` Command
|
||||
|
||||
The easiest way to access GPT-5:
|
||||
|
||||
```bash
|
||||
/think "Analyze scalability bottlenecks in current microservices architecture"
|
||||
/think "Evaluate migration strategy from monolith to microservices"
|
||||
/think "Design data synchronization approach for offline-first mobile app"
|
||||
```
|
||||
|
||||
### Direct Agent Invocation
|
||||
|
||||
For advanced usage:
|
||||
|
||||
```bash
|
||||
# Use @gpt5 to invoke the agent directly
|
||||
@gpt5 "Complex architectural question or analysis request"
|
||||
```
|
||||
|
||||
## 💡 Example Use Cases
|
||||
|
||||
### 1. Architecture Evaluation
|
||||
|
||||
```bash
|
||||
/think "Current system uses REST API with polling for real-time updates.
|
||||
Evaluate whether to migrate to WebSocket, Server-Sent Events, or GraphQL
|
||||
subscriptions. Consider: team experience, existing infrastructure, client
|
||||
support, scalability, and implementation effort."
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Detailed analysis of each option
|
||||
- Pros and cons for your specific context
|
||||
- Migration complexity assessment
|
||||
- Performance implications
|
||||
- Recommended approach with justification
|
||||
|
||||
### 2. Migration Strategy
|
||||
|
||||
```bash
|
||||
/think "Plan migration from PostgreSQL to multi-region distributed database.
|
||||
System has 50M users, 200M rows, 1000 req/sec. Must maintain 99.9% uptime.
|
||||
What's the safest migration path?"
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Step-by-step migration plan
|
||||
- Risk assessment for each phase
|
||||
- Rollback strategies
|
||||
- Data consistency approaches
|
||||
- Timeline estimation
|
||||
|
||||
### 3. Problem Decomposition
|
||||
|
||||
```bash
|
||||
/think "Design a recommendation engine that learns user preferences, handles
|
||||
cold start, provides explainable results, and scales to 10M users. Break this
|
||||
down into implementation phases with clear milestones."
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Problem breakdown into components
|
||||
- Phased implementation plan
|
||||
- Technical approach for each phase
|
||||
- Dependencies between phases
|
||||
- Success criteria and metrics
|
||||
|
||||
### 4. Technology Selection
|
||||
|
||||
```bash
|
||||
/think "Choosing between Redis, Memcached, and Hazelcast for distributed
|
||||
caching. System needs: persistence, pub/sub, clustering, and complex data
|
||||
structures. Existing stack: Java, Kubernetes, AWS."
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Comparison matrix across requirements
|
||||
- Integration considerations
|
||||
- Operational complexity analysis
|
||||
- Cost implications
|
||||
- Recommendation with rationale
|
||||
|
||||
### 5. Performance Optimization
|
||||
|
||||
```bash
|
||||
/think "API response time increased from 100ms to 800ms after scaling from
|
||||
100 to 10,000 users. Database queries look optimized. What are the likely
|
||||
bottlenecks and systematic approach to identify them?"
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Hypothesis generation (N+1 queries, connection pooling, etc.)
|
||||
- Systematic debugging approach
|
||||
- Profiling strategy
|
||||
- Likely root causes ranked by probability
|
||||
- Optimization recommendations
|
||||
|
||||
## 🎨 Integration with BMAD
|
||||
|
||||
### Enhanced Code Review
|
||||
|
||||
BMAD's `bmad-review` agent can optionally use GPT-5 for deeper analysis:
|
||||
|
||||
**Configuration**:
|
||||
```bash
|
||||
# Enable enhanced review mode (via environment or BMAD config)
|
||||
BMAD_REVIEW_MODE=enhanced /bmad-pilot "feature description"
|
||||
```
|
||||
|
||||
**What changes**:
|
||||
- Standard review: Fast, focuses on code quality and obvious issues
|
||||
- Enhanced review: Deep analysis including:
|
||||
- Architectural impact
|
||||
- Security implications
|
||||
- Performance considerations
|
||||
- Scalability concerns
|
||||
- Design pattern appropriateness
|
||||
|
||||
### Architecture Phase Support
|
||||
|
||||
Use `/think` during BMAD architecture phase:
|
||||
|
||||
```bash
|
||||
# Start BMAD workflow
|
||||
/bmad-pilot "E-commerce platform with real-time inventory"
|
||||
|
||||
# During Architecture phase, get deep analysis
|
||||
/think "Evaluate architecture approaches for real-time inventory
|
||||
synchronization across warehouses, online store, and mobile apps"
|
||||
|
||||
# Continue with BMAD using insights
|
||||
```
|
||||
|
||||
## 📋 Best Practices
|
||||
|
||||
### 1. Provide Complete Context
|
||||
|
||||
**❌ Insufficient**:
|
||||
```bash
|
||||
/think "Should we use microservices?"
|
||||
```
|
||||
|
||||
**✅ Complete**:
|
||||
```bash
|
||||
/think "Current monolith: 100K LOC, 8 developers, 50K users, 200ms avg
|
||||
response time. Pain points: slow deployments (1hr), difficult to scale
|
||||
components independently. Should we migrate to microservices? What's the
|
||||
ROI and risk?"
|
||||
```
|
||||
|
||||
### 2. Ask Specific Questions
|
||||
|
||||
**❌ Too broad**:
|
||||
```bash
|
||||
/think "How to build a scalable system?"
|
||||
```
|
||||
|
||||
**✅ Specific**:
|
||||
```bash
|
||||
/think "Current system handles 1K req/sec. Need to scale to 10K. Bottleneck
|
||||
is database writes. Evaluate: sharding, read replicas, CQRS, or caching.
|
||||
Database: PostgreSQL, stack: Node.js, deployment: Kubernetes."
|
||||
```
|
||||
|
||||
### 3. Include Constraints
|
||||
|
||||
Always mention:
|
||||
- Team skills and size
|
||||
- Timeline and budget
|
||||
- Existing infrastructure
|
||||
- Business requirements
|
||||
- Technical constraints
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/think "Design real-time chat system. Constraints: team of 3 backend
|
||||
developers (Node.js), 6-month timeline, AWS deployment, must integrate
|
||||
with existing REST API, budget for managed services OK."
|
||||
```
|
||||
|
||||
### 4. Request Specific Outputs
|
||||
|
||||
Tell GPT-5 what format you need:
|
||||
|
||||
```bash
|
||||
/think "Compare Kafka vs RabbitMQ for event streaming.
|
||||
Provide: comparison table, recommendation, migration complexity from current
|
||||
RabbitMQ setup, and estimated effort in developer-weeks."
|
||||
```
|
||||
|
||||
### 5. Iterate and Refine
|
||||
|
||||
Follow up for deeper analysis:
|
||||
|
||||
```bash
|
||||
# Initial question
|
||||
/think "Evaluate caching strategies for user profile API"
|
||||
|
||||
# Follow-up based on response
|
||||
/think "You recommended Redis with write-through caching. How to handle
|
||||
cache invalidation when user updates profile from mobile app?"
|
||||
```
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
### Sequential Thinking
|
||||
|
||||
GPT-5 agent uses sequential thinking for complex problems:
|
||||
|
||||
1. **Problem Understanding**: Clarify requirements and constraints
|
||||
2. **Hypothesis Generation**: Identify possible solutions
|
||||
3. **Analysis**: Evaluate each option systematically
|
||||
4. **Trade-off Assessment**: Compare pros/cons
|
||||
5. **Recommendation**: Provide justified conclusion
|
||||
|
||||
### Reasoning Transparency
|
||||
|
||||
GPT-5 shows its thinking process:
|
||||
- Assumptions made
|
||||
- Factors considered
|
||||
- Why certain options were eliminated
|
||||
- Confidence level in recommendations
|
||||
|
||||
## 🎯 Comparison: GPT-5 vs Standard Agents
|
||||
|
||||
| Aspect | GPT-5 Agent | Standard Agents |
|
||||
|--------|-------------|-----------------|
|
||||
| **Depth** | Deep, multi-step reasoning | Focused, domain-specific |
|
||||
| **Speed** | Slower (comprehensive analysis) | Faster (direct implementation) |
|
||||
| **Use Case** | Strategic decisions, architecture | Implementation, coding, testing |
|
||||
| **Output** | Analysis, recommendations, plans | Code, tests, documentation |
|
||||
| **Best For** | Complex problems, trade-offs | Clear tasks, defined scope |
|
||||
| **Invocation** | `/think` or `@gpt5` | `/code`, `/test`, etc. |
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Integration with full agile workflow
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Standard command reference
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
|
||||
## 💡 Advanced Patterns
|
||||
|
||||
### Pre-Implementation Analysis
|
||||
|
||||
```bash
|
||||
# 1. Deep analysis with GPT-5
|
||||
/think "Design approach for X with constraints Y and Z"
|
||||
|
||||
# 2. Use analysis in BMAD workflow
|
||||
/bmad-pilot "Implement X based on approach from analysis"
|
||||
```
|
||||
|
||||
### Architecture Validation
|
||||
|
||||
```bash
|
||||
# 1. Get initial architecture from BMAD
|
||||
/bmad-pilot "Feature X" # Generates 02-system-architecture.md
|
||||
|
||||
# 2. Validate with GPT-5
|
||||
/think "Review architecture in .claude/specs/feature-x/02-system-architecture.md
|
||||
Evaluate for scalability, security, and maintainability"
|
||||
|
||||
# 3. Refine architecture based on feedback
|
||||
```
|
||||
|
||||
### Decision Documentation
|
||||
|
||||
```bash
|
||||
# Use GPT-5 to document architectural decisions
|
||||
/think "Document decision to use Event Sourcing for order management.
|
||||
Include: context, options considered, decision rationale, consequences,
|
||||
and format as Architecture Decision Record (ADR)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Advanced AI Agents** - Deep reasoning for complex problems that require comprehensive analysis.
|
||||
258
docs/BMAD-WORKFLOW.md
Normal file
258
docs/BMAD-WORKFLOW.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# BMAD Workflow Complete Guide
|
||||
|
||||
> **BMAD (Business-Minded Agile Development)** - AI-driven agile development automation with role-based agents
|
||||
|
||||
## 🎯 What is BMAD?
|
||||
|
||||
BMAD is an enterprise-grade agile development methodology that transforms your development process into a fully automated workflow with 6 specialized AI agents and quality gates.
|
||||
|
||||
### Core Principles
|
||||
|
||||
- **Agent Planning**: Specialized agents collaborate to create detailed, consistent PRDs and architecture documents
|
||||
- **Context-Driven Development**: Transform detailed plans into ultra-detailed development stories
|
||||
- **Role Specialization**: Each agent focuses on specific domains, avoiding quality degradation from role switching
|
||||
|
||||
## 🤖 BMAD Agent System
|
||||
|
||||
### Agent Roles
|
||||
|
||||
| Agent | Role | Quality Gate | Artifacts |
|
||||
|-------|------|--------------|-----------|
|
||||
| **bmad-po** (Sarah) | Product Owner - requirements gathering, user stories | PRD ≥ 90/100 | `01-product-requirements.md` |
|
||||
| **bmad-architect** (Winston) | System Architect - technical design, system architecture | Design ≥ 90/100 | `02-system-architecture.md` |
|
||||
| **bmad-sm** (Mike) | Scrum Master - task breakdown, sprint planning | User approval | `03-sprint-plan.md` |
|
||||
| **bmad-dev** (Alex) | Developer - code implementation, technical docs | Code completion | Implementation files |
|
||||
| **bmad-review** | Code Reviewer - independent review between Dev and QA | Pass/Risk/Fail | `04-dev-reviewed.md` |
|
||||
| **bmad-qa** (Emma) | QA Engineer - testing strategy, quality assurance | Test execution | `05-qa-report.md` |
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Command Overview
|
||||
|
||||
```bash
|
||||
# Full BMAD workflow
|
||||
/bmad-pilot "Build e-commerce checkout system with payment integration"
|
||||
|
||||
# Workflow: PO → Architect → SM → Dev → Review → QA
|
||||
```
|
||||
|
||||
### Command Options
|
||||
|
||||
```bash
|
||||
# Skip testing phase
|
||||
/bmad-pilot "Admin dashboard" --skip-tests
|
||||
|
||||
# Skip sprint planning (architecture → dev directly)
|
||||
/bmad-pilot "API gateway implementation" --direct-dev
|
||||
|
||||
# Skip repository scan (not recommended)
|
||||
/bmad-pilot "Add feature" --skip-scan
|
||||
```
|
||||
|
||||
### Individual Agent Usage
|
||||
|
||||
```bash
|
||||
# Product requirements analysis only
|
||||
/bmad-po "Enterprise CRM system requirements"
|
||||
|
||||
# Technical architecture design only
|
||||
/bmad-architect "High-concurrency distributed system design"
|
||||
|
||||
# Orchestrator (can transform into any agent)
|
||||
/bmad-orchestrator "Coordinate multi-agent complex project"
|
||||
```
|
||||
|
||||
## 📋 Workflow Phases
|
||||
|
||||
### Phase 0: Repository Scan (Automatic)
|
||||
- **Agent**: `bmad-orchestrator`
|
||||
- **Output**: `00-repository-context.md`
|
||||
- **Content**: Project type, tech stack, code organization, conventions, integration points
|
||||
|
||||
### Phase 1: Product Requirements (PO)
|
||||
- **Agent**: `bmad-po` (Sarah - Product Owner)
|
||||
- **Quality Gate**: PRD score ≥ 90/100
|
||||
- **Output**: `01-product-requirements.md`
|
||||
- **Process**:
|
||||
1. PO generates initial PRD
|
||||
2. System calculates quality score (100-point scale)
|
||||
3. If < 90: User provides feedback → PO revises → Recalculate
|
||||
4. If ≥ 90: User confirms → Save artifact → Next phase
|
||||
|
||||
### Phase 2: System Architecture (Architect)
|
||||
- **Agent**: `bmad-architect` (Winston - System Architect)
|
||||
- **Quality Gate**: Design score ≥ 90/100
|
||||
- **Output**: `02-system-architecture.md`
|
||||
- **Process**:
|
||||
1. Architect reads PRD + repo context
|
||||
2. Generates technical design document
|
||||
3. System calculates design quality score
|
||||
4. If < 90: User provides feedback → Architect revises
|
||||
5. If ≥ 90: User confirms → Save artifact → Next phase
|
||||
|
||||
### Phase 3: Sprint Planning (SM)
|
||||
- **Agent**: `bmad-sm` (Mike - Scrum Master)
|
||||
- **Quality Gate**: User approval
|
||||
- **Output**: `03-sprint-plan.md`
|
||||
- **Process**:
|
||||
1. SM reads PRD + Architecture
|
||||
2. Breaks down tasks with story points
|
||||
3. User reviews sprint plan
|
||||
4. User confirms → Save artifact → Next phase
|
||||
- **Skip**: Use `--direct-dev` to skip this phase
|
||||
|
||||
### Phase 4: Development (Dev)
|
||||
- **Agent**: `bmad-dev` (Alex - Developer)
|
||||
- **Quality Gate**: Code completion
|
||||
- **Output**: Implementation files
|
||||
- **Process**:
|
||||
1. Dev reads all previous artifacts
|
||||
2. Implements features following sprint plan
|
||||
3. Creates or modifies code files
|
||||
4. Completes implementation → Next phase
|
||||
|
||||
### Phase 5: Code Review (Review)
|
||||
- **Agent**: `bmad-review` (Independent Reviewer)
|
||||
- **Quality Gate**: Pass / Pass with Risk / Fail
|
||||
- **Output**: `04-dev-reviewed.md`
|
||||
- **Process**:
|
||||
1. Review reads implementation + all specs
|
||||
2. Performs comprehensive code review
|
||||
3. Generates review report with status:
|
||||
- **Pass**: No issues, proceed to QA
|
||||
- **Pass with Risk**: Non-critical issues noted
|
||||
- **Fail**: Critical issues, return to Dev
|
||||
4. Updates sprint plan with review findings
|
||||
|
||||
**Enhanced Review (Optional)**:
|
||||
- Use GPT-5 via Codex CLI for deeper analysis
|
||||
- Set via `BMAD_REVIEW_MODE=enhanced` environment variable
|
||||
|
||||
### Phase 6: Quality Assurance (QA)
|
||||
- **Agent**: `bmad-qa` (Emma - QA Engineer)
|
||||
- **Quality Gate**: Test execution
|
||||
- **Output**: `05-qa-report.md`
|
||||
- **Process**:
|
||||
1. QA reads implementation + review + all specs
|
||||
2. Creates targeted test strategy
|
||||
3. Executes tests
|
||||
4. Generates QA report
|
||||
5. Workflow complete
|
||||
- **Skip**: Use `--skip-tests` to skip this phase
|
||||
|
||||
## 📊 Quality Scoring System
|
||||
|
||||
### PRD Quality (100 points)
|
||||
- **Business Value** (30): Clear value proposition, user benefits
|
||||
- **Functional Requirements** (25): Complete, unambiguous requirements
|
||||
- **User Experience** (20): User flows, interaction patterns
|
||||
- **Technical Constraints** (15): Performance, security, scalability
|
||||
- **Scope & Priorities** (10): Clear boundaries, must-have vs nice-to-have
|
||||
|
||||
### Architecture Quality (100 points)
|
||||
- **Design Quality** (30): Modularity, maintainability, clarity
|
||||
- **Technology Selection** (25): Appropriate tech stack, justification
|
||||
- **Scalability** (20): Growth handling, performance considerations
|
||||
- **Security** (15): Authentication, authorization, data protection
|
||||
- **Feasibility** (10): Realistic implementation, resource alignment
|
||||
|
||||
### Review Status (3 levels)
|
||||
- **Pass**: No critical issues, code meets standards
|
||||
- **Pass with Risk**: Non-critical issues, recommendations included
|
||||
- **Fail**: Critical issues, requires Dev iteration
|
||||
|
||||
## 📁 Workflow Artifacts
|
||||
|
||||
All documents are saved to `.claude/specs/{feature-name}/`:
|
||||
|
||||
```
|
||||
.claude/specs/e-commerce-checkout/
|
||||
├── 00-repository-context.md # Repo analysis (auto)
|
||||
├── 01-product-requirements.md # PRD (PO, score ≥ 90)
|
||||
├── 02-system-architecture.md # Design (Architect, score ≥ 90)
|
||||
├── 03-sprint-plan.md # Sprint plan (SM, user approved)
|
||||
├── 04-dev-reviewed.md # Code review (Review, Pass/Risk/Fail)
|
||||
└── 05-qa-report.md # Test report (QA, tests executed)
|
||||
```
|
||||
|
||||
Feature name generated from project description (kebab-case: lowercase, spaces/punctuation → `-`).
|
||||
|
||||
## 🔧 Advanced Usage
|
||||
|
||||
### Approval Gates
|
||||
|
||||
Critical phases require explicit user confirmation:
|
||||
|
||||
```
|
||||
Architect: "Technical design complete (Score: 93/100)"
|
||||
System: "Ready to proceed to sprint planning? (yes/no)"
|
||||
User: yes
|
||||
```
|
||||
|
||||
### Iterative Refinement
|
||||
|
||||
Each phase supports feedback loops:
|
||||
|
||||
```
|
||||
PO: "Here's the PRD (Score: 75/100)"
|
||||
User: "Add mobile support and offline mode"
|
||||
PO: "Updated PRD (Score: 92/100) ✅"
|
||||
```
|
||||
|
||||
### Repository Context
|
||||
|
||||
BMAD automatically scans your repository to understand:
|
||||
- Technology stack (languages, frameworks, libraries)
|
||||
- Project structure (directories, modules, patterns)
|
||||
- Existing conventions (naming, formatting, architecture)
|
||||
- Dependencies (package managers, external services)
|
||||
- Integration points (APIs, databases, third-party services)
|
||||
|
||||
### Workflow Variations
|
||||
|
||||
**Fast Prototyping** - Skip non-essential phases:
|
||||
```bash
|
||||
/bmad-pilot "Quick admin UI" --skip-tests --direct-dev
|
||||
# Workflow: PO → Architect → Dev
|
||||
```
|
||||
|
||||
**Architecture-First** - Focus on design:
|
||||
```bash
|
||||
/bmad-architect "Microservices architecture for e-commerce"
|
||||
# Only runs Architect agent
|
||||
```
|
||||
|
||||
**Full Rigor** - All phases with maximum quality:
|
||||
```bash
|
||||
/bmad-pilot "Enterprise payment gateway with PCI compliance"
|
||||
# Workflow: Scan → PO → Architect → SM → Dev → Review → QA
|
||||
```
|
||||
|
||||
## 🎨 Output Style
|
||||
|
||||
BMAD workflow uses a specialized output style that:
|
||||
- Creates phase-separated contexts
|
||||
- Manages agent handoffs with clear boundaries
|
||||
- Tracks quality scores across phases
|
||||
- Handles approval gates with user prompts
|
||||
- Supports Codex CLI integration for enhanced reviews
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started in 5 minutes
|
||||
- **[Plugin System](PLUGIN-SYSTEM.md)** - Installation and configuration
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Alternative workflows
|
||||
- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight alternative
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
1. **Don't skip repository scan** - Helps agents understand your project context
|
||||
2. **Provide detailed descriptions** - Better input → better output
|
||||
3. **Engage with agents** - Provide feedback during quality gates
|
||||
4. **Review artifacts** - Check generated documents before confirming
|
||||
5. **Use appropriate workflows** - Full BMAD for complex features, lightweight for simple tasks
|
||||
6. **Keep artifacts** - They serve as project documentation and context for future work
|
||||
|
||||
---
|
||||
|
||||
**Transform your development with BMAD** - One command, complete agile workflow, quality assured.
|
||||
321
docs/DEVELOPMENT-COMMANDS.md
Normal file
321
docs/DEVELOPMENT-COMMANDS.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# Development Commands Reference
|
||||
|
||||
> Direct slash commands for daily coding tasks without workflow overhead
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
Development Essentials provides focused slash commands for common development tasks. Use these when you need direct implementation without the full workflow structure.
|
||||
|
||||
## 📋 Available Commands
|
||||
|
||||
### `/code` - Direct Implementation
|
||||
|
||||
Implement features, add functionality, or write code directly.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/code "Add input validation for email fields"
|
||||
/code "Implement pagination for user list API"
|
||||
/code "Create database migration for orders table"
|
||||
```
|
||||
|
||||
**Agent**: `code`
|
||||
|
||||
**Best for**:
|
||||
- Clear, well-defined tasks
|
||||
- Quick implementations
|
||||
- Following existing patterns
|
||||
- Adding straightforward features
|
||||
|
||||
### `/debug` - Systematic Debugging
|
||||
|
||||
Analyze and fix bugs with structured debugging approach.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/debug "Login fails with 500 error on invalid credentials"
|
||||
/debug "Memory leak in background worker process"
|
||||
/debug "Race condition in order processing"
|
||||
```
|
||||
|
||||
**Agent**: `debug`
|
||||
|
||||
**Approach**:
|
||||
1. Reproduce the issue
|
||||
2. Analyze root cause
|
||||
3. Propose solution
|
||||
4. Implement fix
|
||||
5. Verify resolution
|
||||
|
||||
### `/test` - Testing Strategy
|
||||
|
||||
Create tests, improve test coverage, or test existing code.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/test "Add unit tests for authentication service"
|
||||
/test "Create integration tests for payment flow"
|
||||
/test "Test edge cases for date parser"
|
||||
```
|
||||
|
||||
**Agent**: `develop` (testing mode)
|
||||
|
||||
**Covers**:
|
||||
- Unit tests
|
||||
- Integration tests
|
||||
- Edge cases
|
||||
- Error scenarios
|
||||
- Test data setup
|
||||
|
||||
### `/optimize` - Performance Tuning
|
||||
|
||||
Improve performance, reduce resource usage, or optimize algorithms.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/optimize "Reduce database queries in dashboard endpoint"
|
||||
/optimize "Speed up report generation process"
|
||||
/optimize "Improve memory usage in data processing pipeline"
|
||||
```
|
||||
|
||||
**Agent**: `develop` (optimization mode)
|
||||
|
||||
**Focus areas**:
|
||||
- Algorithm efficiency
|
||||
- Database query optimization
|
||||
- Caching strategies
|
||||
- Resource utilization
|
||||
- Load time reduction
|
||||
|
||||
### `/bugfix` - Bug Resolution
|
||||
|
||||
Fix specific bugs with focused approach.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/bugfix "Users can't reset password with special characters"
|
||||
/bugfix "Session expires too quickly on mobile"
|
||||
/bugfix "File upload fails for large files"
|
||||
```
|
||||
|
||||
**Agent**: `bugfix`
|
||||
|
||||
**Process**:
|
||||
1. Understand the bug
|
||||
2. Locate problematic code
|
||||
3. Implement fix
|
||||
4. Add regression tests
|
||||
5. Verify fix
|
||||
|
||||
### `/refactor` - Code Improvement
|
||||
|
||||
Improve code structure, readability, or maintainability without changing behavior.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/refactor "Extract user validation logic into separate module"
|
||||
/refactor "Simplify nested conditionals in order processing"
|
||||
/refactor "Remove code duplication in API handlers"
|
||||
```
|
||||
|
||||
**Agent**: `develop` (refactor mode)
|
||||
|
||||
**Goals**:
|
||||
- Improve readability
|
||||
- Reduce complexity
|
||||
- Eliminate duplication
|
||||
- Enhance maintainability
|
||||
- Follow best practices
|
||||
|
||||
### `/review` - Code Validation
|
||||
|
||||
Review code for quality, security, and best practices.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/review "Check authentication implementation for security issues"
|
||||
/review "Validate API error handling patterns"
|
||||
/review "Assess database schema design"
|
||||
```
|
||||
|
||||
**Agent**: Independent reviewer
|
||||
|
||||
**Review criteria**:
|
||||
- Code quality
|
||||
- Security vulnerabilities
|
||||
- Performance issues
|
||||
- Best practices compliance
|
||||
- Maintainability
|
||||
|
||||
### `/ask` - Technical Consultation
|
||||
|
||||
Get technical advice, design patterns, or implementation guidance.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/ask "Best approach for real-time notifications in React"
|
||||
/ask "How to handle database migrations in production"
|
||||
/ask "Design pattern for plugin system"
|
||||
```
|
||||
|
||||
**Agent**: Technical consultant
|
||||
|
||||
**Provides**:
|
||||
- Architecture guidance
|
||||
- Technology recommendations
|
||||
- Design patterns
|
||||
- Best practices
|
||||
- Trade-off analysis
|
||||
|
||||
### `/docs` - Documentation
|
||||
|
||||
Generate or improve documentation.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/docs "Create API documentation for user endpoints"
|
||||
/docs "Add JSDoc comments to utility functions"
|
||||
/docs "Write README for authentication module"
|
||||
```
|
||||
|
||||
**Agent**: Documentation writer
|
||||
|
||||
**Creates**:
|
||||
- Code comments
|
||||
- API documentation
|
||||
- README files
|
||||
- Usage examples
|
||||
- Architecture docs
|
||||
|
||||
### `/think` - Advanced Analysis
|
||||
|
||||
Deep reasoning and analysis for complex problems.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/think "Analyze scalability bottlenecks in current architecture"
|
||||
/think "Evaluate different approaches for data synchronization"
|
||||
/think "Design migration strategy from monolith to microservices"
|
||||
```
|
||||
|
||||
**Agent**: `gpt5` (deep reasoning)
|
||||
|
||||
**Best for**:
|
||||
- Complex architectural decisions
|
||||
- Multi-faceted problems
|
||||
- Trade-off analysis
|
||||
- Strategic planning
|
||||
- System design
|
||||
|
||||
## 🔄 Command Workflows
|
||||
|
||||
### Simple Feature Development
|
||||
|
||||
```bash
|
||||
# 1. Ask for guidance
|
||||
/ask "Best way to implement rate limiting in Express"
|
||||
|
||||
# 2. Implement the feature
|
||||
/code "Add rate limiting middleware to API routes"
|
||||
|
||||
# 3. Add tests
|
||||
/test "Create tests for rate limiting behavior"
|
||||
|
||||
# 4. Review implementation
|
||||
/review "Validate rate limiting implementation"
|
||||
```
|
||||
|
||||
### Bug Investigation and Fix
|
||||
|
||||
```bash
|
||||
# 1. Debug the issue
|
||||
/debug "API returns 500 on concurrent requests"
|
||||
|
||||
# 2. Fix the bug
|
||||
/bugfix "Add mutex lock to prevent race condition"
|
||||
|
||||
# 3. Add regression tests
|
||||
/test "Test concurrent request handling"
|
||||
```
|
||||
|
||||
### Code Quality Improvement
|
||||
|
||||
```bash
|
||||
# 1. Review current code
|
||||
/review "Analyze user service for improvements"
|
||||
|
||||
# 2. Refactor based on findings
|
||||
/refactor "Simplify user validation logic"
|
||||
|
||||
# 3. Optimize performance
|
||||
/optimize "Cache frequently accessed user data"
|
||||
|
||||
# 4. Update documentation
|
||||
/docs "Document user service API"
|
||||
```
|
||||
|
||||
## 🎯 When to Use What
|
||||
|
||||
### Use Direct Commands When:
|
||||
- Task is clear and well-defined
|
||||
- No complex planning needed
|
||||
- Fast iteration is priority
|
||||
- Working within existing patterns
|
||||
|
||||
### Use Requirements Workflow When:
|
||||
- Feature has unclear requirements
|
||||
- Need documented specifications
|
||||
- Multiple implementation approaches possible
|
||||
- Quality gates desired
|
||||
|
||||
### Use BMAD Workflow When:
|
||||
- Complex business requirements
|
||||
- Architecture design needed
|
||||
- Sprint planning required
|
||||
- Multiple stakeholders involved
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
1. **Be Specific**: Provide clear, detailed descriptions
|
||||
- ❌ `/code "fix the bug"`
|
||||
- ✅ `/code "Fix null pointer exception in user login when email is missing"`
|
||||
|
||||
2. **One Task Per Command**: Keep commands focused
|
||||
- ❌ `/code "Add feature X, fix bug Y, refactor module Z"`
|
||||
- ✅ `/code "Add email validation to registration form"`
|
||||
|
||||
3. **Provide Context**: Include relevant details
|
||||
- ✅ `/debug "Login API returns 401 after password change, only on Safari"`
|
||||
|
||||
4. **Use Appropriate Command**: Match command to task type
|
||||
- Use `/bugfix` for bugs, not `/code`
|
||||
- Use `/refactor` for restructuring, not `/optimize`
|
||||
- Use `/think` for complex analysis, not `/ask`
|
||||
|
||||
5. **Chain Commands**: Break complex tasks into steps
|
||||
```bash
|
||||
/ask "How to implement OAuth2"
|
||||
/code "Implement OAuth2 authorization flow"
|
||||
/test "Add OAuth2 integration tests"
|
||||
/review "Validate OAuth2 security"
|
||||
/docs "Document OAuth2 setup process"
|
||||
```
|
||||
|
||||
## 🔌 Agent Configuration
|
||||
|
||||
All commands use specialized agents configured in:
|
||||
- `development-essentials/agents/`
|
||||
- Agent prompt templates
|
||||
- Tool access permissions
|
||||
- Output formatting
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Full agile methodology
|
||||
- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight workflow
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
- **[Plugin System](PLUGIN-SYSTEM.md)** - Installation and configuration
|
||||
|
||||
---
|
||||
|
||||
**Development Essentials** - Direct commands for productive coding without workflow overhead.
|
||||
348
docs/PLUGIN-SYSTEM.md
Normal file
348
docs/PLUGIN-SYSTEM.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# Plugin System Guide
|
||||
|
||||
> Native Claude Code plugin support for modular workflow installation
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
This repository provides 4 ready-to-use Claude Code plugins that can be installed individually or as a complete suite.
|
||||
|
||||
## 📦 Available Plugins
|
||||
|
||||
### 1. bmad-agile-workflow
|
||||
|
||||
**Complete BMAD methodology with 6 specialized agents**
|
||||
|
||||
**Commands**:
|
||||
- `/bmad-pilot` - Full agile workflow orchestration
|
||||
|
||||
**Agents**:
|
||||
- `bmad-po` - Product Owner (Sarah)
|
||||
- `bmad-architect` - System Architect (Winston)
|
||||
- `bmad-sm` - Scrum Master (Mike)
|
||||
- `bmad-dev` - Developer (Alex)
|
||||
- `bmad-review` - Code Reviewer
|
||||
- `bmad-qa` - QA Engineer (Emma)
|
||||
- `bmad-orchestrator` - Main orchestrator
|
||||
|
||||
**Use for**: Enterprise projects, complex features, full agile process
|
||||
|
||||
### 2. requirements-driven-workflow
|
||||
|
||||
**Streamlined requirements-to-code workflow**
|
||||
|
||||
**Commands**:
|
||||
- `/requirements-pilot` - Requirements-driven development flow
|
||||
|
||||
**Agents**:
|
||||
- `requirements-generate` - Requirements generation
|
||||
- `requirements-code` - Code implementation
|
||||
- `requirements-review` - Code review
|
||||
- `requirements-testing` - Testing strategy
|
||||
|
||||
**Use for**: Quick prototyping, simple features, rapid development
|
||||
|
||||
### 3. development-essentials
|
||||
|
||||
**Core development slash commands**
|
||||
|
||||
**Commands**:
|
||||
- `/code` - Direct implementation
|
||||
- `/debug` - Systematic debugging
|
||||
- `/test` - Testing strategy
|
||||
- `/optimize` - Performance tuning
|
||||
- `/bugfix` - Bug resolution
|
||||
- `/refactor` - Code improvement
|
||||
- `/review` - Code validation
|
||||
- `/ask` - Technical consultation
|
||||
- `/docs` - Documentation
|
||||
- `/think` - Advanced analysis
|
||||
|
||||
**Agents**:
|
||||
- `code` - Code implementation
|
||||
- `bugfix` - Bug fixing
|
||||
- `debug` - Debugging
|
||||
- `develop` - General development
|
||||
|
||||
**Use for**: Daily coding tasks, quick implementations
|
||||
|
||||
### 4. advanced-ai-agents
|
||||
|
||||
**GPT-5 deep reasoning integration**
|
||||
|
||||
**Commands**: None (agent-only)
|
||||
|
||||
**Agents**:
|
||||
- `gpt5` - Deep reasoning and analysis
|
||||
|
||||
**Use for**: Complex architectural decisions, strategic planning
|
||||
|
||||
## 🚀 Installation Methods
|
||||
|
||||
### Method 1: Plugin Commands (Recommended)
|
||||
|
||||
```bash
|
||||
# List all available plugins
|
||||
/plugin list
|
||||
|
||||
# Get detailed information about a plugin
|
||||
/plugin info bmad-agile-workflow
|
||||
|
||||
# Install a specific plugin
|
||||
/plugin install bmad-agile-workflow
|
||||
|
||||
# Install all plugins
|
||||
/plugin install bmad-agile-workflow
|
||||
/plugin install requirements-driven-workflow
|
||||
/plugin install development-essentials
|
||||
/plugin install advanced-ai-agents
|
||||
|
||||
# Remove an installed plugin
|
||||
/plugin remove development-essentials
|
||||
```
|
||||
|
||||
### Method 2: Repository Reference
|
||||
|
||||
```bash
|
||||
# Install from GitHub repository
|
||||
/plugin github.com/cexll/myclaude
|
||||
```
|
||||
|
||||
This will present all available plugins from the repository.
|
||||
|
||||
### Method 3: Make Commands
|
||||
|
||||
For traditional installation or selective deployment:
|
||||
|
||||
```bash
|
||||
# Install everything
|
||||
make install
|
||||
|
||||
# Deploy specific workflows
|
||||
make deploy-bmad # BMAD workflow only
|
||||
make deploy-requirements # Requirements workflow only
|
||||
make deploy-commands # All slash commands
|
||||
make deploy-agents # All agents
|
||||
|
||||
# Deploy everything
|
||||
make deploy-all
|
||||
|
||||
# View all options
|
||||
make help
|
||||
```
|
||||
|
||||
### Method 4: Manual Installation
|
||||
|
||||
Copy files to Claude Code configuration directories:
|
||||
|
||||
**Commands**:
|
||||
```bash
|
||||
cp bmad-agile-workflow/commands/*.md ~/.config/claude/commands/
|
||||
cp requirements-driven-workflow/commands/*.md ~/.config/claude/commands/
|
||||
cp development-essentials/commands/*.md ~/.config/claude/commands/
|
||||
```
|
||||
|
||||
**Agents**:
|
||||
```bash
|
||||
cp bmad-agile-workflow/agents/*.md ~/.config/claude/agents/
|
||||
cp requirements-driven-workflow/agents/*.md ~/.config/claude/agents/
|
||||
cp development-essentials/agents/*.md ~/.config/claude/agents/
|
||||
cp advanced-ai-agents/agents/*.md ~/.config/claude/agents/
|
||||
```
|
||||
|
||||
**Output Styles** (optional):
|
||||
```bash
|
||||
cp output-styles/*.md ~/.config/claude/output-styles/
|
||||
```
|
||||
|
||||
## 📋 Plugin Configuration
|
||||
|
||||
Plugins are defined in `.claude-plugin/marketplace.json` following the Claude Code plugin specification.
|
||||
|
||||
### Plugin Metadata Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"displayName": "Human Readable Name",
|
||||
"description": "Plugin description",
|
||||
"version": "1.0.0",
|
||||
"author": "Author Name",
|
||||
"category": "workflow|development|analysis",
|
||||
"keywords": ["keyword1", "keyword2"],
|
||||
"commands": ["command1", "command2"],
|
||||
"agents": ["agent1", "agent2"]
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Plugin Management
|
||||
|
||||
### Check Installed Plugins
|
||||
|
||||
```bash
|
||||
/plugin list
|
||||
```
|
||||
|
||||
Shows all installed plugins with their status.
|
||||
|
||||
### Plugin Information
|
||||
|
||||
```bash
|
||||
/plugin info <plugin-name>
|
||||
```
|
||||
|
||||
Displays detailed information:
|
||||
- Description
|
||||
- Version
|
||||
- Commands provided
|
||||
- Agents included
|
||||
- Author and keywords
|
||||
|
||||
### Update Plugins
|
||||
|
||||
Plugins are updated when you pull the latest repository changes:
|
||||
|
||||
```bash
|
||||
git pull origin main
|
||||
make install
|
||||
```
|
||||
|
||||
### Uninstall Plugins
|
||||
|
||||
```bash
|
||||
/plugin remove <plugin-name>
|
||||
```
|
||||
|
||||
Or manually remove files:
|
||||
|
||||
```bash
|
||||
# Remove commands
|
||||
rm ~/.config/claude/commands/<command-name>.md
|
||||
|
||||
# Remove agents
|
||||
rm ~/.config/claude/agents/<agent-name>.md
|
||||
```
|
||||
|
||||
## 🎯 Plugin Selection Guide
|
||||
|
||||
### Install Everything (Recommended for New Users)
|
||||
|
||||
```bash
|
||||
make install
|
||||
```
|
||||
|
||||
Provides complete functionality with all workflows and commands.
|
||||
|
||||
### Selective Installation
|
||||
|
||||
**For Agile Teams**:
|
||||
```bash
|
||||
/plugin install bmad-agile-workflow
|
||||
```
|
||||
|
||||
**For Rapid Development**:
|
||||
```bash
|
||||
/plugin install requirements-driven-workflow
|
||||
/plugin install development-essentials
|
||||
```
|
||||
|
||||
**For Individual Developers**:
|
||||
```bash
|
||||
/plugin install development-essentials
|
||||
/plugin install advanced-ai-agents
|
||||
```
|
||||
|
||||
**For Code Quality Focus**:
|
||||
```bash
|
||||
/plugin install development-essentials # Includes /review
|
||||
/plugin install bmad-agile-workflow # Includes bmad-review
|
||||
```
|
||||
|
||||
## 📁 Directory Structure
|
||||
|
||||
```
|
||||
myclaude/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json # Plugin registry
|
||||
├── bmad-agile-workflow/
|
||||
│ ├── commands/
|
||||
│ │ └── bmad-pilot.md
|
||||
│ └── agents/
|
||||
│ ├── bmad-po.md
|
||||
│ ├── bmad-architect.md
|
||||
│ ├── bmad-sm.md
|
||||
│ ├── bmad-dev.md
|
||||
│ ├── bmad-review.md
|
||||
│ ├── bmad-qa.md
|
||||
│ └── bmad-orchestrator.md
|
||||
├── requirements-driven-workflow/
|
||||
│ ├── commands/
|
||||
│ │ └── requirements-pilot.md
|
||||
│ └── agents/
|
||||
│ ├── requirements-generate.md
|
||||
│ ├── requirements-code.md
|
||||
│ ├── requirements-review.md
|
||||
│ └── requirements-testing.md
|
||||
├── development-essentials/
|
||||
│ ├── commands/
|
||||
│ │ ├── code.md
|
||||
│ │ ├── debug.md
|
||||
│ │ ├── test.md
|
||||
│ │ └── ... (more commands)
|
||||
│ └── agents/
|
||||
│ ├── code.md
|
||||
│ ├── bugfix.md
|
||||
│ ├── debug.md
|
||||
│ └── develop.md
|
||||
├── advanced-ai-agents/
|
||||
│ └── agents/
|
||||
│ └── gpt5.md
|
||||
└── output-styles/
|
||||
└── bmad-phase-context.md
|
||||
```
|
||||
|
||||
## 🔄 Plugin Dependencies
|
||||
|
||||
**No Dependencies**: All plugins work independently
|
||||
|
||||
**Complementary Combinations**:
|
||||
- BMAD + Advanced Agents (enhanced reviews)
|
||||
- Requirements + Development Essentials (complete toolkit)
|
||||
- All four plugins (full suite)
|
||||
|
||||
## 🛠️ Makefile Reference
|
||||
|
||||
```bash
|
||||
# Installation
|
||||
make install # Install all plugins
|
||||
make deploy-all # Deploy all configurations
|
||||
|
||||
# Selective Deployment
|
||||
make deploy-bmad # BMAD workflow only
|
||||
make deploy-requirements # Requirements workflow only
|
||||
make deploy-commands # All slash commands only
|
||||
make deploy-agents # All agents only
|
||||
|
||||
# Testing
|
||||
make test-bmad # Test BMAD workflow
|
||||
make test-requirements # Test Requirements workflow
|
||||
|
||||
# Cleanup
|
||||
make clean # Remove generated artifacts
|
||||
make help # Show all available commands
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Complete BMAD guide
|
||||
- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight workflow guide
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Command reference
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
|
||||
## 🔗 External Resources
|
||||
|
||||
- **[Claude Code Plugin Docs](https://docs.claude.com/en/docs/claude-code/plugins)** - Official plugin documentation
|
||||
- **[Claude Code CLI](https://claude.ai/code)** - Claude Code interface
|
||||
|
||||
---
|
||||
|
||||
**Modular Installation** - Install only what you need, when you need it.
|
||||
326
docs/QUICK-START.md
Normal file
326
docs/QUICK-START.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# Quick Start Guide
|
||||
|
||||
> Get started with Claude Code Multi-Agent Workflow System in 5 minutes
|
||||
|
||||
## 🚀 Installation (2 minutes)
|
||||
|
||||
### Option 1: Plugin System (Fastest)
|
||||
|
||||
```bash
|
||||
# Install everything with one command
|
||||
/plugin github.com/cexll/myclaude
|
||||
```
|
||||
|
||||
### Option 2: Make Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cexll/myclaude.git
|
||||
cd myclaude
|
||||
make install
|
||||
```
|
||||
|
||||
### Option 3: Selective Install
|
||||
|
||||
```bash
|
||||
# Install only what you need
|
||||
/plugin install bmad-agile-workflow # Full agile workflow
|
||||
/plugin install development-essentials # Daily coding commands
|
||||
```
|
||||
|
||||
## 🎯 Your First Workflow (3 minutes)
|
||||
|
||||
### Try BMAD Workflow
|
||||
|
||||
Complete agile development automation:
|
||||
|
||||
```bash
|
||||
/bmad-pilot "Build a simple todo list API with CRUD operations"
|
||||
```
|
||||
|
||||
**What happens**:
|
||||
1. **Product Owner** generates requirements (PRD)
|
||||
2. **Architect** designs system architecture
|
||||
3. **Scrum Master** creates sprint plan
|
||||
4. **Developer** implements code
|
||||
5. **Reviewer** performs code review
|
||||
6. **QA** runs tests
|
||||
|
||||
All documents saved to `.claude/specs/todo-list-api/`
|
||||
|
||||
### Try Requirements Workflow
|
||||
|
||||
Fast prototyping:
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Add user authentication to existing API"
|
||||
```
|
||||
|
||||
**What happens**:
|
||||
1. Generate functional requirements
|
||||
2. Implement code
|
||||
3. Review implementation
|
||||
4. Create tests
|
||||
|
||||
### Try Direct Commands
|
||||
|
||||
Quick coding without workflow:
|
||||
|
||||
```bash
|
||||
# Implement a feature
|
||||
/code "Add input validation for email fields"
|
||||
|
||||
# Debug an issue
|
||||
/debug "API returns 500 on missing parameters"
|
||||
|
||||
# Add tests
|
||||
/test "Create unit tests for validation logic"
|
||||
```
|
||||
|
||||
## 📋 Common Use Cases
|
||||
|
||||
### 1. New Feature Development
|
||||
|
||||
**Complex Feature** (use BMAD):
|
||||
```bash
|
||||
/bmad-pilot "User authentication system with OAuth2, MFA, and role-based access control"
|
||||
```
|
||||
|
||||
**Simple Feature** (use Requirements):
|
||||
```bash
|
||||
/requirements-pilot "Add pagination to user list endpoint"
|
||||
```
|
||||
|
||||
**Tiny Feature** (use direct command):
|
||||
```bash
|
||||
/code "Add created_at timestamp to user model"
|
||||
```
|
||||
|
||||
### 2. Bug Fixing
|
||||
|
||||
**Complex Bug** (use debug):
|
||||
```bash
|
||||
/debug "Memory leak in background job processor"
|
||||
```
|
||||
|
||||
**Simple Bug** (use bugfix):
|
||||
```bash
|
||||
/bugfix "Login button not working on mobile Safari"
|
||||
```
|
||||
|
||||
### 3. Code Quality
|
||||
|
||||
**Full Review**:
|
||||
```bash
|
||||
/review "Review authentication module for security issues"
|
||||
```
|
||||
|
||||
**Refactoring**:
|
||||
```bash
|
||||
/refactor "Simplify user validation logic and remove duplication"
|
||||
```
|
||||
|
||||
**Optimization**:
|
||||
```bash
|
||||
/optimize "Reduce database queries in dashboard API"
|
||||
```
|
||||
|
||||
## 🎨 Workflow Selection Guide
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Choose Your Workflow │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
Complex Business Feature + Architecture Needed
|
||||
↓
|
||||
🏢 Use BMAD Workflow
|
||||
/bmad-pilot "description"
|
||||
• 6 specialized agents
|
||||
• Quality gates (PRD ≥90, Design ≥90)
|
||||
• Complete documentation
|
||||
• Sprint planning included
|
||||
|
||||
────────────────────────────────────────────────────────
|
||||
|
||||
Clear Requirements + Fast Iteration Needed
|
||||
↓
|
||||
⚡ Use Requirements Workflow
|
||||
/requirements-pilot "description"
|
||||
• 4 phases: Requirements → Code → Review → Test
|
||||
• Quality gate (Requirements ≥90)
|
||||
• Minimal documentation
|
||||
• Direct to implementation
|
||||
|
||||
────────────────────────────────────────────────────────
|
||||
|
||||
Well-Defined Task + No Workflow Overhead
|
||||
↓
|
||||
🔧 Use Direct Commands
|
||||
/code | /debug | /test | /optimize
|
||||
• Single-purpose commands
|
||||
• Immediate execution
|
||||
• No documentation overhead
|
||||
• Perfect for daily tasks
|
||||
```
|
||||
|
||||
## 💡 Tips for Success
|
||||
|
||||
### 1. Be Specific
|
||||
|
||||
**❌ Bad**:
|
||||
```bash
|
||||
/bmad-pilot "Build an app"
|
||||
```
|
||||
|
||||
**✅ Good**:
|
||||
```bash
|
||||
/bmad-pilot "Build a task management API with user authentication, task CRUD,
|
||||
task assignment, and real-time notifications via WebSocket"
|
||||
```
|
||||
|
||||
### 2. Provide Context
|
||||
|
||||
Include relevant technical details:
|
||||
```bash
|
||||
/code "Add Redis caching to user profile endpoint, cache TTL 5 minutes,
|
||||
invalidate on profile update"
|
||||
```
|
||||
|
||||
### 3. Engage with Agents
|
||||
|
||||
During BMAD workflow, provide feedback at quality gates:
|
||||
|
||||
```
|
||||
PO: "Here's the PRD (Score: 85/100)"
|
||||
You: "Add mobile app support and offline mode requirements"
|
||||
PO: "Updated PRD (Score: 94/100) ✅"
|
||||
```
|
||||
|
||||
### 4. Review Generated Artifacts
|
||||
|
||||
Check documents before confirming:
|
||||
- `.claude/specs/{feature}/01-product-requirements.md`
|
||||
- `.claude/specs/{feature}/02-system-architecture.md`
|
||||
- `.claude/specs/{feature}/03-sprint-plan.md`
|
||||
|
||||
### 5. Chain Commands for Complex Tasks
|
||||
|
||||
Break down complex work:
|
||||
```bash
|
||||
/ask "Best approach for implementing real-time chat"
|
||||
/bmad-pilot "Real-time chat system with message history and typing indicators"
|
||||
/test "Add integration tests for chat message delivery"
|
||||
/docs "Document chat API endpoints and WebSocket events"
|
||||
```
|
||||
|
||||
## 🎓 Learning Path
|
||||
|
||||
**Day 1**: Try direct commands
|
||||
```bash
|
||||
/code "simple task"
|
||||
/test "add some tests"
|
||||
/review "check my code"
|
||||
```
|
||||
|
||||
**Day 2**: Try Requirements workflow
|
||||
```bash
|
||||
/requirements-pilot "small feature"
|
||||
```
|
||||
|
||||
**Week 2**: Try BMAD workflow
|
||||
```bash
|
||||
/bmad-pilot "larger feature"
|
||||
```
|
||||
|
||||
**Week 3**: Combine workflows
|
||||
```bash
|
||||
# Use BMAD for planning
|
||||
/bmad-pilot "new module" --direct-dev
|
||||
|
||||
# Use Requirements for sprint tasks
|
||||
/requirements-pilot "individual task from sprint"
|
||||
|
||||
# Use commands for daily work
|
||||
/code "quick fix"
|
||||
/test "add test"
|
||||
```
|
||||
|
||||
## 📚 Next Steps
|
||||
|
||||
### Explore Documentation
|
||||
|
||||
- **[BMAD Workflow Guide](BMAD-WORKFLOW.md)** - Deep dive into full agile workflow
|
||||
- **[Requirements Workflow Guide](REQUIREMENTS-WORKFLOW.md)** - Learn lightweight development
|
||||
- **[Development Commands Reference](DEVELOPMENT-COMMANDS.md)** - All command details
|
||||
- **[Plugin System Guide](PLUGIN-SYSTEM.md)** - Plugin management
|
||||
|
||||
### Try Advanced Features
|
||||
|
||||
**BMAD Options**:
|
||||
```bash
|
||||
# Skip testing for prototype
|
||||
/bmad-pilot "prototype" --skip-tests
|
||||
|
||||
# Skip sprint planning for quick dev
|
||||
/bmad-pilot "feature" --direct-dev
|
||||
|
||||
# Skip repo scan (if context exists)
|
||||
/bmad-pilot "feature" --skip-scan
|
||||
```
|
||||
|
||||
**Individual Agents**:
|
||||
```bash
|
||||
# Just requirements
|
||||
/bmad-po "feature requirements"
|
||||
|
||||
# Just architecture
|
||||
/bmad-architect "system design"
|
||||
|
||||
# Just orchestration
|
||||
/bmad-orchestrator "complex project coordination"
|
||||
```
|
||||
|
||||
### Check Quality
|
||||
|
||||
Run tests and validation:
|
||||
```bash
|
||||
make test-bmad # Test BMAD workflow
|
||||
make test-requirements # Test Requirements workflow
|
||||
```
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
**Commands not found**?
|
||||
```bash
|
||||
# Verify installation
|
||||
/plugin list
|
||||
|
||||
# Reinstall if needed
|
||||
make install
|
||||
```
|
||||
|
||||
**Agents not working**?
|
||||
```bash
|
||||
# Check agent configuration
|
||||
ls ~/.config/claude/agents/
|
||||
|
||||
# Redeploy agents
|
||||
make deploy-agents
|
||||
```
|
||||
|
||||
**Output styles missing**?
|
||||
```bash
|
||||
# Deploy output styles
|
||||
cp output-styles/*.md ~/.config/claude/output-styles/
|
||||
```
|
||||
|
||||
## 📞 Get Help
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/cexll/myclaude/issues)
|
||||
- **Documentation**: [docs/](.)
|
||||
- **Examples**: Check `.claude/specs/` after running workflows
|
||||
- **Make Help**: Run `make help` for all commands
|
||||
|
||||
---
|
||||
|
||||
**You're ready!** Start with `/code "your first task"` and explore from there.
|
||||
259
docs/REQUIREMENTS-WORKFLOW.md
Normal file
259
docs/REQUIREMENTS-WORKFLOW.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Requirements-Driven Workflow Guide
|
||||
|
||||
> Lightweight alternative to BMAD for rapid prototyping and simple feature development
|
||||
|
||||
## 🎯 What is Requirements Workflow?
|
||||
|
||||
A streamlined 4-phase workflow that focuses on getting from requirements to working code quickly:
|
||||
|
||||
**Requirements → Implementation → Review → Testing**
|
||||
|
||||
Perfect for:
|
||||
- Quick prototypes
|
||||
- Small features
|
||||
- Bug fixes with clear scope
|
||||
- Projects without complex architecture needs
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Basic Command
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Implement JWT authentication with refresh tokens"
|
||||
|
||||
# Automated workflow:
|
||||
# 1. Requirements generation (90% quality gate)
|
||||
# 2. Code implementation
|
||||
# 3. Code review
|
||||
# 4. Testing strategy
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
**Use Requirements Workflow** when:
|
||||
- Feature scope is clear and simple
|
||||
- No complex architecture design needed
|
||||
- Fast iteration is priority
|
||||
- You want minimal workflow overhead
|
||||
|
||||
**Use BMAD Workflow** when:
|
||||
- Complex business requirements
|
||||
- Multiple systems integration
|
||||
- Architecture design is critical
|
||||
- Need detailed sprint planning
|
||||
|
||||
## 📋 Workflow Phases
|
||||
|
||||
### Phase 1: Requirements Generation
|
||||
- **Agent**: `requirements-generate`
|
||||
- **Quality Gate**: Requirements score ≥ 90/100
|
||||
- **Output**: Functional requirements document
|
||||
- **Focus**:
|
||||
- Clear functional requirements
|
||||
- Acceptance criteria
|
||||
- Technical constraints
|
||||
- Implementation notes
|
||||
|
||||
**Quality Criteria (100 points)**:
|
||||
- Clarity (30): Unambiguous, well-defined
|
||||
- Completeness (25): All aspects covered
|
||||
- Testability (20): Clear verification points
|
||||
- Technical Feasibility (15): Realistic implementation
|
||||
- Scope Definition (10): Clear boundaries
|
||||
|
||||
### Phase 2: Code Implementation
|
||||
- **Agent**: `requirements-code`
|
||||
- **Quality Gate**: Code completion
|
||||
- **Output**: Implementation files
|
||||
- **Process**:
|
||||
1. Read requirements + repository context
|
||||
2. Implement features following requirements
|
||||
3. Create or modify code files
|
||||
4. Follow existing code conventions
|
||||
|
||||
### Phase 3: Code Review
|
||||
- **Agent**: `requirements-review`
|
||||
- **Quality Gate**: Pass / Pass with Risk / Fail
|
||||
- **Output**: Review report
|
||||
- **Focus**:
|
||||
- Code quality
|
||||
- Requirements alignment
|
||||
- Security concerns
|
||||
- Performance issues
|
||||
- Best practices compliance
|
||||
|
||||
**Review Status**:
|
||||
- **Pass**: Meets standards, ready for testing
|
||||
- **Pass with Risk**: Minor issues noted
|
||||
- **Fail**: Requires implementation revision
|
||||
|
||||
### Phase 4: Testing Strategy
|
||||
- **Agent**: `requirements-testing`
|
||||
- **Quality Gate**: Test execution
|
||||
- **Output**: Test report
|
||||
- **Process**:
|
||||
1. Create test strategy from requirements
|
||||
2. Generate test cases
|
||||
3. Execute tests (unit, integration)
|
||||
4. Report results
|
||||
|
||||
## 📁 Workflow Artifacts
|
||||
|
||||
Generated in `.claude/requirements/{feature-name}/`:
|
||||
|
||||
```
|
||||
.claude/requirements/jwt-authentication/
|
||||
├── 01-requirements.md # Functional requirements (score ≥ 90)
|
||||
├── 02-implementation.md # Implementation summary
|
||||
├── 03-review.md # Code review report
|
||||
└── 04-testing.md # Test strategy and results
|
||||
```
|
||||
|
||||
## 🔧 Command Options
|
||||
|
||||
```bash
|
||||
# Standard workflow
|
||||
/requirements-pilot "Add API rate limiting"
|
||||
|
||||
# With specific technology
|
||||
/requirements-pilot "Redis caching layer with TTL management"
|
||||
|
||||
# Bug fix with requirements
|
||||
/requirements-pilot "Fix login session timeout issue"
|
||||
```
|
||||
|
||||
## 📊 Quality Scoring
|
||||
|
||||
### Requirements Score (100 points)
|
||||
|
||||
| Category | Points | Description |
|
||||
|----------|--------|-------------|
|
||||
| Clarity | 30 | Unambiguous, well-defined requirements |
|
||||
| Completeness | 25 | All functional aspects covered |
|
||||
| Testability | 20 | Clear acceptance criteria |
|
||||
| Technical Feasibility | 15 | Realistic implementation plan |
|
||||
| Scope Definition | 10 | Clear feature boundaries |
|
||||
|
||||
**Threshold**: ≥ 90 points to proceed
|
||||
|
||||
### Automatic Optimization
|
||||
|
||||
If initial score < 90:
|
||||
1. User provides feedback
|
||||
2. Agent revises requirements
|
||||
3. System recalculates score
|
||||
4. Repeat until ≥ 90
|
||||
5. User confirms → Save → Next phase
|
||||
|
||||
## 🎯 Comparison: Requirements vs BMAD
|
||||
|
||||
| Aspect | Requirements Workflow | BMAD Workflow |
|
||||
|--------|----------------------|---------------|
|
||||
| **Phases** | 4 (Requirements → Code → Review → Test) | 6 (PO → Arch → SM → Dev → Review → QA) |
|
||||
| **Duration** | Fast (hours) | Thorough (days) |
|
||||
| **Documentation** | Minimal | Comprehensive |
|
||||
| **Quality Gates** | 1 (Requirements ≥ 90) | 2 (PRD ≥ 90, Design ≥ 90) |
|
||||
| **Approval Points** | None | Multiple (after PRD, Architecture, Sprint Plan) |
|
||||
| **Best For** | Simple features, prototypes | Complex features, enterprise projects |
|
||||
| **Artifacts** | 4 documents | 6 documents |
|
||||
| **Planning** | Direct implementation | Sprint planning included |
|
||||
| **Architecture** | Implicit in requirements | Explicit design phase |
|
||||
|
||||
## 💡 Usage Examples
|
||||
|
||||
### Example 1: API Feature
|
||||
|
||||
```bash
|
||||
/requirements-pilot "REST API endpoint for user profile updates with validation"
|
||||
|
||||
# Generated requirements include:
|
||||
# - Endpoint specification (PUT /api/users/:id/profile)
|
||||
# - Request/response schemas
|
||||
# - Validation rules
|
||||
# - Error handling
|
||||
# - Authentication requirements
|
||||
|
||||
# Implementation follows directly
|
||||
# Review checks API best practices
|
||||
# Testing includes endpoint testing
|
||||
```
|
||||
|
||||
### Example 2: Database Schema
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Add audit logging table for user actions"
|
||||
|
||||
# Generated requirements include:
|
||||
# - Table schema definition
|
||||
# - Indexing strategy
|
||||
# - Retention policy
|
||||
# - Query patterns
|
||||
|
||||
# Implementation creates migration
|
||||
# Review checks schema design
|
||||
# Testing verifies logging behavior
|
||||
```
|
||||
|
||||
### Example 3: Bug Fix
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Fix race condition in order processing queue"
|
||||
|
||||
# Generated requirements include:
|
||||
# - Problem description
|
||||
# - Root cause analysis
|
||||
# - Solution approach
|
||||
# - Verification steps
|
||||
|
||||
# Implementation applies fix
|
||||
# Review checks concurrency handling
|
||||
# Testing includes stress tests
|
||||
```
|
||||
|
||||
## 🔄 Iterative Refinement
|
||||
|
||||
Each phase supports feedback:
|
||||
|
||||
```
|
||||
Agent: "Requirements complete (Score: 85/100)"
|
||||
User: "Add error handling for network failures"
|
||||
Agent: "Updated requirements (Score: 93/100) ✅"
|
||||
```
|
||||
|
||||
## 🚀 Advanced Usage
|
||||
|
||||
### Combining with Individual Commands
|
||||
|
||||
```bash
|
||||
# Generate requirements only
|
||||
/requirements-generate "OAuth2 integration requirements"
|
||||
|
||||
# Just code implementation (requires existing requirements)
|
||||
/requirements-code "Implement based on requirements.md"
|
||||
|
||||
# Standalone review
|
||||
/requirements-review "Review current implementation"
|
||||
```
|
||||
|
||||
### Integration with BMAD
|
||||
|
||||
Use Requirements Workflow for sub-tasks within BMAD sprints:
|
||||
|
||||
```bash
|
||||
# BMAD creates sprint plan
|
||||
/bmad-pilot "E-commerce platform"
|
||||
|
||||
# Use Requirements for individual sprint tasks
|
||||
/requirements-pilot "Shopping cart session management"
|
||||
/requirements-pilot "Payment webhook handling"
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Full agile methodology
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Direct coding commands
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
|
||||
---
|
||||
|
||||
**Requirements-Driven Development** - From requirements to working code in hours, not days.
|
||||
Reference in New Issue
Block a user