@heihei0299/matt-skills 1.3.2 → 1.5.2

package/template/{.pi → .agents}/skills/grill-to-spec/SKILL.md

@@ -57,7 +57,6 @@ disable-model-invocation: true
 | 触发点 | 条件 | 动作 |
 |--------|------|------|
 | ② seam 确认 | 用户不同意 seams | → ① 补充 |
-| ② 综合时 | 关键信息缺失 | → ① 补采 |
 | ② 发布后 | spec 有问题 | → ① 重新循环 |
 
 ## 异常终止
@@ -72,8 +71,6 @@ disable-model-invocation: true
 
 - ① 出口达成后方可进入 ②
 - 全程不写代码、不动源码：唯一允许写入的文件是领域文档（`CONTEXT.md`/ADR）与 spec
-- ② 探索代码只为确认 seams 与术语——只读不改
-- 产出物格式细则（Glossary/ADR/Spec 守则）与反模式见 [references/rules.md](references/rules.md)，不在本文件重写
 
 ## 引用
 

package/template/.agents/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+Call the Skill tool twice, for "grilling" and "domain-modeling".

package/template/.agents/skills/grill-with-docs/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill with Docs"
+  short_description: "Grill a design and write its docs"
+policy:
+  allow_implicit_invocation: false

package/template/.agents/skills/grilling/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/template/.agents/skills/grilling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Grilling"
+  short_description: "Stress-test thinking a round of questions at a time"

package/template/.agents/skills/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/template/.agents/skills/handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Handoff"
+  short_description: "Compact a conversation into a handoff"
+policy:
+  allow_implicit_invocation: false

package/template/.agents/skills/implement/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: implement
+description: "Implement a piece of work based on a spec or set of tickets."
+disable-model-invocation: true
+---
+
+Implement the work described by the user in the spec or tickets.
+
+Use /tdd where possible, at pre-agreed seams.
+
+Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+
+Once done, use /code-review to review the work.
+
+Commit your work to the current branch.

package/template/.agents/skills/implement/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Implement"
+  short_description: "Build work from a spec or tickets"
+policy:
+  allow_implicit_invocation: false

package/template/.agents/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review for {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files**: monospaced list, `font-mono text-sm`.
+- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
+- **Problem**: one sentence. What hurts.
+- **Solution**: one sentence. What changes.
+- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable): one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow: interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"*, because those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

package/template/.agents/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow**, with an interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files**: which files/modules are involved
+- **Problem**: why the current architecture is causing friction
+- **Solution**: plain English description of what would change
+- **Benefits**: explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.

package/template/.agents/skills/improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "Find and grill architecture improvements"
+policy:
+  allow_implicit_invocation: false

package/template/.agents/skills/instance-test/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: instance-test
+disable-model-invocation: true
+description: "matt-skills 专属功能测试示范（由 scaffold-functional-test 从 spec 生成）— 验证 sync 合并 update 后的行为；仅显式调用"
+---
+
+# Instance Test — matt-skills 专属示范
+
+本 skill 是 **matt-skills 专属**的功能测试示范，由 `scaffold-functional-test` 从 `.scratch/sync-merge-update/spec.md` 生成（见 `references/instances.md` 头部 `spec hash` + `generatedAt`）。它是生成器产出形态的示例，不随 Template Snapshot 分发，仅保留于 Workspace。旧通用执行器文案已废弃。
+
+兼容别名：`instance-test` 保留原名以兼容历史调用，实际为 `matt-functional-test` 的示范实现。
+
+## Steps
+
+### 1. Gather instances
+
+实例集已由生成器按**受控扩展模型**落盘于 `references/instances.md`（头部含 `spec hash` + `generatedAt`，每实例含**溯源** `spec.md` 章节/行号，`<!-- manual -->` 段受保护）。
+
+执行前校验指纹：若当前 spec 的 `spec hash` 与 `references/instances.md` 头部不一致，提示「spec 已变更，建议重跑 scaffold-functional-test」但不自动覆盖，需用户显式确认才 regenerate（AI 先给 diff 建议）。
+
+每实例声明：`prompt/command/expected files/content/expected stdout phrases/expected exit code` 必选，`setup/env/timeout/type/teardown` 可选，默认 `type: cli`。
+
+完成：实例清单已固定（含溯源与指纹），`<!-- manual -->` 段未被覆盖。
+
+### 2. Run instances
+
+For each **instance** in order:
+
+1. `mktemp -d` 隔离目录（或项目支持的 `git worktree` / `--dest`），单线程串行，不并行。
+2. 执行实例的 `command` 与可选 `setup`，捕获 stdout/stderr 与 exit code。
+3. 快照 `expected` 声明的文件与副作用。
+
+一个 **instance** 一次，失败不阻断后续，产物不碰撞。
+
+完成：每实例均有独立 run dir 与捕获输出。
+
+### 3. Evaluate
+
+对比每实例的 actual vs expected：
+
+- 文件存在性/内容（`test -f`/`grep -q`/`diff`）
+- Stdout/stderr 含预期短语
+- Exit code 一致
+- 扩展字段（`env`/`timeout`/`type`）行为符合声明
+
+标记 `PASS`/`FAIL`，附 `expected vs actual` diff 与 run dir 证据。
+
+完成：每实例均有 `PASS` 或 `FAIL` 且含证据。
+
+### 4. Report
+
+对话内汇总：
+
+- `PASS m/n` + per-instance evidence
+- 失败项列出 gap（expected vs actual）与 run dir 复现路径
+- 成功默认清理临时目录、失败默认保留；`--keep` 保留全部；`--report` 显式开启才落盘报告文件
+
+不以文件刷屏——默认输出在对话，报告文件仅显式开启才写。
+
+## 实例来源
+
+- 源 spec：`.scratch/sync-merge-update/spec.md`（`spec hash` 见 `references/instances.md` 头部）
+- 推导策略：混合推导（验收标准锚点 + 需求/接口/边界补充），每实例含溯源，无溯源视为幻觉
+- 手工段：`<!-- manual -->` 保护
+
+## 引用
+
+- 生成器：`scaffold-functional-test`（读 spec 产出本 skill）
+- 领域术语：`CONTEXT.md`
+- 技能设计：`docs/agents/skill-design.md`

