specops 0.2.4 → 0.3.0

package/.opencode/workflows/list-phase-assumptions.md

@@ -0,0 +1,178 @@
+<purpose>
+在规划之前，展示 Claude 对某个阶段的假设，让用户能够尽早纠正误解。
+
+与 discuss-phase 的关键区别：这是对 Claude 想法的分析，而不是收集用户信息。不产生文件输出——纯粹是对话式的，用于引发讨论。
+</purpose>
+
+<process>
+
+<step name="validate_phase" priority="first">
+阶段编号：$ARGUMENTS（必填）
+
+**如果未提供参数：**
+
+```
+错误：需要提供阶段编号。
+
+用法：/specops:list-phase-assumptions [阶段编号]
+示例：/specops:list-phase-assumptions 3
+```
+
+退出工作流。
+
+**如果提供了参数：**
+验证阶段是否存在于路线图中：
+
+```bash
+cat .planning/ROADMAP.md | grep -i "Phase ${PHASE}"
+```
+
+**如果未找到阶段：**
+
+```
+错误：在路线图中未找到阶段 ${PHASE}。
+
+可用阶段：
+[列出路线图中的阶段]
+```
+
+退出工作流。
+
+**如果找到阶段：**
+从路线图中解析阶段详情：
+
+- 阶段编号
+- 阶段名称
+- 阶段描述/目标
+- 提到的任何范围细节
+
+继续到 analyze_phase。
+</step>
+
+<step name="analyze_phase">
+根据路线图描述和项目上下文，从五个方面识别假设：
+
+**1. 技术方案：**
+Claude 会使用哪些库、框架、模式或工具？
+- "我会使用 X 库，因为……"
+- "我会遵循 Y 模式，因为……"
+- "我会将其构建为 Z，因为……"
+
+**2. 实现顺序：**
+Claude 会先构建什么、其次构建什么、最后构建什么？
+- "我会先从 X 开始，因为它是基础"
+- "然后是 Y，因为它依赖于 X"
+- "最后是 Z，因为……"
+
+**3. 范围边界：**
+在 Claude 的理解中，哪些包含在内、哪些排除在外？
+- "此阶段包含：A、B、C"
+- "此阶段不包含：D、E、F"
+- "边界模糊之处：G 可能属于任一方"
+
+**4. 风险领域：**
+Claude 预期在哪些地方会遇到复杂性或挑战？
+- "棘手的部分是 X，因为……"
+- "潜在问题：Y、Z"
+- "我会注意……"
+
+**5. 依赖关系：**
+Claude 假设哪些东西已经存在或需要就位？
+- "这假设前面阶段已完成 X"
+- "外部依赖：Y、Z"
+- "这将被……消费"
+
+对不确定的地方要坦诚。用置信度标记假设：
+- "比较确定：……"（从路线图中明确可知）
+- "假设：……"（合理推断）
+- "不确定：……"（可能有多种情况）
+</step>
+
+<step name="present_assumptions">
+以清晰、易扫描的格式展示假设：
+
+```
+## 我对阶段 ${PHASE}：${PHASE_NAME} 的假设
+
+### 技术方案
+[列出关于如何实现的假设]
+
+### 实现顺序
+[列出关于排序的假设]
+
+### 范围边界
+**包含在内：** [包含的内容]
+**排除在外：** [排除的内容]
+**模糊地带：** [可能属于任一方的内容]
+
+### 风险领域
+[列出预期的挑战]
+
+### 依赖关系
+**来自前序阶段：** [需要的内容]
+**外部依赖：** [第三方需求]
+**输出给后续阶段：** [后续阶段需要从此阶段获取的内容]
+
+---
+
+**你怎么看？**
+
+这些假设准确吗？请告诉我：
+- 哪些我说对了
+- 哪些我说错了
+- 哪些我遗漏了
+```
+
+等待用户回复。
+</step>
+
+<step name="gather_feedback">
+**如果用户提供了纠正：**
+
+确认纠正内容：
+
+```
+关键纠正：
+- [纠正 1]
+- [纠正 2]
+
+这显著改变了我的理解。[总结新的理解]
+```
+
+**如果用户确认假设：**
+
+```
+假设已验证。
+```
+
+继续到 offer_next。
+</step>
+
+<step name="offer_next">
+展示后续步骤：
+
+```
+接下来做什么？
+1. 讨论上下文（/specops:discuss-phase ${PHASE}）- 让我向你提问以构建全面的上下文
+2. 规划此阶段（/specops:plan-phase ${PHASE}）- 创建详细的执行计划
+3. 重新审视假设 - 我将根据你的纠正重新分析
+4. 暂时到此为止
+```
+
+等待用户选择。
+
+如果选择"讨论上下文"：注意 CONTEXT.md 将纳入此处讨论的任何纠正
+如果选择"规划此阶段"：在已理解假设的基础上继续
+如果选择"重新审视"：返回 analyze_phase 并更新理解
+</step>
+
+</process>
+
+<success_criteria>
+- 阶段编号已根据路线图验证
+- 从五个方面展示了假设：技术方案、实现顺序、范围、风险、依赖
+- 在适当的地方标记了置信度
+- 展示了"你怎么看？"提示
+- 确认了用户反馈
+- 提供了清晰的后续步骤
+</success_criteria>

