@heihei0299/matt-skills 1.0.0

package/template/.opencode/commands/to-tickets.md

@@ -0,0 +1,12 @@
+---
+description: 把计划/spec/当前对话拆为一批 tracer-bullet 票，每票声明阻塞边，发布到 issue tracker
+---
+
+# To Tickets
+
+加载并执行 to-tickets 技能，把计划或 spec 拆为票：
+
+**主题：** $ARGUMENTS
+
+- 拆为 tracer-bullet 票，每票声明其阻塞边
+- 发布到配置的 issue tracker（本地每票一个文件，或真实 tracker 的原生阻塞链接）

package/template/.opencode/commands/triage.md

@@ -0,0 +1,12 @@
+---
+description: 分诊——把 issue 与外部 PR 按 triage 角色状态机流转：分类、验证、需要时 grill、写 agent-ready brief
+---
+
+# Triage
+
+加载并执行 triage 技能，对 issue/PR 做分诊：
+
+**对象：** $ARGUMENTS
+
+- 按 triage 状态机流转：分类 → 验证 → 需要时 grill → 写 agent-ready brief
+- 遵守 triage labels 与 issue tracker 约定

package/template/.opencode/commands/wayfinder.md

@@ -0,0 +1,13 @@
+---
+description: 巨型规划——把超出一个 agent 会话的大块工作规划为 issue tracker 上的决策票地图，逐票解决直到路径清晰
+---
+
+# Wayfinder
+
+加载并执行 wayfinder 技能，为超长工作规划一张共享的决策票地图：
+
+**目标：** $ARGUMENTS
+
+- 把超过一个 agent 会话能容纳的工作拆为 issue tracker 上的决策票
+- 每票一个决策点，标注依赖与阻塞边
+- 逐票解决，直到通往目标的路径清晰

package/template/.opencode/commands/writing-great-skills.md

@@ -0,0 +1,12 @@
+---
+description: 技能写作参考——编写和编辑技能的最佳实践（词汇表与原则，让技能可预测）
+---
+
+# Writing Great Skills
+
+加载并执行 writing-great-skills 技能，编写/编辑技能：
+
+**主题：** $ARGUMENTS
+
+- 以技能设计规范为参考（回合连续性、模型选择、任务分解等原则）
+- 按 Agent Skills 标准编写可预测的技能文本

package/template/.opencode/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/template/.opencode/docs/agents/issue-tracker.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/template/.opencode/docs/agents/runtime-discipline.md

@@ -0,0 +1,36 @@
+# Runtime Discipline
+
+本仓库会话的运行时纪律，执行口径源自 `.opencode/docs/agents/skill-design.md` 的三条规则（规范正文）。术语定义见 `.opencode/CONTEXT.md`。
+
+## 回合连续性规则
+
+每个逻辑单元（红-绿循环、typecheck、测试修复）必须在一个回合内连续执行完毕后才输出：测试 → 分析失败 → 修正 → 重跑 → 全绿整条链一气呵成，中途不输出、不停止、不等用户"继续"。
+
+输出只允许发生在三种情况：
+- 合规交互点：技能/流程要求的用户确认（如 tdd-implement 的 seams 清单确认）
+- 外部阻塞：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
+- 阶段完成：整个阶段的出口条件满足（如 seam 全绿、typecheck 通过、commit 完成）
+
+预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.opencode/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
+
+## 运行纪律（长程任务）
+
+本仓库会话做**长程任务**（Long-Horizon Skill：多阶段/多 seam 串行执行，如 tdd-implement、diagnosing-bugs、improve-codebase-architecture、wayfinder、grill-to-spec、to-spec）时：
+
+- **长程声明**：执行长程技能前，确认技能文本自带长程任务声明与回合连续性规则（Turn Continuity）——阶段内连续动作一回合内完成，不依赖 harness `/goal` 防线。tdd-implement 已内嵌（SKILL.md 声明 + references/stages.md 阶段③规则）。
+- **模型选择**：flash 级模型长程任务卡住概率显著更高；关键长任务优先强模型或 `/goal` 模式。
+- **任务分解（Chunking）**：巨型操作拆小步执行——单次 `write` 超过 ~150 行先写骨架再分批补全；批量 `replace` 超过 ~5 处分批执行，每批后立即验证。tdd-implement 已内嵌该规则（随包分发）。
+
+## 执行原则（细则）
+
+- 先澄清边界再实现；任务收敛后直接执行，不做不必要的形式化流程
+- 局部修改、最小充分实现，避免无关扩张
+- 用户当次明确指令优先于历史经验与参考项目
+- 脏工作区不回滚他人改动；遇到未明改动先理解再兼容
+
+## 文档维护（细则）
+
+- 本文件与分文件只记录长期有效、跨任务可复用的工程经验与项目级约定
+- 一次性需求、临时接口选择、用户当次指定方案不沉淀；更换接口/方案视为需求变更，不判定"旧错新对"
+- 仅当问题重复出现、暴露长期约束、影响后续多次开发、用户明确要求沉淀，或涉及安全/构建/测试/发布/架构边界时更新
+- 经验条目包含：标题、触发信号、根因/约束、正确做法、验证方式、适用范围

