mirror of
https://github.com/cexll/myclaude.git
synced 2026-02-05 02:30:26 +08:00
Compare commits
32 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
e6b229645a | ||
|
|
9dc3e8f43d | ||
|
|
e9faa0bc2d | ||
|
70caa8d7fc | ||
|
4f74d5afa1 | ||
|
|
7f61437eea | ||
|
|
ed604f6db7 | ||
|
|
fb66b52b68 | ||
|
|
05e32203ee | ||
|
|
1bf7dd9a83 | ||
|
|
19aa237d47 | ||
|
|
5cd1103b85 | ||
|
|
e2f80508b5 | ||
|
|
86cb8f6611 | ||
|
|
04cffd2d21 | ||
|
|
74b47a6f5a | ||
|
|
32514920da | ||
|
|
a36b37c66d | ||
|
|
b4a80f833a | ||
|
|
cc1d22167a | ||
|
|
c080eea98c | ||
|
|
95b43c68fe | ||
|
|
6b06403014 | ||
|
|
4d3789d0dc | ||
|
|
4110ee4600 | ||
|
|
9d16cb4406 | ||
|
|
daa50177f3 | ||
|
|
9c2c91bb1a | ||
|
|
34f1557f83 | ||
|
|
41d776c09e | ||
|
|
9dea5d37ef | ||
|
|
656bdd27c5 |
@@ -149,6 +149,32 @@
|
||||
"agents": [
|
||||
"./agents/gpt5.md"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "requirements-clarity",
|
||||
"source": "./requirements-clarity/",
|
||||
"description": "Transforms vague requirements into actionable PRDs through systematic clarification with 100-point scoring system",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Claude Code Dev Workflows",
|
||||
"url": "https://github.com/cexll/myclaude"
|
||||
},
|
||||
"homepage": "https://github.com/cexll/myclaude",
|
||||
"repository": "https://github.com/cexll/myclaude",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"requirements",
|
||||
"clarification",
|
||||
"prd",
|
||||
"specifications",
|
||||
"quality-gates",
|
||||
"requirements-engineering"
|
||||
],
|
||||
"category": "essentials",
|
||||
"strict": false,
|
||||
"skills": [
|
||||
"./skills/SKILL.md"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@@ -1,3 +1,4 @@
|
||||
CLAUDE.md
|
||||
|
||||
.claude/
|
||||
|
||||
|
||||
|
||||
@@ -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 <PROJECT_DESCRIPTION> [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}` 由 `<PROJECT_DESCRIPTION>` 生成（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`，统一路径与跨阶段引用；明确确认门与目录预创建说明。
|
||||
339
BMAD-README.md
339
BMAD-README.md
@@ -1,339 +0,0 @@
|
||||
# BMAD方法论 Claude Code 使用指南
|
||||
|
||||
[](https://github.com/bmadcode/BMAD-METHOD)
|
||||
[](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代理团队带来的开发效率和质量提升！
|
||||
68
Makefile
68
Makefile
@@ -1,7 +1,7 @@
|
||||
# Claude Code Multi-Agent Workflow System Makefile
|
||||
# Quick deployment for BMAD and Requirements workflows
|
||||
|
||||
.PHONY: help install deploy-bmad deploy-requirements deploy-all clean test
|
||||
.PHONY: help install deploy-bmad deploy-requirements deploy-essentials deploy-advanced deploy-all deploy-commands deploy-agents clean test
|
||||
|
||||
# Default target
|
||||
help:
|
||||
@@ -11,23 +11,29 @@ help:
|
||||
@echo ""
|
||||
@echo "Targets:"
|
||||
@echo " install - Install all configurations to Claude Code"
|
||||
@echo " deploy-bmad - Deploy BMAD workflow (bmad-pilot)"
|
||||
@echo " deploy-requirements - Deploy Requirements workflow (requirements-pilot)"
|
||||
@echo " deploy-commands - Deploy all slash commands"
|
||||
@echo " deploy-agents - Deploy all agent configurations"
|
||||
@echo " deploy-all - Deploy everything (commands + agents)"
|
||||
@echo " test-bmad - Test BMAD workflow with sample"
|
||||
@echo " test-requirements - Test Requirements workflow with sample"
|
||||
@echo " clean - Clean generated artifacts"
|
||||
@echo " help - Show this help message"
|
||||
@echo " deploy-bmad - Deploy BMAD workflow (bmad-pilot)"
|
||||
@echo " deploy-requirements - Deploy Requirements workflow (requirements-pilot)"
|
||||
@echo " deploy-essentials - Deploy Development Essentials workflow"
|
||||
@echo " deploy-advanced - Deploy Advanced AI Agents"
|
||||
@echo " deploy-commands - Deploy all slash commands"
|
||||
@echo " deploy-agents - Deploy all agent configurations"
|
||||
@echo " deploy-all - Deploy everything (commands + agents)"
|
||||
@echo " test-bmad - Test BMAD workflow with sample"
|
||||
@echo " test-requirements - Test Requirements workflow with sample"
|
||||
@echo " clean - Clean generated artifacts"
|
||||
@echo " help - Show this help message"
|
||||
|
||||
# Configuration paths
|
||||
CLAUDE_CONFIG_DIR = ~/.claude
|
||||
COMMANDS_DIR = commands
|
||||
AGENTS_DIR = agents
|
||||
OUTPUT_STYLES_DIR = output-styles
|
||||
SPECS_DIR = .claude/specs
|
||||
|
||||
# Workflow directories
|
||||
BMAD_DIR = bmad-agile-workflow
|
||||
REQUIREMENTS_DIR = requirements-driven-workflow
|
||||
ESSENTIALS_DIR = development-essentials
|
||||
ADVANCED_DIR = advanced-ai-agents
|
||||
OUTPUT_STYLES_DIR = output-styles
|
||||
|
||||
# Install all configurations
|
||||
install: deploy-all
|
||||
@echo "✅ Installation complete!"
|
||||
@@ -38,8 +44,8 @@ deploy-bmad:
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/output-styles
|
||||
@cp $(COMMANDS_DIR)/bmad-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(AGENTS_DIR)/bmad-*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@cp $(BMAD_DIR)/commands/bmad-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(BMAD_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@cp $(OUTPUT_STYLES_DIR)/bmad.md $(CLAUDE_CONFIG_DIR)/output-styles/ 2>/dev/null || true
|
||||
@echo "✅ BMAD workflow deployed successfully!"
|
||||
@echo " Usage: /bmad-pilot \"your feature description\""
|
||||
@@ -49,16 +55,35 @@ deploy-requirements:
|
||||
@echo "🚀 Deploying Requirements workflow..."
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
|
||||
@cp $(COMMANDS_DIR)/requirements-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(AGENTS_DIR)/requirements-*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@cp $(REQUIREMENTS_DIR)/commands/requirements-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(REQUIREMENTS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@echo "✅ Requirements workflow deployed successfully!"
|
||||
@echo " Usage: /requirements-pilot \"your feature description\""
|
||||
|
||||
# Deploy Development Essentials workflow
|
||||
deploy-essentials:
|
||||
@echo "🚀 Deploying Development Essentials workflow..."
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
|
||||
@cp $(ESSENTIALS_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(ESSENTIALS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@echo "✅ Development Essentials deployed successfully!"
|
||||
@echo " Available commands: /ask, /code, /debug, /test, /review, /optimize, /bugfix, /refactor, /docs, /think"
|
||||
|
||||
# Deploy Advanced AI Agents
|
||||
deploy-advanced:
|
||||
@echo "🚀 Deploying Advanced AI Agents..."
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
|
||||
@cp $(ADVANCED_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@echo "✅ Advanced AI Agents deployed successfully!"
|
||||
|
||||
# Deploy all commands
|
||||
deploy-commands:
|
||||
@echo "📦 Deploying all slash commands..."
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
|
||||
@cp $(COMMANDS_DIR)/*.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(BMAD_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(REQUIREMENTS_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@cp $(ESSENTIALS_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
|
||||
@echo "✅ All commands deployed!"
|
||||
@echo " Available commands:"
|
||||
@echo " - /bmad-pilot (Full agile workflow)"
|
||||
@@ -70,7 +95,10 @@ deploy-commands:
|
||||
deploy-agents:
|
||||
@echo "🤖 Deploying all agents..."
|
||||
@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
|
||||
@cp $(AGENTS_DIR)/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@cp $(BMAD_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@cp $(REQUIREMENTS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@cp $(ESSENTIALS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@cp $(ADVANCED_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
|
||||
@echo "✅ All agents deployed!"
|
||||
|
||||
# Deploy everything
|
||||
@@ -105,6 +133,8 @@ clean:
|
||||
# Quick deployment shortcuts
|
||||
bmad: deploy-bmad
|
||||
requirements: deploy-requirements
|
||||
essentials: deploy-essentials
|
||||
advanced: deploy-advanced
|
||||
all: deploy-all
|
||||
|
||||
# Version info
|
||||
|
||||
288
README-zh.md
288
README-zh.md
@@ -1,288 +0,0 @@
|
||||
# Claude Code 多智能体工作流系统
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai/code)
|
||||
[](https://github.com/)
|
||||
[](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 智能体处理专业工作。*
|
||||
308
README.md
308
README.md
@@ -2,288 +2,120 @@
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai/code)
|
||||
[](https://github.com/)
|
||||
[](https://github.com/cexll/myclaude)
|
||||
[](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` |
|
||||
| **[requirements-clarity](docs/REQUIREMENTS-CLARITY.md)** | Automated requirements clarification with 100-point scoring | Auto-activated skill |
|
||||
|
||||
```
|
||||
.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:
|
||||
**Requirements Clarity** - Automated requirements engineering
|
||||
- Auto-detects vague requirements and initiates clarification
|
||||
- 100-point quality scoring system
|
||||
- Generates complete PRD documents
|
||||
|
||||
#### Available Plugins
|
||||
## 🎯 Key Features
|
||||
|
||||
| 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 |
|
||||
- **🤖 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
|
||||
- **🎯 Requirements Clarity**: Automated requirements clarification with quality scoring
|
||||
|
||||
#### Using Plugins
|
||||
## 📚 Documentation
|
||||
|
||||
- **[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.
|
||||
|
||||
121
README_CN.md
Normal file
121
README_CN.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# Claude Code 多智能体工作流系统
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai/code)
|
||||
[](https://github.com/cexll/myclaude)
|
||||
[](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` |
|
||||
| **[requirements-clarity](docs/REQUIREMENTS-CLARITY.md)** | 自动需求澄清，100分制质量评分 | 自动激活技能 |
|
||||
|
||||
## 💡 使用场景
|
||||
|
||||
**BMAD 工作流** - 完整敏捷流程自动化
|
||||
- 产品需求 → 架构设计 → 冲刺规划 → 开发实现 → 代码审查 → 质量测试
|
||||
- 90% 阈值质量门控
|
||||
- 自动生成文档
|
||||
|
||||
**Requirements 工作流** - 快速原型开发
|
||||
- 需求生成 → 实现 → 审查 → 测试
|
||||
- 轻量级实用主义
|
||||
|
||||
**开发命令** - 日常编码
|
||||
- 直接实现、调试、测试、优化
|
||||
- 无工作流开销
|
||||
|
||||
**需求澄清** - 自动化需求工程
|
||||
- 自动检测模糊需求并启动澄清流程
|
||||
- 100分制质量评分系统
|
||||
- 生成完整的产品需求文档
|
||||
|
||||
## 🎯 核心特性
|
||||
|
||||
- **🤖 角色化智能体**: 每个开发阶段的专业 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 驱动的自动化转型您的开发流程** - 一条命令，完整工作流，质量保证。
|
||||
253
development-essentials/README.md
Normal file
253
development-essentials/README.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Development Essentials - Core Development Commands
|
||||
|
||||
核心开发命令套件，提供日常开发所需的所有基础命令。无需工作流开销，直接执行开发任务。
|
||||
|
||||
## 📋 命令列表
|
||||
|
||||
### 1. `/ask` - 技术咨询
|
||||
**用途**: 架构问题咨询和技术决策指导
|
||||
**适用场景**: 需要架构建议、技术选型、系统设计方案时
|
||||
|
||||
**特点**:
|
||||
- 四位架构顾问协同：系统设计师、技术策略师、可扩展性顾问、风险分析师
|
||||
- 遵循 KISS、YAGNI、SOLID 原则
|
||||
- 提供架构分析、设计建议、技术指导和实施策略
|
||||
- **不生成代码**，专注于架构咨询
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/ask "如何设计一个支持百万并发的消息队列系统？"
|
||||
/ask "微服务架构中应该如何处理分布式事务？"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. `/code` - 功能实现
|
||||
**用途**: 直接实现新功能或特性
|
||||
**适用场景**: 需要快速开发新功能时
|
||||
|
||||
**特点**:
|
||||
- 四位开发专家协同：架构师、实现工程师、集成专家、代码审查员
|
||||
- 渐进式开发，每步验证
|
||||
- 包含完整的实现计划、代码实现、集成指南和测试策略
|
||||
- 生成可运行的高质量代码
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/code "实现JWT认证中间件"
|
||||
/code "添加用户头像上传功能"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. `/debug` - 系统调试
|
||||
**用途**: 使用 UltraThink 方法系统性调试问题
|
||||
**适用场景**: 遇到复杂bug或系统性问题时
|
||||
|
||||
**特点**:
|
||||
- 四位专家协同：架构师、研究员、编码员、测试员
|
||||
- UltraThink 反思阶段：综合所有洞察形成解决方案
|
||||
- 生成5-7个假设，逐步缩减到1-2个最可能的原因
|
||||
- 在实施修复前要求用户确认诊断结果
|
||||
- 证据驱动的系统性问题分析
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/debug "API响应时间突然增加10倍"
|
||||
/debug "生产环境内存泄漏问题"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. `/test` - 测试策略
|
||||
**用途**: 设计和实现全面的测试策略
|
||||
**适用场景**: 需要为组件或功能编写测试时
|
||||
|
||||
**特点**:
|
||||
- 四位测试专家：测试架构师、单元测试专家、集成测试工程师、质量验证员
|
||||
- 测试金字塔策略（单元/集成/端到端比例）
|
||||
- 提供测试覆盖率分析和优先级建议
|
||||
- 包含 CI/CD 集成计划
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/test "用户认证模块"
|
||||
/test "支付处理流程"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. `/optimize` - 性能优化
|
||||
**用途**: 识别和优化性能瓶颈
|
||||
**适用场景**: 系统存在性能问题或需要提升性能时
|
||||
|
||||
**特点**:
|
||||
- 四位优化专家：性能分析师、算法工程师、资源管理员、可扩展性架构师
|
||||
- 建立性能基线和量化指标
|
||||
- 优化算法复杂度、内存使用、I/O操作
|
||||
- 设计水平扩展和并发处理方案
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/optimize "数据库查询性能"
|
||||
/optimize "API响应时间优化到200ms以内"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. `/review` - 代码审查
|
||||
**用途**: 全方位代码质量审查
|
||||
**适用场景**: 需要审查代码质量、安全性和架构设计时
|
||||
|
||||
**特点**:
|
||||
- 四位审查专家：质量审计员、安全分析师、性能审查员、架构评估员
|
||||
- 多维度审查：可读性、安全性、性能、架构设计
|
||||
- 提供优先级分类的改进建议
|
||||
- 包含具体代码示例和重构建议
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/review "src/auth/middleware.ts"
|
||||
/review "支付模块代码"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. `/bugfix` - Bug修复
|
||||
**用途**: 快速定位和修复Bug
|
||||
**适用场景**: 需要修复已知Bug时
|
||||
|
||||
**特点**:
|
||||
- 专注于快速修复
|
||||
- 包含验证流程
|
||||
- 确保修复不引入新问题
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/bugfix "登录失败后session未清理"
|
||||
/bugfix "订单状态更新不及时"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. `/refactor` - 代码重构
|
||||
**用途**: 改进代码结构和可维护性
|
||||
**适用场景**: 代码质量下降或需要优化代码结构时
|
||||
|
||||
**特点**:
|
||||
- 保持功能不变
|
||||
- 提升代码质量和可维护性
|
||||
- 遵循设计模式和最佳实践
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/refactor "将用户管理模块拆分为独立服务"
|
||||
/refactor "优化支付流程代码结构"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. `/docs` - 文档生成
|
||||
**用途**: 生成项目文档和API文档
|
||||
**适用场景**: 需要为代码或API生成文档时
|
||||
|
||||
**特点**:
|
||||
- 自动分析代码结构
|
||||
- 生成清晰的文档
|
||||
- 包含使用示例
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/docs "API接口文档"
|
||||
/docs "为认证模块生成开发者文档"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. `/think` - 深度分析
|
||||
**用途**: 对复杂问题进行深度思考和分析
|
||||
**适用场景**: 需要全面分析复杂技术问题时
|
||||
|
||||
**特点**:
|
||||
- 系统性思考框架
|
||||
- 多角度问题分析
|
||||
- 提供深入见解
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/think "如何设计一个高可用的分布式系统？"
|
||||
/think "微服务拆分的最佳实践是什么？"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 11. `/enhance-prompt` - 提示词增强 🆕
|
||||
**用途**: 优化和增强用户提供的指令
|
||||
**适用场景**: 需要改进模糊或不清晰的指令时
|
||||
|
||||
**特点**:
|
||||
- 自动分析指令上下文
|
||||
- 消除歧义，提高清晰度
|
||||
- 修正错误并提高具体性
|
||||
- 立即返回增强后的提示词
|
||||
- 保留代码块等特殊格式
|
||||
|
||||
**输出格式**:
|
||||
```
|
||||
### Here is an enhanced version of the original instruction that is more specific and clear:
|
||||
<enhanced-prompt>增强后的提示词</enhanced-prompt>
|
||||
```
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
/enhance-prompt "帮我做一个登录功能"
|
||||
/enhance-prompt "优化一下这个API"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 命令选择指南
|
||||
|
||||
| 需求场景 | 推荐命令 | 说明 |
|
||||
|---------|---------|------|
|
||||
| 需要架构建议 | `/ask` | 不生成代码，专注咨询 |
|
||||
| 实现新功能 | `/code` | 完整的功能实现流程 |
|
||||
| 调试复杂问题 | `/debug` | UltraThink系统性调试 |
|
||||
| 编写测试 | `/test` | 全面的测试策略 |
|
||||
| 性能优化 | `/optimize` | 性能瓶颈分析和优化 |
|
||||
| 代码审查 | `/review` | 多维度质量审查 |
|
||||
| 修复Bug | `/bugfix` | 快速定位和修复 |
|
||||
| 重构代码 | `/refactor` | 提升代码质量 |
|
||||
| 生成文档 | `/docs` | API和开发者文档 |
|
||||
| 深度思考 | `/think` | 复杂问题分析 |
|
||||
| 优化指令 | `/enhance-prompt` | 提示词增强 |
|
||||
|
||||
## 🔧 代理列表
|
||||
|
||||
Development Essentials 模块包含以下专用代理：
|
||||
|
||||
- `code` - 代码实现代理
|
||||
- `bugfix` - Bug修复代理
|
||||
- `bugfix-verify` - Bug验证代理
|
||||
- `code-optimize` - 代码优化代理
|
||||
- `debug` - 调试分析代理
|
||||
- `develop` - 通用开发代理
|
||||
|
||||
## 📖 使用原则
|
||||
|
||||
1. **直接执行**: 无需工作流开销，直接运行命令
|
||||
2. **专注单一任务**: 每个命令聚焦特定开发任务
|
||||
3. **质量优先**: 所有命令都包含质量验证环节
|
||||
4. **实用主义**: KISS/YAGNI/DRY 原则贯穿始终
|
||||
5. **上下文感知**: 自动理解项目结构和编码规范
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [主文档](../README.md) - 项目总览
|
||||
- [BMAD工作流](../docs/BMAD-WORKFLOW.md) - 完整敏捷流程
|
||||
- [Requirements工作流](../docs/REQUIREMENTS-WORKFLOW.md) - 轻量级开发流程
|
||||
- [插件系统](../PLUGIN_README.md) - 插件安装和管理
|
||||
|
||||
---
|
||||
|
||||
**提示**: 这些命令可以单独使用，也可以组合使用。例如：`/code` → `/test` → `/review` → `/optimize` 构成一个完整的开发周期。
|
||||
9
development-essentials/commands/enhance-prompt.md
Normal file
9
development-essentials/commands/enhance-prompt.md
Normal file
@@ -0,0 +1,9 @@
|
||||
`/enhance-prompt <task info>`
|
||||
|
||||
Here is an instruction that I'd like to give you, but it needs to be improved. Rewrite and enhance this instruction to make it clearer, more specific, less ambiguous, and correct any mistakes. Do not use any tools: reply immediately with your answer, even if you're not sure. Consider the context of our conversation history when enhancing the prompt. If there is code in triple backticks (```) consider whether it is a code sample and should remain unchanged.Reply with the following format:
|
||||
|
||||
### BEGIN RESPONSE
|
||||
|
||||
<enhanced-prompt>enhanced prompt goes here</enhanced-prompt>
|
||||
|
||||
### END RESPONSE
|
||||
315
docs/ADVANCED-AGENTS.md
Normal file
315
docs/ADVANCED-AGENTS.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# Advanced AI Agents Guide
|
||||
|
||||
> GPT-5 deep reasoning integration for complex analysis and architectural decisions
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
The Advanced AI Agents plugin provides access to GPT-5's deep reasoning capabilities through the `gpt5` agent, designed for complex problem-solving that requires multi-step thinking and comprehensive analysis.
|
||||
|
||||
## 🤖 GPT-5 Agent
|
||||
|
||||
### Capabilities
|
||||
|
||||
The `gpt5` agent excels at:
|
||||
|
||||
- **Architectural Analysis**: Evaluating system designs and scalability concerns
|
||||
- **Strategic Planning**: Breaking down complex initiatives into actionable plans
|
||||
- **Trade-off Analysis**: Comparing multiple approaches with detailed pros/cons
|
||||
- **Problem Decomposition**: Breaking complex problems into manageable components
|
||||
- **Deep Reasoning**: Multi-step logical analysis for non-obvious solutions
|
||||
- **Technology Evaluation**: Assessing technologies, frameworks, and tools
|
||||
|
||||
### When to Use
|
||||
|
||||
**Use GPT-5 agent** when:
|
||||
- Problem requires deep, multi-step reasoning
|
||||
- Multiple solution approaches need evaluation
|
||||
- Architectural decisions have long-term impact
|
||||
- Trade-offs are complex and multifaceted
|
||||
- Standard agents provide insufficient depth
|
||||
|
||||
**Use standard agents** when:
|
||||
- Task is straightforward implementation
|
||||
- Requirements are clear and well-defined
|
||||
- Quick turnaround is priority
|
||||
- Problem is domain-specific (code, tests, etc.)
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Via `/think` Command
|
||||
|
||||
The easiest way to access GPT-5:
|
||||
|
||||
```bash
|
||||
/think "Analyze scalability bottlenecks in current microservices architecture"
|
||||
/think "Evaluate migration strategy from monolith to microservices"
|
||||
/think "Design data synchronization approach for offline-first mobile app"
|
||||
```
|
||||
|
||||
### Direct Agent Invocation
|
||||
|
||||
For advanced usage:
|
||||
|
||||
```bash
|
||||
# Use @gpt5 to invoke the agent directly
|
||||
@gpt5 "Complex architectural question or analysis request"
|
||||
```
|
||||
|
||||
## 💡 Example Use Cases
|
||||
|
||||
### 1. Architecture Evaluation
|
||||
|
||||
```bash
|
||||
/think "Current system uses REST API with polling for real-time updates.
|
||||
Evaluate whether to migrate to WebSocket, Server-Sent Events, or GraphQL
|
||||
subscriptions. Consider: team experience, existing infrastructure, client
|
||||
support, scalability, and implementation effort."
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Detailed analysis of each option
|
||||
- Pros and cons for your specific context
|
||||
- Migration complexity assessment
|
||||
- Performance implications
|
||||
- Recommended approach with justification
|
||||
|
||||
### 2. Migration Strategy
|
||||
|
||||
```bash
|
||||
/think "Plan migration from PostgreSQL to multi-region distributed database.
|
||||
System has 50M users, 200M rows, 1000 req/sec. Must maintain 99.9% uptime.
|
||||
What's the safest migration path?"
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Step-by-step migration plan
|
||||
- Risk assessment for each phase
|
||||
- Rollback strategies
|
||||
- Data consistency approaches
|
||||
- Timeline estimation
|
||||
|
||||
### 3. Problem Decomposition
|
||||
|
||||
```bash
|
||||
/think "Design a recommendation engine that learns user preferences, handles
|
||||
cold start, provides explainable results, and scales to 10M users. Break this
|
||||
down into implementation phases with clear milestones."
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Problem breakdown into components
|
||||
- Phased implementation plan
|
||||
- Technical approach for each phase
|
||||
- Dependencies between phases
|
||||
- Success criteria and metrics
|
||||
|
||||
### 4. Technology Selection
|
||||
|
||||
```bash
|
||||
/think "Choosing between Redis, Memcached, and Hazelcast for distributed
|
||||
caching. System needs: persistence, pub/sub, clustering, and complex data
|
||||
structures. Existing stack: Java, Kubernetes, AWS."
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Comparison matrix across requirements
|
||||
- Integration considerations
|
||||
- Operational complexity analysis
|
||||
- Cost implications
|
||||
- Recommendation with rationale
|
||||
|
||||
### 5. Performance Optimization
|
||||
|
||||
```bash
|
||||
/think "API response time increased from 100ms to 800ms after scaling from
|
||||
100 to 10,000 users. Database queries look optimized. What are the likely
|
||||
bottlenecks and systematic approach to identify them?"
|
||||
```
|
||||
|
||||
**GPT-5 provides**:
|
||||
- Hypothesis generation (N+1 queries, connection pooling, etc.)
|
||||
- Systematic debugging approach
|
||||
- Profiling strategy
|
||||
- Likely root causes ranked by probability
|
||||
- Optimization recommendations
|
||||
|
||||
## 🎨 Integration with BMAD
|
||||
|
||||
### Enhanced Code Review
|
||||
|
||||
BMAD's `bmad-review` agent can optionally use GPT-5 for deeper analysis:
|
||||
|
||||
**Configuration**:
|
||||
```bash
|
||||
# Enable enhanced review mode (via environment or BMAD config)
|
||||
BMAD_REVIEW_MODE=enhanced /bmad-pilot "feature description"
|
||||
```
|
||||
|
||||
**What changes**:
|
||||
- Standard review: Fast, focuses on code quality and obvious issues
|
||||
- Enhanced review: Deep analysis including:
|
||||
- Architectural impact
|
||||
- Security implications
|
||||
- Performance considerations
|
||||
- Scalability concerns
|
||||
- Design pattern appropriateness
|
||||
|
||||
### Architecture Phase Support
|
||||
|
||||
Use `/think` during BMAD architecture phase:
|
||||
|
||||
```bash
|
||||
# Start BMAD workflow
|
||||
/bmad-pilot "E-commerce platform with real-time inventory"
|
||||
|
||||
# During Architecture phase, get deep analysis
|
||||
/think "Evaluate architecture approaches for real-time inventory
|
||||
synchronization across warehouses, online store, and mobile apps"
|
||||
|
||||
# Continue with BMAD using insights
|
||||
```
|
||||
|
||||
## 📋 Best Practices
|
||||
|
||||
### 1. Provide Complete Context
|
||||
|
||||
**❌ Insufficient**:
|
||||
```bash
|
||||
/think "Should we use microservices?"
|
||||
```
|
||||
|
||||
**✅ Complete**:
|
||||
```bash
|
||||
/think "Current monolith: 100K LOC, 8 developers, 50K users, 200ms avg
|
||||
response time. Pain points: slow deployments (1hr), difficult to scale
|
||||
components independently. Should we migrate to microservices? What's the
|
||||
ROI and risk?"
|
||||
```
|
||||
|
||||
### 2. Ask Specific Questions
|
||||
|
||||
**❌ Too broad**:
|
||||
```bash
|
||||
/think "How to build a scalable system?"
|
||||
```
|
||||
|
||||
**✅ Specific**:
|
||||
```bash
|
||||
/think "Current system handles 1K req/sec. Need to scale to 10K. Bottleneck
|
||||
is database writes. Evaluate: sharding, read replicas, CQRS, or caching.
|
||||
Database: PostgreSQL, stack: Node.js, deployment: Kubernetes."
|
||||
```
|
||||
|
||||
### 3. Include Constraints
|
||||
|
||||
Always mention:
|
||||
- Team skills and size
|
||||
- Timeline and budget
|
||||
- Existing infrastructure
|
||||
- Business requirements
|
||||
- Technical constraints
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/think "Design real-time chat system. Constraints: team of 3 backend
|
||||
developers (Node.js), 6-month timeline, AWS deployment, must integrate
|
||||
with existing REST API, budget for managed services OK."
|
||||
```
|
||||
|
||||
### 4. Request Specific Outputs
|
||||
|
||||
Tell GPT-5 what format you need:
|
||||
|
||||
```bash
|
||||
/think "Compare Kafka vs RabbitMQ for event streaming.
|
||||
Provide: comparison table, recommendation, migration complexity from current
|
||||
RabbitMQ setup, and estimated effort in developer-weeks."
|
||||
```
|
||||
|
||||
### 5. Iterate and Refine
|
||||
|
||||
Follow up for deeper analysis:
|
||||
|
||||
```bash
|
||||
# Initial question
|
||||
/think "Evaluate caching strategies for user profile API"
|
||||
|
||||
# Follow-up based on response
|
||||
/think "You recommended Redis with write-through caching. How to handle
|
||||
cache invalidation when user updates profile from mobile app?"
|
||||
```
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
### Sequential Thinking
|
||||
|
||||
GPT-5 agent uses sequential thinking for complex problems:
|
||||
|
||||
1. **Problem Understanding**: Clarify requirements and constraints
|
||||
2. **Hypothesis Generation**: Identify possible solutions
|
||||
3. **Analysis**: Evaluate each option systematically
|
||||
4. **Trade-off Assessment**: Compare pros/cons
|
||||
5. **Recommendation**: Provide justified conclusion
|
||||
|
||||
### Reasoning Transparency
|
||||
|
||||
GPT-5 shows its thinking process:
|
||||
- Assumptions made
|
||||
- Factors considered
|
||||
- Why certain options were eliminated
|
||||
- Confidence level in recommendations
|
||||
|
||||
## 🎯 Comparison: GPT-5 vs Standard Agents
|
||||
|
||||
| Aspect | GPT-5 Agent | Standard Agents |
|
||||
|--------|-------------|-----------------|
|
||||
| **Depth** | Deep, multi-step reasoning | Focused, domain-specific |
|
||||
| **Speed** | Slower (comprehensive analysis) | Faster (direct implementation) |
|
||||
| **Use Case** | Strategic decisions, architecture | Implementation, coding, testing |
|
||||
| **Output** | Analysis, recommendations, plans | Code, tests, documentation |
|
||||
| **Best For** | Complex problems, trade-offs | Clear tasks, defined scope |
|
||||
| **Invocation** | `/think` or `@gpt5` | `/code`, `/test`, etc. |
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Integration with full agile workflow
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Standard command reference
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
|
||||
## 💡 Advanced Patterns
|
||||
|
||||
### Pre-Implementation Analysis
|
||||
|
||||
```bash
|
||||
# 1. Deep analysis with GPT-5
|
||||
/think "Design approach for X with constraints Y and Z"
|
||||
|
||||
# 2. Use analysis in BMAD workflow
|
||||
/bmad-pilot "Implement X based on approach from analysis"
|
||||
```
|
||||
|
||||
### Architecture Validation
|
||||
|
||||
```bash
|
||||
# 1. Get initial architecture from BMAD
|
||||
/bmad-pilot "Feature X" # Generates 02-system-architecture.md
|
||||
|
||||
# 2. Validate with GPT-5
|
||||
/think "Review architecture in .claude/specs/feature-x/02-system-architecture.md
|
||||
Evaluate for scalability, security, and maintainability"
|
||||
|
||||
# 3. Refine architecture based on feedback
|
||||
```
|
||||
|
||||
### Decision Documentation
|
||||
|
||||
```bash
|
||||
# Use GPT-5 to document architectural decisions
|
||||
/think "Document decision to use Event Sourcing for order management.
|
||||
Include: context, options considered, decision rationale, consequences,
|
||||
and format as Architecture Decision Record (ADR)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Advanced AI Agents** - Deep reasoning for complex problems that require comprehensive analysis.
|
||||
258
docs/BMAD-WORKFLOW.md
Normal file
258
docs/BMAD-WORKFLOW.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# BMAD Workflow Complete Guide
|
||||
|
||||
> **BMAD (Business-Minded Agile Development)** - AI-driven agile development automation with role-based agents
|
||||
|
||||
## 🎯 What is BMAD?
|
||||
|
||||
BMAD is an enterprise-grade agile development methodology that transforms your development process into a fully automated workflow with 6 specialized AI agents and quality gates.
|
||||
|
||||
### Core Principles
|
||||
|
||||
- **Agent Planning**: Specialized agents collaborate to create detailed, consistent PRDs and architecture documents
|
||||
- **Context-Driven Development**: Transform detailed plans into ultra-detailed development stories
|
||||
- **Role Specialization**: Each agent focuses on specific domains, avoiding quality degradation from role switching
|
||||
|
||||
## 🤖 BMAD Agent System
|
||||
|
||||
### Agent Roles
|
||||
|
||||
| Agent | Role | Quality Gate | Artifacts |
|
||||
|-------|------|--------------|-----------|
|
||||
| **bmad-po** (Sarah) | Product Owner - requirements gathering, user stories | PRD ≥ 90/100 | `01-product-requirements.md` |
|
||||
| **bmad-architect** (Winston) | System Architect - technical design, system architecture | Design ≥ 90/100 | `02-system-architecture.md` |
|
||||
| **bmad-sm** (Mike) | Scrum Master - task breakdown, sprint planning | User approval | `03-sprint-plan.md` |
|
||||
| **bmad-dev** (Alex) | Developer - code implementation, technical docs | Code completion | Implementation files |
|
||||
| **bmad-review** | Code Reviewer - independent review between Dev and QA | Pass/Risk/Fail | `04-dev-reviewed.md` |
|
||||
| **bmad-qa** (Emma) | QA Engineer - testing strategy, quality assurance | Test execution | `05-qa-report.md` |
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Command Overview
|
||||
|
||||
```bash
|
||||
# Full BMAD workflow
|
||||
/bmad-pilot "Build e-commerce checkout system with payment integration"
|
||||
|
||||
# Workflow: PO → Architect → SM → Dev → Review → QA
|
||||
```
|
||||
|
||||
### Command Options
|
||||
|
||||
```bash
|
||||
# Skip testing phase
|
||||
/bmad-pilot "Admin dashboard" --skip-tests
|
||||
|
||||
# Skip sprint planning (architecture → dev directly)
|
||||
/bmad-pilot "API gateway implementation" --direct-dev
|
||||
|
||||
# Skip repository scan (not recommended)
|
||||
/bmad-pilot "Add feature" --skip-scan
|
||||
```
|
||||
|
||||
### Individual Agent Usage
|
||||
|
||||
```bash
|
||||
# Product requirements analysis only
|
||||
/bmad-po "Enterprise CRM system requirements"
|
||||
|
||||
# Technical architecture design only
|
||||
/bmad-architect "High-concurrency distributed system design"
|
||||
|
||||
# Orchestrator (can transform into any agent)
|
||||
/bmad-orchestrator "Coordinate multi-agent complex project"
|
||||
```
|
||||
|
||||
## 📋 Workflow Phases
|
||||
|
||||
### Phase 0: Repository Scan (Automatic)
|
||||
- **Agent**: `bmad-orchestrator`
|
||||
- **Output**: `00-repository-context.md`
|
||||
- **Content**: Project type, tech stack, code organization, conventions, integration points
|
||||
|
||||
### Phase 1: Product Requirements (PO)
|
||||
- **Agent**: `bmad-po` (Sarah - Product Owner)
|
||||
- **Quality Gate**: PRD score ≥ 90/100
|
||||
- **Output**: `01-product-requirements.md`
|
||||
- **Process**:
|
||||
1. PO generates initial PRD
|
||||
2. System calculates quality score (100-point scale)
|
||||
3. If < 90: User provides feedback → PO revises → Recalculate
|
||||
4. If ≥ 90: User confirms → Save artifact → Next phase
|
||||
|
||||
### Phase 2: System Architecture (Architect)
|
||||
- **Agent**: `bmad-architect` (Winston - System Architect)
|
||||
- **Quality Gate**: Design score ≥ 90/100
|
||||
- **Output**: `02-system-architecture.md`
|
||||
- **Process**:
|
||||
1. Architect reads PRD + repo context
|
||||
2. Generates technical design document
|
||||
3. System calculates design quality score
|
||||
4. If < 90: User provides feedback → Architect revises
|
||||
5. If ≥ 90: User confirms → Save artifact → Next phase
|
||||
|
||||
### Phase 3: Sprint Planning (SM)
|
||||
- **Agent**: `bmad-sm` (Mike - Scrum Master)
|
||||
- **Quality Gate**: User approval
|
||||
- **Output**: `03-sprint-plan.md`
|
||||
- **Process**:
|
||||
1. SM reads PRD + Architecture
|
||||
2. Breaks down tasks with story points
|
||||
3. User reviews sprint plan
|
||||
4. User confirms → Save artifact → Next phase
|
||||
- **Skip**: Use `--direct-dev` to skip this phase
|
||||
|
||||
### Phase 4: Development (Dev)
|
||||
- **Agent**: `bmad-dev` (Alex - Developer)
|
||||
- **Quality Gate**: Code completion
|
||||
- **Output**: Implementation files
|
||||
- **Process**:
|
||||
1. Dev reads all previous artifacts
|
||||
2. Implements features following sprint plan
|
||||
3. Creates or modifies code files
|
||||
4. Completes implementation → Next phase
|
||||
|
||||
### Phase 5: Code Review (Review)
|
||||
- **Agent**: `bmad-review` (Independent Reviewer)
|
||||
- **Quality Gate**: Pass / Pass with Risk / Fail
|
||||
- **Output**: `04-dev-reviewed.md`
|
||||
- **Process**:
|
||||
1. Review reads implementation + all specs
|
||||
2. Performs comprehensive code review
|
||||
3. Generates review report with status:
|
||||
- **Pass**: No issues, proceed to QA
|
||||
- **Pass with Risk**: Non-critical issues noted
|
||||
- **Fail**: Critical issues, return to Dev
|
||||
4. Updates sprint plan with review findings
|
||||
|
||||
**Enhanced Review (Optional)**:
|
||||
- Use GPT-5 via Codex CLI for deeper analysis
|
||||
- Set via `BMAD_REVIEW_MODE=enhanced` environment variable
|
||||
|
||||
### Phase 6: Quality Assurance (QA)
|
||||
- **Agent**: `bmad-qa` (Emma - QA Engineer)
|
||||
- **Quality Gate**: Test execution
|
||||
- **Output**: `05-qa-report.md`
|
||||
- **Process**:
|
||||
1. QA reads implementation + review + all specs
|
||||
2. Creates targeted test strategy
|
||||
3. Executes tests
|
||||
4. Generates QA report
|
||||
5. Workflow complete
|
||||
- **Skip**: Use `--skip-tests` to skip this phase
|
||||
|
||||
## 📊 Quality Scoring System
|
||||
|
||||
### PRD Quality (100 points)
|
||||
- **Business Value** (30): Clear value proposition, user benefits
|
||||
- **Functional Requirements** (25): Complete, unambiguous requirements
|
||||
- **User Experience** (20): User flows, interaction patterns
|
||||
- **Technical Constraints** (15): Performance, security, scalability
|
||||
- **Scope & Priorities** (10): Clear boundaries, must-have vs nice-to-have
|
||||
|
||||
### Architecture Quality (100 points)
|
||||
- **Design Quality** (30): Modularity, maintainability, clarity
|
||||
- **Technology Selection** (25): Appropriate tech stack, justification
|
||||
- **Scalability** (20): Growth handling, performance considerations
|
||||
- **Security** (15): Authentication, authorization, data protection
|
||||
- **Feasibility** (10): Realistic implementation, resource alignment
|
||||
|
||||
### Review Status (3 levels)
|
||||
- **Pass**: No critical issues, code meets standards
|
||||
- **Pass with Risk**: Non-critical issues, recommendations included
|
||||
- **Fail**: Critical issues, requires Dev iteration
|
||||
|
||||
## 📁 Workflow Artifacts
|
||||
|
||||
All documents are saved to `.claude/specs/{feature-name}/`:
|
||||
|
||||
```
|
||||
.claude/specs/e-commerce-checkout/
|
||||
├── 00-repository-context.md # Repo analysis (auto)
|
||||
├── 01-product-requirements.md # PRD (PO, score ≥ 90)
|
||||
├── 02-system-architecture.md # Design (Architect, score ≥ 90)
|
||||
├── 03-sprint-plan.md # Sprint plan (SM, user approved)
|
||||
├── 04-dev-reviewed.md # Code review (Review, Pass/Risk/Fail)
|
||||
└── 05-qa-report.md # Test report (QA, tests executed)
|
||||
```
|
||||
|
||||
Feature name generated from project description (kebab-case: lowercase, spaces/punctuation → `-`).
|
||||
|
||||
## 🔧 Advanced Usage
|
||||
|
||||
### Approval Gates
|
||||
|
||||
Critical phases require explicit user confirmation:
|
||||
|
||||
```
|
||||
Architect: "Technical design complete (Score: 93/100)"
|
||||
System: "Ready to proceed to sprint planning? (yes/no)"
|
||||
User: yes
|
||||
```
|
||||
|
||||
### Iterative Refinement
|
||||
|
||||
Each phase supports feedback loops:
|
||||
|
||||
```
|
||||
PO: "Here's the PRD (Score: 75/100)"
|
||||
User: "Add mobile support and offline mode"
|
||||
PO: "Updated PRD (Score: 92/100) ✅"
|
||||
```
|
||||
|
||||
### Repository Context
|
||||
|
||||
BMAD automatically scans your repository to understand:
|
||||
- Technology stack (languages, frameworks, libraries)
|
||||
- Project structure (directories, modules, patterns)
|
||||
- Existing conventions (naming, formatting, architecture)
|
||||
- Dependencies (package managers, external services)
|
||||
- Integration points (APIs, databases, third-party services)
|
||||
|
||||
### Workflow Variations
|
||||
|
||||
**Fast Prototyping** - Skip non-essential phases:
|
||||
```bash
|
||||
/bmad-pilot "Quick admin UI" --skip-tests --direct-dev
|
||||
# Workflow: PO → Architect → Dev
|
||||
```
|
||||
|
||||
**Architecture-First** - Focus on design:
|
||||
```bash
|
||||
/bmad-architect "Microservices architecture for e-commerce"
|
||||
# Only runs Architect agent
|
||||
```
|
||||
|
||||
**Full Rigor** - All phases with maximum quality:
|
||||
```bash
|
||||
/bmad-pilot "Enterprise payment gateway with PCI compliance"
|
||||
# Workflow: Scan → PO → Architect → SM → Dev → Review → QA
|
||||
```
|
||||
|
||||
## 🎨 Output Style
|
||||
|
||||
BMAD workflow uses a specialized output style that:
|
||||
- Creates phase-separated contexts
|
||||
- Manages agent handoffs with clear boundaries
|
||||
- Tracks quality scores across phases
|
||||
- Handles approval gates with user prompts
|
||||
- Supports Codex CLI integration for enhanced reviews
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started in 5 minutes
|
||||
- **[Plugin System](PLUGIN-SYSTEM.md)** - Installation and configuration
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Alternative workflows
|
||||
- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight alternative
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
1. **Don't skip repository scan** - Helps agents understand your project context
|
||||
2. **Provide detailed descriptions** - Better input → better output
|
||||
3. **Engage with agents** - Provide feedback during quality gates
|
||||
4. **Review artifacts** - Check generated documents before confirming
|
||||
5. **Use appropriate workflows** - Full BMAD for complex features, lightweight for simple tasks
|
||||
6. **Keep artifacts** - They serve as project documentation and context for future work
|
||||
|
||||
---
|
||||
|
||||
**Transform your development with BMAD** - One command, complete agile workflow, quality assured.
|
||||
321
docs/DEVELOPMENT-COMMANDS.md
Normal file
321
docs/DEVELOPMENT-COMMANDS.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# Development Commands Reference
|
||||
|
||||
> Direct slash commands for daily coding tasks without workflow overhead
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
Development Essentials provides focused slash commands for common development tasks. Use these when you need direct implementation without the full workflow structure.
|
||||
|
||||
## 📋 Available Commands
|
||||
|
||||
### `/code` - Direct Implementation
|
||||
|
||||
Implement features, add functionality, or write code directly.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/code "Add input validation for email fields"
|
||||
/code "Implement pagination for user list API"
|
||||
/code "Create database migration for orders table"
|
||||
```
|
||||
|
||||
**Agent**: `code`
|
||||
|
||||
**Best for**:
|
||||
- Clear, well-defined tasks
|
||||
- Quick implementations
|
||||
- Following existing patterns
|
||||
- Adding straightforward features
|
||||
|
||||
### `/debug` - Systematic Debugging
|
||||
|
||||
Analyze and fix bugs with structured debugging approach.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/debug "Login fails with 500 error on invalid credentials"
|
||||
/debug "Memory leak in background worker process"
|
||||
/debug "Race condition in order processing"
|
||||
```
|
||||
|
||||
**Agent**: `debug`
|
||||
|
||||
**Approach**:
|
||||
1. Reproduce the issue
|
||||
2. Analyze root cause
|
||||
3. Propose solution
|
||||
4. Implement fix
|
||||
5. Verify resolution
|
||||
|
||||
### `/test` - Testing Strategy
|
||||
|
||||
Create tests, improve test coverage, or test existing code.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/test "Add unit tests for authentication service"
|
||||
/test "Create integration tests for payment flow"
|
||||
/test "Test edge cases for date parser"
|
||||
```
|
||||
|
||||
**Agent**: `develop` (testing mode)
|
||||
|
||||
**Covers**:
|
||||
- Unit tests
|
||||
- Integration tests
|
||||
- Edge cases
|
||||
- Error scenarios
|
||||
- Test data setup
|
||||
|
||||
### `/optimize` - Performance Tuning
|
||||
|
||||
Improve performance, reduce resource usage, or optimize algorithms.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/optimize "Reduce database queries in dashboard endpoint"
|
||||
/optimize "Speed up report generation process"
|
||||
/optimize "Improve memory usage in data processing pipeline"
|
||||
```
|
||||
|
||||
**Agent**: `develop` (optimization mode)
|
||||
|
||||
**Focus areas**:
|
||||
- Algorithm efficiency
|
||||
- Database query optimization
|
||||
- Caching strategies
|
||||
- Resource utilization
|
||||
- Load time reduction
|
||||
|
||||
### `/bugfix` - Bug Resolution
|
||||
|
||||
Fix specific bugs with focused approach.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/bugfix "Users can't reset password with special characters"
|
||||
/bugfix "Session expires too quickly on mobile"
|
||||
/bugfix "File upload fails for large files"
|
||||
```
|
||||
|
||||
**Agent**: `bugfix`
|
||||
|
||||
**Process**:
|
||||
1. Understand the bug
|
||||
2. Locate problematic code
|
||||
3. Implement fix
|
||||
4. Add regression tests
|
||||
5. Verify fix
|
||||
|
||||
### `/refactor` - Code Improvement
|
||||
|
||||
Improve code structure, readability, or maintainability without changing behavior.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/refactor "Extract user validation logic into separate module"
|
||||
/refactor "Simplify nested conditionals in order processing"
|
||||
/refactor "Remove code duplication in API handlers"
|
||||
```
|
||||
|
||||
**Agent**: `develop` (refactor mode)
|
||||
|
||||
**Goals**:
|
||||
- Improve readability
|
||||
- Reduce complexity
|
||||
- Eliminate duplication
|
||||
- Enhance maintainability
|
||||
- Follow best practices
|
||||
|
||||
### `/review` - Code Validation
|
||||
|
||||
Review code for quality, security, and best practices.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/review "Check authentication implementation for security issues"
|
||||
/review "Validate API error handling patterns"
|
||||
/review "Assess database schema design"
|
||||
```
|
||||
|
||||
**Agent**: Independent reviewer
|
||||
|
||||
**Review criteria**:
|
||||
- Code quality
|
||||
- Security vulnerabilities
|
||||
- Performance issues
|
||||
- Best practices compliance
|
||||
- Maintainability
|
||||
|
||||
### `/ask` - Technical Consultation
|
||||
|
||||
Get technical advice, design patterns, or implementation guidance.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/ask "Best approach for real-time notifications in React"
|
||||
/ask "How to handle database migrations in production"
|
||||
/ask "Design pattern for plugin system"
|
||||
```
|
||||
|
||||
**Agent**: Technical consultant
|
||||
|
||||
**Provides**:
|
||||
- Architecture guidance
|
||||
- Technology recommendations
|
||||
- Design patterns
|
||||
- Best practices
|
||||
- Trade-off analysis
|
||||
|
||||
### `/docs` - Documentation
|
||||
|
||||
Generate or improve documentation.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/docs "Create API documentation for user endpoints"
|
||||
/docs "Add JSDoc comments to utility functions"
|
||||
/docs "Write README for authentication module"
|
||||
```
|
||||
|
||||
**Agent**: Documentation writer
|
||||
|
||||
**Creates**:
|
||||
- Code comments
|
||||
- API documentation
|
||||
- README files
|
||||
- Usage examples
|
||||
- Architecture docs
|
||||
|
||||
### `/think` - Advanced Analysis
|
||||
|
||||
Deep reasoning and analysis for complex problems.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
/think "Analyze scalability bottlenecks in current architecture"
|
||||
/think "Evaluate different approaches for data synchronization"
|
||||
/think "Design migration strategy from monolith to microservices"
|
||||
```
|
||||
|
||||
**Agent**: `gpt5` (deep reasoning)
|
||||
|
||||
**Best for**:
|
||||
- Complex architectural decisions
|
||||
- Multi-faceted problems
|
||||
- Trade-off analysis
|
||||
- Strategic planning
|
||||
- System design
|
||||
|
||||
## 🔄 Command Workflows
|
||||
|
||||
### Simple Feature Development
|
||||
|
||||
```bash
|
||||
# 1. Ask for guidance
|
||||
/ask "Best way to implement rate limiting in Express"
|
||||
|
||||
# 2. Implement the feature
|
||||
/code "Add rate limiting middleware to API routes"
|
||||
|
||||
# 3. Add tests
|
||||
/test "Create tests for rate limiting behavior"
|
||||
|
||||
# 4. Review implementation
|
||||
/review "Validate rate limiting implementation"
|
||||
```
|
||||
|
||||
### Bug Investigation and Fix
|
||||
|
||||
```bash
|
||||
# 1. Debug the issue
|
||||
/debug "API returns 500 on concurrent requests"
|
||||
|
||||
# 2. Fix the bug
|
||||
/bugfix "Add mutex lock to prevent race condition"
|
||||
|
||||
# 3. Add regression tests
|
||||
/test "Test concurrent request handling"
|
||||
```
|
||||
|
||||
### Code Quality Improvement
|
||||
|
||||
```bash
|
||||
# 1. Review current code
|
||||
/review "Analyze user service for improvements"
|
||||
|
||||
# 2. Refactor based on findings
|
||||
/refactor "Simplify user validation logic"
|
||||
|
||||
# 3. Optimize performance
|
||||
/optimize "Cache frequently accessed user data"
|
||||
|
||||
# 4. Update documentation
|
||||
/docs "Document user service API"
|
||||
```
|
||||
|
||||
## 🎯 When to Use What
|
||||
|
||||
### Use Direct Commands When:
|
||||
- Task is clear and well-defined
|
||||
- No complex planning needed
|
||||
- Fast iteration is priority
|
||||
- Working within existing patterns
|
||||
|
||||
### Use Requirements Workflow When:
|
||||
- Feature has unclear requirements
|
||||
- Need documented specifications
|
||||
- Multiple implementation approaches possible
|
||||
- Quality gates desired
|
||||
|
||||
### Use BMAD Workflow When:
|
||||
- Complex business requirements
|
||||
- Architecture design needed
|
||||
- Sprint planning required
|
||||
- Multiple stakeholders involved
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
1. **Be Specific**: Provide clear, detailed descriptions
|
||||
- ❌ `/code "fix the bug"`
|
||||
- ✅ `/code "Fix null pointer exception in user login when email is missing"`
|
||||
|
||||
2. **One Task Per Command**: Keep commands focused
|
||||
- ❌ `/code "Add feature X, fix bug Y, refactor module Z"`
|
||||
- ✅ `/code "Add email validation to registration form"`
|
||||
|
||||
3. **Provide Context**: Include relevant details
|
||||
- ✅ `/debug "Login API returns 401 after password change, only on Safari"`
|
||||
|
||||
4. **Use Appropriate Command**: Match command to task type
|
||||
- Use `/bugfix` for bugs, not `/code`
|
||||
- Use `/refactor` for restructuring, not `/optimize`
|
||||
- Use `/think` for complex analysis, not `/ask`
|
||||
|
||||
5. **Chain Commands**: Break complex tasks into steps
|
||||
```bash
|
||||
/ask "How to implement OAuth2"
|
||||
/code "Implement OAuth2 authorization flow"
|
||||
/test "Add OAuth2 integration tests"
|
||||
/review "Validate OAuth2 security"
|
||||
/docs "Document OAuth2 setup process"
|
||||
```
|
||||
|
||||
## 🔌 Agent Configuration
|
||||
|
||||
All commands use specialized agents configured in:
|
||||
- `development-essentials/agents/`
|
||||
- Agent prompt templates
|
||||
- Tool access permissions
|
||||
- Output formatting
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Full agile methodology
|
||||
- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight workflow
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
- **[Plugin System](PLUGIN-SYSTEM.md)** - Installation and configuration
|
||||
|
||||
---
|
||||
|
||||
**Development Essentials** - Direct commands for productive coding without workflow overhead.
|
||||
348
docs/PLUGIN-SYSTEM.md
Normal file
348
docs/PLUGIN-SYSTEM.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# Plugin System Guide
|
||||
|
||||
> Native Claude Code plugin support for modular workflow installation
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
This repository provides 4 ready-to-use Claude Code plugins that can be installed individually or as a complete suite.
|
||||
|
||||
## 📦 Available Plugins
|
||||
|
||||
### 1. bmad-agile-workflow
|
||||
|
||||
**Complete BMAD methodology with 6 specialized agents**
|
||||
|
||||
**Commands**:
|
||||
- `/bmad-pilot` - Full agile workflow orchestration
|
||||
|
||||
**Agents**:
|
||||
- `bmad-po` - Product Owner (Sarah)
|
||||
- `bmad-architect` - System Architect (Winston)
|
||||
- `bmad-sm` - Scrum Master (Mike)
|
||||
- `bmad-dev` - Developer (Alex)
|
||||
- `bmad-review` - Code Reviewer
|
||||
- `bmad-qa` - QA Engineer (Emma)
|
||||
- `bmad-orchestrator` - Main orchestrator
|
||||
|
||||
**Use for**: Enterprise projects, complex features, full agile process
|
||||
|
||||
### 2. requirements-driven-workflow
|
||||
|
||||
**Streamlined requirements-to-code workflow**
|
||||
|
||||
**Commands**:
|
||||
- `/requirements-pilot` - Requirements-driven development flow
|
||||
|
||||
**Agents**:
|
||||
- `requirements-generate` - Requirements generation
|
||||
- `requirements-code` - Code implementation
|
||||
- `requirements-review` - Code review
|
||||
- `requirements-testing` - Testing strategy
|
||||
|
||||
**Use for**: Quick prototyping, simple features, rapid development
|
||||
|
||||
### 3. development-essentials
|
||||
|
||||
**Core development slash commands**
|
||||
|
||||
**Commands**:
|
||||
- `/code` - Direct implementation
|
||||
- `/debug` - Systematic debugging
|
||||
- `/test` - Testing strategy
|
||||
- `/optimize` - Performance tuning
|
||||
- `/bugfix` - Bug resolution
|
||||
- `/refactor` - Code improvement
|
||||
- `/review` - Code validation
|
||||
- `/ask` - Technical consultation
|
||||
- `/docs` - Documentation
|
||||
- `/think` - Advanced analysis
|
||||
|
||||
**Agents**:
|
||||
- `code` - Code implementation
|
||||
- `bugfix` - Bug fixing
|
||||
- `debug` - Debugging
|
||||
- `develop` - General development
|
||||
|
||||
**Use for**: Daily coding tasks, quick implementations
|
||||
|
||||
### 4. advanced-ai-agents
|
||||
|
||||
**GPT-5 deep reasoning integration**
|
||||
|
||||
**Commands**: None (agent-only)
|
||||
|
||||
**Agents**:
|
||||
- `gpt5` - Deep reasoning and analysis
|
||||
|
||||
**Use for**: Complex architectural decisions, strategic planning
|
||||
|
||||
## 🚀 Installation Methods
|
||||
|
||||
### Method 1: Plugin Commands (Recommended)
|
||||
|
||||
```bash
|
||||
# List all available plugins
|
||||
/plugin list
|
||||
|
||||
# Get detailed information about a plugin
|
||||
/plugin info bmad-agile-workflow
|
||||
|
||||
# Install a specific plugin
|
||||
/plugin install bmad-agile-workflow
|
||||
|
||||
# Install all plugins
|
||||
/plugin install bmad-agile-workflow
|
||||
/plugin install requirements-driven-workflow
|
||||
/plugin install development-essentials
|
||||
/plugin install advanced-ai-agents
|
||||
|
||||
# Remove an installed plugin
|
||||
/plugin remove development-essentials
|
||||
```
|
||||
|
||||
### Method 2: Repository Reference
|
||||
|
||||
```bash
|
||||
# Install from GitHub repository
|
||||
/plugin github.com/cexll/myclaude
|
||||
```
|
||||
|
||||
This will present all available plugins from the repository.
|
||||
|
||||
### Method 3: Make Commands
|
||||
|
||||
For traditional installation or selective deployment:
|
||||
|
||||
```bash
|
||||
# Install everything
|
||||
make install
|
||||
|
||||
# Deploy specific workflows
|
||||
make deploy-bmad # BMAD workflow only
|
||||
make deploy-requirements # Requirements workflow only
|
||||
make deploy-commands # All slash commands
|
||||
make deploy-agents # All agents
|
||||
|
||||
# Deploy everything
|
||||
make deploy-all
|
||||
|
||||
# View all options
|
||||
make help
|
||||
```
|
||||
|
||||
### Method 4: Manual Installation
|
||||
|
||||
Copy files to Claude Code configuration directories:
|
||||
|
||||
**Commands**:
|
||||
```bash
|
||||
cp bmad-agile-workflow/commands/*.md ~/.config/claude/commands/
|
||||
cp requirements-driven-workflow/commands/*.md ~/.config/claude/commands/
|
||||
cp development-essentials/commands/*.md ~/.config/claude/commands/
|
||||
```
|
||||
|
||||
**Agents**:
|
||||
```bash
|
||||
cp bmad-agile-workflow/agents/*.md ~/.config/claude/agents/
|
||||
cp requirements-driven-workflow/agents/*.md ~/.config/claude/agents/
|
||||
cp development-essentials/agents/*.md ~/.config/claude/agents/
|
||||
cp advanced-ai-agents/agents/*.md ~/.config/claude/agents/
|
||||
```
|
||||
|
||||
**Output Styles** (optional):
|
||||
```bash
|
||||
cp output-styles/*.md ~/.config/claude/output-styles/
|
||||
```
|
||||
|
||||
## 📋 Plugin Configuration
|
||||
|
||||
Plugins are defined in `.claude-plugin/marketplace.json` following the Claude Code plugin specification.
|
||||
|
||||
### Plugin Metadata Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"displayName": "Human Readable Name",
|
||||
"description": "Plugin description",
|
||||
"version": "1.0.0",
|
||||
"author": "Author Name",
|
||||
"category": "workflow|development|analysis",
|
||||
"keywords": ["keyword1", "keyword2"],
|
||||
"commands": ["command1", "command2"],
|
||||
"agents": ["agent1", "agent2"]
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Plugin Management
|
||||
|
||||
### Check Installed Plugins
|
||||
|
||||
```bash
|
||||
/plugin list
|
||||
```
|
||||
|
||||
Shows all installed plugins with their status.
|
||||
|
||||
### Plugin Information
|
||||
|
||||
```bash
|
||||
/plugin info <plugin-name>
|
||||
```
|
||||
|
||||
Displays detailed information:
|
||||
- Description
|
||||
- Version
|
||||
- Commands provided
|
||||
- Agents included
|
||||
- Author and keywords
|
||||
|
||||
### Update Plugins
|
||||
|
||||
Plugins are updated when you pull the latest repository changes:
|
||||
|
||||
```bash
|
||||
git pull origin main
|
||||
make install
|
||||
```
|
||||
|
||||
### Uninstall Plugins
|
||||
|
||||
```bash
|
||||
/plugin remove <plugin-name>
|
||||
```
|
||||
|
||||
Or manually remove files:
|
||||
|
||||
```bash
|
||||
# Remove commands
|
||||
rm ~/.config/claude/commands/<command-name>.md
|
||||
|
||||
# Remove agents
|
||||
rm ~/.config/claude/agents/<agent-name>.md
|
||||
```
|
||||
|
||||
## 🎯 Plugin Selection Guide
|
||||
|
||||
### Install Everything (Recommended for New Users)
|
||||
|
||||
```bash
|
||||
make install
|
||||
```
|
||||
|
||||
Provides complete functionality with all workflows and commands.
|
||||
|
||||
### Selective Installation
|
||||
|
||||
**For Agile Teams**:
|
||||
```bash
|
||||
/plugin install bmad-agile-workflow
|
||||
```
|
||||
|
||||
**For Rapid Development**:
|
||||
```bash
|
||||
/plugin install requirements-driven-workflow
|
||||
/plugin install development-essentials
|
||||
```
|
||||
|
||||
**For Individual Developers**:
|
||||
```bash
|
||||
/plugin install development-essentials
|
||||
/plugin install advanced-ai-agents
|
||||
```
|
||||
|
||||
**For Code Quality Focus**:
|
||||
```bash
|
||||
/plugin install development-essentials # Includes /review
|
||||
/plugin install bmad-agile-workflow # Includes bmad-review
|
||||
```
|
||||
|
||||
## 📁 Directory Structure
|
||||
|
||||
```
|
||||
myclaude/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json # Plugin registry
|
||||
├── bmad-agile-workflow/
|
||||
│ ├── commands/
|
||||
│ │ └── bmad-pilot.md
|
||||
│ └── agents/
|
||||
│ ├── bmad-po.md
|
||||
│ ├── bmad-architect.md
|
||||
│ ├── bmad-sm.md
|
||||
│ ├── bmad-dev.md
|
||||
│ ├── bmad-review.md
|
||||
│ ├── bmad-qa.md
|
||||
│ └── bmad-orchestrator.md
|
||||
├── requirements-driven-workflow/
|
||||
│ ├── commands/
|
||||
│ │ └── requirements-pilot.md
|
||||
│ └── agents/
|
||||
│ ├── requirements-generate.md
|
||||
│ ├── requirements-code.md
|
||||
│ ├── requirements-review.md
|
||||
│ └── requirements-testing.md
|
||||
├── development-essentials/
|
||||
│ ├── commands/
|
||||
│ │ ├── code.md
|
||||
│ │ ├── debug.md
|
||||
│ │ ├── test.md
|
||||
│ │ └── ... (more commands)
|
||||
│ └── agents/
|
||||
│ ├── code.md
|
||||
│ ├── bugfix.md
|
||||
│ ├── debug.md
|
||||
│ └── develop.md
|
||||
├── advanced-ai-agents/
|
||||
│ └── agents/
|
||||
│ └── gpt5.md
|
||||
└── output-styles/
|
||||
└── bmad-phase-context.md
|
||||
```
|
||||
|
||||
## 🔄 Plugin Dependencies
|
||||
|
||||
**No Dependencies**: All plugins work independently
|
||||
|
||||
**Complementary Combinations**:
|
||||
- BMAD + Advanced Agents (enhanced reviews)
|
||||
- Requirements + Development Essentials (complete toolkit)
|
||||
- All four plugins (full suite)
|
||||
|
||||
## 🛠️ Makefile Reference
|
||||
|
||||
```bash
|
||||
# Installation
|
||||
make install # Install all plugins
|
||||
make deploy-all # Deploy all configurations
|
||||
|
||||
# Selective Deployment
|
||||
make deploy-bmad # BMAD workflow only
|
||||
make deploy-requirements # Requirements workflow only
|
||||
make deploy-commands # All slash commands only
|
||||
make deploy-agents # All agents only
|
||||
|
||||
# Testing
|
||||
make test-bmad # Test BMAD workflow
|
||||
make test-requirements # Test Requirements workflow
|
||||
|
||||
# Cleanup
|
||||
make clean # Remove generated artifacts
|
||||
make help # Show all available commands
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Complete BMAD guide
|
||||
- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight workflow guide
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Command reference
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
|
||||
## 🔗 External Resources
|
||||
|
||||
- **[Claude Code Plugin Docs](https://docs.claude.com/en/docs/claude-code/plugins)** - Official plugin documentation
|
||||
- **[Claude Code CLI](https://claude.ai/code)** - Claude Code interface
|
||||
|
||||
---
|
||||
|
||||
**Modular Installation** - Install only what you need, when you need it.
|
||||
326
docs/QUICK-START.md
Normal file
326
docs/QUICK-START.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# Quick Start Guide
|
||||
|
||||
> Get started with Claude Code Multi-Agent Workflow System in 5 minutes
|
||||
|
||||
## 🚀 Installation (2 minutes)
|
||||
|
||||
### Option 1: Plugin System (Fastest)
|
||||
|
||||
```bash
|
||||
# Install everything with one command
|
||||
/plugin github.com/cexll/myclaude
|
||||
```
|
||||
|
||||
### Option 2: Make Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cexll/myclaude.git
|
||||
cd myclaude
|
||||
make install
|
||||
```
|
||||
|
||||
### Option 3: Selective Install
|
||||
|
||||
```bash
|
||||
# Install only what you need
|
||||
/plugin install bmad-agile-workflow # Full agile workflow
|
||||
/plugin install development-essentials # Daily coding commands
|
||||
```
|
||||
|
||||
## 🎯 Your First Workflow (3 minutes)
|
||||
|
||||
### Try BMAD Workflow
|
||||
|
||||
Complete agile development automation:
|
||||
|
||||
```bash
|
||||
/bmad-pilot "Build a simple todo list API with CRUD operations"
|
||||
```
|
||||
|
||||
**What happens**:
|
||||
1. **Product Owner** generates requirements (PRD)
|
||||
2. **Architect** designs system architecture
|
||||
3. **Scrum Master** creates sprint plan
|
||||
4. **Developer** implements code
|
||||
5. **Reviewer** performs code review
|
||||
6. **QA** runs tests
|
||||
|
||||
All documents saved to `.claude/specs/todo-list-api/`
|
||||
|
||||
### Try Requirements Workflow
|
||||
|
||||
Fast prototyping:
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Add user authentication to existing API"
|
||||
```
|
||||
|
||||
**What happens**:
|
||||
1. Generate functional requirements
|
||||
2. Implement code
|
||||
3. Review implementation
|
||||
4. Create tests
|
||||
|
||||
### Try Direct Commands
|
||||
|
||||
Quick coding without workflow:
|
||||
|
||||
```bash
|
||||
# Implement a feature
|
||||
/code "Add input validation for email fields"
|
||||
|
||||
# Debug an issue
|
||||
/debug "API returns 500 on missing parameters"
|
||||
|
||||
# Add tests
|
||||
/test "Create unit tests for validation logic"
|
||||
```
|
||||
|
||||
## 📋 Common Use Cases
|
||||
|
||||
### 1. New Feature Development
|
||||
|
||||
**Complex Feature** (use BMAD):
|
||||
```bash
|
||||
/bmad-pilot "User authentication system with OAuth2, MFA, and role-based access control"
|
||||
```
|
||||
|
||||
**Simple Feature** (use Requirements):
|
||||
```bash
|
||||
/requirements-pilot "Add pagination to user list endpoint"
|
||||
```
|
||||
|
||||
**Tiny Feature** (use direct command):
|
||||
```bash
|
||||
/code "Add created_at timestamp to user model"
|
||||
```
|
||||
|
||||
### 2. Bug Fixing
|
||||
|
||||
**Complex Bug** (use debug):
|
||||
```bash
|
||||
/debug "Memory leak in background job processor"
|
||||
```
|
||||
|
||||
**Simple Bug** (use bugfix):
|
||||
```bash
|
||||
/bugfix "Login button not working on mobile Safari"
|
||||
```
|
||||
|
||||
### 3. Code Quality
|
||||
|
||||
**Full Review**:
|
||||
```bash
|
||||
/review "Review authentication module for security issues"
|
||||
```
|
||||
|
||||
**Refactoring**:
|
||||
```bash
|
||||
/refactor "Simplify user validation logic and remove duplication"
|
||||
```
|
||||
|
||||
**Optimization**:
|
||||
```bash
|
||||
/optimize "Reduce database queries in dashboard API"
|
||||
```
|
||||
|
||||
## 🎨 Workflow Selection Guide
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Choose Your Workflow │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
Complex Business Feature + Architecture Needed
|
||||
↓
|
||||
🏢 Use BMAD Workflow
|
||||
/bmad-pilot "description"
|
||||
• 6 specialized agents
|
||||
• Quality gates (PRD ≥90, Design ≥90)
|
||||
• Complete documentation
|
||||
• Sprint planning included
|
||||
|
||||
────────────────────────────────────────────────────────
|
||||
|
||||
Clear Requirements + Fast Iteration Needed
|
||||
↓
|
||||
⚡ Use Requirements Workflow
|
||||
/requirements-pilot "description"
|
||||
• 4 phases: Requirements → Code → Review → Test
|
||||
• Quality gate (Requirements ≥90)
|
||||
• Minimal documentation
|
||||
• Direct to implementation
|
||||
|
||||
────────────────────────────────────────────────────────
|
||||
|
||||
Well-Defined Task + No Workflow Overhead
|
||||
↓
|
||||
🔧 Use Direct Commands
|
||||
/code | /debug | /test | /optimize
|
||||
• Single-purpose commands
|
||||
• Immediate execution
|
||||
• No documentation overhead
|
||||
• Perfect for daily tasks
|
||||
```
|
||||
|
||||
## 💡 Tips for Success
|
||||
|
||||
### 1. Be Specific
|
||||
|
||||
**❌ Bad**:
|
||||
```bash
|
||||
/bmad-pilot "Build an app"
|
||||
```
|
||||
|
||||
**✅ Good**:
|
||||
```bash
|
||||
/bmad-pilot "Build a task management API with user authentication, task CRUD,
|
||||
task assignment, and real-time notifications via WebSocket"
|
||||
```
|
||||
|
||||
### 2. Provide Context
|
||||
|
||||
Include relevant technical details:
|
||||
```bash
|
||||
/code "Add Redis caching to user profile endpoint, cache TTL 5 minutes,
|
||||
invalidate on profile update"
|
||||
```
|
||||
|
||||
### 3. Engage with Agents
|
||||
|
||||
During BMAD workflow, provide feedback at quality gates:
|
||||
|
||||
```
|
||||
PO: "Here's the PRD (Score: 85/100)"
|
||||
You: "Add mobile app support and offline mode requirements"
|
||||
PO: "Updated PRD (Score: 94/100) ✅"
|
||||
```
|
||||
|
||||
### 4. Review Generated Artifacts
|
||||
|
||||
Check documents before confirming:
|
||||
- `.claude/specs/{feature}/01-product-requirements.md`
|
||||
- `.claude/specs/{feature}/02-system-architecture.md`
|
||||
- `.claude/specs/{feature}/03-sprint-plan.md`
|
||||
|
||||
### 5. Chain Commands for Complex Tasks
|
||||
|
||||
Break down complex work:
|
||||
```bash
|
||||
/ask "Best approach for implementing real-time chat"
|
||||
/bmad-pilot "Real-time chat system with message history and typing indicators"
|
||||
/test "Add integration tests for chat message delivery"
|
||||
/docs "Document chat API endpoints and WebSocket events"
|
||||
```
|
||||
|
||||
## 🎓 Learning Path
|
||||
|
||||
**Day 1**: Try direct commands
|
||||
```bash
|
||||
/code "simple task"
|
||||
/test "add some tests"
|
||||
/review "check my code"
|
||||
```
|
||||
|
||||
**Day 2**: Try Requirements workflow
|
||||
```bash
|
||||
/requirements-pilot "small feature"
|
||||
```
|
||||
|
||||
**Week 2**: Try BMAD workflow
|
||||
```bash
|
||||
/bmad-pilot "larger feature"
|
||||
```
|
||||
|
||||
**Week 3**: Combine workflows
|
||||
```bash
|
||||
# Use BMAD for planning
|
||||
/bmad-pilot "new module" --direct-dev
|
||||
|
||||
# Use Requirements for sprint tasks
|
||||
/requirements-pilot "individual task from sprint"
|
||||
|
||||
# Use commands for daily work
|
||||
/code "quick fix"
|
||||
/test "add test"
|
||||
```
|
||||
|
||||
## 📚 Next Steps
|
||||
|
||||
### Explore Documentation
|
||||
|
||||
- **[BMAD Workflow Guide](BMAD-WORKFLOW.md)** - Deep dive into full agile workflow
|
||||
- **[Requirements Workflow Guide](REQUIREMENTS-WORKFLOW.md)** - Learn lightweight development
|
||||
- **[Development Commands Reference](DEVELOPMENT-COMMANDS.md)** - All command details
|
||||
- **[Plugin System Guide](PLUGIN-SYSTEM.md)** - Plugin management
|
||||
|
||||
### Try Advanced Features
|
||||
|
||||
**BMAD Options**:
|
||||
```bash
|
||||
# Skip testing for prototype
|
||||
/bmad-pilot "prototype" --skip-tests
|
||||
|
||||
# Skip sprint planning for quick dev
|
||||
/bmad-pilot "feature" --direct-dev
|
||||
|
||||
# Skip repo scan (if context exists)
|
||||
/bmad-pilot "feature" --skip-scan
|
||||
```
|
||||
|
||||
**Individual Agents**:
|
||||
```bash
|
||||
# Just requirements
|
||||
/bmad-po "feature requirements"
|
||||
|
||||
# Just architecture
|
||||
/bmad-architect "system design"
|
||||
|
||||
# Just orchestration
|
||||
/bmad-orchestrator "complex project coordination"
|
||||
```
|
||||
|
||||
### Check Quality
|
||||
|
||||
Run tests and validation:
|
||||
```bash
|
||||
make test-bmad # Test BMAD workflow
|
||||
make test-requirements # Test Requirements workflow
|
||||
```
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
**Commands not found**?
|
||||
```bash
|
||||
# Verify installation
|
||||
/plugin list
|
||||
|
||||
# Reinstall if needed
|
||||
make install
|
||||
```
|
||||
|
||||
**Agents not working**?
|
||||
```bash
|
||||
# Check agent configuration
|
||||
ls ~/.config/claude/agents/
|
||||
|
||||
# Redeploy agents
|
||||
make deploy-agents
|
||||
```
|
||||
|
||||
**Output styles missing**?
|
||||
```bash
|
||||
# Deploy output styles
|
||||
cp output-styles/*.md ~/.config/claude/output-styles/
|
||||
```
|
||||
|
||||
## 📞 Get Help
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/cexll/myclaude/issues)
|
||||
- **Documentation**: [docs/](.)
|
||||
- **Examples**: Check `.claude/specs/` after running workflows
|
||||
- **Make Help**: Run `make help` for all commands
|
||||
|
||||
---
|
||||
|
||||
**You're ready!** Start with `/code "your first task"` and explore from there.
|
||||
259
docs/REQUIREMENTS-WORKFLOW.md
Normal file
259
docs/REQUIREMENTS-WORKFLOW.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Requirements-Driven Workflow Guide
|
||||
|
||||
> Lightweight alternative to BMAD for rapid prototyping and simple feature development
|
||||
|
||||
## 🎯 What is Requirements Workflow?
|
||||
|
||||
A streamlined 4-phase workflow that focuses on getting from requirements to working code quickly:
|
||||
|
||||
**Requirements → Implementation → Review → Testing**
|
||||
|
||||
Perfect for:
|
||||
- Quick prototypes
|
||||
- Small features
|
||||
- Bug fixes with clear scope
|
||||
- Projects without complex architecture needs
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Basic Command
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Implement JWT authentication with refresh tokens"
|
||||
|
||||
# Automated workflow:
|
||||
# 1. Requirements generation (90% quality gate)
|
||||
# 2. Code implementation
|
||||
# 3. Code review
|
||||
# 4. Testing strategy
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
**Use Requirements Workflow** when:
|
||||
- Feature scope is clear and simple
|
||||
- No complex architecture design needed
|
||||
- Fast iteration is priority
|
||||
- You want minimal workflow overhead
|
||||
|
||||
**Use BMAD Workflow** when:
|
||||
- Complex business requirements
|
||||
- Multiple systems integration
|
||||
- Architecture design is critical
|
||||
- Need detailed sprint planning
|
||||
|
||||
## 📋 Workflow Phases
|
||||
|
||||
### Phase 1: Requirements Generation
|
||||
- **Agent**: `requirements-generate`
|
||||
- **Quality Gate**: Requirements score ≥ 90/100
|
||||
- **Output**: Functional requirements document
|
||||
- **Focus**:
|
||||
- Clear functional requirements
|
||||
- Acceptance criteria
|
||||
- Technical constraints
|
||||
- Implementation notes
|
||||
|
||||
**Quality Criteria (100 points)**:
|
||||
- Clarity (30): Unambiguous, well-defined
|
||||
- Completeness (25): All aspects covered
|
||||
- Testability (20): Clear verification points
|
||||
- Technical Feasibility (15): Realistic implementation
|
||||
- Scope Definition (10): Clear boundaries
|
||||
|
||||
### Phase 2: Code Implementation
|
||||
- **Agent**: `requirements-code`
|
||||
- **Quality Gate**: Code completion
|
||||
- **Output**: Implementation files
|
||||
- **Process**:
|
||||
1. Read requirements + repository context
|
||||
2. Implement features following requirements
|
||||
3. Create or modify code files
|
||||
4. Follow existing code conventions
|
||||
|
||||
### Phase 3: Code Review
|
||||
- **Agent**: `requirements-review`
|
||||
- **Quality Gate**: Pass / Pass with Risk / Fail
|
||||
- **Output**: Review report
|
||||
- **Focus**:
|
||||
- Code quality
|
||||
- Requirements alignment
|
||||
- Security concerns
|
||||
- Performance issues
|
||||
- Best practices compliance
|
||||
|
||||
**Review Status**:
|
||||
- **Pass**: Meets standards, ready for testing
|
||||
- **Pass with Risk**: Minor issues noted
|
||||
- **Fail**: Requires implementation revision
|
||||
|
||||
### Phase 4: Testing Strategy
|
||||
- **Agent**: `requirements-testing`
|
||||
- **Quality Gate**: Test execution
|
||||
- **Output**: Test report
|
||||
- **Process**:
|
||||
1. Create test strategy from requirements
|
||||
2. Generate test cases
|
||||
3. Execute tests (unit, integration)
|
||||
4. Report results
|
||||
|
||||
## 📁 Workflow Artifacts
|
||||
|
||||
Generated in `.claude/requirements/{feature-name}/`:
|
||||
|
||||
```
|
||||
.claude/requirements/jwt-authentication/
|
||||
├── 01-requirements.md # Functional requirements (score ≥ 90)
|
||||
├── 02-implementation.md # Implementation summary
|
||||
├── 03-review.md # Code review report
|
||||
└── 04-testing.md # Test strategy and results
|
||||
```
|
||||
|
||||
## 🔧 Command Options
|
||||
|
||||
```bash
|
||||
# Standard workflow
|
||||
/requirements-pilot "Add API rate limiting"
|
||||
|
||||
# With specific technology
|
||||
/requirements-pilot "Redis caching layer with TTL management"
|
||||
|
||||
# Bug fix with requirements
|
||||
/requirements-pilot "Fix login session timeout issue"
|
||||
```
|
||||
|
||||
## 📊 Quality Scoring
|
||||
|
||||
### Requirements Score (100 points)
|
||||
|
||||
| Category | Points | Description |
|
||||
|----------|--------|-------------|
|
||||
| Clarity | 30 | Unambiguous, well-defined requirements |
|
||||
| Completeness | 25 | All functional aspects covered |
|
||||
| Testability | 20 | Clear acceptance criteria |
|
||||
| Technical Feasibility | 15 | Realistic implementation plan |
|
||||
| Scope Definition | 10 | Clear feature boundaries |
|
||||
|
||||
**Threshold**: ≥ 90 points to proceed
|
||||
|
||||
### Automatic Optimization
|
||||
|
||||
If initial score < 90:
|
||||
1. User provides feedback
|
||||
2. Agent revises requirements
|
||||
3. System recalculates score
|
||||
4. Repeat until ≥ 90
|
||||
5. User confirms → Save → Next phase
|
||||
|
||||
## 🎯 Comparison: Requirements vs BMAD
|
||||
|
||||
| Aspect | Requirements Workflow | BMAD Workflow |
|
||||
|--------|----------------------|---------------|
|
||||
| **Phases** | 4 (Requirements → Code → Review → Test) | 6 (PO → Arch → SM → Dev → Review → QA) |
|
||||
| **Duration** | Fast (hours) | Thorough (days) |
|
||||
| **Documentation** | Minimal | Comprehensive |
|
||||
| **Quality Gates** | 1 (Requirements ≥ 90) | 2 (PRD ≥ 90, Design ≥ 90) |
|
||||
| **Approval Points** | None | Multiple (after PRD, Architecture, Sprint Plan) |
|
||||
| **Best For** | Simple features, prototypes | Complex features, enterprise projects |
|
||||
| **Artifacts** | 4 documents | 6 documents |
|
||||
| **Planning** | Direct implementation | Sprint planning included |
|
||||
| **Architecture** | Implicit in requirements | Explicit design phase |
|
||||
|
||||
## 💡 Usage Examples
|
||||
|
||||
### Example 1: API Feature
|
||||
|
||||
```bash
|
||||
/requirements-pilot "REST API endpoint for user profile updates with validation"
|
||||
|
||||
# Generated requirements include:
|
||||
# - Endpoint specification (PUT /api/users/:id/profile)
|
||||
# - Request/response schemas
|
||||
# - Validation rules
|
||||
# - Error handling
|
||||
# - Authentication requirements
|
||||
|
||||
# Implementation follows directly
|
||||
# Review checks API best practices
|
||||
# Testing includes endpoint testing
|
||||
```
|
||||
|
||||
### Example 2: Database Schema
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Add audit logging table for user actions"
|
||||
|
||||
# Generated requirements include:
|
||||
# - Table schema definition
|
||||
# - Indexing strategy
|
||||
# - Retention policy
|
||||
# - Query patterns
|
||||
|
||||
# Implementation creates migration
|
||||
# Review checks schema design
|
||||
# Testing verifies logging behavior
|
||||
```
|
||||
|
||||
### Example 3: Bug Fix
|
||||
|
||||
```bash
|
||||
/requirements-pilot "Fix race condition in order processing queue"
|
||||
|
||||
# Generated requirements include:
|
||||
# - Problem description
|
||||
# - Root cause analysis
|
||||
# - Solution approach
|
||||
# - Verification steps
|
||||
|
||||
# Implementation applies fix
|
||||
# Review checks concurrency handling
|
||||
# Testing includes stress tests
|
||||
```
|
||||
|
||||
## 🔄 Iterative Refinement
|
||||
|
||||
Each phase supports feedback:
|
||||
|
||||
```
|
||||
Agent: "Requirements complete (Score: 85/100)"
|
||||
User: "Add error handling for network failures"
|
||||
Agent: "Updated requirements (Score: 93/100) ✅"
|
||||
```
|
||||
|
||||
## 🚀 Advanced Usage
|
||||
|
||||
### Combining with Individual Commands
|
||||
|
||||
```bash
|
||||
# Generate requirements only
|
||||
/requirements-generate "OAuth2 integration requirements"
|
||||
|
||||
# Just code implementation (requires existing requirements)
|
||||
/requirements-code "Implement based on requirements.md"
|
||||
|
||||
# Standalone review
|
||||
/requirements-review "Review current implementation"
|
||||
```
|
||||
|
||||
### Integration with BMAD
|
||||
|
||||
Use Requirements Workflow for sub-tasks within BMAD sprints:
|
||||
|
||||
```bash
|
||||
# BMAD creates sprint plan
|
||||
/bmad-pilot "E-commerce platform"
|
||||
|
||||
# Use Requirements for individual sprint tasks
|
||||
/requirements-pilot "Shopping cart session management"
|
||||
/requirements-pilot "Payment webhook handling"
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Full agile methodology
|
||||
- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Direct coding commands
|
||||
- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
|
||||
|
||||
---
|
||||
|
||||
**Requirements-Driven Development** - From requirements to working code in hours, not days.
|
||||
26
requirements-clarity/.claude-plugin/marketplace.json
Normal file
26
requirements-clarity/.claude-plugin/marketplace.json
Normal file
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"name": "requirements-clarity",
|
||||
"source": "./",
|
||||
"description": "Transforms vague requirements into actionable PRDs through systematic clarification with 100-point scoring system",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Claude Code Dev Workflows",
|
||||
"url": "https://github.com/cexll/myclaude"
|
||||
},
|
||||
"homepage": "https://github.com/cexll/myclaude",
|
||||
"repository": "https://github.com/cexll/myclaude",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"requirements",
|
||||
"clarification",
|
||||
"prd",
|
||||
"specifications",
|
||||
"quality-gates",
|
||||
"requirements-engineering"
|
||||
],
|
||||
"category": "essentials",
|
||||
"strict": false,
|
||||
"skills": [
|
||||
"./skills/SKILL.md"
|
||||
]
|
||||
}
|
||||
323
requirements-clarity/skills/SKILL.md
Normal file
323
requirements-clarity/skills/SKILL.md
Normal file
@@ -0,0 +1,323 @@
|
||||
---
|
||||
name: Requirements Clarity
|
||||
description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
|
||||
---
|
||||
|
||||
# Requirements Clarity Skill
|
||||
|
||||
## Description
|
||||
|
||||
Automatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system.
|
||||
|
||||
## Activation
|
||||
|
||||
Auto-activate when detecting vague requirements:
|
||||
|
||||
1. **Vague Feature Requests**
|
||||
- User says: "add login feature", "implement payment", "create dashboard"
|
||||
- Missing: How, with what technology, what constraints?
|
||||
|
||||
2. **Missing Technical Context**
|
||||
- No technology stack mentioned
|
||||
- No integration points identified
|
||||
- No performance/security constraints
|
||||
|
||||
3. **Incomplete Specifications**
|
||||
- No acceptance criteria
|
||||
- No success metrics
|
||||
- No edge cases considered
|
||||
- No error handling mentioned
|
||||
|
||||
4. **Ambiguous Scope**
|
||||
- Unclear boundaries ("user management" - what exactly?)
|
||||
- No distinction between MVP and future enhancements
|
||||
- Missing "what's NOT included"
|
||||
|
||||
**Do NOT activate when**:
|
||||
- Specific file paths mentioned (e.g., "auth.go:45")
|
||||
- Code snippets included
|
||||
- Existing functions/classes referenced
|
||||
- Bug fixes with clear reproduction steps
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Systematic Questioning**
|
||||
- Ask focused, specific questions
|
||||
- One category at a time (2-3 questions per round)
|
||||
- Build on previous answers
|
||||
- Avoid overwhelming users
|
||||
|
||||
2. **Quality-Driven Iteration**
|
||||
- Continuously assess clarity score (0-100)
|
||||
- Identify gaps systematically
|
||||
- Iterate until ≥ 90 points
|
||||
- Document all clarification rounds
|
||||
|
||||
3. **Actionable Output**
|
||||
- Generate concrete specifications
|
||||
- Include measurable acceptance criteria
|
||||
- Provide executable phases
|
||||
- Enable direct implementation
|
||||
|
||||
## Clarification Process
|
||||
|
||||
### Step 1: Initial Requirement Analysis
|
||||
|
||||
**Input**: User's requirement description
|
||||
|
||||
**Tasks**:
|
||||
1. Parse and understand core requirement
|
||||
2. Generate feature name (kebab-case format)
|
||||
3. Determine document version (default `1.0` unless user specifies otherwise)
|
||||
4. Ensure `./docs/prds/` exists for PRD output
|
||||
5. Perform initial clarity assessment (0-100)
|
||||
|
||||
**Assessment Rubric**:
|
||||
```
|
||||
Functional Clarity: /30 points
|
||||
- Clear inputs/outputs: 10 pts
|
||||
- User interaction defined: 10 pts
|
||||
- Success criteria stated: 10 pts
|
||||
|
||||
Technical Specificity: /25 points
|
||||
- Technology stack mentioned: 8 pts
|
||||
- Integration points identified: 8 pts
|
||||
- Constraints specified: 9 pts
|
||||
|
||||
Implementation Completeness: /25 points
|
||||
- Edge cases considered: 8 pts
|
||||
- Error handling mentioned: 9 pts
|
||||
- Data validation specified: 8 pts
|
||||
|
||||
Business Context: /20 points
|
||||
- Problem statement clear: 7 pts
|
||||
- Target users identified: 7 pts
|
||||
- Success metrics defined: 6 pts
|
||||
```
|
||||
|
||||
**Initial Response Format**:
|
||||
```markdown
|
||||
I understand your requirement. Let me help you refine this specification.
|
||||
|
||||
**Current Clarity Score**: X/100
|
||||
|
||||
**Clear Aspects**:
|
||||
- [List what's clear]
|
||||
|
||||
**Needs Clarification**:
|
||||
- [List gaps]
|
||||
|
||||
Let me systematically clarify these points...
|
||||
```
|
||||
|
||||
### Step 2: Gap Analysis
|
||||
|
||||
Identify missing information across four dimensions:
|
||||
|
||||
**1. Functional Scope**
|
||||
- What is the core functionality?
|
||||
- What are the boundaries?
|
||||
- What is out of scope?
|
||||
- What are edge cases?
|
||||
|
||||
**2. User Interaction**
|
||||
- How do users interact?
|
||||
- What are the inputs?
|
||||
- What are the outputs?
|
||||
- What are success/failure scenarios?
|
||||
|
||||
**3. Technical Constraints**
|
||||
- Performance requirements?
|
||||
- Compatibility requirements?
|
||||
- Security considerations?
|
||||
- Scalability needs?
|
||||
|
||||
**4. Business Value**
|
||||
- What problem does this solve?
|
||||
- Who are the target users?
|
||||
- What are success metrics?
|
||||
- What is the priority?
|
||||
|
||||
### Step 3: Interactive Clarification
|
||||
|
||||
**Question Strategy**:
|
||||
1. Start with highest-impact gaps
|
||||
2. Ask 2-3 questions per round
|
||||
3. Build context progressively
|
||||
4. Use user's language
|
||||
5. Provide examples when helpful
|
||||
|
||||
**Question Format**:
|
||||
```markdown
|
||||
I need to clarify the following points to complete the requirements document:
|
||||
|
||||
1. **[Category]**: [Specific question]?
|
||||
- For example: [Example if helpful]
|
||||
|
||||
2. **[Category]**: [Specific question]?
|
||||
|
||||
3. **[Category]**: [Specific question]?
|
||||
|
||||
Please provide your answers, and I'll continue refining the PRD.
|
||||
```
|
||||
|
||||
**After Each User Response**:
|
||||
1. Update clarity score
|
||||
2. Capture new information in the working PRD outline
|
||||
3. Identify remaining gaps
|
||||
4. If score < 90: Continue with next round of questions
|
||||
5. If score ≥ 90: Proceed to PRD generation
|
||||
|
||||
**Score Update Format**:
|
||||
```markdown
|
||||
Thank you for the additional information!
|
||||
|
||||
**Clarity Score Update**: X/100 → Y/100
|
||||
|
||||
**New Clarified Content**:
|
||||
- [Summarize new information]
|
||||
|
||||
**Remaining Points to Clarify**:
|
||||
- [List remaining gaps if score < 90]
|
||||
|
||||
[If score < 90: Continue with next round of questions]
|
||||
[If score ≥ 90: "Perfect! I will now generate the complete PRD document..."]
|
||||
```
|
||||
|
||||
### Step 4: PRD Generation
|
||||
|
||||
Once clarity score ≥ 90, generate comprehensive PRD.
|
||||
|
||||
**Output File**:
|
||||
|
||||
1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md`
|
||||
|
||||
Use the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).
|
||||
|
||||
## PRD Document Structure
|
||||
|
||||
```markdown
|
||||
# {Feature Name} - Product Requirements Document (PRD)
|
||||
|
||||
## Requirements Description
|
||||
|
||||
### Background
|
||||
- **Business Problem**: [Describe the business problem to solve]
|
||||
- **Target Users**: [Target user groups]
|
||||
- **Value Proposition**: [Value this feature brings]
|
||||
|
||||
### Feature Overview
|
||||
- **Core Features**: [List of main features]
|
||||
- **Feature Boundaries**: [What is and isn't included]
|
||||
- **User Scenarios**: [Typical usage scenarios]
|
||||
|
||||
### Detailed Requirements
|
||||
- **Input/Output**: [Specific input/output specifications]
|
||||
- **User Interaction**: [User operation flow]
|
||||
- **Data Requirements**: [Data structures and validation rules]
|
||||
- **Edge Cases**: [Edge case handling]
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### Technical Approach
|
||||
- **Architecture Choice**: [Technical architecture decisions and rationale]
|
||||
- **Key Components**: [List of main technical components]
|
||||
- **Data Storage**: [Data models and storage solutions]
|
||||
- **Interface Design**: [API/interface specifications]
|
||||
|
||||
### Constraints
|
||||
- **Performance Requirements**: [Response time, throughput, etc.]
|
||||
- **Compatibility**: [System compatibility requirements]
|
||||
- **Security**: [Security considerations]
|
||||
- **Scalability**: [Future expansion considerations]
|
||||
|
||||
### Risk Assessment
|
||||
- **Technical Risks**: [Potential technical risks and mitigation plans]
|
||||
- **Dependency Risks**: [External dependencies and alternatives]
|
||||
- **Schedule Risks**: [Timeline risks and response strategies]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Functional Acceptance
|
||||
- [ ] Feature 1: [Specific acceptance conditions]
|
||||
- [ ] Feature 2: [Specific acceptance conditions]
|
||||
- [ ] Feature 3: [Specific acceptance conditions]
|
||||
|
||||
### Quality Standards
|
||||
- [ ] Code Quality: [Code standards and review requirements]
|
||||
- [ ] Test Coverage: [Testing requirements and coverage]
|
||||
- [ ] Performance Metrics: [Performance test pass criteria]
|
||||
- [ ] Security Review: [Security review requirements]
|
||||
|
||||
### User Acceptance
|
||||
- [ ] User Experience: [UX acceptance criteria]
|
||||
- [ ] Documentation: [Documentation delivery requirements]
|
||||
- [ ] Training Materials: [If needed, training material requirements]
|
||||
|
||||
## Execution Phases
|
||||
|
||||
### Phase 1: Preparation
|
||||
**Goal**: Environment preparation and technical validation
|
||||
- [ ] Task 1: [Specific task description]
|
||||
- [ ] Task 2: [Specific task description]
|
||||
- **Deliverables**: [Phase deliverables]
|
||||
- **Time**: [Estimated time]
|
||||
|
||||
### Phase 2: Core Development
|
||||
**Goal**: Implement core functionality
|
||||
- [ ] Task 1: [Specific task description]
|
||||
- [ ] Task 2: [Specific task description]
|
||||
- **Deliverables**: [Phase deliverables]
|
||||
- **Time**: [Estimated time]
|
||||
|
||||
### Phase 3: Integration & Testing
|
||||
**Goal**: Integration and quality assurance
|
||||
- [ ] Task 1: [Specific task description]
|
||||
- [ ] Task 2: [Specific task description]
|
||||
- **Deliverables**: [Phase deliverables]
|
||||
- **Time**: [Estimated time]
|
||||
|
||||
### Phase 4: Deployment
|
||||
**Goal**: Release and monitoring
|
||||
- [ ] Task 1: [Specific task description]
|
||||
- [ ] Task 2: [Specific task description]
|
||||
- **Deliverables**: [Phase deliverables]
|
||||
- **Time**: [Estimated time]
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Created**: {timestamp}
|
||||
**Clarification Rounds**: {clarification_rounds}
|
||||
**Quality Score**: {quality_score}/100
|
||||
```
|
||||
|
||||
## Behavioral Guidelines
|
||||
|
||||
### DO
|
||||
- Ask specific, targeted questions
|
||||
- Build on previous answers
|
||||
- Provide examples to guide users
|
||||
- Maintain conversational tone
|
||||
- Summarize clarification rounds within the PRD
|
||||
- Use clear, professional English
|
||||
- Generate concrete specifications
|
||||
- Stay in clarification mode until score ≥ 90
|
||||
|
||||
### DON'T
|
||||
- Ask all questions at once
|
||||
- Make assumptions without confirmation
|
||||
- Generate PRD before 90+ score
|
||||
- Skip any required sections
|
||||
- Use vague or abstract language
|
||||
- Proceed without user responses
|
||||
- Exit skill mode prematurely
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Clarity score ≥ 90/100
|
||||
- All PRD sections complete with substance
|
||||
- Acceptance criteria checklistable (using `- [ ]` format)
|
||||
- Execution phases actionable with concrete tasks
|
||||
- User approves final PRD
|
||||
- Ready for development handoff
|
||||
139
skills/codex/SKILL.md
Normal file
139
skills/codex/SKILL.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: codex
|
||||
description: Execute Codex CLI for code analysis, refactoring, and automated code changes. Use when you need to delegate complex code tasks to Codex AI with file references (@syntax) and structured output.
|
||||
---
|
||||
|
||||
# Codex CLI Integration
|
||||
|
||||
## Overview
|
||||
|
||||
Execute Codex CLI commands and parse structured JSON responses. Supports file references via `@` syntax, multiple models, and sandbox controls.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Complex code analysis requiring deep understanding
|
||||
- Large-scale refactoring across multiple files
|
||||
- Automated code generation with safety controls
|
||||
- Tasks requiring specialized reasoning models (gpt-5.1, gpt-5.1-codex)
|
||||
|
||||
## Usage
|
||||
|
||||
**推荐方式**（使用 uv run，自动管理 Python 环境）：
|
||||
```bash
|
||||
uv run ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
|
||||
```
|
||||
|
||||
**备选方式**（直接执行或使用 Python）：
|
||||
```bash
|
||||
~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
|
||||
# 或
|
||||
python3 ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
|
||||
```
|
||||
|
||||
恢复会话:
|
||||
```bash
|
||||
uv run ~/.claude/skills/codex/scripts/codex.py resume <session_id> "<task>" [model] [working_dir]
|
||||
```
|
||||
|
||||
## Timeout Control
|
||||
|
||||
- **Built-in**: Script enforces 2-hour timeout by default
|
||||
- **Override**: Set `CODEX_TIMEOUT` environment variable (in milliseconds, e.g., `CODEX_TIMEOUT=3600000` for 1 hour)
|
||||
- **Behavior**: On timeout, sends SIGTERM, then SIGKILL after 5s if process doesn't exit
|
||||
- **Exit code**: Returns 124 on timeout (consistent with GNU timeout)
|
||||
- **Bash tool**: Always set `timeout: 7200000` parameter for double protection
|
||||
|
||||
### Parameters
|
||||
|
||||
- `task` (required): Task description, supports `@file` references
|
||||
- `model` (optional): Model to use (default: gpt-5.1-codex)
|
||||
- `gpt-5.1-codex`: Default, optimized for code
|
||||
- `gpt-5.1`: Fast general purpose
|
||||
- `working_dir` (optional): Working directory (default: current)
|
||||
|
||||
### Return Format
|
||||
|
||||
Extracts `agent_message` from Codex JSON stream and appends session ID:
|
||||
```
|
||||
Agent response text here...
|
||||
|
||||
---
|
||||
SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
|
||||
```
|
||||
|
||||
Error format (stderr):
|
||||
```
|
||||
ERROR: Error message
|
||||
```
|
||||
|
||||
### Invocation Pattern
|
||||
|
||||
When calling via Bash tool, always include the timeout parameter:
|
||||
```
|
||||
Bash tool parameters:
|
||||
- command: uv run ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
|
||||
- timeout: 7200000
|
||||
- description: <brief description of the task>
|
||||
```
|
||||
|
||||
Alternatives:
|
||||
```
|
||||
# Direct execution (simplest)
|
||||
- command: ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
|
||||
|
||||
# Using python3
|
||||
- command: python3 ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
**Basic code analysis:**
|
||||
```bash
|
||||
# Recommended: via uv run (auto-manages Python environment)
|
||||
uv run ~/.claude/skills/codex/scripts/codex.py "explain @src/main.ts"
|
||||
# timeout: 7200000
|
||||
|
||||
# Alternative: direct execution
|
||||
~/.claude/skills/codex/scripts/codex.py "explain @src/main.ts"
|
||||
```
|
||||
|
||||
**Refactoring with specific model:**
|
||||
```bash
|
||||
uv run ~/.claude/skills/codex/scripts/codex.py "refactor @src/utils for performance" "gpt-5.1-codex"
|
||||
# timeout: 7200000
|
||||
```
|
||||
|
||||
**Multi-file analysis:**
|
||||
```bash
|
||||
uv run ~/.claude/skills/codex/scripts/codex.py "analyze @. and find security issues" "gpt-5.1-codex" "/path/to/project"
|
||||
# timeout: 7200000
|
||||
```
|
||||
|
||||
**Resume previous session:**
|
||||
```bash
|
||||
# First session
|
||||
uv run ~/.claude/skills/codex/scripts/codex.py "add comments to @utils.js" "gpt-5.1-codex"
|
||||
# Output includes: SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
|
||||
|
||||
# Continue the conversation
|
||||
uv run ~/.claude/skills/codex/scripts/codex.py resume 019a7247-ac9d-71f3-89e2-a823dbd8fd14 "now add type hints"
|
||||
# timeout: 7200000
|
||||
```
|
||||
|
||||
**Using python3 directly (alternative):**
|
||||
```bash
|
||||
python3 ~/.claude/skills/codex/scripts/codex.py "your task here"
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **Recommended**: Use `uv run` for automatic Python environment management (requires uv installed)
|
||||
- **Alternative**: Direct execution `./codex.py` (uses system Python via shebang)
|
||||
- Python implementation using standard library (zero dependencies)
|
||||
- Cross-platform compatible (Windows/macOS/Linux)
|
||||
- PEP 723 compliant (inline script metadata)
|
||||
- Runs with `--dangerously-bypass-approvals-and-sandbox` for automation (new sessions only)
|
||||
- Uses `--skip-git-repo-check` to work in any directory
|
||||
- Streams progress, returns only final agent message
|
||||
- Every execution returns a session ID for resuming conversations
|
||||
- Requires Codex CLI installed and authenticated
|
||||
236
skills/codex/scripts/codex.py
Executable file
236
skills/codex/scripts/codex.py
Executable file
@@ -0,0 +1,236 @@
|
||||
#!/usr/bin/env python3
|
||||
# /// script
|
||||
# requires-python = ">=3.8"
|
||||
# dependencies = []
|
||||
# ///
|
||||
"""
|
||||
Codex CLI wrapper with cross-platform support and session management.
|
||||
**FIXED**: Auto-detect long inputs and use stdin mode to avoid shell argument issues.
|
||||
|
||||
Usage:
|
||||
New session: uv run codex.py "task" [model] [workdir]
|
||||
Resume: uv run codex.py resume <session_id> "task" [model] [workdir]
|
||||
Alternative: python3 codex.py "task"
|
||||
Direct exec: ./codex.py "task"
|
||||
"""
|
||||
import subprocess
|
||||
import json
|
||||
import sys
|
||||
import os
|
||||
from typing import Optional
|
||||
|
||||
DEFAULT_MODEL = 'gpt-5.1-codex'
|
||||
DEFAULT_WORKDIR = '.'
|
||||
DEFAULT_TIMEOUT = 7200 # 2 hours in seconds
|
||||
FORCE_KILL_DELAY = 5
|
||||
STDIN_THRESHOLD = 800 # Auto-switch to stdin for prompts longer than 800 chars
|
||||
|
||||
|
||||
def log_error(message: str):
|
||||
"""输出错误信息到 stderr"""
|
||||
sys.stderr.write(f"ERROR: {message}\n")
|
||||
|
||||
|
||||
def log_warn(message: str):
|
||||
"""输出警告信息到 stderr"""
|
||||
sys.stderr.write(f"WARN: {message}\n")
|
||||
|
||||
|
||||
def resolve_timeout() -> int:
|
||||
"""解析超时配置（秒）"""
|
||||
raw = os.environ.get('CODEX_TIMEOUT', '')
|
||||
if not raw:
|
||||
return DEFAULT_TIMEOUT
|
||||
|
||||
try:
|
||||
parsed = int(raw)
|
||||
if parsed <= 0:
|
||||
log_warn(f"Invalid CODEX_TIMEOUT '{raw}', falling back to {DEFAULT_TIMEOUT}s")
|
||||
return DEFAULT_TIMEOUT
|
||||
# 环境变量是毫秒，转换为秒
|
||||
return parsed // 1000 if parsed > 10000 else parsed
|
||||
except ValueError:
|
||||
log_warn(f"Invalid CODEX_TIMEOUT '{raw}', falling back to {DEFAULT_TIMEOUT}s")
|
||||
return DEFAULT_TIMEOUT
|
||||
|
||||
|
||||
def normalize_text(text) -> Optional[str]:
|
||||
"""规范化文本：字符串或字符串数组"""
|
||||
if isinstance(text, str):
|
||||
return text
|
||||
if isinstance(text, list):
|
||||
return ''.join(text)
|
||||
return None
|
||||
|
||||
|
||||
def parse_args():
|
||||
"""解析命令行参数"""
|
||||
if len(sys.argv) < 2:
|
||||
log_error('Task required')
|
||||
sys.exit(1)
|
||||
|
||||
# 检测是否为 resume 模式
|
||||
if sys.argv[1] == 'resume':
|
||||
if len(sys.argv) < 4:
|
||||
log_error('Resume mode requires: resume <session_id> <task>')
|
||||
sys.exit(1)
|
||||
return {
|
||||
'mode': 'resume',
|
||||
'session_id': sys.argv[2],
|
||||
'task': sys.argv[3],
|
||||
'model': sys.argv[4] if len(sys.argv) > 4 else DEFAULT_MODEL,
|
||||
'workdir': sys.argv[5] if len(sys.argv) > 5 else DEFAULT_WORKDIR
|
||||
}
|
||||
else:
|
||||
return {
|
||||
'mode': 'new',
|
||||
'task': sys.argv[1],
|
||||
'model': sys.argv[2] if len(sys.argv) > 2 else DEFAULT_MODEL,
|
||||
'workdir': sys.argv[3] if len(sys.argv) > 3 else DEFAULT_WORKDIR
|
||||
}
|
||||
|
||||
|
||||
def build_codex_args(params: dict, use_stdin: bool) -> list:
|
||||
"""
|
||||
构建 codex CLI 参数
|
||||
|
||||
Args:
|
||||
params: 参数字典
|
||||
use_stdin: 是否使用 stdin 模式（不在命令行参数中传递 task）
|
||||
"""
|
||||
if params['mode'] == 'resume':
|
||||
if use_stdin:
|
||||
return [
|
||||
'codex', 'e',
|
||||
'--skip-git-repo-check',
|
||||
'--json',
|
||||
'resume',
|
||||
params['session_id'],
|
||||
'-' # 从 stdin 读取
|
||||
]
|
||||
else:
|
||||
return [
|
||||
'codex', 'e',
|
||||
'--skip-git-repo-check',
|
||||
'--json',
|
||||
'resume',
|
||||
params['session_id'],
|
||||
params['task']
|
||||
]
|
||||
else:
|
||||
base_args = [
|
||||
'codex', 'e',
|
||||
'-m', params['model'],
|
||||
'--dangerously-bypass-approvals-and-sandbox',
|
||||
'--skip-git-repo-check',
|
||||
'-C', params['workdir'],
|
||||
'--json'
|
||||
]
|
||||
|
||||
if use_stdin:
|
||||
base_args.append('-') # 从 stdin 读取
|
||||
else:
|
||||
base_args.append(params['task'])
|
||||
|
||||
return base_args
|
||||
|
||||
|
||||
def main():
|
||||
params = parse_args()
|
||||
timeout_sec = resolve_timeout()
|
||||
|
||||
# **FIX: Auto-detect long inputs and enable stdin mode**
|
||||
task_length = len(params['task'])
|
||||
use_stdin = task_length > STDIN_THRESHOLD
|
||||
|
||||
if use_stdin:
|
||||
log_warn(f"Task length ({task_length} chars) exceeds threshold, using stdin mode to avoid shell escaping issues")
|
||||
|
||||
codex_args = build_codex_args(params, use_stdin)
|
||||
|
||||
thread_id: Optional[str] = None
|
||||
last_agent_message: Optional[str] = None
|
||||
|
||||
try:
|
||||
# 启动 codex 子进程
|
||||
process = subprocess.Popen(
|
||||
codex_args,
|
||||
stdin=subprocess.PIPE if use_stdin else None, # **FIX: Enable stdin**
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=sys.stderr, # 错误直接透传到 stderr
|
||||
text=True,
|
||||
bufsize=1 # 行缓冲
|
||||
)
|
||||
|
||||
# **FIX: 如果使用 stdin 模式，写入任务到 stdin**
|
||||
if use_stdin:
|
||||
process.stdin.write(params['task'])
|
||||
process.stdin.close()
|
||||
|
||||
# 逐行解析 JSON 输出
|
||||
for line in process.stdout:
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
|
||||
try:
|
||||
event = json.loads(line)
|
||||
|
||||
# 捕获 thread_id
|
||||
if event.get('type') == 'thread.started':
|
||||
thread_id = event.get('thread_id')
|
||||
|
||||
# 捕获 agent_message
|
||||
if (event.get('type') == 'item.completed' and
|
||||
event.get('item', {}).get('type') == 'agent_message'):
|
||||
text = normalize_text(event['item'].get('text'))
|
||||
if text:
|
||||
last_agent_message = text
|
||||
|
||||
except json.JSONDecodeError:
|
||||
log_warn(f"Failed to parse line: {line}")
|
||||
|
||||
# 等待进程结束
|
||||
returncode = process.wait(timeout=timeout_sec)
|
||||
|
||||
if returncode == 0:
|
||||
if last_agent_message:
|
||||
# 输出 agent_message
|
||||
sys.stdout.write(f"{last_agent_message}\n")
|
||||
|
||||
# 输出 session_id（如果存在）
|
||||
if thread_id:
|
||||
sys.stdout.write(f"\n---\nSESSION_ID: {thread_id}\n")
|
||||
|
||||
sys.exit(0)
|
||||
else:
|
||||
log_error('Codex completed without agent_message output')
|
||||
sys.exit(1)
|
||||
else:
|
||||
log_error(f'Codex exited with status {returncode}')
|
||||
sys.exit(returncode)
|
||||
|
||||
except subprocess.TimeoutExpired:
|
||||
log_error('Codex execution timeout')
|
||||
process.kill()
|
||||
try:
|
||||
process.wait(timeout=FORCE_KILL_DELAY)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
sys.exit(124)
|
||||
|
||||
except FileNotFoundError:
|
||||
log_error("codex command not found in PATH")
|
||||
sys.exit(127)
|
||||
|
||||
except KeyboardInterrupt:
|
||||
process.terminate()
|
||||
try:
|
||||
process.wait(timeout=FORCE_KILL_DELAY)
|
||||
except subprocess.TimeoutExpired:
|
||||
process.kill()
|
||||
sys.exit(130)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Reference in New Issue
Block a user