@heihei0299/matt-skills 1.0.0

package/template/.pi/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`](../../../.opencode/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/.pi/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/.pi/prompts/issue-audit.md

@@ -0,0 +1,114 @@
+---
+description: 审计 feature 的 issue 完成情况（四维：完成度 / spec 遵守 / ADR 遵守 / 文档一致性），输出完整报告，只审计不修改
+argument-hint: "<feature-slug>"
+---
+
+# Issue Audit：`$ARGUMENTS`
+
+对 feature `$ARGUMENTS` 执行完整 issue 审计（对应目录 `.scratch/$ARGUMENTS/`），按以下流程执行。
+
+## 铁律（不可违背）
+
+- **不修改任何现有文档与代码。** issue 文件、spec.md、README*、src-rust/、webui/ 等一切现有文件禁止改动。
+- **唯一允许的写入**：新建审计报告 `.scratch/$ARGUMENTS/audit-<YYYYMMDD-HHMM>.md`（时间戳文件名，保留多次审计历史）。不覆盖、不修改任何其他文件，不生成其他产物。
+- **不勾选验收标准、不改 Status、不做 triage 流转。** 状态机是 triage 技能的职责；审计只产出事实结论。
+- **输入无效立即失败（fail-fast）**：`.scratch/$ARGUMENTS/` 不存在或为空、缺少 `spec.md`、`issues/` 下没有任何 issue 文件时，不进入审计流程，直接输出失败报告（逐项列出缺失内容）并结束。
+- 审计与被审计分离：发现问题不修复、不流转，只在报告中记录（阻断项附"需要什么"），处置由用户决定。
+- 只读 git 命令（status/log/diff/show/rev-parse/ls-files/grep）用于收集提交历史证据；任何写操作命令一律不执行。
+- 报告语言中文；代码标识符、测试名、字段名、提交哈希保留原文。
+
+## 输入来源
+
+- `.scratch/$ARGUMENTS/spec.md`（Implementation Decisions、Testing Decisions、Out of Scope）
+- `.scratch/$ARGUMENTS/issues/*.md`（每票验收标准、Blocked by 依赖）
+- `.scratch/$ARGUMENTS/audit-*.md`（历史审计报告，读取最新一份作为对比基线；无则标注"无历史基线"）
+- `docs/adr/*.md`（架构决策，审计对象）
+- `CONTEXT.md`（术语表；违反术语视为 spec 遵守问题）
+- 当前工作树代码 + 只读 git 历史（提交哈希作为"确实做过"的证据）
+
+## 为什么分四维（不可合并重排）
+
+四维是相互独立的审计轴：完成度（验收标准逐条）可以全绿，而 spec 决策被违背、ADR 被绕过或文档已过期。任一维的通过不得被其他维的结论掩盖，也不得用一维的发现解释掉另一维的未满足项；报告按维呈现、逐维给出最严重问题，由用户综合处置。
+
+## 四维审计
+
+1. **完成度**：逐票核对每个 issue 的验收标准（checkboxes）——逐条判定满足/未满足，引用代码位置、单测名、提交哈希作为证据。Blocked by 依赖未满足的票不计入完成度。
+2. **Spec 遵守**：spec.md 的 Implementation Decisions 是否被落实、是否违背；Testing Decisions 的测试是否真实存在（非空头声明）；**Out of Scope 是否被越过**（实现做了 spec 明说不做的事 = 阻断项）。
+3. **ADR 遵守**：每个 `docs/adr/NNNN-*.md` 的决策在当前实现中是否被遵守。
+4. **文档一致性**：README.md / README_ZH.md（及受影响的其他用户文档）与当前实现是否一致——无过期信息、无声称未实现的功能（如 feature 中某 UI 尚未实现，文档不得声称其存在）、命令示例与界面描述与实际一致。
+
+## 证据分级（下结论的纪律）
+
+- **L1 静态**（默认）：读代码、读 git 提交记录、核对单测存在性与断言内容。
+- **L2 测试套件**：运行仓库完整测试套件（本项目：`cargo test --lib` 于项目根；如有 JS 侧测试一并运行）。每次审计必跑。
+- **L3 端到端**：仅在以下情形升级——① 某验收标准明确要求"链路可用/端到端"；② L1 静态核对发现不一致、仅靠静态无法定案。**审计执行内不执行 L3**；判定需要升级后，将条目列入报告「待主 agent 隔离验证」清单（注明升级条件与需验证内容），由主 agent 在隔离环境（临时 HOME + mock 上游）执行。
+- **弱证据不足**：间接、缺失、仅一致的证据不足以支撑"通过"结论；无法取证到位的条目标为非阻断疑点并注明"需要升级证据"。
+
+## 问题分级
+
+- **阻断项（must-fix）**：验收标准未达成、违反 ADR、越过 Out of Scope、违背 spec 决策。
+- **非阻断项（should-note）**：文档措辞、建议性改进、证据仅间接的疑点。
+- feature 结论 = 阻断项数 + 非阻断项数；**阻断为 0 才判定通过**。
+
+## 执行步骤（顺序自包含）
+
+1. 校验输入（fail-fast）：确认 `.scratch/$ARGUMENTS/` 存在且非空、`spec.md` 存在、`issues/` 下至少有一个 issue 文件；任一项不满足 → 输出失败报告（逐项列出缺失内容）并结束，不进入审计、不生成审计报告文件。校验通过后列出 spec、全部 issue、历史审计报告（若有）。
+2. 收集约定：读 spec.md、全部 issues、`docs/adr/`、CONTEXT.md。
+3. 逐票核对（维度 1）：每票验收标准逐条判定，记录证据。
+4. 维度 2：以 spec 决策与 Out of Scope 对照当前代码实现。
+5. 维度 3：以每个 ADR 对照当前实现。
+6. 维度 4：对照 README 等文档与当前实现。
+7. 跑 L2 测试套件（`cargo test --lib`），记录通过数/失败数。
+8. 判定 L3 升级条件，必要时列出待主 agent 隔离验证清单。
+9. 读取最新历史报告（若有）作基线，对比阻断项变化。
+10. 汇总四维报告：对话输出完整报告，并写入 `.scratch/$ARGUMENTS/audit-<YYYYMMDD-HHMM>.md`。
+    - **文件名必须精确到分钟**（如 `audit-20260802-0604.md`），格式为 `audit-` + 年(4)月(2)日(2)-时(2)分(2) + `.md`。不得省略分钟、不得用其他命名。
+    - 同分钟重跑导致同名时追加 `-2`、`-3` 序号（如 `audit-20260802-0604-2.md`），永不覆盖已有文件。
+
+## 报告原则（逐条独立可验证）
+
+- **逐条独立可验证**：每个验收标准、每个未满足项自成一条并附证据（文件:行号、测试名、提交哈希），不合并成模糊结论——读者可逐条复核。
+- **行为性表述**：阻断项写"违反了什么 + 需要什么"，不做过程性修复指示（如"应该打开 X 文件改 Y"）；证据引用（文件:行号）仅为定位证据，不作修复指令。
+- **不合并重排**：四维结论按维呈现、互不遮盖（见「为什么分四维」）。
+
+## 报告模板（强制，四维缺失视为未完成）
+
+```markdown
+# Issue 审计报告：$ARGUMENTS
+
+审计时间：<YYYY-MM-DD HH:MM>（精确到分钟）｜基线：<上次报告文件名 或 "无历史基线">
+
+## 结论总览
+- 阻断项：N 项 / 非阻断项：M 项 → 通过 / 未通过
+- 每维最严重问题：维度1：<票号+一句> ｜ 维度2：<一句> ｜ 维度3：<一句> ｜ 维度4：<一句>（该维无问题写"无"）
+- 与上次审计对比：新增解决 k 项 / 新引入 j 项 / 持续未满足 i 项（无历史基线时写"本次为首份报告"）
+
+## 维度 1 · 完成度（逐票）
+- 01 <标题>：满足 / 未满足（验收标准逐条 + 证据：文件:行号、测试名、提交哈希）
+
+## 维度 2 · Spec 遵守
+- 满足 / 违反（引用 spec 行号 + 代码证据；Out of Scope 检查结果）
+
+## 维度 3 · ADR 遵守
+- 0001 <标题>：遵守 / 违反（证据）
+
+## 维度 4 · 文档一致性
+- README.md：一致 / 过期信息（引用行 + 实现事实）
+
+## 未满足项清单（显式记录）
+- [阻断] <票号> <内容>：原因 + 需要什么
+- [非阻断] <内容>：原因
+
+## 待主 agent 隔离验证（L3 条目，如无则写"无"）
+- <条目>：升级条件 + 需验证内容
+
+## 备注
+- 证据级别说明（哪些条目用了 L1/L2/L3）
+- 本次审计为只读审计，仅新建本报告文件，未修改任何现有文档
+```
+
+## 出口条件（强制）
+
+- 输入无效按 fail-fast 出口：直接输出失败报告（逐项列出缺失内容），不生成审计报告文件。
+- 正常审计：四维全部给出结论、每维最严重问题列出、未满足项逐条列出、证据引用齐全 → 才可结束。
+- 报告不完整（缺维、未满足项遗漏、证据缺失）→ **继续补齐，不得提前结束**。

package/template/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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 之间信息只在一处存在