package/template/.opencode/docs/agents/skill-design.md

@@ -0,0 +1,32 @@
+# Skill Design Spec
+
+The design rules every skill in this repo must obey. Apply them when writing a new skill or editing an existing one. Terms are defined once in [`CONTEXT.md`](../../CONTEXT.md) — reference them there, never restate the definition.
+
+This spec exists because of a real incident: a long-horizon skill run on a flash-class model stopped its turn at "announce the next step" points four times in one session (see `DIAGNOSIS-tdd-implement-stuck.md`). The three rules below are the preventive measures that came out of that diagnosis. They are repo rules, not advice.
+
+## Rule 1 — Turn Continuity
+
+Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of its own: the consecutive actions of a stage (red → green → typecheck → next seam) are executed serially **within one turn**, until the stage's exit condition is met. Do not end the turn at "announce the next step" points, and do not wait for the user to say "continue".
+
+- State it **positively** (per the negation principle in `writing-great-skills`): describe the target behaviour, never the banned one.
+- It must be **self-contained** — the skill cannot rely on the harness `/goal` line, because no `/goal` exists when the user does not activate one.
+- Every stage ends on a checkable exit condition; reaching it is the only thing that ends the turn.
+- A sub-step going green (e.g. one seam) is not a stage exit — a stage ends only when all of its seams are complete. Progress output does not itself end the turn: output, then keep executing until one of the three endpoints (compliance checkpoint, external blocker, stage exit) is reached.
+- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](../../skills/tdd-implement/references/stages.md) stage ③.
+
+## Rule 2 — Model Selection
+
+Flash-class models are markedly more likely to stop prematurely on long-horizon agentic work. For critical long tasks, prefer a stronger model or `/goal` mode. This is a runtime choice, not something a skill text can enforce — record it here so skill authors and session runners share the same guidance.
+
+## Rule 3 — Progress Chunking
+
+Giant turns — a single `write` of a large file, or a batch `replace` of a hundred-plus lines — hit output caps and get truncated mid-work. Chunk the work into small, individually verifiable steps:
+
+- A single `write` over ~150 lines: write the skeleton first, then fill in batches.
+- A batch of more than ~5 `replace`s: split into batches and verify after each batch.
+
+These thresholds are experience defaults; adjust them as practice shows better values.
+
+## Long-horizon skills inventory
+
+Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — new orchestration skill for diagnosis + TDD fix, carries its own Turn Continuity rule), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec`, `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.

