diff --git a/BMAD-PILOT-USER-GUIDE.md b/BMAD-PILOT-USER-GUIDE.md deleted file mode 100644 index a857d59..0000000 --- a/BMAD-PILOT-USER-GUIDE.md +++ /dev/null @@ -1,163 +0,0 @@ -# BMAD Pilot 使用指南 - -本指南介绍如何使用 BMAD Pilot 工作流，编排一组协作 AI 角色（PO/Architect/SM/Dev/QA）在仓库上下文中完成：01 产品需求文档、02 系统设计规范、03 冲刺计划，并自动进入开发与测试，整个过程包含多次用户确认门与质量评分。 - -参考阅读：BMAD-README.md（BMAD 方法概览）、BMAD-INTEGRATION-GUIDE.md（进阶集成）。 - ---- - -## 命令总览 - -- 命令：`/bmad-pilot [OPTIONS]` -- 作用：在仓库上下文中，按阶段编排 `bmad-po → bmad-architect → bmad-sm → bmad-dev → bmad-qa`。 -- Orchestrator：由工作流统一编排（使用 bmad-orchestrator 进行仓库扫描）。 - -### Options -- `--skip-tests`：跳过 QA 阶段 -- `--direct-dev`：跳过 SM 冲刺计划，架构后直接进入开发 -- `--skip-scan`：跳过初始仓库扫描（不推荐） - -### 输出目录 -- 所有产出归档在：`./.claude/specs/{feature_name}/` - - `00-repo-scan.md` — 仓库扫描摘要（自动生成） - - `01-product-requirements.md` — 产品需求文档（确认后保存） - - `02-system-architecture.md` — 系统设计规范（确认后保存） - - `03-sprint-plan.md` — 冲刺计划（确认后保存；`--direct-dev` 时跳过） - -`{feature_name}` 由 `` 生成（kebab-case：小写，空格/标点转 `-`，连续合并，首尾去除）。 - ---- - -## 快速开始 - -1) 执行 Pilot： -``` -/bmad-pilot 为现有项目新增看板模块，支持多用户权限与移动端适配 -``` -2) 与 PO 交互澄清，直至 PRD ≥ 90 分 → 确认保存。 -3) 与 Architect 讨论技术决策，直至架构 ≥ 90 分 → 确认保存。 -4) 审阅并确认 SM 的冲刺计划（或使用 `--direct-dev` 跳过该阶段）。 -5) Dev 基于文档实现；QA 基于文档与实现测试（除非 `--skip-tests`）。 -6) 查看产出目录：`./.claude/specs/{feature_name}/`。 - ---- - -## 工作流阶段 - -- Phase 0：仓库扫描（自动，除非 `--skip-scan`） - - Agent：`bmad-orchestrator` - - 结果：扫描摘要返回并写入 `00-repo-scan.md` - - 内容：项目类型、技术栈、代码组织、惯例、集成点、约束与注意事项 - -- Phase 1：产品需求（交互） - - Agent：`bmad-po` - - 循环：澄清问题 → 更新 PRD → 评分（目标 ≥ 90） - - 确认门：PRD ≥ 90 分后，需要用户明确确认再继续 - - 保存：`01-product-requirements.md` - -- Phase 2：系统架构（交互） - - Agent：`bmad-architect` - - 循环：技术选型与设计澄清 → 更新架构 → 评分（目标 ≥ 90） - - 确认门：架构 ≥ 90 分后，需要用户明确确认再继续 - - 保存：`02-system-architecture.md` - -- Phase 3：冲刺计划（交互，除非 `--direct-dev`） - - Agent：`bmad-sm` - - 循环：计划要点与问题澄清 → 更新计划 → 确认保存 - - 保存：`03-sprint-plan.md` - -- Phase 4：开发实现（自动） - - Agent：`bmad-dev` - - 输入：PRD、架构、冲刺计划、`00-repo-scan.md` - -- Phase 5：质量保障（自动，除非 `--skip-tests`） - - Agent：`bmad-qa` - - 输入：PRD、架构、冲刺计划、实现、`00-repo-scan.md` - ---- - -## 交互与质量门 - -- 质控阈值：PRD 与架构质量评分需达到 ≥ 90 分。 -- 强制确认门：每个关键阶段完成后，Orchestrator 会停下等待你的“继续/确认”。 -- 迭代澄清：PO/Architect/SM 会提出 2-5 个精准问题，Orchestrator 转述并汇总你的回答以供下一轮完善。 - ---- - -## 仓库上下文 - -- 首次扫描：由工作流触发的 orchestrator 扫描（`bmad-orchestrator`）自动分析当前仓库（`--skip-scan` 可跳过）。 -- 缓存路径：`./.claude/specs/{feature_name}/00-repo-scan.md`（供所有后续 Agent 引用）。 -- 作用：提供技术栈识别、约定、测试模式、集成点，避免上下文丢失并保持一致性。 - ---- - -## 角色职责 - -- `bmad-po`：需求澄清与 PRD 产出，评分与问题驱动迭代。 -- `bmad-architect`：技术架构与关键决策，评分与问题驱动迭代。 -- `bmad-sm`：冲刺计划、任务拆分、依赖/风险/节奏规划。 -- `bmad-dev`：按文档实现、测试、日志/安全/性能与同构风格。 -- `bmad-qa`：基于需求与实现的全维度测试（单测/集成/E2E/性能/安全）。 - ---- - -## 示例 - -- 基础运行： -``` -/bmad-pilot 在线商城结算流程升级，支持优惠券与发票 -``` - -- 跳过测试： -``` -/bmad-pilot H5 活动页生成器 --skip-tests -``` - -- 直接从架构进入开发（跳过 SM）： -``` -/bmad-pilot 小程序客服模块重构 --direct-dev -``` - -- 跳过扫描（不推荐）： -``` -/bmad-pilot 部署流水线可视化 --skip-scan -``` - ---- - -## 目录结构 - -``` -.claude/ - specs/ - {feature_name}/ - 00-repo-scan.md - 01-product-requirements.md - 02-system-architecture.md - 03-sprint-plan.md -``` - ---- - -## Tips & 常见问题 - -- 分数上不去：优先补齐评分分项的缺口（业务指标、关键流程、性能/安全约束等）。 -- 上下文不一致：检查并引用 `00-repo-scan.md` 的关键约定与模式，保证 PRD/架构/计划一致。 -- 依赖/网络受限：Dev/QA 的实际执行受环境影响；请在项目内准备依赖与测试环境，或先提交伪实现/测试策略。 -- 文档路径：确保在项目根目录执行，Pilot 会将文件写入 `./.claude/specs/{feature_name}/`。 - ---- - -## 最佳实践 - -- 小步快跑：每轮补充最关键信息，快速达成 ≥ 90 分文档。 -- 统一术语：在 PRD 固定术语词表；架构与代码沿用同名。 -- 用例先行：PRD 的验收标准应转化为 QA 的关键测试用例。 -- 复用模式：尽量沿用扫描识别的现有代码/测试模式，减少偏差。 - ---- - -## 版本记录 - -- 2025-08-11：新增仓库扫描摘要缓存 `00-repo-scan.md`，统一路径与跨阶段引用；明确确认门与目录预创建说明。 diff --git a/BMAD-README.md b/BMAD-README.md deleted file mode 100644 index df0e3ba..0000000 --- a/BMAD-README.md +++ /dev/null @@ -1,339 +0,0 @@ -# BMAD方法论 Claude Code 使用指南 - -[![BMAD Method](https://img.shields.io/badge/BMAD-Method-blue)](https://github.com/bmadcode/BMAD-METHOD) -[![Claude Code](https://img.shields.io/badge/Claude-Code-green)](https://claude.ai/code) - -> 从产品理念到代码实现的完整AI驱动敏捷开发工作流 - -## 🎯 什么是BMAD方法论？ - -BMAD (Business, Market, Architecture, Development) 是一个AI驱动的敏捷开发方法论，通过专业化代理团队实现从商业需求到技术实现的完整工作流程。 - -### 核心理念 -- **智能体规划**: 专门代理协作创建详细、一致的PRD和架构文档 -- **上下文工程开发**: 将详细计划转换为超详细的开发故事 -- **角色专业化**: 每个代理专注特定领域，避免角色切换导致的质量下降 - -## 🏗️ BMAD代理体系 - -### 代理角色说明 -- **PO (Product Owner)** - 产品负责人Sarah：需求分析、用户故事、验收标准 -- **Analyst** - 业务分析师Mary：市场研究、竞争分析、商业案例 -- **Architect** - 系统架构师Winston：技术架构、系统设计、技术选择 -- **SM (Scrum Master)** - 敏捷教练：任务分解、冲刺规划、流程协调 -- **Dev (Developer)** - 开发工程师：代码实现、技术文档 -- **QA (Quality Assurance)** - 质量保证：测试策略、质量验证 -- **UX Expert** - 用户体验专家：交互设计、可用性测试 - -## 🚀 快速开始 - -### 安装配置 -BMAD方法论已集成到您的Claude Code系统中，无需额外安装。 - -### 基本使用方法 - -#### 1. 完整BMAD工作流 -```bash -# 一键执行完整开发流程 -/bmad-pilot "实现企业级用户管理系统，支持RBAC权限控制和LDAP集成" - -# 执行流程：PO → Architect → SM → Dev → QA -``` - -#### 2. 常用选项 -```bash -# 跳过测试（PO → Architect → SM → Dev） -/bmad-pilot "实现支付网关API" --skip-tests - -# 直接从架构进入开发（跳过 SM 规划） -/bmad-pilot "设计微服务电商平台" --direct-dev - -# 跳过仓库扫描（不推荐） -/bmad-pilot "用户界面优化" --skip-scan -``` - -#### 3. 直接开发与部分流程 -```bash -# 技术焦点（架构后直接进入开发与测试） -/bmad-pilot "API网关实现" --direct-dev - -# 完整设计流程（需求→架构→规划→开发→测试） -/bmad-pilot "系统重构规划" - -# 仅业务相关分析 → 请使用下方“独立代理使用”中的 /bmad-po 与 /bmad-analyst -``` - -#### 4. 独立代理使用 -```bash -# 产品需求分析 -/bmad-po "企业CRM系统功能需求定义" - -# 市场调研分析 -/bmad-analyst "SaaS市场竞争格局和机会分析" - -# 系统架构设计 -/bmad-architect "高并发分布式系统架构设计" - -# 主协调器（可转换为任意代理） -/bmad-orchestrator "协调多代理完成复杂项目" -``` - -## 📋 详细命令说明 - -### `/bmad-pilot` - 完整工作流执行 -**用法**: `/bmad-pilot <项目描述> [选项]` - -**选项**: -- `--skip-tests`: 跳过 QA 阶段 -- `--direct-dev`: 跳过 SM 冲刺计划，架构后直接进入开发 -- `--skip-scan`: 跳过初始仓库扫描（不推荐） - -**示例**: -```bash -/bmad-pilot "构建在线教育平台，支持直播、录播、作业系统" -/bmad-pilot "API网关设计" --direct-dev -/bmad-pilot "支付模块" --skip-tests -``` - -### `/bmad-po` - 产品负责人 -**角色**: Sarah - 技术产品负责人 & 流程管家 -**专长**: 需求分析、用户故事、验收标准、冲刺规划 - -**用法**: `/bmad-po <需求描述>` - -**工作流程**: -1. 需求分解和功能点识别 -2. 用户故事创建（As a... I want... So that...） -3. 验收标准定义和优先级排序 -4. 利益相关者验证和签署 - -**示例**: -```bash -/bmad-po "设计企业级权限管理系统，支持多租户和细粒度权限控制" -/bmad-po "移动端电商APP功能需求分析" -``` - -### `/bmad-analyst` - 业务分析师 -**角色**: Mary - 洞察分析师 & 战略合作伙伴 -**专长**: 市场研究、竞争分析、商业案例开发、利益相关者分析 - -**用法**: `/bmad-analyst <分析主题>` - -**工作流程**: -1. 市场格局和竞争对手分析 -2. 商业案例开发和ROI分析 -3. 利益相关者分析和需求收集 -4. 项目简报和战略建议 - -**示例**: -```bash -/bmad-analyst "企业级认证市场分析，JWT vs OAuth2.0 vs SAML" -/bmad-analyst "云原生架构迁移的商业价值和风险评估" -``` - -### `/bmad-architect` - 系统架构师 -**角色**: Winston - 全栈系统架构师 & 技术领导者 -**专长**: 系统设计、技术选择、API设计、基础架构规划 - -**用法**: `/bmad-architect <系统设计需求>` - -**工作流程**: -1. 系统需求和约束分析 -2. 技术栈和架构模式选择 -3. 组件设计和系统架构图 -4. 实施策略和开发指导 - -**示例**: -```bash -/bmad-architect "微服务架构设计，支持事件驱动和最终一致性" -/bmad-architect "高可用API网关架构，支持限流、熔断、监控" -``` - -### `/bmad-orchestrator` - 主协调器 -**角色**: BMAD主协调器 -**专长**: 工作流协调、代理转换、多代理任务管理 - -**用法**: `/bmad-orchestrator [命令] [参数]` - -**功能**: -- 动态转换为任意专门代理 -- 协调复杂多代理工作流 -- 管理代理间的上下文传递 -- 提供工作流指导和建议 - -## 🔄 与现有系统集成 - -### 现有系统 vs BMAD方法论 - -| 特性 | Requirements-Pilot | BMAD方法论 | -|------|-------------------|-----------| -| **执行时间** | 30分钟 | 1-2小时 | -| **适用场景** | 快速功能开发 | 企业级项目 | -| **覆盖范围** | 技术实现 | 商业+技术全流程 | -| **质量门控** | 90%技术质量 | 多维度质量验证 | -| **代理数量** | 4个技术代理 | 7个全角色代理 | - -### 使用场景建议 - -#### 🚅 快速开发（推荐现有系统） -```bash -# 简单功能快速实现 -/requirements-pilot "添加用户登录功能" -/requirements-pilot "实现数据导出API" -``` - -#### 🏢 企业级项目（推荐BMAD） -```bash -# 复杂系统完整流程 -/bmad-pilot "构建企业级ERP系统，集成财务、人事、项目管理模块" -/bmad-pilot "设计多租户SaaS平台，支持自定义配置和第三方集成" -``` - -#### 🔄 混合模式（规划+实现） -```bash -# 先用BMAD做规划（在 PRD/架构确认门停留） -/bmad-pilot "电商平台架构设计" - -# 再用现有系统快速实现 -/requirements-pilot "基于架构规格实现用户服务模块" -/requirements-pilot "基于架构规格实现订单服务模块" -``` - -## 🎯 典型工作流示例 - -### 示例1: 企业级认证系统 -```bash -# 完整BMAD流程 -/bmad-pilot "企业级JWT认证系统，支持RBAC权限控制、LDAP集成、审计日志、高可用部署" - -# 预期输出： -# 1. PO: 详细用户故事和验收标准 -# 2. Architect: 完整系统架构和技术选择 -# 3. SM: 开发任务分解和冲刺计划 -# 4. Dev: 生产就绪代码实现 -# 5. QA: 测试策略与用例并执行（可选） -``` - -### 示例2: API网关开发 -```bash -# 技术焦点流程（跳过SM，架构后直接进入开发） -/bmad-pilot "高性能API网关，支持限流、熔断、监控、服务发现" --direct-dev - -# 执行流程： -# 1. Architect: 系统架构设计 -# 2. Dev: 代码实现 -# 3. QA: 性能测试和质量验证 -``` - -### 示例3: 产品市场分析 -```bash -# 业务分析流程（使用独立代理） -/bmad-po "云原生数据库市场机会分析的产品需求假设与范围界定" -/bmad-analyst "云原生数据库市场机会分析" - -# 执行流程： -# 1. PO: 产品需求定义 -# 2. Analyst: 市场研究和竞争分析 -``` - -## 📊 质量保证体系 - -### BMAD质量标准 -- **需求完整性**: 90+ 分需求清晰度评分 -- **商业对齐**: 明确的价值主张和市场定位 -- **架构完善**: 全面的系统设计和技术选择 -- **实现就绪**: 可执行的开发规格和质量标准 - -### 集成现有质量门控 -- 保持90%技术质量阈值 -- 增加商业价值验证维度 -- 多代理交叉验证机制 -- 自动化质量反馈循环 - -## 🔧 高级用法和最佳实践 - -### 1. 渐进式复杂度管理 -```bash -# MVP阶段 -/bmad-workflow "用户管理系统MVP版本" --phase=development - -# 功能增强阶段 -/bmad-analyst "用户反馈分析和功能增强建议" -/requirements-pilot "基于反馈实现增强功能" - -# 企业级增强 -/bmad-workflow "企业级安全增强和合规支持" --agents=architect,dev,qa -``` - -### 2. 跨项目知识管理 -```bash -# 项目文档化 -/bmad-orchestrator "将当前项目架构文档化，便于后续项目参考" - -# 最佳实践提取 -/bmad-architect "基于项目经验总结微服务架构最佳实践" -``` - -### 3. 团队协作优化 -```bash -# 团队能力评估 -/bmad-analyst "评估团队技术栈和能力匹配度" - -# 开发计划调整 -/bmad-po "根据团队能力调整功能优先级和实现计划" -``` - -## 🚦 故障排除 - -### 常见问题 - -**Q: BMAD工作流执行时间较长，如何优化？** -A: -- 简单功能使用 `/requirements-pilot` -- 复杂项目使用分阶段执行 `--phase=planning` -- 使用自定义代理序列减少不必要的步骤 - -**Q: 如何在BMAD和现有系统间选择？** -A: -- 项目复杂度 < 中等：使用 `/requirements-pilot` -- 项目复杂度 ≥ 高：使用 `/bmad-workflow` -- 需要商业分析：必须使用BMAD -- 纯技术实现：可选择任一系统 - -**Q: 代理输出质量不符合预期怎么办？** -A: -- 提供更详细的项目描述 -- 使用分阶段执行，逐步细化 -- 结合独立代理使用进行专项优化 - -## 🎉 开始你的BMAD之旅 - -### 第一次使用 -```bash -# 体验完整BMAD工作流 -/bmad-workflow "构建一个简单的博客系统，支持文章发布、评论、用户管理" -``` - -### 学习不同代理角色 -```bash -# 产品思维 -/bmad-po "分析博客系统的用户需求和使用场景" - -# 商业思维 -/bmad-analyst "个人博客vs企业CMS市场定位分析" - -# 技术思维 -/bmad-architect "可扩展博客系统架构设计" -``` - -## 📚 进阶学习资源 - -- [BMAD-METHOD原理](https://github.com/bmadcode/BMAD-METHOD) -- [Claude Code文档](https://docs.anthropic.com/en/docs/claude-code) -- [敏捷开发最佳实践](https://agilemanifesto.org/) - ---- - -**BMAD方法论 + Claude Code = 从理念到代码的完整AI开发工作流** 🚀 - -开始使用BMAD方法论，体验专业化AI代理团队带来的开发效率和质量提升！ diff --git a/README-zh.md b/README-zh.md deleted file mode 100644 index 03fbd9f..0000000 --- a/README-zh.md +++ /dev/null @@ -1,288 +0,0 @@ -# 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/) -[![Plugin Ready](https://img.shields.io/badge/Plugin-Ready-purple)](https://docs.claude.com/en/docs/claude-code/plugins) - -> 企业级敏捷开发工作流自动化与多智能体编排 - -[English](README.md) - -## 🚀 BMAD 方法论：敏捷开发自动化 - -**BMAD (Business-Minded Agile Development)** 将您的开发流程转换为全自动化的敏捷工作流，配备角色化 AI 智能体和质量门控。 - -### 一条命令，完整工作流 - -```bash -/bmad-pilot "构建电商结账系统，集成支付功能" -# 自动化：产品 → 架构 → 冲刺 → 开发 → 审查 → 测试 -``` - -## 🎯 BMAD 工作流架构 - -```mermaid -graph LR - PO[产品负责人] -->|PRD 90+| Architect[架构师] - Architect -->|设计 90+| SM[Scrum Master] - SM -->|冲刺计划| Dev[开发者] - Dev -->|代码| Review[审查] - Review -->|Pass/Fail| QA[测试] - QA -->|测试| Done[完成] -``` - -### 核心特性 - -- **🤖 6个专业智能体**：PO、Architect、SM、Dev、Review、QA -- **📊 质量门控**：90% 阈值自动优化 -- **✅ 确认节点**：关键阶段用户确认 -- **📁 持久化产物**：所有文档保存至 `./.claude/specs/` -- **🔄 迭代优化**：自动改进直至质量达标 - -## 📋 BMAD 智能体与角色 - -| 智能体 | 角色 | 质量门控 | 输出 | -|--------|------|----------|------| -| **bmad-po** (Sarah) | 产品需求收集 | 90/100 PRD 评分 | `01-product-requirements.md` | -| **bmad-architect** (Winston) | 技术设计与架构 | 90/100 设计评分 | `02-system-architecture.md` | -| **bmad-sm** (Mike) | 冲刺计划与任务分解 | 用户确认 | `03-sprint-plan.md` | -| **bmad-dev** (Alex) | 功能实现 | 代码完成 | 实现文件 | -| **bmad-review** | 独立代码审查 | Pass/Risk/Fail | `04-dev-reviewed.md` | -| **bmad-qa** (Emma) | 测试与质量保证 | 测试执行 | `05-qa-report.md` | - -## 🚀 快速开始 - -### 安装方法 - -#### 方法1：插件系统（推荐）🎯 - -```bash -/plugin github.com/cexll/myclaude -``` - -#### 方法2：传统安装 - -```bash -# 克隆仓库 -git clone https://github.com/your-repo/claude-code-workflows.git -cd claude-code-workflows - -# 使用 make 安装所有配置 -make install - -# 或部署特定工作流 -make deploy-bmad # 仅部署 BMAD 工作流 -make deploy-requirements # 仅部署 Requirements 工作流 -make deploy-all # 部署所有命令和智能体 -``` - -### 基本 BMAD 工作流 - -```bash -# 完整敏捷工作流（所有阶段） -/bmad-pilot "用户认证系统，支持 OAuth2 和多因素认证" - -# 快速原型（跳过测试） -/bmad-pilot "管理后台" --skip-tests - -# 直接开发（跳过冲刺计划） -/bmad-pilot "修复登录问题" --direct-dev - -# 跳过仓库扫描（使用现有上下文） -/bmad-pilot "添加功能" --skip-scan -``` - -### 工作流产物 - -每次 BMAD 运行创建结构化文档： - -``` -.claude/specs/user-authentication/ -├── 00-repository-context.md # 仓库分析 -├── 01-product-requirements.md # PRD 及业务目标 -├── 02-system-architecture.md # 技术设计 -├── 03-sprint-plan.md # 冲刺任务 -├── 04-dev-reviewed.md # 代码审查报告（v3.1 新增） -└── 05-qa-report.md # 测试结果 -``` - -## 🎨 BMAD 输出样式 - -BMAD 工作流使用专门的输出样式： -- 创建阶段隔离的上下文 -- 管理智能体交接 -- 跟踪质量评分 -- 处理确认门控 -- 支持 Codex CLI 集成 - -## ⚡ v3.2 插件系统 - -### 🔌 原生插件支持（新增） -本项目现已包含原生 Claude Code 插件支持，提供4个即装即用的插件包： - -#### 可用插件 - -| 插件 | 描述 | 命令 | 智能体 | -|------|------|------|--------| -| **bmad-agile-workflow** | 完整 BMAD 方法论及角色化智能体 | `/bmad-pilot` | bmad-po, bmad-architect, bmad-sm, bmad-dev, bmad-qa | -| **requirements-driven-development** | 精简需求工作流 | `/requirements-pilot` | requirements-generate, requirements-code, requirements-review | -| **development-essentials** | 核心开发命令 | `/code`, `/debug`, `/test`, `/optimize` | code, bugfix, debug, develop | -| **advanced-ai-agents** | GPT-5 深度分析集成 | - | gpt5 | - -#### 使用插件 - -```bash -# 列出所有可用插件 -/plugin list - -# 获取插件详细信息 -/plugin info bmad-agile-workflow - -# 安装插件以激活其命令和智能体 -/plugin install requirements-driven-development - -# 移除已安装的插件 -/plugin remove development-essentials -``` - -#### 插件配置 -插件定义在 `.claude-plugin/marketplace.json`，遵循 Claude Code 插件规范。每个插件包含： -- 命令（斜杠命令） -- 智能体（专业 AI 智能体） -- 元数据（版本、作者、关键词） -- 类别分类 - -## ⚡ v3.1 特性 - -### 独立代码审查智能体 -- **bmad-review**：Dev 和 QA 之间的自动审查 -- **双版本支持**： - - 标准版：Claude Code 原生审查 - - 增强版：通过 Codex CLI 调用 GPT-5 -- **三级状态**：Pass / Pass with Risk / Fail - -### 增强工作流 -- Dev → Review → QA 质量链 -- 自动更新冲刺计划 -- 针对性 QA 测试建议 - -## 📊 质量评分系统 - -### PRD 质量（100分） -- 业务价值：30 -- 功能需求：25 -- 用户体验：20 -- 技术约束：15 -- 范围与优先级：10 - -### 架构质量（100分） -- 设计质量：30 -- 技术选型：25 -- 可扩展性：20 -- 安全性：15 -- 可行性：10 - -### 审查状态 -- **Pass**：无问题，进入 QA -- **Pass with Risk**：非关键问题 -- **Fail**：必须返回 Dev - -## 🔧 高级用法 - -### 仓库上下文 -BMAD 自动扫描仓库了解： -- 技术栈 -- 项目结构 -- 现有模式 -- 依赖关系 -- 编码规范 - -### 交互式优化 -每个阶段支持迭代改进： -``` -PO: "这是 PRD（评分：75/100）" -用户: "添加移动端支持和离线模式" -PO: "更新的 PRD（评分：92/100）✅" -``` - -### 确认门控 -关键阶段需要明确确认： -``` -架构师: "技术设计完成（评分：93/100）" -系统: "准备继续？(yes/no)" -用户: yes -``` - ---- - -## 🏭 Requirements-Driven 工作流 - -适用于简单项目的轻量级替代方案： - -```bash -/requirements-pilot "实现 JWT 认证" -# 自动化：需求 → 代码 → 审查 → 测试 -``` - -### 特性 -- 90% 质量门控 -- 自动优化循环 -- 实现导向规格 -- 实用主义优先 - -## 🛠️ 其他命令 - -### 开发命令 -- `/ask` - 技术咨询 -- `/code` - 直接实现 -- `/debug` - 系统化调试 -- `/test` - 测试策略 -- `/review` - 代码验证 -- `/optimize` - 性能优化 -- `/bugfix` - 错误解决 -- `/refactor` - 代码改进 -- `/docs` - 文档生成 -- `/think` - 高级分析 - -### 手动工作流示例 -```bash -/ask "实时消息的设计模式" -/code "实现 WebSocket 服务器" -/test "创建集成测试" -/review "验证安全性" -``` - -## 📄 许可证 - -MIT 许可证 - 查看 [LICENSE](LICENSE) 文件 - -## 🙋 支持 - -- **文档**：查看 `/commands/` 和 `/agents/` 目录 -- **插件指南**：查看 [PLUGIN_README.md](PLUGIN_README.md) 了解插件系统详情 -- **问题**：GitHub issues 用于报告 bug 和功能请求 -- **Makefile 帮助**：运行 `make help` 查看所有部署选项 -- **Claude Code 文档**：[插件系统](https://docs.claude.com/en/docs/claude-code/plugins) - -### 可用的 Make 命令 - -```bash -make install # 安装所有配置到 Claude Code -make deploy-bmad # 仅部署 BMAD 工作流 -make deploy-requirements # 仅部署 Requirements 工作流 -make deploy-commands # 部署所有斜杠命令 -make deploy-agents # 部署所有智能体配置 -make test-bmad # 测试 BMAD 工作流示例 -make test-requirements # 测试 Requirements 工作流示例 -make clean # 清理生成的文件 -make help # 显示所有可用命令 -``` - ---- - -**使用 BMAD 转型您的开发** - 一条命令，完整敏捷工作流，质量保证。 - -*通过 `/plugin install bmad-agile-workflow` 安装或使用传统安装方法。* - -*让专业的 AI 智能体处理专业工作。* 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.