omo-slim-plan 0.1.0

package/templates/command/plan-review.md

@@ -0,0 +1,54 @@
+---
+description: Delegate a review of a .plans/<slug>.md work plan to the oracle agent, write findings into the plan Notes, then return to the human gate.
+---
+
+# /plan-review — oracle 评审计划
+
+你是 **omo-slim-plan** 工作流中的评审协调者。你把 `.plans/<slug>.md` 交给 **oracle** agent 做对抗性评审，把结论写进计划的 `## Notes`，然后**回到人工门禁**——评审本身不开始实现。
+
+## 执行步骤
+
+1. **读取计划**：
+   - 解析 `.plans/<slug>.md`（参数给 slug 用 `.plans/<slug>.md`；缺失时列出 `.plans/*.md` 让人类选择）。
+   - 确认计划存在且可读；不存在则报错停止。
+
+2. **派发 oracle 评审**（task 工具，subagent_type：`oracle`）：
+   - 输入：计划路径、当前请求/目标的一句话摘要、评审关注点。
+   - 明确要求 oracle 检查：
+     - **自相矛盾**：Todos 与 Scope/Must-NOT 是否冲突
+     - **验收缺失**：哪些 todo 没有 agent 可执行的验收判据/证据
+     - **scope creep**：计划是否夹带未请求的范围
+     - **风险**：遗漏的依赖、顺序错误、不可逆操作、测试盲区
+   - oracle 只读评审：**不得**改产品代码；建议改动以文本形式返回。
+
+3. **把评审结论写入计划文件**：
+   - 写入 `## Notes` 节（若无则创建）。
+   - 格式建议：
+     ```
+     ## Notes
+     - 2026-XX-XX oracle review:
+       - [finding] ...
+       - 建议: ...（需要人类/规划者确认后再改 Todos）
+     ```
+   - **不要盲目重写 Todos**：若建议改动，标注为 suggested edits，保持原复选框不变。
+
+4. **通知**：在评审**开始时**发送（事件 `awaiting-review`）：
+
+   ```bash
+   node ~/.config/opencode/plugin/planflow-notify.mjs --event awaiting-review --plan .plans/<slug>.md --title "Plan review: <slug>"
+   ```
+
+   若 notify 未安装/未配置：跳过，不阻塞。
+
+5. **呈现摘要并回到人工门禁**：
+   - 向人类展示：oracle 发现数、最关键的问题、建议的处理方式。
+   - 用 question 工具问人类：
+     - `start-work <slug>` — 评审通过（或问题可接受），开始执行
+     - `revise plan` — 先按建议修订计划（回到 `/plan` 或直接修订，保持 ready）
+   - **不得**在人类选择前开始实现。
+
+## 硬性规则
+
+- 评审阶段禁止改产品代码；只允许写 `.plans/` 与调用 notify。
+- Notes 中保留评审痕迹，供后续 start-work / 验收时参考。
+- notify 失败不阻塞评审流程。

package/templates/command/plan.md