package/template/.opencode/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/template/.opencode/skills/commit-check/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: commit-check
+description: "Run the pre-commit gate before any commit: verify docs match the implementation, align README, keep the directory clean, and write a clear commit message. Use whenever the user is about to commit or asks to check anything about the commit — e.g. verifying docs/README are in sync, cleaning up temp files, scanning for secrets/keys/.env in the change, or having you write the commit message. Not for general PR/code review (that's code-review), and not for explaining git/commit conventions (that's a teach task)."
+---
+
+# Commit Check
+
+提交前的**门禁检查**：审查文档 → 对齐 README → 保持目录卫生 → 规范 commit message，四项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
+
+## 四项检查（全部通过才 commit）
+
+### ① 审查文档
+
+- 本次改动涉及的行为/接口/配置/命令是否有对应文档（README、`docs/`、技能正文）描述
+- 文档描述与实现一致：无过期信息、无声称未实现的功能、无遗留的旧接口描述
+- 涉及技能/模板/配置改动时，检查正文引用的路径与实际一致（如相对路径、目录结构）
+- 发现不一致 → 先修文档（或更新实现），再进入下一步
+
+### ② 对齐 README
+
+- 改动涉及项目结构、分发文件、技能/命令清单时，检查 README 中对应的结构说明、映射表、清单是否同步
+- 改动涉及用法/CLI/配置/示例时，检查 README 对应描述与实际一致
+- 存在模板镜像/分发副本时，确认源文件与副本同步（如有守护测试，跑一遍确认）
+
+### ③ 保持目录卫生
+
+- `git status` 确认工作区只含预期改动：无残留未跟踪文件、无临时产物（调试脚本、日志、备份文件、`[DEBUG-...]` 残留）
+- 清理本次改动产生的临时文件（一次性脚本、转储、探针）——删除或移入明确的非提交位置
+- 确认没有敏感信息进入改动（密钥、token、`.env`、私钥）——跑 `scripts/scan-sensitive.sh`，不用手写扫描
+- 提交后工作区应为干净状态（`git status` 无输出）
+
+### ④ 规范 commit message
+
+- 格式遵循仓库约定（常见：`<type>(<scope>): <subject>`，type 用 feat/fix/docs/chore/refactor/test）
+- subject 描述变更内容而非过程（不说"我做了什么"，说"改成了什么"）
+- 需要时补充 body：动机、影响范围、验收证据（测试结果、同步确认）
+- 一次 commit 只含一个逻辑变更；多主题拆多个 commit
+
+## 不做什么
+
+- 不做全量 code review：审查语义以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源，本技能不重写
+- 不替代实现流程的收尾：`tdd-implement` 阶段⑦已含文档对齐与目录卫生，本技能只管独立 commit 的门禁
+- 不顺手重构：只检查与本次改动直接相关的内容，不扩权到无关文档/目录
+- 不发明扫描规则：敏感信息检测跑 `scripts/scan-sensitive.sh`，不每次重写 grep 模式
+
+## 执行顺序（回合内串行）
+
+1. 跑 ① 审查文档 → ② 对齐 README → ③ 保持目录卫生 → ④ 写 commit message
+2. 任一项发现问题：修复后重跑该项，全部通过才 commit
+3. commit 后确认 `git status` 干净，工作结束
+
+**回合连续性**：四项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到四项全过或遇到外部阻塞（权限/授权缺失）。
+
+## 出口条件
+
+- [ ] 文档审查通过（无过期/不一致描述）
+- [ ] README 对齐（涉及结构/分发改动时已同步）
+- [ ] 目录卫生（`git status` 干净，无临时产物/敏感信息）
+- [ ] commit message 规范（遵循仓库格式）
+- 四项全过 → commit
+
+## 引用
+
+- 代码审查语义：[code-review](.agents/skills/code-review/SKILL.md)（唯一事实源，本技能不重写）
+- 完整实现流程：[tdd-implement](.agents/skills/tdd-implement/SKILL.md)（含流程内收尾的文档对齐与目录卫生）

package/template/.opencode/skills/commit-check/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Commit Check"
+  short_description: "提交前门禁：审查文档、对齐 README、保持目录卫生、规范 commit message"
+policy:
+  allow_implicit_invocation: false

