specops 0.2.4 → 0.3.0

package/.opencode/workflows/new-project.md

@@ -0,0 +1,1116 @@
+<purpose>
+通过统一流程初始化新项目：提问、研究（可选）、需求、路线图。这是任何项目中最具杠杆效应的时刻——在这里深入提问意味着更好的计划、更好的执行、更好的结果。一个工作流带你从想法到准备规划。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<auto_mode>
+## 自动模式检测
+
+检查 $ARGUMENTS 中是否存在 `--auto` 标志。
+
+**如果是自动模式：**
+- 跳过棕地映射提议（假设为绿地项目）
+- 跳过深度提问（从提供的文档中提取上下文）
+- 配置：YOLO 模式是隐含的（跳过该问题），但先询问深度/git/agents（步骤 2a）
+- 配置完成后：使用智能默认值自动运行步骤 6-9：
+  - 研究：始终是
+  - 需求：包含提供文档中的所有基本功能 + 特性
+  - 需求审批：自动批准
+  - 路线图审批：自动批准
+
+**文档要求：**
+自动模式需要一个想法文档——以下任一：
+- 文件引用：`/specops:new-project --auto @prd.md`
+- 在提示中粘贴/编写的文本
+
+如果未提供文档内容，报错：
+
+```
+Error: --auto requires an idea document.
+
+Usage:
+  /specops:new-project --auto @your-idea.md
+  /specops:new-project --auto [paste or write your idea here]
+
+The document should describe what you want to build.
+```
+</auto_mode>
+
+<process>
+
+## 1. 设置
+
+**必须首先执行——在任何用户交互之前执行这些检查：**
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init new-project)
+```
+
+解析 JSON 获取：`researcher_model`、`synthesizer_model`、`roadmapper_model`、`commit_docs`、`project_exists`、`has_codebase_map`、`planning_exists`、`has_existing_code`、`has_package_file`、`is_brownfield`、`needs_codebase_map`、`has_git`、`project_path`。
+
+**如果 `project_exists` 为 true：** 报错——项目已初始化。使用 `/specops:progress`。
+
+**如果 `has_git` 为 false：** 初始化 git：
+```bash
+git init
+```
+
+## 2. 棕地提议
+
+**如果是自动模式：** 跳到步骤 4（假设为绿地项目，从提供的文档合成 PROJECT.md）。
+
+**如果 `needs_codebase_map` 为 true**（来自 init——检测到现有代码但没有代码库映射）：
+
+使用 AskUserQuestion：
+- header: "Codebase"
+- question: "我检测到此目录中有现有代码。你想先映射代码库吗？"
+- options:
+  - "先映射代码库" — 运行 /specops:map-codebase 了解现有架构（推荐）
+  - "跳过映射" — 继续项目初始化
+
+**如果"先映射代码库"：**
+```
+先运行 `/specops:map-codebase`，然后返回 `/specops:new-project`
+```
+退出命令。
+
+**如果"跳过映射"或 `needs_codebase_map` 为 false：** 继续到步骤 3。
+
+## 2a. 自动模式配置（仅自动模式）
+
+**如果是自动模式：** 在处理想法文档之前先收集配置设置。
+
+YOLO 模式是隐含的（auto = YOLO）。询问剩余配置问题：
+
+**第 1 轮——核心设置（3 个问题，无 Mode 问题）：**
+
+```
+AskUserQuestion([
+  {
+    header: "Depth",
+    question: "规划应该多详尽？",
+    multiSelect: false,
+    options: [
+      { label: "Quick (Recommended)", description: "快速交付（3-5 个阶段，每个 1-3 个计划）" },
+      { label: "Standard", description: "平衡范围和速度（5-8 个阶段，每个 3-5 个计划）" },
+      { label: "Comprehensive", description: "全面覆盖（8-12 个阶段，每个 5-10 个计划）" }
+    ]
+  },
+  {
+    header: "Execution",
+    question: "并行运行计划？",
+    multiSelect: false,
+    options: [
+      { label: "Parallel (Recommended)", description: "独立计划同时运行" },
+      { label: "Sequential", description: "一次一个计划" }
+    ]
+  },
+  {
+    header: "Git Tracking",
+    question: "将规划文档提交到 git？",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "规划文档纳入版本控制" },
+      { label: "No", description: "保持 .planning/ 仅本地（添加到 .gitignore）" }
+    ]
+  }
+])
+```
+
+**第 2 轮——工作流 Agent（与步骤 5 相同）：**
+
+```
+AskUserQuestion([
+  {
+    header: "Research",
+    question: "在规划每个阶段前进行研究？（增加 token/时间）",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "调查领域，发现模式，发掘陷阱" },
+      { label: "No", description: "直接从需求开始规划" }
+    ]
+  },
+  {
+    header: "Plan Check",
+    question: "验证计划是否能达成目标？（增加 token/时间）",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "在执行开始前发现缺口" },
+      { label: "No", description: "不验证直接执行计划" }
+    ]
+  },
+  {
+    header: "Verifier",
+    question: "每个阶段后验证工作是否满足需求？（增加 token/时间）",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "确认交付物匹配阶段目标" },
+      { label: "No", description: "信任执行，跳过验证" }
+    ]
+  },
+  {
+    header: "AI Models",
+    question: "规划 Agent 使用哪些 AI 模型？",
+    multiSelect: false,
+    options: [
+      { label: "Balanced (Recommended)", description: "大多数 Agent 使用 Sonnet——良好的质量/成本比" },
+      { label: "Quality", description: "研究/路线图使用 Opus——更高成本，更深入分析" },
+      { label: "Budget", description: "尽可能使用 Haiku——最快，最低成本" }
+    ]
+  }
+])
+```
+
+创建 `.planning/config.json`，mode 设为 "yolo"：
+
+```json
+{
+  "mode": "yolo",
+  "depth": "[selected]",
+  "parallelization": true|false,
+  "commit_docs": true|false,
+  "model_profile": "quality|balanced|budget",
+  "workflow": {
+    "research": true|false,
+    "plan_check": true|false,
+    "verifier": true|false,
+    "auto_advance": true
+  }
+}
+```
+
+**如果 commit_docs = No：** 将 `.planning/` 添加到 `.gitignore`。
+
+**提交 config.json：**
+
+```bash
+mkdir -p .planning
+node .opencode/bin/specops-tools.cjs commit "chore: add project config" --files .planning/config.json
+```
+
+**将自动推进持久化到配置（在上下文压缩后仍然有效）：**
+
+```bash
+node .opencode/bin/specops-tools.cjs config-set workflow.auto_advance true
+```
+
+继续到步骤 4（跳过步骤 3 和 5）。
+
+## 3. 深度提问
+
+**如果是自动模式：** 跳过（已在步骤 2a 中处理）。改为从提供的文档中提取项目上下文，然后继续到步骤 4。
+
+**显示阶段横幅：**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 提问阶段
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**开启对话：**
+
+内联提问（自由形式，不使用 AskUserQuestion）：
+
+"你想构建什么？"
+
+等待他们的回复。这为你提供了提出智能后续问题所需的上下文。
+
+**跟随线索：**
+
+根据他们所说的内容，提出深入其回复的后续问题。使用 AskUserQuestion 并提供探究他们提到内容的选项——解读、澄清、具体示例。
+
+持续跟随线索。每个回答都会打开新的线索去探索。询问：
+- 什么让他们兴奋
+- 什么问题激发了这个想法
+- 模糊术语的含义
+- 实际看起来会是什么样
+- 什么已经决定了
+
+参考 `questioning.md` 获取技巧：
+- 挑战模糊性
+- 将抽象变具体
+- 发掘假设
+- 找到边界
+- 揭示动机
+
+**检查上下文（后台进行，不要说出来）：**
+
+在进行过程中，心理检查 `questioning.md` 中的上下文清单。如果有缺口，自然地融入问题。不要突然切换到清单模式。
+
+**决策门：**
+
+当你能写出清晰的 PROJECT.md 时，使用 AskUserQuestion：
+
+- header: "Ready?"
+- question: "我想我理解你的想法了。准备好创建 PROJECT.md 了吗？"
+- options:
+  - "创建 PROJECT.md" — 让我们继续
+  - "继续探索" — 我想分享更多 / 继续问我
+
+如果"继续探索"——询问他们想添加什么，或识别缺口并自然地探究。
+
+循环直到选择"创建 PROJECT.md"。
+
+## 4. 编写 PROJECT.md
+
+**如果是自动模式：** 从提供的文档合成。没有显示"Ready?"门——直接进入提交。
+
+将所有上下文合成到 `.planning/PROJECT.md`，使用 `templates/project.md` 中的模板。
+
+**对于绿地项目：**
+
+将需求初始化为假设：
+
+```markdown
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] [需求 1]
+- [ ] [需求 2]
+- [ ] [需求 3]
+
+### Out of Scope
+
+- [排除项 1] — [原因]
+- [排除项 2] — [原因]
+```
+
+所有 Active 需求在交付和验证之前都是假设。
+
+**对于棕地项目（代码库映射已存在）：**
+
+从现有代码推断 Validated 需求：
+
+1. 阅读 `.planning/codebase/ARCHITECTURE.md` 和 `STACK.md`
+2. 识别代码库已经做了什么
+3. 这些成为初始 Validated 集合
+
+```markdown
+## Requirements
+
+### Validated
+
+- ✓ [现有功能 1] — existing
+- ✓ [现有功能 2] — existing
+- ✓ [现有功能 3] — existing
+
+### Active
+
+- [ ] [新需求 1]
+- [ ] [新需求 2]
+
+### Out of Scope
+
+- [排除项 1] — [原因]
+```
+
+**关键决策：**
+
+用提问期间做出的任何决策初始化：
+
+```markdown
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [提问中的选择] | [原因] | — Pending |
+```
+
+**最后更新页脚：**
+
+```markdown
+---
+*Last updated: [date] after initialization*
+```
+
+不要压缩。捕获收集到的所有内容。
+
+**提交 PROJECT.md：**
+
+```bash
+mkdir -p .planning
+node .opencode/bin/specops-tools.cjs commit "docs: initialize project" --files .planning/PROJECT.md
+```
+
+## 5. 工作流偏好
+
+**如果是自动模式：** 跳过——配置已在步骤 2a 中收集。继续到步骤 5.5。
+
+**检查全局默认值**（`.opencode/defaults.json`）。如果文件存在，提议使用保存的默认值：
+
+```
+AskUserQuestion([
+  {
+    question: "使用你保存的默认设置？（来自 .opencode/defaults.json）",
+    header: "Defaults",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "使用保存的默认值，跳过设置问题" },
+      { label: "No", description: "手动配置设置" }
+    ]
+  }
+])
+```
+
+如果"Yes"：读取 `.opencode/defaults.json`，使用这些值填充 config.json，直接跳到下方的**提交 config.json**。
+
+如果"No"或 `.opencode/defaults.json` 不存在：继续下面的问题。
+
+**第 1 轮——核心工作流设置（4 个问题）：**
+
+```
+questions: [
+  {
+    header: "Mode",
+    question: "你想如何工作？",
+    multiSelect: false,
+    options: [
+      { label: "YOLO (Recommended)", description: "自动批准，直接执行" },
+      { label: "Interactive", description: "每步确认" }
+    ]
+  },
+  {
+    header: "Depth",
+    question: "规划应该多详尽？",
+    multiSelect: false,
+    options: [
+      { label: "Quick", description: "快速交付（3-5 个阶段，每个 1-3 个计划）" },
+      { label: "Standard", description: "平衡范围和速度（5-8 个阶段，每个 3-5 个计划）" },
+      { label: "Comprehensive", description: "全面覆盖（8-12 个阶段，每个 5-10 个计划）" }
+    ]
+  },
+  {
+    header: "Execution",
+    question: "并行运行计划？",
+    multiSelect: false,
+    options: [
+      { label: "Parallel (Recommended)", description: "独立计划同时运行" },
+      { label: "Sequential", description: "一次一个计划" }
+    ]
+  },
+  {
+    header: "Git Tracking",
+    question: "将规划文档提交到 git？",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "规划文档纳入版本控制" },
+      { label: "No", description: "保持 .planning/ 仅本地（添加到 .gitignore）" }
+    ]
+  }
+]
+```
+
+**第 2 轮——工作流 Agent：**
+
+这些在规划/执行期间生成额外的 Agent。它们增加 token 和时间但提高质量。
+
+| Agent | 运行时机 | 功能 |
+|-------|----------|------|
+| **Researcher** | 规划每个阶段之前 | 调查领域，发现模式，发掘陷阱 |
+| **Plan Checker** | 计划创建之后 | 验证计划是否真正能达成阶段目标 |
+| **Verifier** | 阶段执行之后 | 确认必要功能已交付 |
+
+重要项目推荐全部启用。快速实验可以跳过。
+
+```
+questions: [
+  {
+    header: "Research",
+    question: "在规划每个阶段前进行研究？（增加 token/时间）",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "调查领域，发现模式，发掘陷阱" },
+      { label: "No", description: "直接从需求开始规划" }
+    ]
+  },
+  {
+    header: "Plan Check",
+    question: "验证计划是否能达成目标？（增加 token/时间）",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "在执行开始前发现缺口" },
+      { label: "No", description: "不验证直接执行计划" }
+    ]
+  },
+  {
+    header: "Verifier",
+    question: "每个阶段后验证工作是否满足需求？（增加 token/时间）",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "确认交付物匹配阶段目标" },
+      { label: "No", description: "信任执行，跳过验证" }
+    ]
+  },
+  {
+    header: "AI Models",
+    question: "规划 Agent 使用哪些 AI 模型？",
+    multiSelect: false,
+    options: [
+      { label: "Balanced (Recommended)", description: "大多数 Agent 使用 Sonnet——良好的质量/成本比" },
+      { label: "Quality", description: "研究/路线图使用 Opus——更高成本，更深入分析" },
+      { label: "Budget", description: "尽可能使用 Haiku——最快，最低成本" }
+    ]
+  }
+]
+```
+
+创建 `.planning/config.json` 包含所有设置：
+
+```json
+{
+  "mode": "yolo|interactive",
+  "depth": "quick|standard|comprehensive",
+  "parallelization": true|false,
+  "commit_docs": true|false,
+  "model_profile": "quality|balanced|budget",
+  "workflow": {
+    "research": true|false,
+    "plan_check": true|false,
+    "verifier": true|false
+  }
+}
+```
+
+**如果 commit_docs = No：**
+- 在 config.json 中设置 `commit_docs: false`
+- 将 `.planning/` 添加到 `.gitignore`（如需要则创建）
+
+**如果 commit_docs = Yes：**
+- 不需要额外的 gitignore 条目
+
+**提交 config.json：**
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "chore: add project config" --files .planning/config.json
+```
+
+**注意：** 随时运行 `/specops:settings` 更新这些偏好。
+
+## 5.5. 解析模型配置
+
+使用 init 返回的模型：`researcher_model`、`synthesizer_model`、`roadmapper_model`。
+
+## 6. 研究决策
+
+**如果是自动模式：** 默认选择"先研究"，无需询问。
+
+使用 AskUserQuestion：
+- header: "Research"
+- question: "在定义需求之前研究领域生态系统？"
+- options:
+  - "先研究（推荐）" — 发现标准技术栈、预期功能、架构模式
+  - "跳过研究" — 我熟悉这个领域，直接进入需求
+
+**如果"先研究"：**
+
+显示阶段横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 研究中
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+正在研究 [领域] 生态系统...
+```
+
+创建研究目录：
+```bash
+mkdir -p .planning/research
+```
+
+**确定里程碑上下文：**
+
+检查是绿地还是后续里程碑：
+- 如果 PROJECT.md 中没有"Validated"需求 → 绿地（从零开始构建）
+- 如果存在"Validated"需求 → 后续里程碑（在现有应用上添加）
+
+显示生成指示器：
+```
+◆ 并行生成 4 个研究员...
+  → 技术栈研究
+  → 功能研究
+  → 架构研究
+  → 陷阱研究
+```
+
+并行生成 4 个 specops-project-researcher Agent，使用路径引用：
+
+```
+Task(prompt="First, read .opencode/agent/specops-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Stack dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: Research the standard stack for building [domain] from scratch.
+Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
+</milestone_context>
+
+<question>
+What's the standard 2025 stack for [domain]?
+</question>
+
+<files_to_read>
+- {project_path} (Project context and goals)
+</files_to_read>
+
+<downstream_consumer>
+Your STACK.md feeds into roadmap creation. Be prescriptive:
+- Specific libraries with versions
+- Clear rationale for each choice
+- What NOT to use and why
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Versions are current (verify with Context7/official docs, not training data)
+- [ ] Rationale explains WHY, not just WHAT
+- [ ] Confidence levels assigned to each recommendation
+</quality_gate>
+
+<output>
+Write to: .planning/research/STACK.md
+Use template: .opencode/templates/research-project/STACK.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
+
+Task(prompt="First, read .opencode/agent/specops-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Features dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
+Subsequent: How do [target features] typically work? What's expected behavior?
+</milestone_context>
+
+<question>
+What features do [domain] products have? What's table stakes vs differentiating?
+</question>
+
+<files_to_read>
+- {project_path} (Project context)
+</files_to_read>
+
+<downstream_consumer>
+Your FEATURES.md feeds into requirements definition. Categorize clearly:
+- Table stakes (must have or users leave)
+- Differentiators (competitive advantage)
+- Anti-features (things to deliberately NOT build)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
+- [ ] Complexity noted for each feature
+- [ ] Dependencies between features identified
+</quality_gate>
+
+<output>
+Write to: .planning/research/FEATURES.md
+Use template: .opencode/templates/research-project/FEATURES.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
+
+Task(prompt="First, read .opencode/agent/specops-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Architecture dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: How are [domain] systems typically structured? What are major components?
+Subsequent: How do [target features] integrate with existing [domain] architecture?
+</milestone_context>
+
+<question>
+How are [domain] systems typically structured? What are major components?
+</question>
+
+<files_to_read>
+- {project_path} (Project context)
+</files_to_read>
+
+<downstream_consumer>
+Your ARCHITECTURE.md informs phase structure in roadmap. Include:
+- Component boundaries (what talks to what)
+- Data flow (how information moves)
+- Suggested build order (dependencies between components)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Components clearly defined with boundaries
+- [ ] Data flow direction explicit
+- [ ] Build order implications noted
+</quality_gate>
+
+<output>
+Write to: .planning/research/ARCHITECTURE.md
+Use template: .opencode/templates/research-project/ARCHITECTURE.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
+
+Task(prompt="First, read .opencode/agent/specops-project-researcher.md for your role and instructions.
+
+<research_type>
+Project Research — Pitfalls dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
+Subsequent: What are common mistakes when adding [target features] to [domain]?
+</milestone_context>
+
+<question>
+What do [domain] projects commonly get wrong? Critical mistakes?
+</question>
+
+<files_to_read>
+- {project_path} (Project context)
+</files_to_read>
+
+<downstream_consumer>
+Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
+- Warning signs (how to detect early)
+- Prevention strategy (how to avoid)
+- Which phase should address it
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Pitfalls are specific to this domain (not generic advice)
+- [ ] Prevention strategies are actionable
+- [ ] Phase mapping included where relevant
+</quality_gate>
+
+<output>
+Write to: .planning/research/PITFALLS.md
+Use template: .opencode/templates/research-project/PITFALLS.md
+</output>
+", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
+```
+
+所有 4 个 Agent 完成后，生成合成器创建 SUMMARY.md：
+
+```
+Task(prompt="
+<task>
+Synthesize research outputs into SUMMARY.md.
+</task>
+
+<files_to_read>
+- .planning/research/STACK.md
+- .planning/research/FEATURES.md
+- .planning/research/ARCHITECTURE.md
+- .planning/research/PITFALLS.md
+</files_to_read>
+
+<output>
+Write to: .planning/research/SUMMARY.md
+Use template: .opencode/templates/research-project/SUMMARY.md
+Commit after writing.
+</output>
+", subagent_type="specops-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+```
+
+显示研究完成横幅和关键发现：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 研究完成 ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 关键发现
+
+**技术栈：** [来自 SUMMARY.md]
+**基本功能：** [来自 SUMMARY.md]
+**注意事项：** [来自 SUMMARY.md]
+
+文件：`.planning/research/`
+```
+
+**如果"跳过研究"：** 继续到步骤 7。
+
+## 7. 定义需求
+
+显示阶段横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 定义需求
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**加载上下文：**
+
+读取 PROJECT.md 并提取：
+- 核心价值（必须工作的那一件事）
+- 声明的约束（预算、时间线、技术限制）
+- 任何明确的范围边界
+
+**如果研究存在：** 读取 research/FEATURES.md 并提取功能类别。
+
+**如果是自动模式：**
+- 自动包含所有基本功能（用户期望这些）
+- 包含提供文档中明确提到的功能
+- 自动推迟文档中未提到的差异化功能
+- 跳过按类别的 AskUserQuestion 循环
+- 跳过"还有补充吗？"问题
+- 跳过需求审批门
+- 直接生成 REQUIREMENTS.md 并提交
+
+**按类别展示功能（仅交互模式）：**
+
+```
+以下是 [领域] 的功能：
+
+## 认证
+**基本功能：**
+- 邮箱/密码注册
+- 邮箱验证
+- 密码重置
+- 会话管理
+
+**差异化功能：**
+- 魔法链接登录
+- OAuth（Google、GitHub）
+- 双因素认证
+
+**研究备注：** [任何相关备注]
+
+---
+
+## [下一个类别]
+...
+```
+
+**如果没有研究：** 通过对话收集需求。
+
+询问："用户需要能做的主要事情是什么？"
+
+对于提到的每个功能：
+- 提出澄清问题使其具体化
+- 探究相关功能
+- 按类别分组
+
+**确定每个类别的范围：**
+
+对于每个类别，使用 AskUserQuestion：
+
+- header: "[类别]"（最多 12 个字符）
+- question: "哪些 [类别] 功能在 v1 中？"
+- multiSelect: true
+- options:
+  - "[功能 1]" — [简要描述]
+  - "[功能 2]" — [简要描述]
+  - "[功能 3]" — [简要描述]
+  - "v1 中不需要" — 推迟整个类别
+
+跟踪响应：
+- 选中的功能 → v1 需求
+- 未选中的基本功能 → v2（用户期望这些）
+- 未选中的差异化功能 → 范围外
+
+**识别缺口：**
+
+使用 AskUserQuestion：
+- header: "补充"
+- question: "有研究遗漏的需求吗？（你愿景中特有的功能）"
+- options:
+  - "没有，研究已覆盖" — 继续
+  - "有，让我补充" — 捕获补充内容
+
+**验证核心价值：**
+
+将需求与 PROJECT.md 中的核心价值交叉检查。如果检测到缺口，提出来。
+
+**生成 REQUIREMENTS.md：**
+
+创建 `.planning/REQUIREMENTS.md` 包含：
+- v1 需求按类别分组（复选框，REQ-ID）
+- v2 需求（推迟的）
+- 范围外（明确排除及理由）
+- 可追溯性部分（空的，由路线图填充）
+
+**REQ-ID 格式：** `[CATEGORY]-[NUMBER]`（AUTH-01、CONTENT-02）
+
+**需求质量标准：**
+
+好的需求是：
+- **具体且可测试的：** "用户可以通过邮件链接重置密码"（不是"处理密码重置"）
+- **以用户为中心的：** "用户可以 X"（不是"系统做 Y"）
+- **原子的：** 每个需求一个功能（不是"用户可以登录和管理个人资料"）
+- **独立的：** 对其他需求的依赖最小
+
+拒绝模糊的需求。推动具体化：
+- "处理认证" → "用户可以使用邮箱/密码登录并跨会话保持登录"
+- "支持分享" → "用户可以通过链接分享帖子，链接在接收者的浏览器中打开"
+
+**展示完整需求列表（仅交互模式）：**
+
+显示每个需求（不是数量）供用户确认：
+
+```
+## v1 需求
+
+### 认证
+- [ ] **AUTH-01**: 用户可以使用邮箱/密码创建账户
+- [ ] **AUTH-02**: 用户可以登录并跨会话保持登录
+- [ ] **AUTH-03**: 用户可以从任何页面登出
+
+### 内容
+- [ ] **CONT-01**: 用户可以创建文本帖子
+- [ ] **CONT-02**: 用户可以编辑自己的帖子
+
+[... 完整列表 ...]
+
+---
+
+这是否捕获了你要构建的内容？（是 / 调整）
+```
+
+如果"调整"：返回范围确定。
+
+**提交需求：**
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
+```
+
+## 8. 创建路线图
+
+显示阶段横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 创建路线图
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 正在生成路线图制定者...
+```
+
+生成 specops-roadmapper Agent，使用路径引用：
+
+```
+Task(prompt="
+<planning_context>
+
+<files_to_read>
+- .planning/PROJECT.md (Project context)
+- .planning/REQUIREMENTS.md (v1 Requirements)
+- .planning/research/SUMMARY.md (Research findings - if exists)
+- .planning/config.json (Depth and mode settings)
+</files_to_read>
+
+</planning_context>
+
+<instructions>
+Create roadmap:
+1. Derive phases from requirements (don't impose structure)
+2. Map every v1 requirement to exactly one phase
+3. Derive 2-5 success criteria per phase (observable user behaviors)
+4. Validate 100% coverage
+5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+6. Return ROADMAP CREATED with summary
+
+Write files first, then return. This ensures artifacts persist even if context is lost.
+</instructions>
+", subagent_type="specops-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+```
+
+**处理路线图制定者返回：**
+
+**如果 `## ROADMAP BLOCKED`：**
+- 展示阻塞信息
+- 与用户合作解决
+- 解决后重新生成
+
+**如果 `## ROADMAP CREATED`：**
+
+读取创建的 ROADMAP.md 并内联美观展示：
+
+```
+---
+
+## 提议的路线图
+
+**[N] 个阶段** | **[X] 个需求已映射** | 所有 v1 需求已覆盖 ✓
+
+| # | 阶段 | 目标 | 需求 | 成功标准 |
+|---|------|------|------|----------|
+| 1 | [名称] | [目标] | [REQ-ID] | [数量] |
+| 2 | [名称] | [目标] | [REQ-ID] | [数量] |
+| 3 | [名称] | [目标] | [REQ-ID] | [数量] |
+...
+
+### 阶段详情
+
+**Phase 1: [名称]**
+目标：[目标]
+需求：[REQ-ID]
+成功标准：
+1. [标准]
+2. [标准]
+3. [标准]
+
+**Phase 2: [名称]**
+目标：[目标]
+需求：[REQ-ID]
+成功标准：
+1. [标准]
+2. [标准]
+
+[... 所有阶段继续 ...]
+
+---
+```
+
+**如果是自动模式：** 跳过审批门——自动批准并直接提交。
+
+**关键：提交前征求批准（仅交互模式）：**
+
+使用 AskUserQuestion：
+- header: "Roadmap"
+- question: "这个路线图结构适合你吗？"
+- options:
+  - "批准" — 提交并继续
+  - "调整阶段" — 告诉我要改什么
+  - "查看完整文件" — 显示原始 ROADMAP.md
+
+**如果"批准"：** 继续提交。
+
+**如果"调整阶段"：**
+- 获取用户的调整意见
+- 使用修订上下文重新生成路线图制定者：
+  ```
+  Task(prompt="
+  <revision>
+  User feedback on roadmap:
+  [user's notes]
+
+  <files_to_read>
+  - .planning/ROADMAP.md (Current roadmap to revise)
+  </files_to_read>
+
+  Update the roadmap based on feedback. Edit files in place.
+  Return ROADMAP REVISED with changes made.
+  </revision>
+  ", subagent_type="specops-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
+  ```
+- 展示修订后的路线图
+- 循环直到用户批准
+
+**如果"查看完整文件"：** 显示原始 `cat .planning/ROADMAP.md`，然后重新询问。
+
+**提交路线图（批准后或自动模式）：**
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+## 9. 完成
+
+展示完成摘要：
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 项目已初始化 ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**[项目名称]**
+
+| 产物           | 位置                        |
+|----------------|-----------------------------|
+| 项目           | `.planning/PROJECT.md`      |
+| 配置           | `.planning/config.json`     |
+| 研究           | `.planning/research/`       |
+| 需求           | `.planning/REQUIREMENTS.md` |
+| 路线图         | `.planning/ROADMAP.md`      |
+
+**[N] 个阶段** | **[X] 个需求** | 准备构建 ✓
+```
+
+**如果是自动模式：**
+
+```
+╔══════════════════════════════════════════╗
+║  自动推进 → 讨论 PHASE 1                ║
+╚══════════════════════════════════════════╝
+```
+
+退出 skill 并调用 SlashCommand("/specops:discuss-phase 1 --auto")
+
+**如果是交互模式：**
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ 下一步
+
+**Phase 1: [阶段名称]** — [ROADMAP.md 中的目标]
+
+/specops:discuss-phase 1 — 收集上下文并澄清方案
+
+<sub>/clear 先清理 → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- /specops:plan-phase 1 — 跳过讨论，直接规划
+
+───────────────────────────────────────────────────────────────
+```
+
+</process>
+
+<output>
+
+- `.planning/PROJECT.md`
+- `.planning/config.json`
+- `.planning/research/`（如果选择了研究）
+  - `STACK.md`
+  - `FEATURES.md`
+  - `ARCHITECTURE.md`
+  - `PITFALLS.md`
+  - `SUMMARY.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
+
+</output>
+
+<success_criteria>
+
+- [ ] .planning/ 目录已创建
+- [ ] Git 仓库已初始化
+- [ ] 棕地检测已完成
+- [ ] 深度提问已完成（跟随线索，不急于求成）
+- [ ] PROJECT.md 捕获完整上下文 → **已提交**
+- [ ] config.json 包含工作流模式、深度、并行化设置 → **已提交**
+- [ ] 研究已完成（如果选择）——4 个并行 Agent 已生成 → **已提交**
+- [ ] 需求已收集（来自研究或对话）
+- [ ] 用户确定了每个类别的范围（v1/v2/范围外）
+- [ ] REQUIREMENTS.md 已创建并包含 REQ-ID → **已提交**
+- [ ] specops-roadmapper 已生成并附带上下文
+- [ ] 路线图文件立即写入（不是草稿）
+- [ ] 用户反馈已纳入（如有）
+- [ ] ROADMAP.md 已创建，包含阶段、需求映射、成功标准
+- [ ] STATE.md 已初始化
+- [ ] REQUIREMENTS.md 可追溯性已更新
+- [ ] 用户知道下一步是 `/specops:discuss-phase 1`
+
+**原子提交：** 每个阶段立即提交其产物。如果上下文丢失，产物仍然保留。
+
+</success_criteria>