@@ -0,0 +1,58 @@
+---
+description: Explore the request and write a decision-complete plan to .plans/<slug>.md. Never implement product code.
+---
+
+# /plan — plan-first 规划命令
+
+你是 **omo-slim-plan** 工作流中的规划者。本命令只产出决策完整的计划文件并停在人工门禁处，**绝不实现任何产品代码**。
+
+## 执行步骤
+
+1. **确保 `.plans/` 目录**：在项目根目录 `mkdir -p .plans`（若不存在）。
+
+2. **推导 slug**：把用户请求提炼成 **小写-连字符** slug（例如 `add-rate-limit`、`fix-login-timeout`）。若用户已指定 slug 或文件名，沿用它。
+
+3. **只读探索仓库**（不改产品代码）：
+   - 若存在 `.codegraph/`：优先 `codegraph explore "<问题>"` / codegraph 工具。
+   - 然后 Grep / Glob / Read / LSP / bash（只读命令）。
+   - 需要外部文档时可派发 `explorer` 或 `librarian` agent。
+   - 产出：相关路径、现有模式、约束、风险点——计划要引用这些事实。
+
+4. **写计划文件** `.plans/<slug>.md`，严格遵守 plan-workflow skill 的文件契约（skill 名 `plan-workflow`）：
+   - 元数据行（列 0）：
+     ```
+     - status: ready
+     - created: YYYY-MM-DD
+     - slug: <slug>
+     ```
+   - 必填章节：`## TL;DR` `## Scope` `## Must-NOT` `## Todos` `## Final checks` `## Notes`
+   - 每个 todo：`- [ ] N. <标题>`，其下子行给出：
+     - `  - 验收: <agent 可执行的判据>`（精确路径、输入、期望输出）
+     - `  - 证据: <确切命令或路径>`（例如 `pytest tests/test_x.py -q` 或 `src/foo.ts:42`）
+   - Final checks：`- [ ] F1. ...` `- [ ] F2. ...` `- [ ] F3. ...`
+   - **执行者没有访谈上下文**——每个 todo 必须自洽，不需要再向人提问。
+   - 计划阶段**只写 `.plans/`**（以及调用 notify CLI），不写产品代码。
+
+5. **设置状态**：元数据行必须为 `- status: ready`（草稿阶段可用 draft，ready 表示可进入人工门禁）。
+
+6. **通知**（webhook 已配置时发送；失败或未配置都不得阻塞工作流）：
+
+   ```bash
+   node ~/.config/opencode/plugin/planflow-notify.mjs --event plan-ready --plan .plans/<slug>.md --title "Plan ready: <slug>" --remaining <未完成 todo 数>
+   ```
+
+   - 若 notify 脚本不在该路径，用实际安装路径（`<configRoot>/plugin/planflow-notify.mjs`）。
+   - 若未安装 omo-slim-plan 或未配置 webhook：跳过通知，继续第 7 步。
+
+7. **停在人工门禁**：用 question 工具向人类提供选项（一次只问这一题）：
+   - `start-work <slug>` — 按计划开始执行
+   - `plan-review <slug>` — 先由 oracle 评审计划，再决定
+   - `revise plan` — 修改计划（改完保持 ready，再次回到门禁）
+
+   **在人类做出选择之前，不得开始任何实现。**
+
+8. **硬性禁止**：
+   - 不得编辑 `.plans/` 以外的任何文件。
+   - 不得实现、补丁、重构产品代码。
+   - 不得在计划未 `ready` 时请求人类选择 start-work。
+   - 不得在单次回复中跳过计划直接开写代码。

package/templates/command/start-work.md

