| name | ohspec |
| description | Use when 需要生成 RFC 技术规范、进行需求分析、设计 API 契约，或需要 OHSpec 多代理编排输出。Triggers on "RFC", "需求分析", "API 契约", "设计规范", "OHSpec", "/ohspec". |
| allowed-tools | Task, AskUserQuestion, Read, Write, Glob, Grep, Bash |
OHSpec - 需求分析与设计规范
AI辅助需求分析与设计规范生成，强调多代理编排、结构化产物和质量门禁。
Architecture
架构概览与职责划分。
+-------------------------------------------------------------------+
| Orchestrator (你) |
| - 协调流程 / 复杂度路由 / 质量门禁 / 维护三文件 |
+-------------------------------+-----------------------------------+
| Subagents | Artifacts |
| Dispatcher / 需求分析师 / | rfc.md / findings.json / |
| 架构设计师 / 质量审查员 | progress.json |
+-------------------------------+-----------------------------------+
| Optional export: /ohspec:export -> rfc.digest.json + tasks.json |
+-------------------------------------------------------------------+
角色职责：
- 协调工作流：启动专家子代理，管理阶段转换，确保质量门禁
- 委托执行：优先委托（Claude Code/Task 子代理环境）；Task 不可用时启用 Codex 兼容回退
- 管理上下文：将繁重工作委托给子代理，保持主上下文清洁
- 确保质量：执行强制检查，验证输出，维护 RFC 标准
关键产物：rfc.md、findings.json、progress.json（三文件是 scan-of-record 与质量审计入口）。
Execution Flow
用户需求
-> 初始化三文件（rfc.md/findings.json/progress.json）
-> PRECHECK：快速需求预检（30秒过滤不可行需求）
-> ASSESS：确定工具与 scan scope，写入 progress.json + audit_log
-> 快速意图澄清（≤2问题，确保扫描准确性）
-> Dispatcher 基线扫描（scan-of-record）
-> 深度技术澄清（基于扫描结果）
-> 复杂度路由 + 路由信号
-> analyze -> design -> precheck -> audit
-> RFC 输出
-> 可选 /ohspec:export 生成机读件
复杂度路由：
| 级别 | 特征 | 模式 |
|---|
| SIMPLE | 单文件，<50行 | 快速通道 |
| MEDIUM | 多文件，单子系统 | 标准流程 |
| COMPLEX | 跨子系统，架构级 | 完整流程 + spike |
路由信号：
| 信号 | 动作 |
|---|
SKIP_ANALYZE | 需求明确、单文件 → 跳过 analyze |
LOAD_DIPLOMAT | 跨子系统依赖 → 加载 Diplomat |
TRIGGER_SPIKE | 技术不确定 → 触发 Spike |
SIMPLIFY_CLARIFY | 详细需求 → 简化澄清 |
⚠️ Mandatory Prerequisites
⛔ 禁止跳过：在执行任何操作之前，必须完整阅读以下文档。P1 表示触发该模式前必须读。
工作流 (必读)
规范文档 (必读)
模板文件 (必读)
Scripts (必读)
语言要求
强制：所有交付物必须使用简体中文（RFC、findings.json、progress.json、审查报告）。
例外：代码标识符遵循项目约定。
快速开始
/ohspec "为音频服务增加 3D 音效开关"
核心规则（必须遵守）
- 默认委托 Dispatcher 执行基线扫描（scan-of-record）；Task 不可用时使用 Codex 兼容回退
- 初始化三文件：
rfc.md、findings.json、progress.json 必须先落盘再扫描
- 所有详细扫描结果写入 findings.json
- 子代理返回 JSON 摘要（≤500 tokens）
- 每阶段结束更新 progress.json
- DFX 必须量化，禁止模糊描述
- 禁止开放式问题，必须选项式
- 机读件不写进 RFC：通过
/ohspec:export 手动生成 rfc.digest.json（可选 tasks.json）
- 澄清/门禁提问工具优先级：Codex CLI 用
request_user_input；Claude Code CLI 用 AskUserQuestion；若工具不可用/被禁用，输出“选项式问题 + 影响 + 建议”的文本并暂停，不得进入 plan/design/audit
- 禁止假设：找不到证据就补扫或阻断，不得编造设置键/接口/默认值
Codex 兼容回退（Task 不可用）
当无法使用 Task 子代理时（例如 Codex 环境），允许编排器执行最小化 scan-of-record：
- 优先使用
rg（其次 ag/grep）做关键词预过滤，快速定位候选关键文件
- 必须排除生成物目录：避免把历史 RFC/缓存当作“证据”并拉爆上下文（示例：
rg --glob '!**/.ohspec/**' --glob '!**/.claude/ohspec/**' --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/build/**' ...）
- 先落盘三文件（rfc.md/findings.json/progress.json），再开始任何扫描
- ASSESS 必须先落盘：在进入任何内容级扫描前，先用 ASSESS 选定工具与 scan_scope，并写入
progress.json.tooling + phases.assess + audit_log
- 产出必须写入
findings.confirmed.key_files（≥3 且覆盖入口/配置/依赖或测试/可观测）
- 同时写入
findings.confirmed.facts（SIMPLE ≥ 1；MEDIUM/COMPLEX ≥ 3，项目事实：配置/存储/权限/错误码/线程模型/可观测等，每条附证据锚点）
- 禁止假设：找不到证据就补扫/阻断，不得编造设置键/接口/默认值
- 第一分钟基线：开始深度 Read/设计推演前，必须先把 key_files+facts 落盘（否则中断会导致三文件“空壳”）
- 记录到
progress.json.tooling 与 audit_log
阶段定义
| 阶段 | 目标 | 专家 | 输出 |
|---|
| assess | 评估代码库规模，决策扫描策略 | 编排器 | 扫描策略 |
| analyze | 理解需求，澄清歧义 | 需求分析师 | RFC §1-§2 |
| design | 设计方案，定义接口 | 架构设计师 | RFC §3-§5 |
| precheck | 自动验证结构和覆盖 | 编排器 | 预检报告 |
| audit | 质量审查，评分决策 | 质量审查员 | 审查报告 |
阶段定义（扩展）
| 阶段 | 目标 | 触发条件 | 输出 |
|---|
| requirement_precheck | 快速需求预检，过滤不可行/信息不足需求 | 所有任务 | 可行性判断 |
| assess | 评估代码库规模，决策扫描策略 | requirement_precheck 通过 | 扫描策略 |
| intent_clarify | 快速意图澄清，确保扫描准确 | assess 完成 | 意图理解 |
| dispatcher | 基线扫描（scan-of-record） | intent_clarify 完成 | key_files + facts |
| analyze | 深度技术澄清，输出 RFC §1-§2 | dispatcher 完成 | RFC §1-§2 |
专家团队
核心专家：Dispatcher、需求分析师、架构设计师、质量审查员
扩展专家：Diplomat（跨子系统）、API设计师、Prototyper（spike验证）
质量门禁
必须满足：
- 5 个 RFC 章节完整
- 8 个 DFX 维度量化
- 4 种场景类型覆盖（Gherkin格式）
- 无模糊描述
RFC 格式
ID格式：RFC-{YYYYMMDD}-{slug}-{hash4}
目录（推荐）：.ohspec/rfcs/{RFC-ID}/
兼容（历史）：.claude/ohspec/rfcs/{RFC-ID}/
Reference Documents
工作流：
文档：
模板：
脚本：