package/template/.opencode/skills/commit-check/scripts/scan-sensitive.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Deterministic secret scan for commit-check check ③.
+# The grep patterns are fragile to freehand — run this instead of re-writing
+# the scan every time. Two confidence tiers:
+#   FAIL  — structured secrets (KEY=value assignments, private key blocks)
+#   WARN  — bare keywords (may legitimately appear in docs that mention them)
+# Checks the staged diff (fail) and, unless --staged-only is passed, reports
+# matches in the unstaged diff (warn).
+#
+# Usage:
+#   scripts/scan-sensitive.sh            # staged (fail) + unstaged (warn)
+#   scripts/scan-sensitive.sh --staged-only
+set -euo pipefail
+
+fail_patterns='(api[_-]?key|secret|token|passwd|password)[[:space:]]*[=:][[:space:]]*[^[:space:]]{8,}|BEGIN (RSA|OPENSSH|EC|DSA) PRIVATE KEY'
+warn_patterns='(api[_-]?key|secret|token|passwd|password|\.env)'
+
+fail=0
+
+if git diff --cached -U0 | grep -inE "$fail_patterns"; then
+  echo "❌ Structured secrets found in STAGED diff — remove them before committing." >&2
+  fail=1
+else
+  echo "✅ No structured secrets in staged diff."
+  if git diff --cached -U0 | grep -inE "$warn_patterns"; then
+    echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
+  fi
+fi
+
+if [[ "${1:-}" != "--staged-only" ]]; then
+  if git diff -U0 | grep -inE "$fail_patterns"; then
+    echo "⚠  Structured-secret matches in UNSTAGED diff — decide whether they belong in the commit." >&2
+  fi
+fi
+
+exit "$fail"

package/template/.opencode/skills/diagnose-fix/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: diagnose-fix
+description: "Complete diagnosis→fix→regression channel for bugs: diagnose, then fix via a TDD red-green loop with a hard gate (no fix code before a failing regression test). Use when the user says diagnose/debug/fix this, or reports something broken/throwing/failing/slow — prefer this over diagnosing-bugs when a fix is wanted, not just a diagnosis."
+---
+
+# Diagnose Fix
+
+诊断 **bug** 并修复的编排技能：诊断语义以 [diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md) 为唯一事实源，修复语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能只编排三个阶段并设一道**硬门槛**，不重写两个上游技能的规则。
+
+本技能是**长程任务**（Long-Horizon Skill）：诊断 → 修复 → 回归在**一个回合内串行完成**，自带**回合连续性**（Turn Continuity）规则（见下文）。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
+
+## 流程速览
+
+```
+① 诊断 → ② TDD 修复（硬门槛）→ ③ 回归验证
+```
+
+## ① 诊断
+
+按 [diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md) 的 Phase 1-4 执行：
+
+1. **反馈回路**（Phase 1）：构建能对 _这个 bug_ 变红的紧致 pass/fail 信号——优先失败测试，其次 curl/CLI/浏览器脚本/重放/一次性 harness 等；没有回路不进入假设。
+2. **复现 + 最小化**（Phase 2）：跑回路看它红，确认失败模式与用户描述一致；逐步删减输入/调用方/配置，只保留 load-bearing 元素。
+3. **假设**（Phase 3）：生成 3-5 个可证伪的排名假设，先展示给用户。
+4. **探针**（Phase 4）：一次只改一个变量，临时探针用 `[DEBUG-...]` 前缀标记。
+
+**出口条件**：反馈回路已红（已实际跑过并确认捕捉到该 bug）、复现已最小化。诊断完成前不写任何修复代码。
+
+## ② TDD 修复（硬门槛）
+
+**TDD 语义（红-绿循环、seam 定义、好测试标准、anti-patterns）以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源**——本技能不重写；进入本阶段前先读取 tdd 技能。
+
+**硬门槛**：写任何修复代码之前，必须已存在一个**失败**的回归测试——把最小复现转写为正确 seam 上的测试，先运行看它红，然后才允许写修复代码让它变绿。
+
+- **无逃生舱**：不存在正确 seam 时，**本身即 finding**——向用户明确说明"架构阻止锁定该 bug"，请求 seam 决策或记录为架构改进建议（可转交 `/improve-codebase-architecture`）；**不得**绕过测试直接改代码。
+- **轻量声明**：本技能不套用 tdd-implement 的重流程——不做逐 todo 的循环编排、不设 seams 确认步骤、无 typecheck/commit 前置门禁；单 seam 修复场景直走红-绿。
+
+**出口条件**：回归测试先红 → 写最小修复 → 回归测试变绿。
+
+## ③ 回归验证
+
+1. 重跑诊断阶段①的**原始反馈回路**（未最小化场景）确认症状消失。
+2. 清理：删除所有 `[DEBUG-...]` 标记的临时探针与一次性 harness（`grep` 前缀确认无残留）。
+3. 在 commit / PR 消息中写明**验证正确的假设**（诊断阶段哪个假设被证实），让下一个调试者受益。
+
+**出口条件**：原始症状消失 + 回归测试绿 + 临时探针清理完成。
+
+## 反模式（不做什么）
+
+完整反模式清单见 [references/anti-patterns.md](references/anti-patterns.md)——正文各阶段规则是正面约束，反模式清单是负向边界；细节只在一处存在，本文件不重复。
+
+## 回合连续性规则
+
+诊断 → 修复 → 回归**在一个回合内串行完成**，不等用户"继续"：构建回路 → 复现 → 假设 → 探针 → 失败测试 → 修复 → 回归 → 清理整条链一气呵成，中途不停顿。
+
+输出只允许发生在以下三种情况：
+- **合规交互点**：技能要求的用户确认——阶段①假设清单展示、阶段②无 seam finding 上报或 seam 决策请求
+- **外部阻塞**：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
+- **阶段出口**：整个阶段的出口条件满足（阶段①回路已红 + 复现最小化；阶段②失败测试已红 → 修复变绿；阶段③症状消失 + 回归绿 + 清理完成）
+
+预告下一步后立即执行该步骤，回合终点仅为合规交互点、外部阻塞或阶段出口条件满足。进度输出本身不结束回合——输出后继续执行，直到三类终点之一达成。
+
+## 引用
+
+- 诊断：[diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md)
+- TDD 修复：[tdd 技能](.agents/skills/tdd/SKILL.md)、[tdd/tests.md](.agents/skills/tdd/tests.md)、[tdd/mocking.md](.agents/skills/tdd/mocking.md)

