dsh-pstack 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/skills/authored/decision-write/SKILL.zh.md

@@ -0,0 +1,131 @@
+---
+name: decision-write
+description: 撰写、更新、落地或取代决策记录。用于已定取舍、缺失设计理由、推翻决策或任何记录文件改动；落地模式查找并校验实现。
+---
+
+# 撰写或更新决策记录
+
+将一项已收敛的选择交付为经校验的记录和证据报告。所有记录修改都通过本技能；`decision-audit` 只读报告。
+
+## 入口规则
+
+任何对 `Status`、`Implemented-by`、`Superseded-by`、`Review`、正文或链接的修改都执行本流程。流程无法运行时停下报告；本规则优先于 `<dir>/AGENTS.md` 中允许直接编辑的约定。
+
+## 定位记录目录
+
+检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`：
+
+- 只有一个存在：记为 `<dir>`，沿用其命名约定，并在存在时读取其 `AGENTS.md`。
+- 多个存在：询问哪个是当前目录并等待。
+- 都不存在：说明本仓库不保存决策记录，建议使用 `/setup-project-docs`，然后停止。
+
+`AGENTS.md` 与 `README.md` 是约定而非记录；检索、分类与更新都排除它们。
+
+## 选择模式
+
+- **撰写：** 没有既有记录拥有这个决策、新记录取代旧记录，或既有记录需要实质更新正文或关系。重复与部分重叠的归类留在撰写模式；明确的状态字段更新走落地。执行步骤 1–5，在步骤 6 展示确认关口，仅在确认后写入，再执行步骤 7 报告。
+- **落地：** 用户明确要求把既有记录标为 `accepted` 或更新其状态字段。执行步骤 4、5、7。记录路径加 `accepted` 就是足够输入；不要自行进入落地。未给出路径时，列出 `Scope` 匹配落地改动的记录并询问更新哪一条。
+
+## 1. 确认选择
+
+先从改动与讨论中取得全部三项，只询问缺失内容并等待：
+
+- **目标：** 这个决策要解决的问题。
+- **约束：** 排除某个选项的边界。
+- **备选方案：** 实际被否决的选项，或者只考虑过单一候选这一明确事实。
+
+## 2. 查找相关记录
+
+用主题、受影响模块和备选方案的专有词检索：
+
+```bash
+grep -ril --exclude=AGENTS.md --exclude=README.md \
+  -e "<关键词 1>" -e "<关键词 2>" <dir>/*.md
+```
+
+读取每个命中至第一个 `## ` 标题；头部无法区分归类，或无法提供更新所需内容时再读正文。检索过宽时收紧关键词，不通读整个目录。给每个命中分类：
+
+- **重复：** 既有记录拥有这个决策。更新该记录，不另写第二条。
+- **完全取代：** 起草新记录，让两条记录互相链接；把旧记录的取代变更放进确认关口。
+- **部分重叠：** 保留两者，互相链接，并更正已变化的事实。
+- **无关：** 不作修改。
+- **未决：** 将关系与需要人工回答的问题带入报告。
+
+每个命中都有归类、每项由此产生的修改都已明确时，本步完成。
+
+## 3. 起草记录
+
+遵循 `<dir>/AGENTS.md`，包括标题语言；没有该文件时使用：
+
+```markdown
+# Decision: <one-line title>
+
+Status: proposed | accepted | superseded
+Date: YYYY-MM-DD
+Scope: <glob>[, <glob>...]
+Implemented-by: <PR #N | commit:SHA | ->
+Review: YYYY-MM-DD
+Superseded-by: <记录路径> — <一句原因>   （仅 Status 为 superseded 时）
+
+## Background
+## Decision
+## Alternatives
+## Consequences
+```
+
+让 `Background` 脱离所选方案也能读懂。已接受的记录在 `Decision` 中用现在时描述系统。每个实际考虑过的备选方案独立成段并写明落选原因；只有单一候选时如实说明。
+
+## 4. 设定状态并校验锚点
+
+`Status` 与 `Implemented-by` 是一对。按证据选中下表的一行，并在同一次修改中写入两个字段：
+
+| 证据 | Status | Implemented-by |
+|---|---|---|
+| 没有可核验的落地锚点 | `proposed` | `-` |
+| `PR #N` 为 `MERGED` | `accepted` | `PR #N` |
+| `commit:SHA` 是默认分支的祖先 | `accepted` | `commit:SHA` |
+| 用户确认仅记录提交的例外 | `accepted` | `commit:<记录提交>` |
+| 被更新的草稿取代 | `superseded` | 保留原值 |
+
+新记录在落地前保持 `proposed`。`Implemented-by` 指向实现改动；追溯性记录指向更早的实现。仅记录提交必须走用户确认的例外。squash 合并的仓库优先用已合并 PR。
+
+落地模式没有给定锚点，或需要“仅记录提交”例外时，编辑前读取[查找并校验实现](references/land.zh.md)。校验其他已有锚点时，只执行该参考中的校验流程，不执行查找步骤。
+
+`<base>` 取仓库默认分支，并报告选中的 ref。校验每个锚点；证据不可用或基线无法解析时，新记录保持 `proposed` + `-`。既有 `accepted` 记录的锚点校验失败时，停下报告，不静默降级。只改证据要求的字段；单独推进 `Review` 不改变状态。
+
+新草稿取代旧记录时，在同一次获批的修改中把旧记录改为 `superseded`，即使旧记录原为 `accepted`。保留旧正文与锚点，添加互链，并在 `Review` 下方写 `Superseded-by: <新记录路径> — <一句原因>`。原因缺失时先询问并等待。原为 `proposed` 的旧记录保留 `Implemented-by: -`。
+
+## 5. 检查范围覆盖改动
+
+调用方提供 `scope` 路径时直接使用。带已核验实现改动的落地分支，用以下命令列出实现路径：
+
+```bash
+gh pr view N --json files --jq '.files[].path'
+git show --pretty=format: --name-only SHA
+```
+
+经确认的“仅记录提交”回退跳过本项检查，并在报告中说明例外。其他分支收集相对基线的提交与未提交改动：
+
+```bash
+git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
+git status --porcelain=v1 --untracked-files=all
+```
+
+解析 `git status` 中的路径，重命名取目标路径。每条新增或更新的记录都必须有至少一个所选改动路径匹配其 `Scope` glob。全部不匹配时，询问是放宽 glob，还是该记录不属于这次改动。将匹配路径留作报告。
+
+## 6. 草稿确认关口
+
+每次撰写写入（包括重复记录的更新）都要展示每条新增或更新记录的完整结果，以及每个相关记录的分类。包括每项拟议的旧记录取代变更及其 `Superseded-by` 路径和原因。请求用户明确确认并等待。确认后严格应用获批的修改；草稿被拒绝时保持所有文件不变。
+
+## 7. 报告
+
+覆盖每个检索命中、改动的记录、关系判断、锚点校验、范围匹配和未决问题。等待落地的 `proposed` 记录在合并后需要一次“落地”更新。报告查到的实现及其改动路径；仅记录锚点须标明为经确认的例外。包括每个 `Superseded-by` 路径和原因。
+
+```text
+Record: docs/decisions/2026-10-27-use-postgres.md
+Status: accepted
+Related: 2026-03-02-mysql-setup.md -> overlapping, cross-linked
+Anchor: PR #412 -> MERGED (gh pr view 412 --json state,files)
+Scope: src/db/** matched src/db/client.ts
+Open: none
+```

package/dist/skills/authored/decision-write/references/land.md

@@ -0,0 +1,48 @@
+# Find and verify the implementation
+
+Use this reference for Land anchor discovery, record-only fallback, and anchor verification. The main skill owns status pairs, supersession, scope, approval, and reporting.
+
+## Find the implementation
+
+In Land when no candidate anchor is available, search commits and merged PRs touching the record's `Scope`:
+
+```bash
+git log --since=<Date> --format='%H %cs %s' -- <Scope paths>
+gh pr list --state merged --search "<record title or scope keyword>" --json number,title,mergedAt,files --limit 20
+```
+
+If `Scope` is absent, search commit subjects and PR titles for the record's title or keywords. Start at its `Date`; for a retrospective record, also inspect recent commits before `Date` that touch `Scope`. If `gh` is unavailable, search commits and report that PR discovery was skipped.
+
+Keep candidates whose changed paths intersect `Scope` and include at least one path outside `<dir>`; a change containing only decision records is not an implementation. Use one clearly matching candidate's `PR #N` or `commit:SHA`. If several match, list their dates, titles, and paths and ask which one. If none matches, use the fallback below.
+
+## Record-only fallback
+
+When no implementation exists and the user still wants `accepted`, explain both points and wait for explicit confirmation:
+
+- **Reason:** the record commit records the decision but does not implement it, so the anchor would claim a landing that never happened.
+- **Consequence:** `decision-audit` reports this anchor as a C finding; a later implementation should replace it.
+
+Ask whether to use `commit:<record-commit>` or leave `proposed` + `-`. Use `accepted` + `commit:<record-commit>` only after confirmation, and report the exception. This exception overrides an `<dir>/AGENTS.md` ban on record-only anchors. If that commit is outside the default branch, retain `proposed` + `-` until it merges.
+
+## Verify the anchor
+
+Resolve `<base>` as the default branch:
+
+```bash
+git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null ||
+  git rev-parse --verify origin/main 2>/dev/null ||
+  git rev-parse --verify origin/master 2>/dev/null ||
+  git rev-parse --verify main 2>/dev/null ||
+  git rev-parse --verify master 2>/dev/null
+```
+
+Verify every proposed `Implemented-by` value:
+
+| Value | Command | Verified when |
+|---|---|---|
+| `PR #N` | `gh pr view N --json state,files` | `state` is `MERGED` and the change implements the decision |
+| `commit:SHA` | `git merge-base --is-ancestor SHA <base>` | Exit code 0 and the change implements the decision |
+
+List candidate paths with `gh pr view N --json files --jq '.files[].path'` or `git show --pretty=format: --name-only SHA`. A real implementation intersects `Scope` and includes a path outside `<dir>`; a record-only anchor needs the confirmed exception. Return these paths to the scope check.
+
+For unlanded work, failed verification, unavailable `gh`, or an unresolved `<base>`, write `proposed` + `-` and report the evidence or attempted refs. An unresolved base also blocks base-relative scope checks; use caller-supplied paths or report that evidence as unavailable. Never demote an existing `accepted` record on failed verification; return its broken anchor to the main skill's stop-and-report rule.

package/dist/skills/authored/decision-write/references/land.zh.md

@@ -0,0 +1,48 @@
+# 查找并校验实现
+
+本参考用于落地锚点查找、仅记录提交回退和锚点校验。状态成对、取代、范围、确认和报告规则见主技能。
+
+## 查找实现
+
+落地模式没有可用的候选锚点时，检索触及记录 `Scope` 的提交与已合并 PR：
+
+```bash
+git log --since=<Date> --format='%H %cs %s' -- <Scope paths>
+gh pr list --state merged --search "<记录标题或范围关键词>" --json number,title,mergedAt,files --limit 20
+```
+
+没有 `Scope` 时，用记录标题或关键词检索提交主题与 PR 标题。从记录的 `Date` 开始；追溯性记录也检查 `Date` 之前最近触及 `Scope` 的提交。`gh` 不可用时只检索提交，并报告已跳过 PR 查找。
+
+保留改动路径与 `Scope` 相交、且至少有一个 `<dir>` 之外路径的候选；只含决策记录的改动不是实现。只有一个明确候选时，用它的 `PR #N` 或 `commit:SHA`。多个候选时列出日期、标题、路径并询问选哪个。没有候选时走下面的回退。
+
+## 仅记录提交的回退
+
+没有找到实现、而用户仍要求 `accepted` 时，解释以下两点并等待明确确认：
+
+- **原因：** 记录提交只记录决策，没有实现它，锚点会声称一个并未发生的落地。
+- **后果：** `decision-audit` 会把该锚点报为 C 类发现；后续实现落地后应替换它。
+
+直接询问是用 `commit:<记录提交>`，还是保持 `proposed` + `-`。只有用户确认后才写 `accepted` + `commit:<记录提交>`，并在报告中说明例外。本例外优先于 `<dir>/AGENTS.md` 中禁止仅记录锚点的约定。记录提交不在默认分支时，保持 `proposed` + `-` 直到合并。
+
+## 校验锚点
+
+将 `<base>` 解析为默认分支：
+
+```bash
+git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null ||
+  git rev-parse --verify origin/main 2>/dev/null ||
+  git rev-parse --verify origin/master 2>/dev/null ||
+  git rev-parse --verify main 2>/dev/null ||
+  git rev-parse --verify master 2>/dev/null
+```
+
+校验每个拟写入的 `Implemented-by` 值：
+
+| 值 | 命令 | 通过条件 |
+|---|---|---|
+| `PR #N` | `gh pr view N --json state,files` | `state` 为 `MERGED`，且改动实现该决策 |
+| `commit:SHA` | `git merge-base --is-ancestor SHA <base>` | 退出码为 0，且改动实现该决策 |
+
+用 `gh pr view N --json files --jq '.files[].path'` 或 `git show --pretty=format: --name-only SHA` 列出候选路径。真实实现与 `Scope` 相交，且至少有一个 `<dir>` 之外的路径；仅记录锚点需要经确认的例外。将这些路径交给范围检查。
+
+改动未落地、校验失败、`gh` 不可用或 `<base>` 无法解析时，写入 `proposed` + `-`，并报告证据或尝试过的 ref。基线无法解析也会阻止相对基线的范围检查；此时使用调用方提供的路径，或报告该证据不可用。既有 `accepted` 记录校验失败时不得降级；回到主技能的停下报告规则处理断裂锚点。

package/dist/skills/authored/setup-project-docs/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: setup-project-docs
+description: Bootstrap architecture, glossary, decision-record documentation, and root agent-doc pointers; rerun to fill approved gaps.
+disable-model-invocation: true
+---
+
+# Set up project docs
+
+Create or complete living project documentation and its context pointers. Obtain approval before writing or modifying files.
+
+| Piece | Answers | Default location |
+|---|---|---|
+| Architecture | What is the system now? | `docs/architecture.md` |
+| Glossary | What is each concept called? | `docs/glossary.md` |
+| Decision records | Why did it turn out this way? | `docs/decisions/` |
+| Pointers | When should an agent open each document? | Root `AGENTS.md` |
+
+## 1. Inventory the repository
+
+Inspect root `AGENTS.md`, existing architecture and glossary documents, and `docs/decisions/`, `docs/adr/`, `doc/adr/`. Reuse existing homes and conventions. If several decision directories exist, ask which is current and wait.
+
+Read build and workspace configuration, real directories, and entry points until every principal module has a source-backed responsibility. Finish with an outline for each proposed document and an explicit list of facts the repository cannot supply.
+
+## 2. Confirm the plan
+
+Present existing, missing, and proposed paths. Lead with recommendations for decisions the repository cannot supply:
+
+- **Decision records:** recommend them when choices are costly to reverse; a small script or disposable prototype usually needs none. Declining leaves the related skills inert.
+- **Glossary layout:** recommend one file; split by context only for genuinely separate bounded contexts.
+
+Confirm the proposed paths and content. On a rerun, limit the plan to missing pieces and stale pointers. Step 3 supplies the final write approval.
+
+## 3. Draft source-backed content
+
+- **Architecture:** use a module table with real directories and entry points. Document dependency direction and extension points demonstrated by the code; put rationale in decision records.
+- **Glossary:** define three to five existing code terms whose ambiguity could produce divergent names.
+- **Decisions:** create no placeholder record. Leave any real record to `decision-write`; this skill only scaffolds the directory and conventions.
+- **Decision conventions:** when enabled, write `<dir>/AGENTS.md` following [the decision-record conventions](references/decision-conventions.md).
+
+Present every draft together and obtain approval before writing. The approved set is the write plan.
+
+## 4. Write or update
+
+Create or update exactly the approved paths, editing existing files in place. Keep one `## Project docs` block in root `AGENTS.md`, adapted to its language and actual paths:
+
+```markdown
+## Project docs
+
+- Read `docs/architecture.md` before changing a module; update it when module boundaries or entry points change.
+- Read `docs/glossary.md` when naming a concept; add terms when introducing concepts.
+- Before writing or reviewing decisions, read `docs/decisions/AGENTS.md` for format and search conventions.
+```
+
+Lead each pointer with its trigger and target; include only approved branches. Point decision work to the plain reference.
+
+## 5. Verify and report
+
+Confirm that root `AGENTS.md` contains one `## Project docs` block, every approved path was written or updated, and every pointer resolves from the repository root. Report written, updated, and skipped paths with reasons. State that pointers take effect in the next session.

package/dist/skills/authored/setup-project-docs/SKILL.zh.md

@@ -0,0 +1,58 @@
+---
+name: setup-project-docs
+description: 初始化架构、术语表、决策记录文档及根目录 agent 文档指针；重跑时补齐已批准的缺口。
+disable-model-invocation: true
+---
+
+# 建立项目文档
+
+创建或补齐持续维护的项目文档及其上下文指针。写入或修改文件前必须获得批准。
+
+| 部分 | 回答 | 默认位置 |
+|---|---|---|
+| 架构 | 系统现在是什么？ | `docs/architecture.md` |
+| 术语表 | 每个概念叫什么？ | `docs/glossary.md` |
+| 决策记录 | 为何演变成现在这样？ | `docs/decisions/` |
+| 指针 | agent 何时打开每份文档？ | 根目录 `AGENTS.md` |
+
+## 1. 盘点仓库
+
+检查根目录 `AGENTS.md`、既有架构与术语文档，以及 `docs/decisions/`、`docs/adr/`、`doc/adr/`。沿用已有路径与约定。存在多个决策目录时，询问哪个是当前目录并等待。
+
+读取构建与工作区配置、真实目录和入口点，直到每个主要模块的职责都有代码依据。最终为每份拟建文档形成提纲，并明确列出仓库无法提供的事实。
+
+## 2. 确认计划
+
+列出已有内容、缺失内容与拟用路径。对仓库无法决定的事项先给建议：
+
+- **决策记录：** 选择难以逆转时建议启用；小脚本或一次性原型通常不需要。拒绝会让相关技能保持惰性。
+- **术语表布局：** 建议单个文件；仅对真正独立的限界上下文按上下文拆分。
+
+确认拟用路径与内容。重跑时，计划只覆盖缺失部分和失效指针。步骤 3 提供最终写入批准。
+
+## 3. 起草有依据的内容
+
+- **架构：** 用真实目录与入口点列出模块表；记录代码已体现的依赖方向与扩展点，理由写入决策记录。
+- **术语表：** 定义代码中已有且易引发不同命名的三到五个术语。
+- **决策记录：** 不创建占位记录。真实决策交给 `decision-write`；本技能只搭建目录与约定。
+- **决策约定：** 启用时，按[决策记录约定](references/decision-conventions.zh.md)起草 `<dir>/AGENTS.md`。
+
+集中展示所有草稿，获得批准后再写入。批准集合就是写入计划。
+
+## 4. 写入或更新
+
+只创建或更新已批准的路径，既有文件就地编辑。根目录 `AGENTS.md` 只保留一个 `## Project docs` 块，并适配其语言与实际路径：
+
+```markdown
+## Project docs
+
+- Read `docs/architecture.md` before changing a module; update it when module boundaries or entry points change.
+- Read `docs/glossary.md` when naming a concept; add terms when introducing concepts.
+- Before writing or reviewing decisions, read `docs/decisions/AGENTS.md` for format and search conventions.
+```
+
+每条指针以触发条件和目标开头，只包含已批准的分支。决策工作指向普通参考文档。
+
+## 5. 验证并报告
+
+确认根目录 `AGENTS.md` 只有一个 `## Project docs` 块，每个已批准的路径均已写入或更新，且每个指针都能从仓库根目录解析。报告写入、更新和跳过的路径及原因。说明指针从下个会话开始生效。

package/dist/skills/authored/setup-project-docs/references/decision-conventions.md

@@ -0,0 +1,11 @@
+# Decision-record conventions
+
+When decision records are enabled, draft `<dir>/AGENTS.md` as the repository's authoritative format, scope, status, and search reference. Include:
+
+- The five-field header: `Status`, `Date`, `Scope`, `Implemented-by`, `Review`.
+- The status/anchor pair rule and transitions, including immediate supersession by a new draft. A replaced `proposed` record retains `Implemented-by: -`; preserve its body rather than deleting or reverting it.
+- Related-record search and classification.
+- `decision-write` as the entry rule for every record change.
+- `Superseded-by` with the replacing record path and one-line reason for every `superseded` record.
+
+Adapt `decision-write`'s fallback template to the repository's language and conventions. Require a real implementation anchor to intersect `Scope` and include a path outside `<dir>`. Permit a record-only commit only through `decision-write`'s explicitly confirmed Land exception, and state that audits continue to report it.

package/dist/skills/authored/setup-project-docs/references/decision-conventions.zh.md

@@ -0,0 +1,11 @@
+# 决策记录约定
+
+启用决策记录时，起草 `<dir>/AGENTS.md`，作为仓库中格式、范围、状态与检索规则的权威参考。包括：
+
+- 五字段头部：`Status`、`Date`、`Scope`、`Implemented-by`、`Review`。
+- 状态/锚点成对规则与状态流转，包括新草稿立即取代旧记录。被取代的 `proposed` 记录保留 `Implemented-by: -`；保留旧正文，不删除、不回退。
+- 相关记录检索与分类。
+- 以 `decision-write` 作为所有记录修改的入口。
+- 每条 `superseded` 记录都带 `Superseded-by`，包含替代记录路径和一句原因。
+
+以 `decision-write` 的回退模板为基础，适配仓库的语言与约定。真实实现锚点的路径须与 `Scope` 相交，且至少一个路径在 `<dir>` 之外；仅允许通过 `decision-write` 落地模式中经用户明确确认的例外使用仅记录提交，并写明审计仍会报告该例外。

package/dist/skills/vendored/retro/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: retro
+description: "Conduct a retrospective on a coding session."
+disable-model-invocation: true
+---
+
+The user has asked for a **retrospective**. You are suggesting improvements to the coding agent's **environment** to improve future runs.
+
+## Steps
+
+1. Call the Skill tool with `writing-for-agents` for the writing style guide.
+
+2. Read the primary sources for the session the user specifies. This may mean searching through session logs on this machine. If the user doesn't specify a session, default to the current one.
+
+3. Look for candidates for improvement in these categories.
+
+- **Navigation**: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a **navigation pointer** make it easier? _Use when_ the session took a long time to find a piece of information.
+- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its `package.json`/build-tool `lint`/`check` scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no **guardrail** (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. _Use when_ the agent made a mistake an automated check could have caught, or the repo has no guardrail at all.
+- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a **mechanical** one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve `CODING_STANDARDS.md` for genuine **judgement calls** (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). _Use when_ the reviewer agent failed to catch a mistake.
+- **Global AGENTS.md**: are there any steering instructions that should be moved to coding standards (or automated checks) instead? _Use when_ the AGENTS.md file is particularly large - in the repo OR the user's global scope.
+- **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? _Use when_ the agent made an expensive tool call.
+- **No-ops**: look for instructions in steering files that don't modify the agent's behavior. _Use when_ the steering files are large and unwieldy.
+- **Information access**: look for opportunities to increase the agent's access to information. Teeing dev server logs, readonly access to third-party services. _Use when_ a crucial piece of information was not available to the agent.
+
+4. Present these candidates to the user, in order of severity.
+
+## Reference
+
+### Implementation vs Review
+
+Remember that all work goes through two stages: implementation and review. The implementation agent has the most **context pressure**. They are responsible for exploration, writing code, and debugging failures.
+
+The review agent has the least context pressure - it receives a diff, so no exploration needed. It often does not need to write code or debug.
+
+This means that the review agent should be responsible for imposing coding standards, not the implementation agent.
+
+### Files
+
+You have access to several files in the repo:
+
+- `CLAUDE.md`/`AGENTS.md`: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for **navigation pointers** to other files.
+- `CODING_STANDARDS.md`: this file is read during review, not implementation. Add **navigation pointers** to docs folders if the standards file gets more than 1,000 lines long.
+- Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones.
+- Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the `writing-for-agents` skill.

package/dist/skills/vendored/retro/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Retro"
+  short_description: "Conduct a retrospective on a coding session."
+policy:
+  allow_implicit_invocation: false

package/dist/skills/vendored/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,22 @@
+# Skill mechanics
+
+The skill-specific branch of [`writing-for-agents`](SKILL.md): what changes when the document is a skill (frontmatter, the invocation choice, and router skills). Everything else about writing it is the universal reference in `SKILL.md`.
+
+## Invocation
+
+Two choices, trading the two loads:
+
+- A **model-invoked** skill keeps a `description`, so the agent can fire it autonomously, and other skills can reach it. You can still type its name: model-invocation always _includes_ user reach; a description only ever adds agent discovery, never removes the human's. The description is the skill's top-level context pointer, forced to stay loaded at all times: permanent context load in exchange for discoverability. A model-invoked skill whose content is all reference is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Mechanics: omit `disable-model-invocation`, and write a model-facing description carrying the trigger branches (the pointer-writing rules in `SKILL.md` apply in full).
+- A **user-invoked** skill strips the description from the agent's reach: only the human typing its name can invoke it, and no other skill can. Zero context load, but it spends cognitive load: you are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing: a one-line summary, trigger lists stripped.
+
+Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
+
+Shared reference that two user-invoked skills both need can live in neither: with no descriptions, neither can fire the other. Push it to a plain file outside the skill system: external reference any skill can point at.
+
+## Splitting by invocation
+
+The invocation cut of splitting (the sequence cut lives in `SKILL.md`): split off a model-invoked skill when you have a distinct leading word that should trigger it on its own (a trigger word you actually use in your prompts), or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
+
+## Router skills
+
+When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each, so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them.

package/dist/skills/vendored/writing-for-agents/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: writing-for-agents
+description: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
+---
+
+Reference for writing any document an agent consumes: a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same _process_ every run rather than producing the same output.
+
+When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.
+
+## Context pointers
+
+A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs: state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
+
+- **Front-load the leading word**: the pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
+- **Cut identity the body already carries.**
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** is the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires.
+- **Cognitive load** is the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise: it is the price of human agency; spend it where human judgement matters, remove it where it does not.
+
+Material reached only through a pointer escapes context load at the price of the pointer's own line; material with no pointer at all rides entirely on cognitive load.
+
+## Information hierarchy
+
+A document is built from two content types: **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand). The two mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-file step** is the primary tier: what the agent does, in order.
+2. **In-file reference** is consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung), which is a fine arrangement, not a smell.
+3. **Disclosed reference** is pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder (out of the main file and behind a pointer) so the top stays legible. Not primarily a token optimisation: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. When a document has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip: a variance lever, not just a legibility one.
+
+**Co-location** is the within-file companion: where the ladder decides _how far down_ a piece sits, co-location decides _what sits beside it_ once there. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. The test: the document should read like documentation written for the agent. Grouped material reads that way; scattered material does not. (Distinct from duplication: that repeats one meaning in two places; scattering fragments one meaning across many.)
+
+**Sprawl** is the failure mode here: a document simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion**, the condition that tells the agent the work is done. Two properties make it a lever:
+
+- **Clarity**: can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: ending the step before it is genuinely done, attention slipping to _being done_. The visible steps still ahead (the **post-completion steps**) supply the pull; the criterion's clarity is the resistance. Defend in order: **sharpen the bound first** (local and cheap); only if it is irreducibly fuzzy _and_ you observe the rush, hide the later steps by splitting the sequence. Hiding only works across a real context boundary (a hand-off or a subagent dispatch; an inline call leaves the later steps in context and clears nothing).
+- **Demand**: how much it requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives **legwork** (the digging the agent does within the work, latent in the wording rather than written as its own step), and it is not step-bound: "every rule applied" binds a body of flat reference just as "every step done" binds a sequence, which is how an all-reference document still carries an exhaustiveness bar.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By sequence**: split a run of steps where the post-completion steps tempt the agent to rush the one in front of it. Keeping them out of view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's later steps to what follows, inviting premature completion.
+- **By invocation**, skill-specific: see [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md).
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the document (_lesson_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits no priors: you pay in definition tokens what a pretrained word gives free; reach for an existing word first.
+
+It anchors twice. In the body, _execution_: the agent reaches for the same behaviour every time the word appears, and inside flat reference it focuses attention on a class of thing to look for. In a pointer, _invocation_: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the material and reaches it more reliably.
+
+Hunt for opportunities to refactor with leading words. A triad spelled out at three sites, a pointer spending a sentence to gesture at one idea. Each is a passage begging to collapse into a single token:
+
+- "fast, deterministic, low-overhead" → _tight_ (a _tight_ loop).
+- "a loop you believe in" → _red_, turning a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every document is carrying restatements that leading words retire. Go find them.
+
+**Negation** is the failure mode beside this lever: steering by prohibition drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Prompt the **positive**: state the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** (the same meaning in more than one place) costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.)
+- The **environment** is a source of truth too (`package.json` scripts, config files, the directory layout, `--help` output), and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
+- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live.
+- Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test (does it change behaviour versus the default?) is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The test also grades leading words: a word too weak to beat the default (_be thorough_ when the agent is already thorough-ish) is a no-op, and the fix is a stronger word (_relentless_), not a different technique.

package/dist/skills/vendored/writing-for-agents/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Writing for Agents"
+  short_description: "Write documents agents consume"