specops 0.2.4 → 0.3.0

package/.opencode/references/tdd.md

@@ -0,0 +1,263 @@
+<overview>
+TDD 关注的是设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现之前思考行为，从而产生更清晰的接口和更可测试的代码。
+
+**原则：** 如果你能在编写 `fn` 之前将行为描述为 `expect(fn(input)).toBe(output)`，TDD 就能改善结果。
+
+**关键洞察：** TDD 工作本质上比标准任务更重，它需要 2-3 个执行周期（RED -> GREEN -> REFACTOR），每个周期都涉及文件读取、测试运行和潜在的调试。TDD 特性会获得专门的计划，以确保整个周期中有充足的上下文。
+</overview>
+
+<when_to_use_tdd>
+## 何时使用 TDD
+
+**TDD 候选（创建 TDD 计划）：**
+- 有明确输入/输出的业务逻辑
+- 有请求/响应契约的 API 端点
+- 数据转换、解析、格式化
+- 验证规则和约束
+- 有可测试行为的算法
+- 状态机和工作流
+- 有明确规格的工具函数
+
+**跳过 TDD（使用带 `type="auto"` 任务的标准计划）：**
+- UI 布局、样式、视觉组件
+- 配置变更
+- 连接现有组件的胶水代码
+- 一次性脚本和迁移
+- 无业务逻辑的简单 CRUD
+- 探索性原型
+
+**判断标准：** 你能在编写 `fn` 之前写出 `expect(fn(input)).toBe(output)` 吗？
+-> 能：创建 TDD 计划
+-> 不能：使用标准计划，需要时再补测试
+</when_to_use_tdd>
+
+<tdd_plan_structure>
+## TDD 计划结构
+
+每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 周期实现**一个特性**。
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: tdd
+---
+
+<objective>
+[什么特性以及为什么]
+Purpose: [TDD 对此特性的设计收益]
+Output: [可工作的、经过测试的特性]
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@relevant/source/files.ts
+</context>
+
+<feature>
+  <name>[特性名称]</name>
+  <files>[源文件, 测试文件]</files>
+  <behavior>
+    [以可测试的术语描述预期行为]
+    Cases: input -> expected output
+  </behavior>
+  <implementation>[测试通过后如何实现]</implementation>
+</feature>
+
+<verification>
+[证明特性工作的测试命令]
+</verification>
+
+<success_criteria>
+- 编写并提交了失败的测试
+- 实现通过了测试
+- 重构完成（如需要）
+- 所有 2-3 个提交都存在
+</success_criteria>
+
+<output>
+完成后，创建 SUMMARY.md 包含：
+- RED：编写了什么测试，为什么失败
+- GREEN：什么实现使其通过
+- REFACTOR：做了什么清理（如有）
+- Commits：产生的提交列表
+</output>
+```
+
+**每个 TDD 计划一个特性。** 如果特性简单到可以批量处理，那就简单到可以跳过 TDD，使用标准计划并在之后添加测试。
+</tdd_plan_structure>
+
+<execution_flow>
+## 红-绿-重构循环
+
+**RED - 编写失败的测试：**
+1. 按项目约定创建测试文件
+2. 编写描述预期行为的测试（来自 `<behavior>` 元素）
+3. 运行测试 - 必须失败
+4. 如果测试通过：特性已存在或测试有误。需要调查。
+5. 提交：`test({phase}-{plan}): add failing test for [feature]`
+
+**GREEN - 实现使其通过：**
+1. 编写最少的代码使测试通过
+2. 不要耍聪明，不要优化 - 只要让它工作
+3. 运行测试 - 必须通过
+4. 提交：`feat({phase}-{plan}): implement [feature]`
+
+**REFACTOR（如需要）：**
+1. 如果有明显的改进空间，清理实现
+2. 运行测试 - 必须仍然通过
+3. 仅在有变更时提交：`refactor({phase}-{plan}): clean up [feature]`
+
+**结果：** 每个 TDD 计划产生 2-3 个原子提交。
+</execution_flow>
+
+<test_quality>
+## 好测试 vs 坏测试
+
+**测试行为，而非实现：**
+- 好：「返回格式化的日期字符串」
+- 坏：「用正确的参数调用 formatDate 辅助函数」
+- 测试应该能经受住重构
+
+**每个测试一个概念：**
+- 好：分别测试有效输入、空输入、格式错误的输入
+- 坏：单个测试用多个断言检查所有边界情况
+
+**描述性命名：**
+- 好：「should reject empty email」、「returns null for invalid ID」
+- 坏：「test1」、「handles error」、「works correctly」
+
+**不涉及实现细节：**
+- 好：测试公共 API、可观察的行为
+- 坏：mock 内部实现、测试私有方法、断言内部状态
+</test_quality>
+
+<framework_setup>
+## 测试框架设置（如果不存在）
+
+执行 TDD 计划但没有配置测试框架时，在 RED 阶段进行设置：
+
+**1. 检测项目类型：**
+```bash
+# JavaScript/TypeScript
+if [ -f package.json ]; then echo "node"; fi
+
+# Python
+if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
+
+# Go
+if [ -f go.mod ]; then echo "go"; fi
+
+# Rust
+if [ -f Cargo.toml ]; then echo "rust"; fi
+```
+
+**2. 安装最小框架：**
+| 项目 | 框架 | 安装命令 |
+|------|------|----------|
+| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
+| Node.js (Vite) | Vitest | `npm install -D vitest` |
+| Python | pytest | `pip install pytest` |
+| Go | testing | 内置 |
+| Rust | cargo test | 内置 |
+
+**3. 按需创建配置：**
+- Jest：带 ts-jest preset 的 `jest.config.js`
+- Vitest：带 test globals 的 `vitest.config.ts`
+- pytest：`pytest.ini` 或 `pyproject.toml` 中的配置段
+
+**4. 验证设置：**
+```bash
+# 运行空测试套件 - 应该以 0 个测试通过
+npm test  # Node
+pytest    # Python
+go test ./...  # Go
+cargo test    # Rust
+```
+
+**5. 创建第一个测试文件：**
+按项目约定确定测试位置：
+- `*.test.ts` / `*.spec.ts` 放在源文件旁边
+- `__tests__/` 目录
+- 根目录的 `tests/` 目录
+
+框架设置是一次性成本，包含在第一个 TDD 计划的 RED 阶段中。
+</framework_setup>
+
+<error_handling>
+## 错误处理
+
+**RED 阶段测试没有失败：**
+- 特性可能已存在 - 需要调查
+- 测试可能有误（没有测试你以为在测试的东西）
+- 在继续之前修复
+
+**GREEN 阶段测试没有通过：**
+- 调试实现
+- 不要跳到重构
+- 持续迭代直到变绿
+
+**REFACTOR 阶段测试失败：**
+- 撤销重构
+- 提交为时过早
+- 用更小的步骤重构
+
+**不相关的测试中断：**
+- 停下来调查
+- 可能表明耦合问题
+- 在继续之前修复
+</error_handling>
+
+<commit_pattern>
+## TDD 计划的提交模式
+
+TDD 计划产生 2-3 个原子提交（每个阶段一个）：
+
+```
+test(08-02): add failing test for email validation
+
+- Tests valid email formats accepted
+- Tests invalid formats rejected
+- Tests empty input handling
+
+feat(08-02): implement email validation
+
+- Regex pattern matches RFC 5322
+- Returns boolean for validity
+- Handles edge cases (empty, null)
+
+refactor(08-02): extract regex to constant (optional)
+
+- Moved pattern to EMAIL_REGEX constant
+- No behavior changes
+- Tests still pass
+```
+
+**与标准计划的对比：**
+- 标准计划：每个任务 1 个提交，每个计划 2-4 个提交
+- TDD 计划：单个特性 2-3 个提交
+
+两者遵循相同格式：`{type}({phase}-{plan}): {description}`
+
+**收益：**
+- 每个提交可独立回滚
+- Git bisect 在提交级别工作
+- 清晰的历史展示 TDD 纪律
+- 与整体提交策略一致
+</commit_pattern>
+
+<context_budget>
+## 上下文预算
+
+TDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。
+
+为什么更低：
+- RED 阶段：编写测试、运行测试、可能需要调试为什么没有失败
+- GREEN 阶段：实现、运行测试、可能需要对失败进行迭代
+- REFACTOR 阶段：修改代码、运行测试、验证无回归
+
+每个阶段都涉及读取文件、运行命令、分析输出。这种来回交互本质上比线性任务执行更重。
+
+单一特性聚焦确保整个周期的完整质量。
+</context_budget>

package/.opencode/references/ui-brand.md

@@ -0,0 +1,160 @@
+<ui_patterns>
+
+面向用户的 SpecOps 输出的视觉模式。编排器通过 @ 引用此文件。
+
+## 阶段横幅
+
+用于主要工作流转换。
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► {STAGE NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**阶段名称（大写）：**
+- `QUESTIONING`
+- `RESEARCHING`
+- `DEFINING REQUIREMENTS`
+- `CREATING ROADMAP`
+- `PLANNING PHASE {N}`
+- `EXECUTING WAVE {N}`
+- `VERIFYING`
+- `PHASE {N} COMPLETE ✓`
+- `MILESTONE COMPLETE 🎉`
+
+---
+
+## 检查点框
+
+需要用户操作。62 字符宽度。
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Content}
+
+──────────────────────────────────────────────────────────────
+→ {ACTION PROMPT}
+──────────────────────────────────────────────────────────────
+```
+
+**类型：**
+- `CHECKPOINT: Verification Required` -> `-> Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` -> `-> Select: option-a / option-b`
+- `CHECKPOINT: Action Required` -> `-> Type "done" when complete`
+
+---
+
+## 状态符号
+
+```
+✓  完成 / 通过 / 已验证
+✗  失败 / 缺失 / 阻塞
+◆  进行中
+○  待处理
+⚡ 自动批准
+⚠  警告
+🎉 里程碑完成（仅在横幅中）
+```
+
+---
+
+## 进度显示
+
+**阶段/里程碑级别：**
+```
+Progress: ████████░░ 80%
+```
+
+**任务级别：**
+```
+Tasks: 2/4 complete
+```
+
+**计划级别：**
+```
+Plans: 3/5 complete
+```
+
+---
+
+## 生成指示器
+
+```
+◆ Spawning researcher...
+
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+
+✓ Researcher complete: STACK.md written
+```
+
+---
+
+## 下一步区块
+
+始终在主要完成后显示。
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{Identifier}: {Name}** — {one-line description}
+
+`{copy-paste command}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/specops:alternative-1` — description
+- `/specops:alternative-2` — description
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## 错误框
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## 表格
+
+```
+| Phase | Status | Plans | Progress |
+|-------|--------|-------|----------|
+| 1     | ✓      | 3/3   | 100%     |
+| 2     | ◆      | 1/4   | 25%      |
+| 3     | ○      | 0/2   | 0%       |
+```
+
+---
+
+## 反模式
+
+- 框/横幅宽度不一致
+- 混用横幅样式（`===`、`---`、`***`）
+- 横幅中遗漏 `SpecOps ►` 前缀
+- 随意使用 emoji（`🚀`、`✨`、`💫`）
+- 完成后缺少 Next Up 区块
+
+</ui_patterns>