package/template/.agents/skills/instance-test/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Instance Test"
+  short_description: "matt-skills 专属功能测试示范 — 验证 sync 合并 update 后行为"
+policy:
+  allow_implicit_invocation: false

package/template/.agents/skills/instance-test/references/instances.md

@@ -0,0 +1,75 @@
+# Instances for matt-skills — sync 行为功能测试（由 scaffold-functional-test 生成）
+
+> 源 spec：`.scratch/sync-merge-update/spec.md`
+> spec hash: `062a76fc872d`  # .scratch/sync-merge-update/spec.md 的 sha256 前 12 位
+> generatedAt: 2026-05-11
+> 推导策略：混合推导（验收标准锚点 + 需求/行为补充），每实例含溯源，无溯源视为幻觉
+
+本文件由 `scaffold-functional-test` 按**受控扩展模型**生成：必选 `prompt/command/expected files/content/expected stdout phrases/expected exit code`，可选 `setup/env/timeout/type/teardown`，默认 `type: cli`。执行语义：`mktemp -d` 隔离、单线程串行、`PASS m/n` 汇总、证据含 `expected vs actual` diff + `run dir`。
+
+执行前校验：对比当前 `.scratch/sync-merge-update/spec.md` 的 hash 与本文件头部 `spec hash`，不一致时提示「spec 已变更，建议重跑 scaffold-functional-test」但不自动覆盖。
+
+---
+
+## 1. sync 默认 check（无参不写盘）
+
+- Prompt: 验证 `matt-skills sync` 无参等价 check，打印表且不改 AGENTS.md
+- 溯源: spec.md — 需求/行为「`matt-skills sync` 无参：等价 `check`」+ 验收标准「`sync` 无参在已定制的 `pi-switch` 仓库上不改 `AGENTS.md`」
+- type: cli
+- setup: `node bin/cli.js init --dest <tmp>` 后手工改 `AGENTS.md` 加入 `tdd-implement` 定制行
+- Command: `node bin/cli.js sync --dest <tmp>`（无参）
+- Expected:
+  - `git diff HEAD -- AGENTS.md` 为空（`AGENTS.md` 未被覆盖）
+  - stdout 含 `上游 HEAD` 与 `新增/更新/删除/一致` 表头
+  - stdout 含 `--json` 可解析提示或表格行
+  - exit 0 或 1（有差异时 exit 1，判 exit code 符合 check 语义）
+- Expected files/content: `AGENTS.md` 保留定制行，无 `AGENTS.md.bak` 新增
+- Expected stdout phrases: `上游 HEAD`, `一致`
+- Expected exit code: 1（有差异时）/ 0（无差异时）— 按实现定义，测试以实际 check 语义为准
+
+## 2. sync --apply 安全增量（AGENTS.md 跳过、上游强制覆盖不删）
+
+- Prompt: 验证 `sync --apply` 为安全增量，`AGENTS.md` 定制跳过、上游技能被覆盖但 remove 列表不删
+- 溯源: spec.md — 需求/行为「`sync --apply`：安全增量写盘。`AGENTS.md` 若含独有路由则跳过；上游技能 `rm+cp force` 覆盖，跳过 `PROPRIETARY`，不执行 `remove`」+ 验收标准「`sync --apply` 后上游技能被强制更新为上游 `HEAD`，`remove` 列表的技能仍保留」
+- type: cli
+- setup: 在 `<tmp>` 放置旧版上游技能 `test-skill` 过期文件，并手工改 `AGENTS.md`
+- Command: `node bin/cli.js sync --apply --dest <tmp>`
+- Expected:
+  - `AGENTS.md` 仍含定制行（未被模板覆盖）
+  - 上游技能文件已更新为上游 HEAD 内容（`diff` 无旧版残留）
+  - `remove` 列表中的技能目录仍存在（未被删除）
+- Expected files/content: `AGENTS.md` 定制行存在；`test-skill` 被覆盖为新版；无 `AGENTS.md.bak`（安全档不备份）或按实现保留但不覆盖
+- Expected stdout phrases: `已同步` 或 `已更新` 或 `同步`
+- Expected exit code: 0
+- timeout: 30000
+
+## 3. sync --force 硬盖（AGENTS.md 备份后覆盖、全量 add/update/remove）
+
+- Prompt: 验证 `sync --force` 硬盖，`AGENTS.md` 备份后被模板覆盖、技能与模板全量同步含删除
+- 溯源: spec.md — 需求/行为「`sync --force`：硬盖。`AGENTS.md` 先 `backupIfExists → .bak` 再 `cp -r force`；技能与模板均 `add/update/remove` 全做」+ 验收标准「`sync --force` 后 `AGENTS.md` 变为模板且 `AGENTS.md.bak` 存在，`remove` 列表的技能被删除」
+- type: cli
+- setup: 在 `<tmp>` 放置 `AGENTS.md` 定制行 + 一个上游已删的本地技能 `obsolete-skill/`
+- Command: `node bin/cli.js sync --force --dest <tmp>`
+- Expected:
+  - `AGENTS.md` 已被模板覆盖（定制行消失，与 `template/AGENTS.md` 一致）
+  - `AGENTS.md.bak` 存在且含定制行备份
+  - `obsolete-skill/` 已被删除
+- Expected files/content: `AGENTS.md` 内容等于 `template/AGENTS.md`；`AGENTS.md.bak` 存在
+- Expected stdout phrases: `已覆盖` 或 `硬盖`
+- Expected exit code: 0
+
+## 4. update 已合并到 sync --apply（删除分支、提示已合并）
+
+- Prompt: 验证 `matt-skills update` 已删除，执行后报错提示已合并到 `sync --apply`，且 `--help` 不再列 `update`
+- 溯源: spec.md — 需求/行为「`matt-skills update`：删除该分支，`main` 中 `command === 'update'` 改为 `stderr: 'update 已合并到 sync --apply'` 且 `exit 1`，`--help` 不再列 `update`」+ 验收标准「`matt-skills update` 执行后报错提示已合并，`--help` 无 `update`」
+- type: cli
+- Command: `node bin/cli.js update 2>&1; echo "exit:$?"` 与 `node bin/cli.js --help`
+- Expected:
+  - `update` 命令 stdout/stderr 含 `已合并到 sync --apply` 且 exit 1
+  - `--help` 输出不含独立的 `update` 子命令行（不匹配 `^\s*update`）
+- Expected stdout phrases: `已合并到 sync --apply`
+- Expected exit code: 1（`update` 分支）
+- env: {}
+
+<!-- manual -->
+<!-- 以下为人工定制实例保护段：由开发者手写，scaffold-functional-test 重生成时不覆盖此段以上的内容。如需新增手工实例，请在此段后追加。 -->

package/template/.agents/skills/prototype/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain expert) and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste, so make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic (the bit that's answering the question) in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer**: `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine**: explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state, just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS: no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language**, not code: buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state**: the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons**: one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs**: a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario (the situation it sets up and what to watch for) and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases, the ones hard to reason about on paper: the happy path, a tricky edge case, an attempt at something that should be illegal.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks: nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different"; those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps the prototype as a primary source, and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

package/template/.agents/skills/prototype/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered, using the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a single shareable HTML file (free-play buttons plus tabbed guided walkthroughs) that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts, so getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious, but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **Trivial to run.** A UI prototype starts from one command in the project's task runner: `pnpm <name>`, `python <path>`, `bun <path>`, etc. A logic demo is a single HTML file the user double-clicks. Either way, no thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE, wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too (the verdict and the question it settled) in the issue or a commit. The main branch keeps only the validated decision.