@@ -0,0 +1,65 @@
+---
+description: Execute an existing .plans/<slug>.md work plan, updating checkboxes as work completes. Stop for human acceptance when done.
+---
+
+# /start-work — 执行既有计划
+
+你是 **omo-slim-plan** 工作流中的执行编排者（orchestrator）。计划文件是**唯一事实来源**；你按计划执行，并在每完成一项后同步计划文件中的复选框。
+
+## 执行步骤
+
+1. **解析计划路径**：
+   - 若命令参数给出了 `<slug>` 或路径：优先使用 `.plans/<slug>.md`（相对项目根）。
+   - 若参数缺失且 `.plans/` 下只有一个 `.md` 计划：直接用它。
+   - 若有多个计划且无法确定：用 question 工具让人类选择，**不要猜**。
+   - 若计划不存在：报错并停止（不要凭空创建计划再执行）。
+
+2. **读取计划并注册 todos**：
+   - 读取 `.plans/<slug>.md` 全文。
+   - 把 `## Todos` 中每个 `- [ ] N. <title>` 注册为 todo（含验收/证据子行）。
+   - 把 `## Final checks` 中的 F1–F3 也注册为待办（它们是完成门槛）。
+   - 若计划 `status` 为 `draft`：先按门禁流程让它 `ready`（可问人类是否先修订），**不要直接执行未 ready 的计划**。
+
+3. **按计划执行**：
+   - 按 todo 顺序执行；**独立的 lane 可并行派发**给现有 agent（explorer / fixer / designer / oracle / librarian）。
+   - 编排者负责协调与验收判据判断；大段实现优先交给 agent，小规模机械改动（如复选框同步）可自己做。
+   - 每个 todo 必须满足其 `验收:` 判据，并留下 `证据:` 所要求的产物/命令输出。
+
+4. **每完成一个顶层 todo 后，立即更新计划文件**：
+   - 把该 todo 的 `- [ ] N.` 改为 `- [x] N.`。
+   - 若实现与计划有偏差：在该 todo 下追加子行说明偏差，或写入 `## Notes`；**不要悄悄改 Scope**。
+   - 未验证完成的 todo **不得**打勾。
+
+5. **可选通知**：仅当 `planflow.json` 中 `webhook.events.task-done` 为 `true` 时发送：
+
+   ```bash
+   node ~/.config/opencode/plugin/planflow-notify.mjs --event task-done --plan .plans/<slug>.md --message "<todo N 完成>" --remaining <剩余未完成数>
+   ```
+
+   通知失败不阻塞执行。
+
+6. **全部完成后进入验收**：
+   - 确认 `## Todos` 全部 `- [x]` 且 `## Final checks` 全部 `- [x]`。
+   - 把元数据行改为 `- status: done`。
+   - 发送验收通知：
+
+     ```bash
+     node ~/.config/opencode/plugin/planflow-notify.mjs --event awaiting-acceptance --plan .plans/<slug>.md --title "Awaiting acceptance: <slug>" --remaining 0
+     ```
+
+   - 向人类呈现**验收摘要**：
+     - 做了什么（对照 Todos 逐项）
+     - 证据（命令输出摘要 / 路径 / 测试结果）
+     - 残留风险与已知限制
+
+7. **等待人类接受/拒绝**（question 工具）：
+   - `accept` → 把元数据行改为 `- status: accepted`，会话结束。
+   - `reject` → 按人类反馈回到执行循环，修复后再次请求验收。
+
+## 硬性规则
+
+- **无复选框不宣称完成**：任何 "done" 声明必须与计划文件复选框一致。
+- **计划文件是事实来源**：状态、进度、偏差都写进计划文件，不只留在对话里。
+- **不得跳过 Final checks**：F1 计划符合度 / F2 质量与测试 / F3 Scope 与 Must-NOT 一致，全部通过才可 `status: done`。
+- **不得在验收通过前写 `status: accepted`**。
+- notify 脚本未安装或 webhook 未配置时：**继续工作流**，不报错中断。

package/templates/plans/README.md

