move claude-marketplace to ai-proj-helper

2026-03-12 21:42:30 +08:00
parent d7b6835e1d
commit 43585b8504
188 changed files with 39510 additions and 0 deletions
--- a/plugins/req-plugin/skills/SKILL.md
+++ b/plugins/req-plugin/skills/SKILL.md
@@ -0,0 +1,314 @@
+---
+name: req
+description: 需求工作流管理。用于 /req 命令使用、需求全生命周期管理（创建→PRD→评审→开发→测试→部署→归档）。当用户提到需求管理、/req 命令、REQ-XXX 相关任务时自动激活。
+arguments: <subcommand> [args]
+---
+
+# req - 需求工作流管理
+
+需求全流程工作流管理，与 ai-proj CLI 深度集成。
+
+## 需求生命周期
+
+**审批状态**（status）：
+```
+draft ──[讨论]──► draft(已讨论) ──[PRD]──► pending ──[pass]──► approved ──► archived
+          │                                    │
+      与 AI 讨论                           [reject]
+      明确方案                                 ▼
+                                           rejected
+```
+
+**开发阶段**（delivery_stage，approved 后启用）：
+```
+analysis → design → dev → review → testing → [待部署池] → released
+  评审       评审    开发   代码评审   测试    等待批量部署   已上线
+```
+
+**部署模型**：各需求独立走到 testing → 进入待部署池；`/req deploy` 一次构建批量推进到 released。
+
+## ⭐ 关键约束
+
+- **需求创建后，必须与 AI 进行一次需求讨论**，明确方案后再编写 PRD
+- **讨论结束后必须输出方案确认摘要**（强制流程：讨论 → 摘要 → 用户确认 → PRD）：
+  1. AI 输出结构化摘要（`## 讨论结论` 章节），`ai-proj req update` 追加到 description 末尾
+  2. AskUserQuestion 确认：「方案确认通过」或「需要修改」
+  3. **用户确认后才能开始 PRD 编写，禁止跳过确认**
+- 需求描述三段式（技术方案写入 PRD，不写在需求中）：
+  1. **需求描述** — 问题背景、现状痛点
+  2. **预期结果** — 期望达到的效果
+  3. **验收标准** — 可检查的完成条件（checklist，≥2 条）
+- PRD 文档是提交评审的前置条件；代码评审是测试的前置条件
+- **force=true 禁止自动使用** — 门禁未通过时必须 AskUserQuestion 确认 + 记录跳过原因
+- **评审必须用户确认** — 禁止 AI 自审批
+- **归档前门禁检查** — `/req done` 按需求类型（code/skill/ops）动态检查
+- **部署是项目级动作**，由 `/req deploy` 统一触发
+- **需求完成后必须 git 提交并 push** — commit 格式：`feat(skill): REQ-XXXX 需求标题`
+- **操作前先确认实际 ID** — 从 URL 提取 ID（如 `/requirements/897` → ID=897）
+- **务实路线关闭也必须补全关联任务** — 每个进度条阶段需创建关联任务
+- **阶段内容门禁（防空转）** — `/req next` 时检查关键阶段任务是否有实质内容
+
+## 禁止直接调用（必须走命令流程）
+
+| 禁止直接调用 | 必须通过 | 原因 |
+|-------------|---------|------|
+| `ai-proj req create` with allowSelfApprove | `/req new` | 禁止自动提交，必须创建为 draft |
+| `ai-proj req submit` (直接调用) | `/req submit` | 必须先通过 4 道门禁检查 |
+| `ai-proj req archive` | `/req done` | 必须先执行类型化门禁检查 |
+| `ai-proj req approve` | `/req review pass` | 必须先展示 PRD 摘要并等待用户确认 |
+| `ai-proj req advance --to <stage>` (force) | `/req next` | 必须先 AskUserQuestion 确认 + 记录跳过原因 |
+
+## 需求创建强制规则
+
+```bash
+# ✅ 正确：传完整业务字段
+ai-proj req create \
+  --title "需求标题" \
+  --description "## 需求描述\n...\n## 预期结果\n...\n## 验收标准\n..." \
+  --priority medium \
+  --category feature \
+  --due-date "2026-03-15"
+# → 结果必定是 draft 状态
+```
+
+### 从 draft 到 submit 的 4 道门禁
+
+```
+Gate 1: 需求讨论 ── description 末尾有「## 讨论结论」章节
+Gate 2: 方案确认 ── AskUserQuestion 获得「方案确认通过」
+Gate 3: PRD 文档 ── linkRole=prd 的任务存在且有文档
+Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD 存在
+```
+
+## 完整工作流
+
+```
+1.  /req new         → 创建需求 (draft)
+2.  需求讨论         → 输出结论摘要，用户确认
+3.  req-prd 技能     → 编写 PRD（创建【评审】PRD 任务）
+4.  /req submit      → 提交评审 (pending)，含 4 道门禁
+5.  /req review pass → 评审通过 (approved, delivery_stage=analysis)
+6.  /req next        → 推进到 design/dev 阶段
+7.  /req dev         → 启动开发（创建【开发】任务, delivery_stage=dev）
+8.  /req next        → 推进到 review 阶段
+9.  /req cr          → 代码评审（创建【代码评审】任务）
+10. /req next        → 推进到 testing 阶段
+11. /req test        → 测试验收（5-Gate 流程）
+12. /req deploy      → 批量部署（DG1-DG6 Deploy Gates）
+13. /req done        → 归档 (archived) + git commit + push
+```
+
+**5 阶段文档**：
+
+| 阶段 | 文档名 | 技能 |
+|------|--------|------|
+| PRD | 01-PRD.md | `req-prd` |
+| 测试 | 02-测试报告.md | 自动生成 |
+| 发布 | 03-发布记录.md | 自动生成 |
+| 归档 | 04-生命周期总结.md | 自动生成 |
+
+## 任务命名规范
+
+| linkRole | 前缀 | 示例 |
+|----------|------|------|
+| prd | 【评审】 | 【评审】PRD: 用户认证功能 |
+| design | 【评审】 | 【评审】技术设计: 数据模型 |
+| implementation | 【开发】 | 【开发-后端】实现 API |
+| code_review | 【代码评审】 | 【代码评审】CR: 代码审查 |
+| test | 【测试】 | 【测试】集成测试验证 |
+| deploy | 【部署】 | 【部署】部署到 staging |
+| documentation | 【文档】 | 【文档】API 文档更新 |
+
+## 阶段内容门禁（防空转）
+
+`/req next` 推进时，对关键阶段检查任务**是否有实质内容**（文档附件）：
+
+| 离开阶段 | 检查标准 |
+|----------|---------|
+| **review** | CR 任务有文档，字数 ≥ 500，含 `file:line` 代码引用，含结论章节 |
+| **testing** | 测试任务有文档，含测试结果表格，含通过/失败结论 |
+| **staging** | 部署任务有文档，含健康检查结果 |
+
+未通过 → AskUserQuestion（补充文档 or 强制跳过+记录原因）
+
+### CR 报告最低模板
+
+```markdown
+## 代码评审报告 - {需求标题}
+日期: YYYY-MM-DD
+评审范围: {N} 个文件, {M} 行变更
+
+### 变更概要
+{1-3 句描述}
+
+### 审查发现
+| 严重度 | 文件:行号 | 描述 | 建议 |
+|--------|----------|------|------|
+| {Critical/High/Medium/Low} | {file:line} | {问题} | {建议} |
+
+### 结论
+{通过 / 有条件通过 / 需修改}
+```
+
+## 命令参考
+
+### 撰写命令
+
+**`/req new [标题]`** — 对话式创建需求（仅 draft）
+- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
+- 流程：描述→提取关键信息→用户故事→验收标准→`ai-proj req create`→ Gate 1 需求讨论
+
+**`/req draft <描述>`** — 一句话快速创建 draft，AI 自动补全
+
+**`/req edit [REQ-ID]`** — 编辑需求：`ai-proj req get` → 询问修改点 → `ai-proj req update` → 显示变更摘要
+
+**`/req check [REQ-ID]`** — 完整性检查（Gate 4）：
+```
+✅ 三段式结构完整 / ✅ 验收标准: 4 条 / ✅ 讨论结论已记录 / ❌ PRD 文档缺失
+```
+
+**`/req split [REQ-ID]`** — 拆分为开发任务（后端/前端/测试）并关联
+
+### 提交评审
+
+**`/req submit [REQ-ID]`** ⭐ — 从 draft 到 pending 的唯一合法路径：
+1. Gate 1: description 末尾有「## 讨论结论」
+2. Gate 2: 讨论结论经过用户确认
+3. Gate 3: 有 linkRole=prd 任务且附有文档
+4. Gate 4: 执行 `/req check` 全部通过
+5. → `ai-proj req submit --id <id>` → 展示 PRD 摘要 → 等待评审
+
+**`/req review pass [REQ-ID]`** — 评审通过（必须用户明确确认后才调用 `ai-proj req approve --id <id>`）
+
+**`/req review reject [REQ-ID] [原因]`** — 评审驳回，必须提供原因
+
+### 阶段管理
+
+**`/req` 或 `/req list`** — 按状态分组列出所有需求（`ai-proj req list`）
+
+**`/req status [REQ-ID]`** — 查看需求详情（`ai-proj req get --id <id>`）、进度、关联任务
+
+**`/req next [REQ-ID]`** — 推进到下一阶段：
+1. 检查当前阶段任务完成度
+2. 智能跳阶段检测（无 implementation 任务时建议跳过 review/testing）
+3. `ai-proj req advance --id <id> --to <stage>`（门禁检查，未通过→AskUserQuestion，**禁止 AI 自动 force**）
+4. ⭐ 内容门禁检查（review/testing/staging 阶段）
+5. 自动创建目标阶段建议任务
+6. 展示：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
+
+**阶段顺序**：`analysis → design → dev → review → testing → [待部署池] → released`
+
+**`/req resume [REQ-ID]`** — 会话断点恢复：`ai-proj req get --id <id>` 获取 delivery_stage + 任务状态 + 建议操作
+
+### 开发命令
+
+**`/req dev [REQ-ID]`** — 启动开发：
+1. `ai-proj req tasks --id <id>` 找 implementation 任务
+2. `ai-proj task start --id <task_id>` 更新任务状态为开发中
+3. `/pr start` 从 origin/main 建分支
+
+**`/req cr [REQ-ID]`** — 代码评审：Git diff 摘要 + 生成检查清单（前置：开发任务完成）
+
+**`/req test [REQ-ID]`** — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程
+
+**`/req deploy [--project <name>] [--env <env>]`** — 项目级批量部署：
+1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
+2. AskUserQuestion 确认范围
+3. `ai-proj task create` 创建部署批次任务
+4. Deploy Gates DG1-DG6：staging 部署 → 冒烟测试 → 回归 → 生产部署
+5. `ai-proj task append-doc` 记录部署文档
+6. `ai-proj req advance --id <id> --to released` 批量推进
+
+**`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id <id>`：
+- **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
+- **code 检查**：delivery_stage=released + deploy 任务完成 + 部署文档 + 所有任务完成
+- **skill 检查**：delivery_stage≥testing + 所有任务完成
+- **ops 检查**：deploy 任务完成 + 所有任务完成
+
+### PRD 文档创建（通过任务中转）
+
+```bash
+# create-and-attach 只支持任务 ID（task_documents 外键约束）
+# 1. 创建任务
+ai-proj task create --title "【评审】PRD: 用户认证功能"
+
+# 2. 关联需求
+ai-proj req link --id 711 --task-ids 5214
+
+# 3. 附加文档到任务
+ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
+```
+
+### 阶段任务 Checklist
+
+| 阶段 | 建议任务 | linkRole |
+|------|----------|----------|
+| analysis | 【评审】PRD: {需求标题} | prd |
+| design | 【评审】技术设计: {需求标题} | design |
+| dev | 【开发-后端】{需求标题}、【开发-前端】{需求标题} | implementation |
+| review | 【代码评审】{需求标题} | code_review |
+| testing | 【测试】集成测试: {需求标题} | test |
+| deploy | 由 `/req deploy` 批量创建 | deploy |
+
+## 测试环境流程
+
+```
+[本机] → 通过 → [预发布] → 通过 → [生产]
+   ↑                │              │
+   └────────────────┴─── 失败 ─────┘
+```
+
+## 任务关联规范
+
+| link_role | 阶段前缀 | 所属阶段 | 进度权重 |
+|-----------|----------|----------|----------|
+| prd | 【评审】 | analysis | 10% |
+| design | 【评审】 | design | 5% |
+| implementation | 【开发】 | dev | 50% |
+| code_review | 【代码评审】 | review | 5% |
+| test | 【测试】 | testing | 15% |
+| deploy | 【部署】 | staging/released | 10% |
+| documentation | 【文档】 | any | 5% |
+
+## 标准任务结构
+
+```
+需求 REQ-xxx
+├── 📝 analysis  → 【评审】PRD: {需求标题}                    (linkRole: prd)
+├── 📐 design    → 【评审】技术设计: {需求标题}               (linkRole: design)
+├── 💻 dev       → 【开发-后端】、【开发-前端】{描述}          (linkRole: implementation)
+├── 🔍 review    → 【代码评审】CR: {需求标题}                 (linkRole: code_review)
+├── 🧪 testing   → 【测试】集成测试: {需求标题}               (linkRole: test)
+├── 🚀 staging   → 【部署】部署到 staging                     (linkRole: deploy)
+└── 🏁 released  → 【部署】部署到 prod                        (linkRole: deploy)
+```
+
+## ai-proj CLI 速查
+
+```bash
+# 需求操作
+ai-proj req list                          # 列出需求
+ai-proj req get --id <id>                 # 查看详情
+ai-proj req create --title "..." ...      # 创建需求
+ai-proj req update --id <id> ...          # 更新需求
+ai-proj req submit --id <id>              # 提交评审
+ai-proj req approve --id <id>             # 批准需求
+ai-proj req advance --id <id> --to <stage> # 推进阶段
+ai-proj req link --id <id> --task-ids ... # 关联任务
+ai-proj req tasks --id <id>               # 查看关联任务
+```
+
+## 有效值
+
+**审批状态**: `draft`, `pending`, `reviewing`, `approved`, `rejected`, `archived`
+
+**开发阶段**: `backlog`, `analysis`, `design`, `dev`, `review`, `integration`, `testing`, `staging`, `released`
+
+**linkRole**: `prd`, `design`, `implementation`, `code_review`, `test`, `deploy`, `regression`, `documentation`
+
+## 相关技能
+
+| 技能 | 用途 |
+|------|------|
+| `req-prd` | PRD 文档编写 + 评审方法论 |
+| `dev-test` | 测试 + 质量门禁 |