package/template/.opencode/skills/diagnose-fix/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Diagnose Fix"
+  short_description: "诊断硬 bug 并按 TDD 红-绿修复"
+policy:
+  allow_implicit_invocation: false

package/template/.opencode/skills/diagnose-fix/references/anti-patterns.md

@@ -0,0 +1,20 @@
+# 反模式清单（Diagnose-Fix）
+
+SKILL.md 正文各阶段规则是正面约束；本文件是负向边界（不做什么），为细节唯一出处。SKILL.md 只引用本文件，不重复内容。
+
+## 诊断阶段
+
+- 不跳过反馈回路直接猜根因：回路未红之前不进入假设、不写修复代码
+- 不把最小复现留在 harness 里：必须转写为正确 seam 上的回归测试，harness 只作诊断工具
+- 不一次改多个变量：探针一次只改一个，`[DEBUG-...]` 前缀标记
+
+## 修复阶段
+
+- 不绕过测试直接改代码（见 SKILL.md ②无逃生舱）——没有 seam 是 finding，不是豁免
+- 不套用 tdd-implement 重流程：见 SKILL.md ②轻量声明——单 seam 修复直走红-绿，不引入重流程编排
+- 不重写 tdd 技能的红-绿语义：seam 定义、好测试标准、mocking 边界一律查上游技能
+
+## 回归阶段
+
+- 不遗留探针：`[DEBUG-...]` 前缀的临时改动在回归验证后全部清理
+- 不跳过原始反馈回路的重跑：最小化场景绿 ≠ 原始症状消失