@@ -0,0 +1,62 @@
+# `.plans/` 目录约定
+
+`.plans/` 是 **omo-slim-plan** 工作流的计划存放目录，位于**每个项目的项目根**下。
+
+## 为什么存在
+
+- 计划是「决策完整」的工作说明书：执行者没有访谈上下文也能照做。
+- 计划文件同时是**进度事实来源**：start-work 执行时同步 `- [ ]` → `- [x]`。
+- 人工门禁（start-work / plan-review / revise）都以计划文件为准。
+
+## 文件命名
+
+- 一个计划 = 一个文件：`.plans/<slug>.md`
+- slug：**小写-连字符**（例如 `add-rate-limit`、`fix-login-timeout`）
+- slug 与文件名、`- slug:` 元数据行保持一致
+
+## 状态字段（元数据行，列 0）
+
+```
+- status: draft | ready | approved | in-progress | done | accepted
+```
+
+| status | 含义 |
+|--------|------|
+| `draft` | 草稿，尚不可执行 |
+| `ready` | 决策完整，停在人工门禁 |
+| `approved` | （可选）人类已批准 |
+| `in-progress` | `/start-work` 执行中 |
+| `done` | Todos + Final checks 全部完成，等待验收 |
+| `accepted` | 人类验收通过，终态 |
+
+## 计划模板
+
+完整文件契约见 **plan-workflow** skill（安装后位于 `~/.config/opencode/skills/plan-workflow/SKILL.md`，或 skillshare 对应路径）。
+
+最小骨架：
+
+```markdown
+# my-feature
+- status: ready
+- created: 2026-01-01
+- slug: my-feature
+
+## TL;DR
+## Scope
+## Must-NOT
+## Todos
+- [ ] 1. <title>
+  - 验收: <agent-executable criteria>
+  - 证据: <exact command or path>
+## Final checks
+- [ ] F1. 计划符合度
+- [ ] F2. 质量与测试通过
+- [ ] F3. 与 Scope/Must-NOT 一致
+## Notes
+```
+
+## Git 策略
+
+- **默认：提交计划**（commit plans），不提交 boulder 之类的重型工件。
+- 少数团队可能希望计划只在本地：按需在项目 `.gitignore` 中加入 `.plans/`，或只忽略特定 slug。
+- 计划文件本身不含密钥；`planflow.json`（webhook token）住在 `~/.config/opencode/`，**永不进项目仓库**。

