specops 0.2.4 → 0.3.0

package/.opencode/references/continuation-format.md

@@ -0,0 +1,249 @@
+# 延续格式
+
+完成命令或工作流后呈现下一步的标准格式。
+
+## 核心结构
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## 格式规则
+
+1. **始终展示它是什么** - 名称 + 描述，永远不要只有命令路径
+2. **从源头拉取上下文** - ROADMAP.md 用于阶段，PLAN.md `<objective>` 用于计划
+3. **命令用行内代码** - 反引号，易于复制粘贴，渲染为可点击链接
+4. **`/clear` 说明** - 始终包含，保持简洁但解释原因
+5. **"Also available" 而非 "Other options"** - 听起来更像应用
+6. **视觉分隔符** - 上下用 `---` 使其突出
+
+## 变体
+
+### 执行下一个计划
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/specops:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/specops:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### 执行阶段中的最后一个计划
+
+添加说明这是最后一个计划以及之后会发生什么：
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/specops:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### 规划一个阶段
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/specops:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/specops:discuss-phase 2` — gather context first
+- `/specops:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### 阶段完成，准备下一个
+
+在下一步操作前显示完成状态：
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/specops:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/specops:discuss-phase 3` — gather context first
+- `/specops:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### 多个同等选项
+
+当没有明确的主要操作时：
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/specops:plan-phase 3`
+
+**To discuss context first:** `/specops:discuss-phase 3`
+
+**To research unknowns:** `/specops:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### 里程碑完成
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/specops:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## 拉取上下文
+
+### 对于阶段（从 ROADMAP.md）：
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+提取：`**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### 对于计划（从 ROADMAP.md）：
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+或从 PLAN.md `<objective>`：
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+提取：`**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## 反模式
+
+### 不要：只有命令（没有上下文）
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/specops:execute-phase 2
+```
+
+用户不知道 02-03 是关于什么的。
+
+### 不要：缺少 /clear 说明
+
+```
+`/specops:plan-phase 3`
+
+Run /clear first.
+```
+
+没有解释为什么。用户可能会跳过。
+
+### 不要：「Other options」措辞
+
+```
+Other options:
+- Review roadmap
+```
+
+听起来像事后想法。用 "Also available:" 代替。
+
+### 不要：命令用围栏代码块
+
+````
+```
+/specops:plan-phase 3
+```
+````
+
+模板内的围栏代码块会造成嵌套歧义。用行内反引号代替。

package/.opencode/references/decimal-phase-calculation.md

@@ -0,0 +1,65 @@
+# 小数阶段计算
+
+计算紧急插入的下一个小数阶段编号。
+
+## 使用 specops-tools
+
+```bash
+# 获取阶段 6 之后的下一个小数阶段
+node .opencode/bin/specops-tools.cjs phase next-decimal 6
+```
+
+输出：
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+已有小数阶段时：
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## 提取值
+
+```bash
+DECIMAL_INFO=$(node .opencode/bin/specops-tools.cjs phase next-decimal "${AFTER_PHASE}")
+DECIMAL_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.next')
+BASE_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.base_phase')
+```
+
+或使用 --raw 标志：
+```bash
+DECIMAL_PHASE=$(node .opencode/bin/specops-tools.cjs phase next-decimal "${AFTER_PHASE}" --raw)
+# 仅返回：06.1
+```
+
+## 示例
+
+| 现有阶段 | 下一个阶段 |
+|----------|-----------|
+| 仅 06 | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3（有间隔） | 06.4 |
+
+## 目录命名
+
+小数阶段目录使用完整的小数编号：
+
+```bash
+SLUG=$(node .opencode/bin/specops-tools.cjs generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+示例：`.planning/phases/06.1-fix-critical-auth-bug/`

package/.opencode/references/git-integration.md

@@ -0,0 +1,248 @@
+<overview>
+SpecOps 框架的 Git 集成。
+</overview>
+
+<core_principle>
+
+**提交成果，而非过程。**
+
+Git 日志应该读起来像已交付内容的变更日志，而非规划活动的日记。
+</core_principle>
+
+<commit_points>
+
+| 事件                    | 提交？ | 原因                                             |
+| ----------------------- | ------ | ------------------------------------------------ |
+| BRIEF + ROADMAP 创建    | 是     | 项目初始化                                       |
+| PLAN.md 创建            | 否     | 中间产物 - 随计划完成一起提交                    |
+| RESEARCH.md 创建        | 否     | 中间产物                                         |
+| DISCOVERY.md 创建       | 否     | 中间产物                                         |
+| **任务完成**            | 是     | 原子工作单元（每个任务 1 个提交）                |
+| **计划完成**            | 是     | 元数据提交（SUMMARY + STATE + ROADMAP）          |
+| 交接创建                | 是     | 保存 WIP 状态                                    |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+如果 NO_GIT：静默运行 `git init`。SpecOps 项目始终有自己的仓库。
+</git_check>
+
+<commit_formats>
+
+<format name="initialization">
+## 项目初始化（brief + roadmap 一起）
+
+```
+docs: initialize [project-name] ([N] phases)
+
+[PROJECT.md 中的一句话描述]
+
+Phases:
+1. [phase-name]: [goal]
+2. [phase-name]: [goal]
+3. [phase-name]: [goal]
+```
+
+提交内容：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+```
+
+</format>
+
+<format name="task-completion">
+## 任务完成（计划执行期间）
+
+每个任务在完成后立即获得自己的提交。
+
+```
+{type}({phase}-{plan}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+```
+
+**提交类型：**
+- `feat` - 新功能/特性
+- `fix` - Bug 修复
+- `test` - 仅测试（TDD RED 阶段）
+- `refactor` - 代码清理（TDD REFACTOR 阶段）
+- `perf` - 性能改进
+- `chore` - 依赖、配置、工具
+
+**示例：**
+
+```bash
+# 标准任务
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08-02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# TDD 任务 - RED 阶段
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07-02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour
+- Tests signature verification
+"
+
+# TDD 任务 - GREEN 阶段
+git add src/utils/jwt.ts
+git commit -m "feat(07-02): implement JWT generation
+
+- Uses jose library for signing
+- Includes user ID and expiry claims
+- Signs with HS256 algorithm
+"
+```
+
+</format>
+
+<format name="plan-completion">
+## 计划完成（所有任务完成后）
+
+所有任务提交后，一个最终的元数据提交记录计划完成。
+
+```
+docs({phase}-{plan}): complete [plan-name] plan
+
+Tasks completed: [N]/[N]
+- [Task 1 name]
+- [Task 2 name]
+- [Task 3 name]
+
+SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
+```
+
+提交内容：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+```
+
+**注意：** 代码文件不包含在内，已在每个任务中提交。
+
+</format>
+
+<format name="handoff">
+## 交接（WIP）
+
+```
+wip: [phase-name] paused at task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+提交内容：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+**旧方式（按计划提交）：**
+```
+a7f2d1 feat(checkout): Stripe payments with webhook verification
+3e9c4b feat(products): catalog with search, filters, and pagination
+8a1b2c feat(auth): JWT with refresh rotation using jose
+5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
+2f4a8d docs: initialize ecommerce-app (5 phases)
+```
+
+**新方式（按任务提交）：**
+```
+# Phase 04 - Checkout
+1a2b3c docs(04-01): complete checkout flow plan
+4d5e6f feat(04-01): add webhook signature verification
+7g8h9i feat(04-01): implement payment session creation
+0j1k2l feat(04-01): create checkout page component
+
+# Phase 03 - Products
+3m4n5o docs(03-02): complete product listing plan
+6p7q8r feat(03-02): add pagination controls
+9s0t1u feat(03-02): implement search and filters
+2v3w4x feat(03-01): create product catalog schema
+
+# Phase 02 - Auth
+5y6z7a docs(02-02): complete token refresh plan
+8b9c0d feat(02-02): implement refresh token rotation
+1e2f3g test(02-02): add failing test for token refresh
+4h5i6j docs(02-01): complete JWT setup plan
+7k8l9m feat(02-01): add JWT generation and validation
+0n1o2p chore(02-01): install jose library
+
+# Phase 01 - Foundation
+3q4r5s docs(01-01): complete scaffold plan
+6t7u8v feat(01-01): configure Tailwind and globals
+9w0x1y feat(01-01): set up Prisma with database
+2z3a4b feat(01-01): create Next.js 15 project
+
+# Initialization
+5c6d7e docs: initialize ecommerce-app (5 phases)
+```
+
+每个计划产生 2-4 个提交（任务 + 元数据）。清晰、细粒度、可 bisect。
+
+</example_log>
+
+<anti_patterns>
+
+**仍然不提交（中间产物）：**
+- PLAN.md 创建（随计划完成一起提交）
+- RESEARCH.md（中间产物）
+- DISCOVERY.md（中间产物）
+- 小的规划调整
+- 「修复路线图中的拼写错误」
+
+**要提交（成果）：**
+- 每个任务完成（feat/fix/test/refactor）
+- 计划完成元数据（docs）
+- 项目初始化（docs）
+
+**关键原则：** 提交可工作的代码和已交付的成果，而非规划过程。
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## 为什么按任务提交？
+
+**AI 的上下文工程：**
+- Git 历史成为未来 Claude 会话的主要上下文来源
+- `git log --grep="{phase}-{plan}"` 显示计划的所有工作
+- `git diff <hash>^..<hash>` 显示每个任务的精确变更
+- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作
+
+**故障恢复：**
+- 任务 1 已提交 ✅，任务 2 失败 ❌
+- 下一个会话中的 Claude：看到任务 1 完成，可以重试任务 2
+- 可以 `git reset --hard` 到最后一个成功的任务
+
+**调试：**
+- `git bisect` 找到精确的失败任务，而非只是失败的计划
+- `git blame` 追溯到特定任务上下文
+- 每个提交可独立回滚
+
+**可观测性：**
+- 独立开发者 + Claude 工作流受益于细粒度归因
+- 原子提交是 git 最佳实践
+- 当消费者是 Claude 而非人类时，「提交噪音」无关紧要
+
+</commit_strategy_rationale>

package/.opencode/references/git-planning-commit.md

@@ -0,0 +1,38 @@
+# Git 规划提交
+
+使用 specops-tools CLI 提交规划产物，它会自动检查 `commit_docs` 配置和 gitignore 状态。
+
+## 通过 CLI 提交
+
+始终使用 `specops-tools.cjs commit` 处理 `.planning/` 文件，它会自动处理 `commit_docs` 和 gitignore 检查：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+```
+
+如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（附带原因）。无需手动条件检查。
+
+## 修改上一次提交
+
+将 `.planning/` 文件变更合并到上一次提交：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "" --files .planning/codebase/*.md --amend
+```
+
+## 提交消息模式
+
+| 命令 | 范围 | 示例 |
+|------|------|------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## 何时跳过
+
+- 配置中 `commit_docs: false`
+- `.planning/` 被 gitignore
+- 没有要提交的变更（用 `git status --porcelain .planning/` 检查）

package/.opencode/references/model-profile-resolution.md

@@ -0,0 +1,34 @@
+# 模型配置解析
+
+在编排开始时解析一次模型配置，然后在所有 Task 调用中使用。
+
+## 解析模式
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+默认值：如果未设置或配置缺失，为 `balanced`。
+
+## 查找表
+
+@.opencode/references/model-profiles.md
+
+在表中查找已解析配置对应的代理。将 model 参数传递给 Task 调用：
+
+```
+Task(
+  prompt="...",
+  subagent_type="specops-planner",
+  model="{resolved_model}"  # "inherit"、"sonnet" 或 "haiku"
+)
+```
+
+**注意：** Opus 级别的代理解析为 `"inherit"`（不是 `"opus"`）。这使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。
+
+## 用法
+
+1. 在编排开始时解析一次
+2. 存储配置值
+3. 生成代理时从表中查找每个代理的模型
+4. 将 model 参数传递给每个 Task 调用（值：`"inherit"`、`"sonnet"`、`"haiku"`）