package/template/.opencode/skills/grill-to-spec/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: grill-to-spec
+description: "Router：编排 grill-with-docs → to-spec，把模糊想法打磨成可执行 Spec。Use when the user asks to grill/design/polish an idea into a spec——只产出领域文档与 spec，不写代码。"
+disable-model-invocation: true
+---
+
+# Grill to Spec
+
+**grill-with-docs**（grilling + domain-modeling）与 **to-spec** 的编排器。本 skill 只做编排：把设计压力测试成共识，把共识综合成 spec 发布——不写代码，不动源码。
+
+## 职责
+
+| 做 | 不做 |
+|----|------|
+| 编排 `grill-with-docs` → `to-spec` 完整通道 | 不编写代码、不修改任何源码（含测试） |
+| 引导用户从模糊想法 → 结构化 spec | 不拆 tickets（`/to-tickets` 职责） |
+| grilling 逐问挑战、打磨设计 | 不调用 `/code-review` |
+| 同步产出领域文档（glossary inline；ADR 草稿经用户确认后落盘） | 阶段②仅综合，不新增采访 |
+| 综合对话为可执行的 spec 文档并发布 | 不维护已发布的 spec |
+| 产出物仅限领域文档与 spec | 实现与修复交给实现类 skill（如 `/tdd-implement`） |
+
+## 流程
+
+```text
+① Grill with docs → ② Synthesize to spec
+```
+
+① 加载 `/grill-with-docs`：grilling 采访（一次一问、等反馈；决策逐条交由用户定夺）+ domain-modeling 产出 glossary/ADR。出口：用户确认共识达成。
+
+   ① 内 ADR 子流转（与 glossary 的 inline 更新严格区分）：
+   1. 触发：仅当 domain-modeling 三条件全满足（难逆转 / 无上下文费解 / 真实权衡）才提议 ADR
+   2. 草稿：按 ADR-FORMAT 把完整标题+正文展示给用户审阅，等待反馈
+   3. 确认：用户显式说「确认/写入」才落盘；用户拒绝则不写、继续访谈；用户要求修改则改草稿重新确认
+   4. 未确认前不得创建或写入 `docs/adr/` 下的任何文件
+
+② 加载 `/to-spec`：探索代码（glossary 词汇贯穿 spec、尊重相关 ADR）→ 确认 seams（既有优先、最高 seam、理想一个）→ 编写 spec 草稿 → 展示给用户确认（只展示等决定，不新增采访提问）→ 发布到 `.scratch/<feature-slug>/spec.md` 并标 `ready-for-agent`。出口：spec 已发布。
+
+## 产出物（格式严格对齐下游技能）
+
+本技能产出物仅以下三种，格式以各技能文件为唯一事实源，不在本技能重写：
+
+| 产出物 | 位置 | 格式来源 |
+|--------|------|----------|
+| Glossary | `CONTEXT.md`（多上下文：`CONTEXT-MAP.md` + 各上下文 `CONTEXT.md`） | [CONTEXT-FORMAT.md](.agents/skills/domain-modeling/CONTEXT-FORMAT.md) |
+| ADR | `docs/adr/NNNN-slug.md`（多上下文：系统级在根，上下文级在 `src/<ctx>/docs/adr/`） | [ADR-FORMAT.md](.agents/skills/domain-modeling/ADR-FORMAT.md) |
+| Spec | 发布到 issue tracker：`.scratch/<feature-slug>/spec.md` | [to-spec 七节模板](.agents/skills/to-spec/SKILL.md) |
+
+三类产出物的格式细则（Glossary 守则 / ADR 守则 / Spec 守则）见 [references/rules.md](references/rules.md)——SKILL.md 不重复细节。
+
+## 不可协商规则（无任何例外）
+
+- **写入 ADR 必须由用户显式确认，无论任何情况、无任何例外**：三条件全满足、决策看似显然、② 补记，均不豁免。ADR 一旦落盘记录不可撤销（可 supersede，但痕迹永存），全部门槛都在写入之前
+- **ADR 与 glossary 不对称**：`CONTEXT.md` 术语可随访谈 inline 更新（domain-modeling 规则），ADR 必须先审草稿、用户确认后才落盘——禁止把 inline 逻辑套用到 ADR
+
+## 回退
+
+| 触发点 | 条件 | 动作 |
+|--------|------|------|
+| ② seam 确认 | 用户不同意 seams | → ① 补充 |
+| ② 综合时 | 关键信息缺失 | → ① 补采 |
+| ② 发布后 | spec 有问题 | → ① 重新循环 |
+
+## 异常终止
+
+| 情况 | 处理 |
+|------|------|
+| 用户中途放弃 / 无主题 | 终止 |
+| tracker 未配置 | 提示 `/setup-matt-pocock-skills`，终止 |
+| ① 超过 5 轮无进展 | 建议暂停或缩小范围 |
+
+## 约束
+
+- ① 出口达成后方可进入 ②
+- 全程不写代码、不动源码：唯一允许写入的文件是领域文档（`CONTEXT.md`/ADR）与 spec
+- ② 探索代码只为确认 seams 与术语——只读不改
+- 产出物格式细则（Glossary/ADR/Spec 守则）与反模式见 [references/rules.md](references/rules.md)，不在本文件重写
+
+## 引用
+
+- [grill-with-docs](.agents/skills/grill-with-docs/SKILL.md)
+- [grilling](.agents/skills/grilling/SKILL.md)
+- [domain-modeling](.agents/skills/domain-modeling/SKILL.md)
+- [to-spec](.agents/skills/to-spec/SKILL.md)