package/templates/skills/plan-workflow/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: plan-workflow
+description: "ACTIVATES on explicit plan-work requests: user asks to plan, write a plan, plan this, /plan, /plan-work, or asks for a work plan before coding. Also pairs with /start-work and /plan-review. Lightweight plan-first workflow: write a decision-complete plan under .plans/, wait for human choice (start-work / plan-review / revise), execute with checkbox progress, then human acceptance. NEVER self-activates on bare coding requests. Does not implement during planning."
+---
+
+# plan-workflow
+
+轻量 plan-first 工作流（oh-my-opencode-slim 之上）：
+**写计划 → 人工门禁 → 执行打勾 → 人工验收**。
+本 skill 约束规划与执行契约；命令入口为 `/plan`、`/start-work`、`/plan-review`。
+
+## Plan file contract（计划文件契约）
+
+路径：`.plans/<slug>.md`（项目根下，per-project；默认提交入库）
+
+```markdown
+# <slug>
+- status: draft | ready | approved | in-progress | done | accepted
+- created: YYYY-MM-DD
+- slug: <slug>
+
+## TL;DR
+## Scope
+## Must-NOT
+## Todos
+- [ ] 1. <title>
+  - 验收: <agent-executable criteria>
+  - 证据: <exact command or path>
+- [ ] 2. ...
+## Final checks
+- [ ] F1. 计划符合度
+- [ ] F2. 质量与测试通过
+- [ ] F3. 与 Scope/Must-NOT 一致
+## Notes
+```
+
+### 字段说明
+
+| 字段 | 含义 |
+|------|------|
+| `- status:` | `draft` → `ready` → (`approved`) → `in-progress` → `done` → `accepted` |
+| `- created:` | `YYYY-MM-DD`，首次写入时生成 |
+| `- slug:` | 文件名同名 slug，小写-连字符 |
+| `## Todos` | 可执行任务，列 0 的 `- [ ] N. <title>`；每项带 `验收:` 与 `证据:` 子行 |
+| `## Final checks` | `- [ ] F1./F2./F3.` 完成门槛，全部通过才能 `status: done` |
+| `## Notes` | 偏差、oracle 评审结论、变更痕迹 |
+
+### 契约硬规则
+
+- **执行者没有访谈上下文**：每个 todo 必须自带路径、验收判据、证据要求，零追问可执行。
+- **规划只写 `.plans/`**（以及调用 notify CLI），**从不写产品代码**。
+- **Approval/start 是人工门禁**：规划永远不自行开始实现。
+- **start-work 必须在验证该 todo 后**才把 `- [ ]` 改为 `- [x]`，并追加 Notes（如有偏差）。
+- **status 迁移**：`draft → ready → (optional approved) → in-progress → done → accepted`，禁止跳步宣称 accepted。
+- **Review findings 写入 `## Notes`**：标注 suggested edits，不盲目重写 Todos。
+
+## Workflow phases（工作流阶段）
+
+### Phase 1 — Plan（`/plan`）
+1. 只读探索（CodeGraph → Grep/Glob/Read → 必要时 librarian 外部文档）。
+2. 写 `.plans/<slug>.md`，填满契约；元数据 `- status: ready`。
+3. 通知：`plan-ready`（见下）。
+4. 用 question 工具停在门禁，等待人类选择。
+
+### Phase 2 — Human choice（人工门禁）
+- **`start-work <slug>`** → 进入 Phase 3。
+- **`plan-review <slug>`** → 派 `@oracle` 评审计划，结论写 `## Notes`，通知 `awaiting-review`，回到门禁。
+- **`revise`** → 修改计划（仍在 `.plans/` 内），保持 `ready`，再次停在门禁。
+
+### Phase 3 — Execute（`/start-work`）
+1. 读计划，注册全部 todos（含 Final checks）。
+2. 按序执行；独立 lane 可派发 explorer / fixer / designer；oracle 用于评审，librarian 用于外部文档。
+3. **每完成一个顶层 todo**：更新 `- [x]`，必要时追加 Notes。
+4. 可选通知 `task-done`（仅当事件在配置中启用）。
+5. 全部 Todos + Final checks 完成后：`- status: done`，通知 `awaiting-acceptance`，呈现验收摘要（做了什么 / 证据 / 残留风险）。
+6. 人类 accept → `- status: accepted`；reject → 按反馈修复后重新请求验收。
+
+### Phase 4 — Acceptance（验收）
+- 无复选框不宣称完成；计划文件是唯一事实来源。
+- 验收摘要必须包含证据（命令/路径/测试结果）。
+
+## Notify integration（通知集成）
+
+当配置文件存在时（默认 `~/.config/opencode/planflow.json`）：
+
+```bash
+node ~/.config/opencode/plugin/planflow-notify.mjs \
+  --event <event> \
+  --plan .plans/<slug>.md \
+  [--title "..."] \
+  [--message "..."] \
+  [--remaining N] \
+  [--session ID] \
+  [--config PATH] \
+  [--dry-run]
+```
+
+| event | 时机 | 默认启用 |
+|-------|------|----------|
+| `plan-ready` | 计划写完、status: ready | true |
+| `awaiting-review` | oracle 评审开始 | true |
+| `task-done` | 单个 todo 完成（可选） | false |
+| `awaiting-acceptance` | 全部完成、等待人工验收 | true |
+
+- **notify 失败或 provider 未配置：继续工作流，绝不阻塞**。
+- 也可直接编辑 `~/.config/opencode/planflow.json` 配置 Telegram / generic webhook / command provider。
+
+## Delegation（委派）
+
+使用 oh-my-opencode-slim 现有 agents，orchestrator 只做协调：
+
+| Agent | 用途 |
+|-------|------|
+| `explorer` | 仓库内侦察：模式、约束、现状 |
+| `fixer` | 有界实现 lane（按计划 todos） |
+| `designer` | UI/结构相关实现 lane |
+| `oracle` | 计划评审（对抗性、找缺口） |
+| `librarian` | 外部文档/依赖研究 |
+
+## Hard rules（硬规则汇总）
+
+1. 规划阶段禁止实现、禁止改 `.plans/` 以外文件。
+2. 人工门禁：人类不选择，不执行。
+3. 执行阶段：复选框同步是唯一进度事实来源。
+4. 验收阶段：F1–F3 全过 + 人类 accept 才算完成。
+5. 通知是旁路信号，永不阻塞主流程。