package/.opencode/workflows/map-codebase.md

@@ -0,0 +1,315 @@
+<purpose>
+编排并行代码库映射 Agent 来分析代码库，并在 .planning/codebase/ 中生成结构化文档。
+
+每个 Agent 拥有全新的上下文，探索特定的焦点领域，并**直接写入文档**。编排器只接收确认信息和行数，然后写入摘要。
+
+输出：.planning/codebase/ 文件夹，包含 7 个关于代码库状态的结构化文档。
+</purpose>
+
+<philosophy>
+**为什么使用专用映射 Agent：**
+- 每个领域拥有全新上下文（无 token 污染）
+- Agent 直接写入文档（无需将上下文传回编排器）
+- 编排器只汇总创建了什么（最小上下文使用）
+- 更快的执行（Agent 同时运行）
+
+**文档质量优先于长度：**
+包含足够的细节以作为参考使用。优先提供实际示例（特别是代码模式）而非任意的简洁。
+
+**始终包含文件路径：**
+文档是 Claude 在规划/执行时的参考材料。始终包含用反引号格式化的实际文件路径：`src/services/user.ts`。
+</philosophy>
+
+<process>
+
+<step name="init_context" priority="first">
+加载代码库映射上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init map-codebase)
+```
+
+从初始化 JSON 中提取：`mapper_model`、`commit_docs`、`codebase_dir`、`existing_maps`、`has_maps`、`codebase_dir_exists`。
+</step>
+
+<step name="check_existing">
+使用初始化上下文中的 `has_maps` 检查 .planning/codebase/ 是否已存在。
+
+如果 `codebase_dir_exists` 为 true：
+```bash
+ls -la .planning/codebase/
+```
+
+**如果已存在：**
+
+```
+.planning/codebase/ 已存在，包含以下文档：
+[列出找到的文件]
+
+接下来做什么？
+1. 刷新 - 删除现有并重新映射代码库
+2. 更新 - 保留现有，仅更新特定文档
+3. 跳过 - 使用现有代码库映射
+```
+
+等待用户回复。
+
+如果选择"刷新"：删除 .planning/codebase/，继续到 create_structure
+如果选择"更新"：询问要更新哪些文档，继续到 spawn_agents（已过滤）
+如果选择"跳过"：退出工作流
+
+**如果不存在：**
+继续到 create_structure。
+</step>
+
+<step name="create_structure">
+创建 .planning/codebase/ 目录：
+
+```bash
+mkdir -p .planning/codebase
+```
+
+**预期输出文件：**
+- STACK.md（来自技术映射器）
+- INTEGRATIONS.md（来自技术映射器）
+- ARCHITECTURE.md（来自架构映射器）
+- STRUCTURE.md（来自架构映射器）
+- CONVENTIONS.md（来自质量映射器）
+- TESTING.md（来自质量映射器）
+- CONCERNS.md（来自关注点映射器）
+
+继续到 spawn_agents。
+</step>
+
+<step name="spawn_agents">
+生成 4 个并行的 specops-codebase-mapper Agent。
+
+使用 Task 工具，设置 `subagent_type="specops-codebase-mapper"`、`model="{mapper_model}"`，并设置 `run_in_background=true` 以并行执行。
+
+**关键：** 使用专用的 `specops-codebase-mapper` Agent，而不是 `Explore`。映射 Agent 直接写入文档。
+
+**Agent 1：技术焦点**
+
+```
+Task(
+  subagent_type="specops-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase tech stack",
+  prompt="Focus: tech
+
+Analyze this codebase for technology stack and external integrations.
+
+Write these documents to .planning/codebase/:
+- STACK.md - Languages, runtime, frameworks, dependencies, configuration
+- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 2：架构焦点**
+
+```
+Task(
+  subagent_type="specops-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase architecture",
+  prompt="Focus: arch
+
+Analyze this codebase architecture and directory structure.
+
+Write these documents to .planning/codebase/:
+- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
+- STRUCTURE.md - Directory layout, key locations, naming conventions
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 3：质量焦点**
+
+```
+Task(
+  subagent_type="specops-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase conventions",
+  prompt="Focus: quality
+
+Analyze this codebase for coding conventions and testing patterns.
+
+Write these documents to .planning/codebase/:
+- CONVENTIONS.md - Code style, naming, patterns, error handling
+- TESTING.md - Framework, structure, mocking, coverage
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 4：关注点焦点**
+
+```
+Task(
+  subagent_type="specops-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase concerns",
+  prompt="Focus: concerns
+
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+Write this document to .planning/codebase/:
+- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
+
+Explore thoroughly. Write document directly using template. Return confirmation only."
+)
+```
+
+继续到 collect_confirmations。
+</step>
+
+<step name="collect_confirmations">
+等待所有 4 个 Agent 完成。
+
+读取每个 Agent 的输出文件以收集确认信息。
+
+**每个 Agent 的预期确认格式：**
+```
+## 映射完成
+
+**焦点：** {focus}
+**已写入文档：**
+- `.planning/codebase/{DOC1}.md`（{N} 行）
+- `.planning/codebase/{DOC2}.md`（{N} 行）
+
+已准备好供编排器汇总。
+```
+
+**你收到的内容：** 仅文件路径和行数。不是文档内容。
+
+如果任何 Agent 失败，记录失败并继续处理成功的文档。
+
+继续到 verify_output。
+</step>
+
+<step name="verify_output">
+验证所有文档是否成功创建：
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+**验证清单：**
+- 所有 7 个文档都存在
+- 没有空文档（每个应超过 20 行）
+
+如果有文档缺失或为空，记录哪些 Agent 可能失败了。
+
+继续到 scan_for_secrets。
+</step>
+
+<step name="scan_for_secrets">
+**关键安全检查：** 在提交前扫描输出文件中意外泄露的密钥。
+
+运行密钥模式检测：
+
+```bash
+# 检查生成文档中的常见 API 密钥模式
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**如果 SECRETS_FOUND=true：**
+
+```
+⚠️  安全警告：在代码库文档中检测到潜在密钥！
+
+在以下位置发现类似 API 密钥或令牌的模式：
+[显示 grep 输出]
+
+如果提交，这将暴露凭据。
+
+**需要操作：**
+1. 审查上面标记的内容
+2. 如果这些是真实密钥，必须在提交前移除
+3. 考虑将敏感文件添加到 Claude Code "Deny" 权限
+
+在提交前暂停。如果标记的内容实际上不敏感，请回复"可以继续"，否则请先编辑文件。
+```
+
+等待用户确认后再继续到 commit_codebase_map。
+
+**如果 SECRETS_FOUND=false：**
+
+继续到 commit_codebase_map。
+</step>
+
+<step name="commit_codebase_map">
+提交代码库映射：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: map existing codebase" --files .planning/codebase/*.md
+```
+
+继续到 offer_next。
+</step>
+
+<step name="offer_next">
+展示完成摘要和后续步骤。
+
+**获取行数：**
+```bash
+wc -l .planning/codebase/*.md
+```
+
+**输出格式：**
+
+```
+代码库映射完成。
+
+已创建 .planning/codebase/：
+- STACK.md（[N] 行）- 技术和依赖
+- ARCHITECTURE.md（[N] 行）- 系统设计和模式
+- STRUCTURE.md（[N] 行）- 目录布局和组织
+- CONVENTIONS.md（[N] 行）- 代码风格和模式
+- TESTING.md（[N] 行）- 测试结构和实践
+- INTEGRATIONS.md（[N] 行）- 外部服务和 API
+- CONCERNS.md（[N] 行）- 技术债务和问题
+
+
+---
+
+## ▶ 下一步
+
+**初始化项目** — 使用代码库上下文进行规划
+
+`/specops:new-project`
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+---
+
+**其他可用操作：**
+- 重新运行映射：`/specops:map-codebase`
+- 查看特定文件：`cat .planning/codebase/STACK.md`
+- 在继续之前编辑任何文档
+
+---
+```
+
+结束工作流。
+</step>
+
+</process>
+
+<success_criteria>
+- .planning/codebase/ 目录已创建
+- 4 个并行 specops-codebase-mapper Agent 已使用 run_in_background=true 生成
+- Agent 直接写入文档（编排器不接收文档内容）
+- 读取 Agent 输出文件以收集确认信息
+- 所有 7 个代码库文档都存在
+- 清晰的完成摘要包含行数
+- 以 SpecOps 风格向用户提供清晰的后续步骤
+</success_criteria>