From 9dea5d37efd83c01f985611f57e562c986add085 Mon Sep 17 00:00:00 2001 From: "swe-agent[bot]" <0+swe-agent[bot]@users.noreply.github.com> Date: Mon, 20 Oct 2025 07:24:53 +0000 Subject: [PATCH] Optimize README structure - Solution A (modular) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- README.md | 301 ++++++----------------------- README_CN.md | 114 +++++++++++ docs/ADVANCED-AGENTS.md | 315 ++++++++++++++++++++++++++++++ docs/BMAD-WORKFLOW.md | 258 +++++++++++++++++++++++++ docs/DEVELOPMENT-COMMANDS.md | 321 +++++++++++++++++++++++++++++++ docs/PLUGIN-SYSTEM.md | 348 ++++++++++++++++++++++++++++++++++ docs/QUICK-START.md | 326 +++++++++++++++++++++++++++++++ docs/REQUIREMENTS-WORKFLOW.md | 259 +++++++++++++++++++++++++ 8 files changed, 2004 insertions(+), 238 deletions(-) create mode 100644 README_CN.md create mode 100644 docs/ADVANCED-AGENTS.md create mode 100644 docs/BMAD-WORKFLOW.md create mode 100644 docs/DEVELOPMENT-COMMANDS.md create mode 100644 docs/PLUGIN-SYSTEM.md create mode 100644 docs/QUICK-START.md create mode 100644 docs/REQUIREMENTS-WORKFLOW.md diff --git a/README.md b/README.md index b265937..a0b8239 100644 --- a/README.md +++ b/README.md @@ -2,288 +2,113 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code) -[![Version](https://img.shields.io/badge/Version-3.2-green)](https://github.com/) +[![Version](https://img.shields.io/badge/Version-3.2-green)](https://github.com/cexll/myclaude) [![Plugin Ready](https://img.shields.io/badge/Plugin-Ready-purple)](https://docs.claude.com/en/docs/claude-code/plugins) -> Enterprise-grade agile development workflow automation with multi-agent orchestration +> Enterprise-grade agile development automation with AI-powered multi-agent orchestration -[ไธญๆ–‡](README-zh.md) - -## ๐Ÿš€ BMAD Methodology: Agile Development Automation - -**BMAD (Business-Minded Agile Development)** transforms your development process into a fully automated agile workflow with role-based AI agents and quality gates. - -### One Command, Complete Workflow - -```bash -/bmad-pilot "Build e-commerce checkout system with payment integration" -# Automated: Product โ†’ Architecture โ†’ Sprint โ†’ Dev โ†’ Review โ†’ QA -``` - -## ๐ŸŽฏ BMAD Workflow Architecture - -```mermaid -graph LR - PO[Product Owner] -->|PRD 90+| Architect - Architect -->|Design 90+| SM[Scrum Master] - SM -->|Sprint Plan| Dev - Dev -->|Code| Review - Review -->|Pass/Fail| QA - QA -->|Tests| Done -``` - -### Key Features - -- **๐Ÿค– 6 Specialized Agents**: PO, Architect, SM, Dev, Review, QA -- **๐Ÿ“Š Quality Gates**: 90% thresholds with automatic optimization -- **โœ… Approval Points**: User confirmation at critical phases -- **๐Ÿ“ Persistent Artifacts**: All documents saved to `./.claude/specs/` -- **๐Ÿ”„ Iterative Refinement**: Automatic improvement until quality met - -## ๐Ÿ“‹ BMAD Agents & Roles - -| Agent | Role | Quality Gate | Output | -|-------|------|--------------|--------| -| **bmad-po** (Sarah) | Product requirements gathering | 90/100 PRD score | `01-product-requirements.md` | -| **bmad-architect** (Winston) | Technical design & architecture | 90/100 design score | `02-system-architecture.md` | -| **bmad-sm** (Mike) | Sprint planning & task breakdown | User approval | `03-sprint-plan.md` | -| **bmad-dev** (Alex) | Feature implementation | Code completion | Implementation files | -| **bmad-review** | Independent code review | Pass/Risk/Fail | `04-dev-reviewed.md` | -| **bmad-qa** (Emma) | Testing & quality assurance | Test execution | `05-qa-report.md` | +[ไธญๆ–‡ๆ–‡ๆกฃ](README_CN.md) | [Documentation](docs/) ## ๐Ÿš€ Quick Start -### Installation Methods - -#### Method 1: Plugin System (Recommended) ๐ŸŽฏ +### Installation +**Plugin System (Recommended)** ```bash -# List available plugins /plugin github.com/cexll/myclaude ``` -#### Method 2: Traditional Installation - +**Traditional Installation** ```bash -# Clone the repository -git clone https://github.com/your-repo/claude-code-workflows.git -cd claude-code-workflows - -# Install everything with make +git clone https://github.com/cexll/myclaude.git +cd myclaude make install - -# Or deploy specific workflows -make deploy-bmad # Deploy BMAD workflow only -make deploy-requirements # Deploy Requirements workflow only -make deploy-all # Deploy all commands and agents ``` -### Basic BMAD Workflow +### Basic Usage ```bash -# Full agile workflow with all phases -/bmad-pilot "User authentication system with OAuth2 and MFA" +# Full agile workflow +/bmad-pilot "Build user authentication with OAuth2 and MFA" -# Skip testing for quick prototypes -/bmad-pilot "Admin dashboard" --skip-tests +# Lightweight development +/requirements-pilot "Implement JWT token refresh" -# Direct development (skip sprint planning) -/bmad-pilot "Bug fix for login issue" --direct-dev - -# Skip repository scanning (use existing context) -/bmad-pilot "Add feature" --skip-scan +# Direct development commands +/code "Add API rate limiting" ``` -### Workflow Artifacts +## ๐Ÿ“ฆ Plugin Modules -Each BMAD run creates structured documentation: +| Plugin | Description | Key Commands | +|--------|-------------|--------------| +| **[bmad-agile-workflow](docs/BMAD-WORKFLOW.md)** | Complete BMAD methodology with 6 specialized agents | `/bmad-pilot` | +| **[requirements-driven-workflow](docs/REQUIREMENTS-WORKFLOW.md)** | Streamlined requirements-to-code workflow | `/requirements-pilot` | +| **[development-essentials](docs/DEVELOPMENT-COMMANDS.md)** | Core development slash commands | `/code` `/debug` `/test` `/optimize` | +| **[advanced-ai-agents](docs/ADVANCED-AGENTS.md)** | GPT-5 deep reasoning integration | Agent: `gpt5` | -``` -.claude/specs/user-authentication/ -โ”œโ”€โ”€ 00-repository-context.md # Repository analysis -โ”œโ”€โ”€ 01-product-requirements.md # PRD with business goals -โ”œโ”€โ”€ 02-system-architecture.md # Technical design -โ”œโ”€โ”€ 03-sprint-plan.md # Sprint tasks -โ”œโ”€โ”€ 04-dev-reviewed.md # Code review report (NEW v3.1) -โ””โ”€โ”€ 05-qa-report.md # Test results -``` +## ๐Ÿ’ก Use Cases -## ๐ŸŽจ BMAD Output Style +**BMAD Workflow** - Full agile process automation +- Product requirements โ†’ Architecture design โ†’ Sprint planning โ†’ Development โ†’ Code review โ†’ QA testing +- Quality gates with 90% thresholds +- Automated document generation -The BMAD workflow uses a specialized output style that: -- Creates phase-separated contexts -- Manages agent handoffs -- Tracks quality scores -- Handles approval gates -- Supports Codex CLI integration +**Requirements Workflow** - Fast prototyping +- Requirements generation โ†’ Implementation โ†’ Review โ†’ Testing +- Lightweight and practical -## โšก v3.2 Plugin System +**Development Commands** - Daily coding +- Direct implementation, debugging, testing, optimization +- No workflow overhead -### ๐Ÿ”Œ Native Plugin Support (NEW) -This project now includes native Claude Code plugin support with 4 ready-to-use plugin packages: +## ๐ŸŽฏ Key Features -#### Available Plugins +- **๐Ÿค– Role-Based Agents**: Specialized AI agents for each development phase +- **๐Ÿ“Š Quality Gates**: Automatic quality scoring with iterative refinement +- **โœ… Approval Points**: User confirmation at critical workflow stages +- **๐Ÿ“ Persistent Artifacts**: All specs saved to `.claude/specs/` +- **๐Ÿ”Œ Plugin System**: Native Claude Code plugin support +- **๐Ÿ”„ Flexible Workflows**: Choose full agile or lightweight development -| Plugin | Description | Commands | Agents | -|--------|------------|----------|--------| -| **bmad-agile-workflow** | Full BMAD methodology with role-based agents | `/bmad-pilot` | bmad-po, bmad-architect, bmad-sm, bmad-dev, bmad-qa | -| **requirements-driven-development** | Streamlined requirements workflow | `/requirements-pilot` | requirements-generate, requirements-code, requirements-review | -| **development-essentials** | Core development commands | `/code`, `/debug`, `/test`, `/optimize` | code, bugfix, debug, develop | -| **advanced-ai-agents** | GPT-5 deep analysis integration | - | gpt5 | +## ๐Ÿ“š Documentation -#### Using Plugins +- **[BMAD Workflow Guide](docs/BMAD-WORKFLOW.md)** - Complete methodology and agent roles +- **[Requirements Workflow](docs/REQUIREMENTS-WORKFLOW.md)** - Lightweight development process +- **[Development Commands](docs/DEVELOPMENT-COMMANDS.md)** - Slash command reference +- **[Plugin System](docs/PLUGIN-SYSTEM.md)** - Installation and configuration +- **[Quick Start Guide](docs/QUICK-START.md)** - Get started in 5 minutes +## ๐Ÿ› ๏ธ Installation Methods + +**Method 1: Plugin Install** (One command) ```bash -# List all available plugins -/plugin list - -# Get detailed information about a plugin -/plugin info bmad-agile-workflow - -# Install a plugin to activate its commands and agents -/plugin install requirements-driven-development - -# Remove an installed plugin -/plugin remove development-essentials +/plugin install bmad-agile-workflow ``` -#### Plugin Configuration -Plugins are defined in `.claude-plugin/marketplace.json` following the Claude Code plugin specification. Each plugin includes: -- Commands (slash commands) -- Agents (specialized AI agents) -- Metadata (version, author, keywords) -- Category classification - -## โšก v3.1 Features - -### Independent Code Review Agent -- **bmad-review**: Automated review between Dev and QA -- **Dual Version Support**: - - Standard: Native Claude Code review - - Enhanced: GPT-5 via Codex CLI -- **Three-tier Status**: Pass / Pass with Risk / Fail - -### Enhanced Workflow -- Dev โ†’ Review โ†’ QA quality chain -- Automatic Sprint plan updates -- Targeted QA test recommendations - -## ๐Ÿ“Š Quality Scoring Systems - -### PRD Quality (100 points) -- Business Value: 30 -- Functional Requirements: 25 -- User Experience: 20 -- Technical Constraints: 15 -- Scope & Priorities: 10 - -### Architecture Quality (100 points) -- Design Quality: 30 -- Technology Selection: 25 -- Scalability: 20 -- Security: 15 -- Feasibility: 10 - -### Review Status -- **Pass**: No issues, proceed to QA -- **Pass with Risk**: Non-critical issues -- **Fail**: Must return to Dev - -## ๐Ÿ”ง Advanced Usage - -### Repository Context -BMAD automatically scans your repository to understand: -- Technology stack -- Project structure -- Existing patterns -- Dependencies -- Conventions - -### Interactive Refinement -Each phase supports iterative improvement: -``` -PO: "Here's the PRD (Score: 75/100)" -User: "Add mobile support and offline mode" -PO: "Updated PRD (Score: 92/100) โœ…" -``` - -### Approval Gates -Critical phases require explicit confirmation: -``` -Architect: "Technical design complete (Score: 93/100)" -System: "Ready to proceed? (yes/no)" -User: yes -``` - ---- - -## ๐Ÿญ Requirements-Driven Workflow - -An alternative lightweight workflow for simpler projects: - +**Method 2: Make Commands** (Selective installation) ```bash -/requirements-pilot "Implement JWT authentication" -# Automated: Requirements โ†’ Code โ†’ Review โ†’ Test +make deploy-bmad # BMAD workflow only +make deploy-requirements # Requirements workflow only +make deploy-all # Everything ``` -### Features -- 90% quality gates -- Automatic optimization loops -- Implementation-focused specs -- Pragmatic over architectural +**Method 3: Manual Setup** +- Copy `/commands/*.md` to `~/.config/claude/commands/` +- Copy `/agents/*.md` to `~/.config/claude/agents/` -## ๐Ÿ› ๏ธ Other Commands - -### Development Commands -- `/ask` - Technical consultation -- `/code` - Direct implementation -- `/debug` - Systematic debugging -- `/test` - Testing strategies -- `/review` - Code validation -- `/optimize` - Performance tuning -- `/bugfix` - Bug resolution -- `/refactor` - Code improvement -- `/docs` - Documentation -- `/think` - Advanced analysis - -### Manual Workflow Example -```bash -/ask "Design patterns for real-time messaging" -/code "Implement WebSocket server" -/test "Create integration tests" -/review "Validate security" -``` +Run `make help` for all options. ## ๐Ÿ“„ License -MIT License - see [LICENSE](LICENSE) file +MIT License - see [LICENSE](LICENSE) ## ๐Ÿ™‹ Support -- **Documentation**: Check `/commands/` and `/agents/` directories -- **Plugin Guide**: See [PLUGIN_README.md](PLUGIN_README.md) for plugin system details -- **Issues**: GitHub issues for bugs and features -- **Makefile Help**: Run `make help` for all deployment options -- **Claude Code Docs**: [Plugin System](https://docs.claude.com/en/docs/claude-code/plugins) - -### Available Make Commands - -```bash -make install # Install everything to Claude Code -make deploy-bmad # Deploy BMAD workflow only -make deploy-requirements # Deploy Requirements workflow only -make deploy-commands # Deploy all slash commands -make deploy-agents # Deploy all agent configurations -make test-bmad # Test BMAD workflow sample -make test-requirements # Test Requirements workflow sample -make clean # Clean generated artifacts -make help # Show all available commands -``` +- **Issues**: [GitHub Issues](https://github.com/cexll/myclaude/issues) +- **Documentation**: [docs/](docs/) +- **Plugin Guide**: [PLUGIN_README.md](PLUGIN_README.md) --- -**Transform your development with BMAD** - One command, complete agile workflow, quality assured. - -*Install with `/plugin install bmad-agile-workflow` or use traditional installation methods.* - -*Let specialized AI agents handle specialized work.* +**Transform your development with AI-powered automation** - One command, complete workflow, quality assured. diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000..dbf1fd3 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,114 @@ +# Claude Code ๅคšๆ™บ่ƒฝไฝ“ๅทฅไฝœๆต็ณป็ปŸ + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code) +[![Version](https://img.shields.io/badge/Version-3.2-green)](https://github.com/cexll/myclaude) +[![Plugin Ready](https://img.shields.io/badge/Plugin-Ready-purple)](https://docs.claude.com/en/docs/claude-code/plugins) + +> ไผไธš็บงๆ•ๆทๅผ€ๅ‘่‡ชๅŠจๅŒ–ไธŽ AI ้ฉฑๅŠจ็š„ๅคšๆ™บ่ƒฝไฝ“็ผ–ๆŽ’ + +[English](README.md) | [ๆ–‡ๆกฃ](docs/) + +## ๐Ÿš€ ๅฟซ้€Ÿๅผ€ๅง‹ + +### ๅฎ‰่ฃ… + +**ๆ’ไปถ็ณป็ปŸ๏ผˆๆŽจ่๏ผ‰** +```bash +/plugin github.com/cexll/myclaude +``` + +**ไผ ็ปŸๅฎ‰่ฃ…** +```bash +git clone https://github.com/cexll/myclaude.git +cd myclaude +make install +``` + +### ๅŸบๆœฌไฝฟ็”จ + +```bash +# ๅฎŒๆ•ดๆ•ๆทๅทฅไฝœๆต +/bmad-pilot "ๆž„ๅปบ็”จๆˆท่ฎค่ฏ็ณป็ปŸ๏ผŒๆ”ฏๆŒ OAuth2 ๅ’Œๅคšๅ› ็ด ่ฎค่ฏ" + +# ่ฝป้‡็บงๅผ€ๅ‘ +/requirements-pilot "ๅฎž็Žฐ JWT ไปค็‰Œๅˆทๆ–ฐ" + +# ็›ดๆŽฅๅผ€ๅ‘ๅ‘ฝไปค +/code "ๆทปๅŠ  API ้™ๆตๅŠŸ่ƒฝ" +``` + +## ๐Ÿ“ฆ ๆ’ไปถๆจกๅ— + +| ๆ’ไปถ | ๆ่ฟฐ | ไธป่ฆๅ‘ฝไปค | +|------|------|---------| +| **[bmad-agile-workflow](docs/BMAD-WORKFLOW.md)** | ๅฎŒๆ•ด BMAD ๆ–นๆณ•่ฎบ๏ผŒๅŒ…ๅซ6ไธชไธ“ไธšๆ™บ่ƒฝไฝ“ | `/bmad-pilot` | +| **[requirements-driven-workflow](docs/REQUIREMENTS-WORKFLOW.md)** | ็ฒพ็ฎ€็š„้œ€ๆฑ‚ๅˆฐไปฃ็ ๅทฅไฝœๆต | `/requirements-pilot` | +| **[development-essentials](docs/DEVELOPMENT-COMMANDS.md)** | ๆ ธๅฟƒๅผ€ๅ‘ๆ–œๆ ๅ‘ฝไปค | `/code` `/debug` `/test` `/optimize` | +| **[advanced-ai-agents](docs/ADVANCED-AGENTS.md)** | GPT-5 ๆทฑๅบฆๆŽจ็†้›†ๆˆ | ๆ™บ่ƒฝไฝ“: `gpt5` | + +## ๐Ÿ’ก ไฝฟ็”จๅœบๆ™ฏ + +**BMAD ๅทฅไฝœๆต** - ๅฎŒๆ•ดๆ•ๆทๆต็จ‹่‡ชๅŠจๅŒ– +- ไบงๅ“้œ€ๆฑ‚ โ†’ ๆžถๆž„่ฎพ่ฎก โ†’ ๅ†ฒๅˆบ่ง„ๅˆ’ โ†’ ๅผ€ๅ‘ๅฎž็Žฐ โ†’ ไปฃ็ ๅฎกๆŸฅ โ†’ ่ดจ้‡ๆต‹่ฏ• +- 90% ้˜ˆๅ€ผ่ดจ้‡้—จๆŽง +- ่‡ชๅŠจ็”Ÿๆˆๆ–‡ๆกฃ + +**Requirements ๅทฅไฝœๆต** - ๅฟซ้€ŸๅŽŸๅž‹ๅผ€ๅ‘ +- ้œ€ๆฑ‚็”Ÿๆˆ โ†’ ๅฎž็Žฐ โ†’ ๅฎกๆŸฅ โ†’ ๆต‹่ฏ• +- ่ฝป้‡็บงๅฎž็”จไธปไน‰ + +**ๅผ€ๅ‘ๅ‘ฝไปค** - ๆ—ฅๅธธ็ผ–็  +- ็›ดๆŽฅๅฎž็Žฐใ€่ฐƒ่ฏ•ใ€ๆต‹่ฏ•ใ€ไผ˜ๅŒ– +- ๆ— ๅทฅไฝœๆตๅผ€้”€ + +## ๐ŸŽฏ ๆ ธๅฟƒ็‰นๆ€ง + +- **๐Ÿค– ่ง’่‰ฒๅŒ–ๆ™บ่ƒฝไฝ“**: ๆฏไธชๅผ€ๅ‘้˜ถๆฎต็š„ไธ“ไธš AI ๆ™บ่ƒฝไฝ“ +- **๐Ÿ“Š ่ดจ้‡้—จๆŽง**: ่‡ชๅŠจ่ดจ้‡่ฏ„ๅˆ†๏ผŒ่ฟญไปฃไผ˜ๅŒ– +- **โœ… ็กฎ่ฎค่Š‚็‚น**: ๅ…ณ้”ฎๅทฅไฝœๆต้˜ถๆฎต็š„็”จๆˆท็กฎ่ฎค +- **๐Ÿ“ ๆŒไน…ๅŒ–ไบง็‰ฉ**: ๆ‰€ๆœ‰่ง„ๆ ผไฟๅญ˜่‡ณ `.claude/specs/` +- **๐Ÿ”Œ ๆ’ไปถ็ณป็ปŸ**: ๅŽŸ็”Ÿ Claude Code ๆ’ไปถๆ”ฏๆŒ +- **๐Ÿ”„ ็ตๆดปๅทฅไฝœๆต**: ้€‰ๆ‹ฉๅฎŒๆ•ดๆ•ๆทๆˆ–่ฝป้‡ๅผ€ๅ‘ + +## ๐Ÿ“š ๆ–‡ๆกฃ + +- **[BMAD ๅทฅไฝœๆตๆŒ‡ๅ—](docs/BMAD-WORKFLOW.md)** - ๅฎŒๆ•ดๆ–นๆณ•่ฎบๅ’Œๆ™บ่ƒฝไฝ“่ง’่‰ฒ +- **[Requirements ๅทฅไฝœๆต](docs/REQUIREMENTS-WORKFLOW.md)** - ่ฝป้‡็บงๅผ€ๅ‘ๆต็จ‹ +- **[ๅผ€ๅ‘ๅ‘ฝไปคๅ‚่€ƒ](docs/DEVELOPMENT-COMMANDS.md)** - ๆ–œๆ ๅ‘ฝไปค่ฏดๆ˜Ž +- **[ๆ’ไปถ็ณป็ปŸ](docs/PLUGIN-SYSTEM.md)** - ๅฎ‰่ฃ…ไธŽ้…็ฝฎ +- **[ๅฟซ้€ŸไธŠๆ‰‹](docs/QUICK-START.md)** - 5ๅˆ†้’Ÿๅ…ฅ้—จ + +## ๐Ÿ› ๏ธ ๅฎ‰่ฃ…ๆ–นๅผ + +**ๆ–นๅผ1: ๆ’ไปถๅฎ‰่ฃ…**๏ผˆไธ€ๆกๅ‘ฝไปค๏ผ‰ +```bash +/plugin install bmad-agile-workflow +``` + +**ๆ–นๅผ2: Make ๅ‘ฝไปค**๏ผˆ้€‰ๆ‹ฉๆ€งๅฎ‰่ฃ…๏ผ‰ +```bash +make deploy-bmad # ไป… BMAD ๅทฅไฝœๆต +make deploy-requirements # ไป… Requirements ๅทฅไฝœๆต +make deploy-all # ๅ…จ้ƒจๅฎ‰่ฃ… +``` + +**ๆ–นๅผ3: ๆ‰‹ๅŠจๅฎ‰่ฃ…** +- ๅคๅˆถ `/commands/*.md` ๅˆฐ `~/.config/claude/commands/` +- ๅคๅˆถ `/agents/*.md` ๅˆฐ `~/.config/claude/agents/` + +่ฟ่กŒ `make help` ๆŸฅ็œ‹ๆ‰€ๆœ‰้€‰้กนใ€‚ + +## ๐Ÿ“„ ่ฎธๅฏ่ฏ + +MIT ่ฎธๅฏ่ฏ - ๆŸฅ็œ‹ [LICENSE](LICENSE) + +## ๐Ÿ™‹ ๆ”ฏๆŒ + +- **้—ฎ้ข˜ๅ้ฆˆ**: [GitHub Issues](https://github.com/cexll/myclaude/issues) +- **ๆ–‡ๆกฃ**: [docs/](docs/) +- **ๆ’ไปถๆŒ‡ๅ—**: [PLUGIN_README.md](PLUGIN_README.md) + +--- + +**ไฝฟ็”จ AI ้ฉฑๅŠจ็š„่‡ชๅŠจๅŒ–่ฝฌๅž‹ๆ‚จ็š„ๅผ€ๅ‘ๆต็จ‹** - ไธ€ๆกๅ‘ฝไปค๏ผŒๅฎŒๆ•ดๅทฅไฝœๆต๏ผŒ่ดจ้‡ไฟ่ฏใ€‚ diff --git a/docs/ADVANCED-AGENTS.md b/docs/ADVANCED-AGENTS.md new file mode 100644 index 0000000..e77d40e --- /dev/null +++ b/docs/ADVANCED-AGENTS.md @@ -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. diff --git a/docs/BMAD-WORKFLOW.md b/docs/BMAD-WORKFLOW.md new file mode 100644 index 0000000..80755e6 --- /dev/null +++ b/docs/BMAD-WORKFLOW.md @@ -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. diff --git a/docs/DEVELOPMENT-COMMANDS.md b/docs/DEVELOPMENT-COMMANDS.md new file mode 100644 index 0000000..2d948f5 --- /dev/null +++ b/docs/DEVELOPMENT-COMMANDS.md @@ -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. diff --git a/docs/PLUGIN-SYSTEM.md b/docs/PLUGIN-SYSTEM.md new file mode 100644 index 0000000..be7e9a2 --- /dev/null +++ b/docs/PLUGIN-SYSTEM.md @@ -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 +``` + +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 +``` + +Or manually remove files: + +```bash +# Remove commands +rm ~/.config/claude/commands/.md + +# Remove agents +rm ~/.config/claude/agents/.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. diff --git a/docs/QUICK-START.md b/docs/QUICK-START.md new file mode 100644 index 0000000..4d3be99 --- /dev/null +++ b/docs/QUICK-START.md @@ -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. diff --git a/docs/REQUIREMENTS-WORKFLOW.md b/docs/REQUIREMENTS-WORKFLOW.md new file mode 100644 index 0000000..debfaa6 --- /dev/null +++ b/docs/REQUIREMENTS-WORKFLOW.md @@ -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.