package/template/.opencode/skills/grill-to-spec/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill to Spec"
+  short_description: "从模糊想法到可执行 Spec — 只打磨设计、产出领域文档与 Spec，不写代码"
+policy:
+  allow_implicit_invocation: false

package/template/.opencode/skills/grill-to-spec/references/rules.md

@@ -0,0 +1,33 @@
+# 守则：Grill-to-Spec 产出物格式细则
+
+三类产出物（Glossary / ADR / Spec）格式的**唯一细节出处**，由 SKILL.md 直链引用。SKILL.md 只保留流程、导航与不可协商规则，本文件不重复流程内容。
+
+## Glossary 守则
+
+- 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问
+- 只是 glossary：零实现细节，不当 spec/scratch pad
+- 只收本上下文特有术语，通用编程概念不收
+- 定义 WHAT 非 HOW，1-2 句；opinionated，同义词列 `_Avoid_`；术语解析即 inline 更新，不批量
+
+## ADR 守则
+
+- 三条件全满足才提议（难逆转 / 无上下文费解 / 真实权衡）；`docs/adr/` 懒创建
+- 格式：标题 + 1-3 句正文；可选节（Status/Considered Options/Consequences）按需，大多数不需要
+- 编号：`0001-slug.md` 顺序递增，扫描最高号 +1
+- 草稿经用户显式确认后落盘，任何情况无例外（见 SKILL.md 流程① 与不可协商规则）
+
+## Spec 守则
+
+- 完整七节模板逐节不缺：Problem Statement / Solution / User Stories / Implementation Decisions / Testing Decisions / Out of Scope / Further Notes
+- User Stories：长编号列表，`As an <actor>, I want a <feature>, so that <benefit>` 格式
+- Implementation Decisions：不含文件路径/代码片段；例外——原型产出的决策密集片段可 inline，注明来源并裁剪至决策部分
+- 全文贯穿 glossary 词汇；尊重所触区域既有 ADR
+- seams：既有优先于新建、取最高、理想数量 1，与用户确认
+- 发布后标 `ready-for-agent`，triage 状态以 issue 文件顶部 `Status:` 行记录
+
+## 反模式（不做什么）
+
+- 不把守则当逐条朗读的检查清单——守则约束产出物格式，不约束对话节奏
+- 不把 ADR 当 glossary 一样 inline 更新（见 SKILL.md 不可协商规则）
+- 不产出守则之外的文件：产出物只有三种（Glossary / ADR / Spec）
+- 不在本文件之外重复守则细节——SKILL.md 与 references 之间信息只在一处存在