specops 0.2.5 → 0.3.2

package/.opencode/workflows/discuss-phase.md

@@ -0,0 +1,542 @@
+<purpose>
+提取下游 Agent 所需的实现决策。分析阶段以识别灰色地带，让用户选择要讨论的内容，然后深入探讨每个选定的领域直到满意为止。
+
+你是一个思考伙伴，而不是面试官。用户是愿景制定者——你是构建者。你的工作是捕获将指导研究和规划的决策，而不是自己去弄清楚实现方式。
+</purpose>
+
+<downstream_awareness>
+**CONTEXT.md 供以下角色使用：**
+
+1. **specops-phase-researcher** — 读取 CONTEXT.md 以了解要研究什么
+   - "用户想要卡片式布局" → 研究员调查卡片组件模式
+   - "决定使用无限滚动" → 研究员研究虚拟化库
+
+2. **specops-planner** — 读取 CONTEXT.md 以了解哪些决策已锁定
+   - "移动端下拉刷新" → 规划器将其纳入任务规格
+   - "Claude 自行决定：加载骨架屏" → 规划器可以决定实现方式
+
+**你的职责：** 清晰地捕获决策，使下游 Agent 无需再次询问用户即可执行。
+
+**不是你的职责：** 弄清楚如何实现。研究和规划会利用你捕获的决策来完成这些工作。
+</downstream_awareness>
+
+<philosophy>
+**用户 = 创始人/愿景制定者。Claude = 构建者。**
+
+用户了解：
+- 他们想象中的工作方式
+- 它应该看起来/感觉如何
+- 什么是必要的 vs 锦上添花的
+- 他们脑中的具体行为或参考
+
+用户不了解（也不应该被问到）：
+- 代码库模式（研究员读代码）
+- 技术风险（研究员识别这些）
+- 实现方式（规划器来解决）
+- 成功指标（从工作中推断）
+
+询问愿景和实现选择。为下游 Agent 捕获决策。
+</philosophy>
+
+<scope_guardrail>
+**关键：不允许范围蔓延。**
+
+阶段边界来自 ROADMAP.md 且是固定的。讨论是澄清如何实现已确定范围内的内容，而不是是否添加新功能。
+
+**允许（澄清模糊性）：**
+- "帖子应该如何展示？"（布局、密度、显示信息）
+- "空状态时显示什么？"（功能范围内）
+- "下拉刷新还是手动？"（行为选择）
+
+**不允许（范围蔓延）：**
+- "我们是否也应该添加评论？"（新功能）
+- "搜索/过滤怎么样？"（新功能）
+- "也许加入收藏功能？"（新功能）
+
+**判断标准：** 这是在澄清如何实现阶段中已有的内容，还是在添加一个可以成为独立阶段的新功能？
+
+**当用户建议范围蔓延时：**
+```
+"[功能 X] 是一个新功能——应该作为独立阶段。
+要我记录到路线图待办中吗？
+
+现在让我们专注于 [当前阶段领域]。"
+```
+
+将想法记录在"延迟想法"部分。不要丢失它，也不要执行它。
+</scope_guardrail>
+
+<gray_area_identification>
+灰色地带是**用户关心的实现决策**——可以有多种方式且会改变结果的事情。
+
+**如何识别灰色地带：**
+
+1. **阅读阶段目标**（来自 ROADMAP.md）
+2. **理解领域** — 正在构建什么类型的东西？
+   - 用户能看到的 → 视觉呈现、交互、状态很重要
+   - 用户能调用的 → 接口契约、响应、错误很重要
+   - 用户能运行的 → 调用方式、输出、行为模式很重要
+   - 用户能阅读的 → 结构、语气、深度、流程很重要
+   - 需要组织的 → 标准、分组、异常处理很重要
+3. **生成阶段特定的灰色地带** — 不是通用类别，而是此阶段的具体决策
+
+**不要使用通用类别标签**（UI、UX、行为）。生成具体的灰色地带：
+
+```
+阶段："用户认证"
+→ 会话处理、错误响应、多设备策略、恢复流程
+
+阶段："整理照片库"
+→ 分组标准、重复处理、命名规范、文件夹结构
+
+阶段："数据库备份 CLI"
+→ 输出格式、标志设计、进度报告、错误恢复
+
+阶段："API 文档"
+→ 结构/导航、代码示例深度、版本管理方式、交互元素
+```
+
+**核心问题：** 哪些决策会改变结果，需要用户来权衡？
+
+**Claude 处理这些（不要问）：**
+- 技术实现细节
+- 架构模式
+- 性能优化
+- 范围（路线图定义了这些）
+</gray_area_identification>
+
+<process>
+
+**快速路径可用：** 如果你已经有 PRD 或验收标准文档，使用 `/specops:plan-phase {phase} --prd path/to/prd.md` 跳过此讨论直接进入规划。
+
+<step name="initialize" priority="first">
+从参数中获取阶段编号（必需）。
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "${PHASE}")
+```
+
+解析 JSON 获取：`commit_docs`、`phase_found`、`phase_dir`、`phase_number`、`phase_name`、`phase_slug`、`padded_phase`、`has_research`、`has_context`、`has_plans`、`has_verification`、`plan_count`、`roadmap_exists`、`planning_exists`。
+
+**如果 `phase_found` 为 false：**
+```
+阶段 [X] 在路线图中未找到。
+
+使用 /specops:progress 查看可用阶段。
+```
+退出工作流。
+
+**如果 `phase_found` 为 true：** 继续到 check_existing。
+</step>
+
+<step name="check_existing">
+使用 init 返回的 `has_context` 检查 CONTEXT.md 是否已存在。
+
+```bash
+ls ${phase_dir}/*-CONTEXT.md 2>/dev/null
+```
+
+**如果已存在：**
+使用 AskUserQuestion：
+- header: "Context"
+- question: "阶段 [X] 已有上下文。你想怎么做？"
+- options:
+  - "更新它" — 审查并修改现有上下文
+  - "查看它" — 显示当前内容
+  - "跳过" — 使用现有上下文
+
+如果"更新"：加载现有内容，继续到 analyze_phase
+如果"查看"：显示 CONTEXT.md，然后提供更新/跳过选项
+如果"跳过"：退出工作流
+
+**如果不存在：**
+
+检查 init 返回的 `has_plans` 和 `plan_count`。**如果 `has_plans` 为 true：**
+
+使用 AskUserQuestion：
+- header: "计划已存在"
+- question: "阶段 [X] 已有 {plan_count} 个计划，但没有用户上下文。你在这里做的决策不会影响现有计划，除非你重新规划。"
+- options:
+  - "继续并之后重新规划" — 捕获上下文，然后运行 /specops:plan-phase {X} 重新规划
+  - "查看现有计划" — 在决定前查看计划
+  - "取消" — 跳过 discuss-phase
+
+如果"继续并之后重新规划"：继续到 analyze_phase。
+如果"查看现有计划"：显示计划文件，然后提供"继续"/"取消"选项。
+如果"取消"：退出工作流。
+
+**如果 `has_plans` 为 false：** 继续到 analyze_phase。
+</step>
+
+<step name="analyze_phase">
+分析阶段以识别值得讨论的灰色地带。
+
+**阅读 ROADMAP.md 中的阶段描述并确定：**
+
+1. **领域边界** — 此阶段交付什么功能？清晰陈述。
+
+2. **按类别划分的灰色地带** — 对于每个相关类别（UI、UX、行为、空状态、内容），识别 1-2 个会改变实现的具体模糊点。
+
+3. **跳过评估** — 如果没有有意义的灰色地带（纯基础设施、明确的实现），该阶段可能不需要讨论。
+
+**在内部输出你的分析，然后呈现给用户。**
+
+"帖子信息流"阶段的分析示例：
+```
+领域：展示关注用户的帖子
+灰色地带：
+- UI：布局风格（卡片 vs 时间线 vs 网格）
+- UI：信息密度（完整帖子 vs 预览）
+- 行为：加载模式（无限滚动 vs 分页）
+- 空状态：没有帖子时显示什么
+- 内容：显示哪些元数据（时间、作者、反应数）
+```
+</step>
+
+<step name="present_gray_areas">
+向用户呈现领域边界和灰色地带。
+
+**首先，陈述边界：**
+```
+阶段 [X]：[名称]
+领域：[此阶段交付什么——来自你的分析]
+
+我们将澄清如何实现这些内容。
+（新功能属于其他阶段。）
+```
+
+**然后使用 AskUserQuestion（multiSelect: true）：**
+- header: "讨论"
+- question: "你想讨论 [阶段名称] 的哪些方面？"
+- options：生成 3-4 个阶段特定的灰色地带，每个包含：
+  - "[具体领域]"（标签）— 具体的，不是通用的
+  - [此领域涵盖的 1-2 个问题]（描述）
+  - **高亮推荐选项并简要说明原因**
+
+**不要包含"跳过"或"你来决定"选项。** 用户运行此命令就是为了讨论——给他们真正的选择。
+
+**按领域的示例：**
+
+"帖子信息流"（视觉功能）：
+```
+☐ 布局风格 — 卡片 vs 列表 vs 时间线？信息密度？
+☐ 加载行为 — 无限滚动还是分页？下拉刷新？
+☐ 内容排序 — 时间顺序、算法推荐还是用户选择？
+☐ 帖子元数据 — 每个帖子显示什么信息？时间戳、反应、作者？
+```
+
+"数据库备份 CLI"（命令行工具）：
+```
+☐ 输出格式 — JSON、表格还是纯文本？详细程度级别？
+☐ 标志设计 — 短标志、长标志还是两者都有？必需 vs 可选？
+☐ 进度报告 — 静默、进度条还是详细日志？
+☐ 错误恢复 — 快速失败、重试还是提示操作？
+```
+
+"整理照片库"（组织任务）：
+```
+☐ 分组标准 — 按日期、位置、人脸还是事件？
+☐ 重复处理 — 保留最佳、全部保留还是每次提示？
+☐ 命名规范 — 原始名称、日期还是描述性名称？
+☐ 文件夹结构 — 扁平、按年嵌套还是按类别？
+```
+
+继续到 discuss_areas 处理选定的领域。
+</step>
+
+<step name="discuss_areas">
+对每个选定的领域进行聚焦讨论循环。
+
+**理念：4 个问题，然后检查。**
+
+每个领域问 4 个问题后再提供继续或转到下一个的选项。每个回答通常会引出下一个问题。
+
+**对于每个领域：**
+
+1. **宣布领域：**
+   ```
+   让我们谈谈 [领域]。
+   ```
+
+2. **使用 AskUserQuestion 问 4 个问题：**
+   - header: "[领域]"（最多 12 个字符——必要时缩写）
+   - question：此领域的具体决策
+   - options：2-3 个具体选项（AskUserQuestion 自动添加"其他"），推荐选项高亮并简要说明原因
+   - 合理时包含"你来决定"选项——记录 Claude 自行决定的内容
+
+3. **4 个问题后检查：**
+   - header: "[领域]"（最多 12 个字符）
+   - question: "关于 [领域] 还有更多问题，还是转到下一个？"
+   - options: "更多问题" / "下一个领域"
+
+   如果"更多问题" → 再问 4 个，然后再次检查
+   如果"下一个领域" → 进入下一个选定的领域
+   如果"其他"（自由文本）→ 解读意图：继续类短语（"继续聊"、"继续"、"是的"、"更多"）映射到"更多问题"；推进类短语（"完成"、"下一个"、"跳过"）映射到"下一个领域"。如果模糊，询问："继续讨论 [领域] 的更多问题，还是转到下一个领域？"
+
+4. **所有初始选定的领域完成后：**
+   - 总结讨论中捕获的内容
+   - AskUserQuestion：
+     - header: "完成"
+     - question: "我们已经讨论了 [列出领域]。还有哪些灰色地带不清楚？"
+     - options: "探索更多灰色地带" / "准备好生成上下文了"
+   - 如果"探索更多灰色地带"：
+     - 根据已学到的内容识别 2-4 个额外的灰色地带
+     - 返回 present_gray_areas 逻辑处理这些新领域
+     - 循环：讨论新领域，然后再次提示
+   - 如果"准备好生成上下文了"：进入 write_context
+
+**问题设计：**
+- 选项应该是具体的，不是抽象的（"卡片"而不是"选项 A"）
+- 每个回答应该为下一个问题提供信息
+- 如果用户选择"其他"，接收他们的输入，复述确认
+
+**范围蔓延处理：**
+如果用户提到阶段领域之外的内容：
+```
+"[功能] 听起来像是一个新功能——应该属于独立阶段。
+我会记录为延迟想法。
+
+回到 [当前领域]：[返回当前问题]"
+```
+
+在内部跟踪延迟想法。
+</step>
+
+<step name="write_context">
+创建 CONTEXT.md 捕获所做的决策。
+
+**查找或创建阶段目录：**
+
+使用 init 返回的值：`phase_dir`、`phase_slug`、`padded_phase`。
+
+如果 `phase_dir` 为 null（阶段存在于路线图中但没有目录）：
+```bash
+mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+```
+
+**文件位置：** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+**按讨论内容组织内容：**
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[清晰陈述此阶段交付什么——范围锚点]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [讨论的类别 1]
+- [捕获的决策或偏好]
+- [如适用的另一个决策]
+
+### [讨论的类别 2]
+- [捕获的决策或偏好]
+
+### Claude's Discretion
+[用户说"你来决定"的领域——注明 Claude 在此有灵活性]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[讨论中的任何特定参考、示例或"我想要像 X 那样"的时刻]
+
+[如果没有："没有特定要求——对标准方法持开放态度"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[讨论中出现但属于其他阶段的想法。不要丢失它们。]
+
+[如果没有："无——讨论保持在阶段范围内"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date]*
+```
+
+写入文件。
+</step>
+
+<step name="confirm_creation">
+展示摘要和后续步骤：
+
+```
+已创建：.planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
+
+## 捕获的决策
+
+### [类别]
+- [关键决策]
+
+### [类别]
+- [关键决策]
+
+[如果有延迟想法：]
+## 记录待后续处理
+- [延迟想法] — 未来阶段
+
+---
+
+## ▶ 下一步
+
+**Phase ${PHASE}: [Name]** — [ROADMAP.md 中的目标]
+
+`/specops:plan-phase ${PHASE}`
+
+<sub>`/clear` 先清理 → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- `/specops:plan-phase ${PHASE} --skip-research` — 不做研究直接规划
+- 在继续之前审查/编辑 CONTEXT.md
+
+---
+```
+</step>
+
+<step name="git_commit">
+提交阶段上下文（内部使用 init 返回的 `commit_docs`）：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+确认："已提交：docs(${padded_phase}): capture phase context"
+</step>
+
+<step name="update_state">
+更新 STATE.md 的会话信息：
+
+```bash
+node .opencode/bin/specops-tools.cjs state record-session \
+  --stopped-at "Phase ${PHASE} context gathered" \
+  --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+提交 STATE.md：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md
+```
+</step>
+
+<step name="auto_advance">
+检查自动推进触发条件：
+
+1. 从 $ARGUMENTS 解析 `--auto` 标志
+2. 从配置读取 `workflow.auto_advance`：
+   ```bash
+   AUTO_CFG=$(node .opencode/bin/specops-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+   ```
+
+**如果存在 `--auto` 标志且 `AUTO_CFG` 不为 true：** 将自动推进持久化到配置（处理不通过 new-project 直接使用 `--auto` 的情况）：
+```bash
+node .opencode/bin/specops-tools.cjs config-set workflow.auto_advance true
+```
+
+**如果存在 `--auto` 标志或 `AUTO_CFG` 为 true：**
+
+显示横幅：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 自动推进到规划
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+上下文已捕获。正在生成 plan-phase...
+```
+
+将 plan-phase 作为 Task 生成，使用直接工作流文件引用（不要使用 Skill 工具——Skill 在 Task 子 Agent 中无法解析）：
+```
+Task(
+  prompt="
+    <objective>
+    你是 plan-phase 编排器。为 Phase ${PHASE}: ${PHASE_NAME} 创建可执行计划，然后自动推进到执行。
+    </objective>
+
+    <execution_context>
+    @.opencode/workflows/plan-phase.md
+    @.opencode/references/ui-brand.md
+    @.opencode/references/model-profile-resolution.md
+    </execution_context>
+
+    <arguments>
+    PHASE=${PHASE}
+    ARGUMENTS='${PHASE} --auto'
+    </arguments>
+
+    <instructions>
+    1. 从 execution_context 读取 plan-phase.md 获取完整工作流
+    2. 遵循所有步骤：initialize、validate、load context、research、plan、verify、auto-advance
+    3. 生成 Agent（specops-phase-researcher、specops-planner、specops-plan-checker）时，使用 Task 并指定 subagent_type 和 model
+    4. 对于步骤 14（自动推进到执行）：将 execute-phase 作为 Task 生成，使用直接文件引用——告诉它读取 execute-phase.md。包含 @file 引用 execute-phase.md、checkpoints.md、tdd.md、model-profile-resolution.md。传递 --no-transition 标志使 execute-phase 返回结果而不是继续链式调用。
+    5. 不要使用 Skill 工具或 /specops: 命令。直接读取工作流 .md 文件。
+    6. 返回：PHASE COMPLETE（完整流水线成功）、PLANNING COMPLETE（规划完成但执行失败/跳过）、PLANNING INCONCLUSIVE 或 GAPS FOUND
+    </instructions>
+  ",
+  subagent_type="general-purpose",
+  description="Plan Phase ${PHASE}"
+)
+```
+
+**处理 plan-phase 返回：**
+- **PHASE COMPLETE** → 完整链成功。显示：
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   SpecOps ► PHASE ${PHASE} 完成
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  自动推进流水线完成：discuss → plan → execute
+
+  下一步：/specops:discuss-phase ${NEXT_PHASE} --auto
+  <sub>先 /clear → 全新上下文窗口</sub>
+  ```
+- **PLANNING COMPLETE** → 规划完成，执行未完成：
+  ```
+  自动推进部分完成：规划完成，执行未完成。
+  继续：/specops:execute-phase ${PHASE}
+  ```
+- **PLANNING INCONCLUSIVE / CHECKPOINT** → 停止链：
+  ```
+  自动推进已停止：规划需要输入。
+  继续：/specops:plan-phase ${PHASE}
+  ```
+- **GAPS FOUND** → 停止链：
+  ```
+  自动推进已停止：执行过程中发现缺口。
+  继续：/specops:plan-phase ${PHASE} --gaps
+  ```
+
+**如果既没有 `--auto` 也没有配置启用：**
+路由到 `confirm_creation` 步骤（现有行为——显示手动后续步骤）。
+</step>
+
+</process>
+
+<success_criteria>
+- 阶段已根据路线图验证
+- 通过智能分析识别灰色地带（不是通用问题）
+- 用户选择了要讨论的领域
+- 每个选定的领域探讨到用户满意为止
+- 范围蔓延被重定向到延迟想法
+- CONTEXT.md 捕获了实际决策，而不是模糊的愿景
+- 延迟想法为未来阶段保留
+- STATE.md 已更新会话信息
+- 用户知道后续步骤
+</success_criteria>