@namewta/speculo 0.3.4 → 0.5.0

package/template/skills/docs-sync/references/agents/agent-writing.md

@@ -0,0 +1,75 @@
+# Agent 文档写作
+
+任何由 agent 消费的文档的撰写参考——一份 skill、一个 `AGENTS.md` / `CLAUDE.md`、一份通过指针到达的文档。包装形式不同，撰写之道相同：同样的杠杆让每一份文档都可预测——agent 每次都走相同的*流程*，而不是产出相同的输出。
+
+## 上下文指针
+
+**上下文指针（context pointer）** 是 agent 上下文中持有的一条引用，它指明某份上下文之外的资料，并编码了到达它的条件。一份 skill 的 description 是指针；`AGENTS.md` 中一行指向某文档的引用，也是同一个东西。决定 agent 何时——以及多可靠地——到达该资料的，是指针的*措辞*，而不是它的目标。一个措辞薄弱的指针指向一份必读资料，就是一个变异 bug：先打磨措辞；只有打磨失败时，才把资料内联进来。
+
+指针承担两项工作——说明资料是什么，并列出应触发到达它的**分支**（branch 是文档处理的某个不同情况，因此不同运行会走不同的路径）。一个始终加载的指针，每个字都要在每一轮对话中付出成本，所以它比正文更需要被毫不留情地精简：
+
+- **前置引导词**——触发工作是在指针上完成的。
+- **每个分支一个触发器。** 只是给同一分支换了个说法的同义词，等于把同一个分支写了两遍；把它们合并，只保留真正不同的分支。
+- **删掉正文已经承载的身份信息。**
+
+## 两种负载
+
+你添加的每份文档和每个指针，都要花掉两种预算之一：
+
+- **上下文负载（context load）**——始终加载的资料对 agent 窗口的代价：`AGENTS.md` 里的一行、一份 skill 描述、任何每轮对话都待在上下文里的东西，无论是否触发，都在消耗 token 和注意力。
+- **认知负载（cognitive load）**——对人类的代价：存在哪些文档、何时该去取哪一份。人类就是索引。这不是需要最小化的成本——它是人类主动性的价格；在人类判断重要的地方花它，在无关紧要的地方拿掉它。
+
+只通过指针到达的资料，免去了上下文负载，代价是指针自身的那一行；完全没有指针的资料，则完全压在认知负载上。
+
+## 信息层级
+
+一份文档由两种内容类型构成——**步骤**（agent 执行的有序操作）和**参考**（按需查阅的定义、规则、事实）——两者自由混合：全是步骤（一份菜谱）、全是参考（一次 review 的规则、本技能），或两者兼有。核心决策是每一块内容在**信息层级**上所处的位置，这是一把按 agent 需要资料的即时程度排序的梯子：
+
+1. **文件内步骤**——第一层级：agent 做什么，按顺序。
+2. **文件内参考**——按需查阅。它常常是一个合理扁平的并列集合（一次 review 的全部规则在同一条横档上）——这没什么不好，不是坏味道。
+3. **外置参考（disclosed reference）**——推到独立文件里，通过上下文指针到达，只在指针触发时加载。从同一文件夹的兄弟文件，一直到住在任何地方、任何文档都能指向的完全外部参考。
+
+推得太少，顶层会臃肿；推得太多，你会把 agent 真正需要的资料藏起来。这个张力就是全部决策所在。
+
+**渐进式披露（progressive disclosure）** 是沿梯子向下的移动——从主文件中移出、放到指针后面——让顶层保持可读。它首先不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：每个分支都要用到的内容内联保留，只有部分分支会碰到的内容推到指针后面。当一份文档有步骤时，本应披露的文件内参考会埋没这些步骤，让"照做"变成抛硬币——这不只是可读性杠杆，而是变异杠杆。
+
+**就近放置（co-location）** 是文件内部的伴侣：梯子决定一块内容*下探多深*，就近放置决定它落到那里后*旁边放着什么*。把一个概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样读到一部分时，相邻部分也随之而来。判断标准：文档读起来应该像专门写给 agent 的文档——归组的内容如此，散落的内容则不然。（它与重复不同：重复是在两个地方重述同一层含义；散落是把一层含义打碎到多处。）
+
+**臃肿（sprawl）** 是这里的失败模式：一份文档单纯地太长，即使每一行都是活的、独一无二的。注意力在过剩内容中变薄，而每一行额外的内容都是又多一条需要保持相关的东西。解药就是那把梯子：把参考披露到指针后面，并按分支或序列拆分，让每条路径只携带它需要的东西。
+
+## 步骤与完成标准
+
+每个步骤都以一个**完成标准（completion criterion）** 收尾——告诉 agent 工作已完成的条件。两个属性使它成为杠杆：
+
+- **清晰度**——agent 能否区分"完成"与"未完成"？一个模糊的边界（"已达成理解"）会招致**提前完成（premature completion）**：在步骤真正完成之前就结束它，注意力滑向*看起来完成了*。仍可见的后续步骤——**完成后的步骤（post-completion steps）**——提供拉力；标准的清晰度是阻力。按顺序防御：**先磨利边界**（局部且廉价）；只有当边界不可约地模糊*且*你观察到赶工行为时，才通过拆分序列隐藏后续步骤——而隐藏只在真正的上下文边界处有效（一次交接或一个 subagent 派遣；内联调用会让后续步骤留在上下文中，什么也清不掉）。
+- **要求强度（demand）**——它要求多少。"每个修改过的模型都被说明"逼出彻底的工作，而"生成一份变更清单"不会。要求强度驱动**苦功（legwork）**——agent 在工作内部做的挖掘，它藏在措辞里而不是写成独立步骤——并且它不绑定步骤："每条规则都适用"绑定一整个扁平的参考集合，正如"每个步骤都完成"绑定一条序列，这正是一份纯参考文档仍然带着穷尽性门槛的方式。
+
+最强的标准既可核查又穷尽。
+
+## 何时拆分
+
+把一份文档拆成两份，要花掉两种负载之一，所以只有在切口值得时才拆：
+
+- **按序列拆分**——拆分一段步骤序列，此时完成后的步骤会诱使 agent 赶工眼前的步骤。让它们不可见，会驱动当前任务上更多的苦功。当心反向情况：合并序列会让每个步骤都暴露在后续步骤面前，招致提前完成。
+
+## 引导词
+
+**引导词（leading word）** 是一个早已存在于模型预训练中的紧凑概念，agent 在运行文档时用它思考（_lesson_、_fog of war_、_tracer bullets_）。以 token 形式重复、永不用句子重述，它累积出一个分布式的定义，并以最少的 token 锚定一整个行为区域——通过征用模型已有的先验。自己造词也行，只要定义清楚，但一个生造的词征用不到任何先验——你在定义 token 上付出的，正是预训练词免费给予的；先用已有的词。
+
+它双重锚定。在正文里是*执行*：每次该词出现，agent 都伸手取同样的行为；在扁平参考内部，它把注意力聚焦到要找的一类事物上。在指针里是*调用*：当同一个词同时存在于你的 prompts、你的文档和你的代码库时，agent 会把这份共享语言与资料联系起来，更可靠地到达它。
+
+寻找用引导词重构的机会。一个在三个地方展开的三件套、一个花一句话指向同一个概念的指针——每一处都是渴望塌缩成单个 token 的段落：
+
+- "fast, deterministic, low-overhead" → _tight_（一个 _tight_ 循环）。
+- "a loop you believe in" → _red_——一个模糊的闸门变成二元的可观察状态（遇到 bug 循环变 _red_，或不变）。
+
+你赢两次：更少的 token，以及一个更锋利的钩子让 agent 挂上它的思考。假设每份文档都携带着引导词可以退役的重述——去把它们找出来。
+
+**否定式表述（negation）** 是这个杠杆旁边的失败模式：用禁止来引导，会把被禁止的行为拖进上下文，让它变得*更容易*被激活，而不是更难。_不要想大象_，然后脑子里就全是大象；否定是一个脆弱的修饰符，会被强激活的概念碾过去，于是禁令有一半读起来像是在指示去做那件事。用**肯定式**提示——陈述目标行为（"写一行注释"），让被禁止的行为永远不被说出来。只有当你实在无法用肯定句式表达时，一条禁令才配占有一席之地；即使如此，也要配上肯定的目标，让注意力落在"做什么"上。
+
+## 精简
+
+- 让每个含义都有**单一事实来源（single source of truth）**：一个权威的位置，这样改变行为就是改一处。**重复（duplication）**——同一含义出现在多个地方——耗费维护成本和 token，并把一个含义在梯子上的显著性抬到超过它实际等级的高度。（它是引导词的意外反面：引导词是有意重复一个 token，从来不是重复含义。）
+- **环境（environment）** 也是事实来源——`package.json` 脚本、配置文件、目录布局、`--help` 输出——而重述环境的文档就是一份**缓存（cache）**：一次查询的副本，只有当查询本身昂贵时才值得负担这份负载。只缓存 agent 无法通过查找得到的东西：不成文的约定、选择背后的原因、任何配置文件都不会招认的坑。把"一个文件一条命令"式的查找留给环境，在那里它们不会过期。
+- 逐行检查**相关性（relevance）**：它是否仍然与文档所做的事有关？一行内容失去相关性，要么因为从未作用于任务（纯叙述，或一个本应披露的分支），要么因为行为或世界变化而过期。更短的文档更容易保持相关。没有精简纪律，默认的归宿是**沉积（sediment）**：一层层过期的内容沉淀下来——因为添加感觉安全、删除感觉冒险——直到你必须钻穿它们才能找到仍然活着的东西。
+- 逐句猎杀**无效指令（no-ops）**：一句模型本来就默认遵守的指令，花了负载却没说出任何东西。判断标准——它是否改变了相对默认的行为？——是模型相对的，不是读者相对的：两个人争论一句无效指令，争论的是默认是什么，而且要靠运行文档来裁决，不是靠辩论。当一句指令不合格时，删除整句，而不是从里面删词。这个判断标准也给引导词打分：一个弱到打不过默认的词（在 agent 已经够"be thorough"的地方写*要彻底*）就是无效指令，修法是换一个更强的词（*毫不留情*），而不是换一种技巧。

package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/claude-redirect.md

@@ -10,7 +10,7 @@
 Speculo agent handbook: see [AGENTS.md](./AGENTS.md).
 ```
 
-此格式与 `../../docs-sync/references/agents-contract.md` 的规定一致（该契约为权威）：`AGENTS.md` 始终是唯一的权威代理手册，`CLAUDE.md` 永远只是入口指针。
+此格式与 [`../agents-contract.md`](../agents-contract.md) 的规定一致（该契约为权威）：`AGENTS.md` 始终是唯一的权威代理手册，`CLAUDE.md` 永远只是入口指针。
 
 ## 设计缘由
 

package/template/skills/docs-sync/references/agents-contract.md

@@ -1,6 +1,28 @@
 # AI 代理手册同步契约
 
-本契约用于差量维护已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。创建或重建多层手册树时调用 `../../agents-md-builder/SKILL.md`，不要在 docs-sync 中复制其扫描和模板逻辑。
+本契约用于差量维护或重建已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。调用方传入 `handbook_mode=incremental|rebuild`；默认使用 `incremental`，仅在用户显式要求、手册缺失或 manifest 拓扑变化时进入 `rebuild`。
+
+## 分支路由
+
+### Incremental
+
+读取当前手册、Git 输入区间和直接事实源，逐段执行下方内容优先级、生命周期和验证规则。不重新分类未受影响目录，也不加载重建模板。
+
+**完成标准**：所有被 Git 区间或当前事实命中的手册均已整份审计，未命中手册保持不变。
+
+### Rebuild
+
+按顺序读取：
+
+1. `agents/manifest-discovery.md`，发现 manifest、忽略目录、父子树和孤立手册；
+2. `agents/role-classification.md`，为每个目录判定唯一角色；
+3. `agents/evidence-collection.md`，为每个输出结论收集真实文件证据；
+4. `agents/content-contract.md`、`agents/writing-style.md` 和对应 `agents/templates/*`，自底向上生成 AGENTS.md；
+5. `agents/claude-redirect.md`，生成或修复同层 CLAUDE.md。
+
+展示创建、更新和删除候选；整文件删除或把多行 CLAUDE.md 改成重定向前取得明确确认。
+
+**完成标准**：扫描范围内每个合法目录恰好一个 AGENTS.md，每个 AGENTS.md 有唯一 CLAUDE.md 重定向，父子 routing 完整，所有处置均有证据和确认状态。
 
 ## 内容优先级
 

package/template/skills/typescript-standards-builder/README.md

@@ -0,0 +1,53 @@
+# TypeScript Standards Builder Skill
+
+这是一个“规范生成器”Skill，而不是静态编码规范合集。它会先读取项目事实，再通过用户问答确认决策，最后为当前项目生成专属的 TypeScript Standards Skill。
+
+## 生成目标
+
+```text
+.agents/skills/typescript-standards/     # 唯一正式规范源
+.agents/skills/typescript--standards/    # 双连字符兼容跳转
+.claude/skills/typescript-standards/     # 只有一句强制引用
+```
+
+## 核心特点
+
+- 先扫描仓库，再提问，不让用户回答配置中已经明确的事实。
+- 通过自适应问答确认真正有分歧的项目规则。
+- 主 Skill 精简，详细规则拆入项目内 `references/`。
+- 默认采用领域内部局部平铺、具体文件名、文件大小预算、WHY 注释、自动化门禁和测试共置。
+- 不机械复制 Electron、React 或某个工具的专属目录。
+- 对遗留项目采用只降不升的 Ratchet 策略。
+- 同时兼容 `.agents` 与 `.claude` 的 Skill 发现方式。
+
+## 包结构
+
+```text
+typescript-standards-builder/
+├── SKILL.md
+├── README.md
+├── references/
+├── templates/
+├── examples/
+└── manifest.txt
+```
+
+## 使用方式
+
+将整个目录安装到支持 Skill 的位置，以 `SKILL.md` 为入口。运行后，Skill 会在当前项目中生成项目专属规范，而不是修改本生成器包本身。
+
+## 路径说明
+
+正式项目规范使用单连字符：
+
+```text
+.agents/skills/typescript-standards/SKILL.md
+```
+
+为兼容用户指定的 Claude 引用路径，还会创建：
+
+```text
+.agents/skills/typescript--standards/SKILL.md
+```
+
+该兼容文件只跳转到正式规范，避免维护两份内容。

package/template/skills/typescript-standards-builder/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: typescript-standards-builder
+description: 通过仓库事实分析与用户问答，为当前 TypeScript 项目生成项目专属编码规范 Skill。输出正式 Skill 到 .agents/skills/typescript-standards，并创建 Claude 强制引用入口；适用于 TypeScript、React、Node.js、Electron、CLI、库及 Monorepo。
+---
+
+# TypeScript Standards Builder
+
+本 Skill 的职责不是直接把一份通用规范复制进项目，而是：
+
+1. 分析当前仓库的真实结构、工具链和历史约定。
+2. 使用简短、逐项的用户问答确认仍需决策的规范。
+3. 将确认结果生成当前项目专属的 TypeScript 编码规范 Skill。
+4. 把正式规范写入 `.agents/skills/typescript-standards/`。
+5. 同时创建 `.claude/skills/typescript-standards/SKILL.md`，强制转向 `.agents` 中的唯一规范源。
+
+详细规则采用渐进式读取。不要一次读取全部 `references/`。
+
+## 最终输出目录
+
+完成问答后，必须生成：
+
+```text
+.agents/
+└── skills/
+    ├── typescript-standards/
+    │   ├── SKILL.md
+    │   └── references/
+    │       ├── 00-project-profile.md
+    │       ├── 01-architecture-and-layout.md
+    │       ├── 02-naming-and-files.md
+    │       ├── 03-modules-and-dependencies.md
+    │       ├── 04-type-system.md
+    │       ├── 05-functions-async-errors.md
+    │       ├── 06-comments-and-documentation.md
+    │       ├── 07-testing.md
+    │       ├── 08-framework-specific.md
+    │       ├── 09-tooling-and-quality-gates.md
+    │       ├── 10-review-checklist.md
+    │       └── 11-decisions-and-exceptions.md
+    └── typescript--standards/
+        └── SKILL.md
+
+.claude/
+└── skills/
+    └── typescript-standards/
+        └── SKILL.md
+```
+
+`.agents/skills/typescript-standards/` 是唯一正式规范源。
+
+由于兼容要求，必须额外生成双连字符入口：
+
+```text
+.agents/skills/typescript--standards/SKILL.md
+```
+
+该文件只负责跳转到正式的单连字符目录。
+
+`.claude/skills/typescript-standards/SKILL.md` 必须只有一句话，并强制引用用户指定的双连字符路径：
+
+```md
+必须先读取并完整遵循项目根目录下的 `.agents/skills/typescript--standards/SKILL.md`，禁止在未读取该文件时执行任何 TypeScript 相关任务。
+```
+
+除这一句话外，不得添加 YAML、标题、空白说明、示例或第二句话。
+
+## 已确认的固定默认原则
+
+以下规则来自用户已认可的工程实践，应直接作为生成规范的默认基线；除非仓库存在框架、生成器或公共 API 的硬性冲突，不需要再次询问用户是否采用：
+
+- **领域内部局部平铺**：明确领域内优先平铺文件，只有形成稳定子域后再增加目录。
+- **文件名具体**：文件名表达领域和职责，禁止用 `utils`、`helpers`、`common`、`misc` 等模糊名称承载不相关能力。
+- **控制文件体积**：为普通 TypeScript、React、测试和脚本设置不同的审查预算；阈值是拆分触发器，不是机械裁决。
+- **注释关注 WHY**：注释解释兼容性、性能、安全、平台差异和非直观约束，不逐行翻译代码。
+- **工具链形成门禁**：格式化、Lint、类型检查、测试和构建形成自动化质量门禁，不得通过关闭核心规则或删除测试绕过。
+- **测试靠近实现**：单元测试与源码共置；跨模块集成、契约和 E2E 测试集中管理。
+- **不机械复制结构**：复制规则背后的目的，不把 Electron、React 或某个工具的专属结构强加给不相关项目。
+
+这些原则已分别融入架构、命名、注释、测试、复杂度、CI 和迁移参考文档，不再维护独立的 Orca 附录。
+
+## 规则优先级
+
+发生冲突时依次遵循：
+
+1. 用户在本次问答中明确确认的决定。
+2. 运行平台、框架、协议、生成器和公共 API 的硬性约束。
+3. 当前仓库已经生效的配置和 CI 门禁。
+4. 当前模块一致且可解释的局部惯例。
+5. 本 Skill 的固定默认原则和通用推荐。
+
+安全、数据正确性、资源生命周期和外部输入验证不得因为“历史一直如此”而继续弱化。
+
+## 执行流程
+
+### 阶段 1：确认工作区
+
+确定仓库根目录和规范适用范围：
+
+- 单一应用、单一包或整个 Monorepo。
+- 是否只覆盖 TypeScript，还是同时覆盖 JavaScript、React、Node.js、Electron、CLI。
+- 是否存在自动生成目录、第三方镜像或不应修改的区域。
+
+仓库中可直接判断的事实不得反复询问用户。
+
+### 阶段 2：读取仓库事实
+
+按 `references/01-project-discovery.md` 检查：
+
+- `package.json`、Workspace 配置和锁文件。
+- `tsconfig*.json` 及项目引用。
+- ESLint、Oxlint、Biome、Prettier、Oxfmt 等配置。
+- 测试框架、测试文件命名和覆盖范围。
+- `src/`、`apps/`、`packages/` 的实际结构。
+- 路径别名、导出入口、包边界和运行环境。
+- `AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING.md`、CI 工作流。
+- 文件行数、模糊名称、循环依赖和测试共置情况的代表性样本。
+
+输出一份内部项目画像，区分：
+
+- 已由仓库事实确定的规则。
+- 存在冲突或不一致的规则。
+- 必须由用户决定的规则。
+
+### 阶段 3：进行自适应问答
+
+按 `references/02-interview-workflow.md` 执行。
+
+要求：
+
+- 一次只确认一个决策维度；必要时可把高度关联的两项放在同一轮。
+- 每个问题先给出基于仓库事实的推荐默认值。
+- 提供 2～4 个具体选项，并允许用户自定义。
+- 不询问已经能从配置或代码中确定的事实。
+- 不要求用户重新确认上面的七项固定默认原则，除非仓库存在硬冲突。
+- 新项目通常确认 5～8 个高影响决策；成熟项目通常只确认冲突和缺失项。
+- 每轮记录决定，避免重复提问。
+
+至少要解决以下仍然不明确的项目级问题：
+
+- 规范覆盖范围与遗留代码执行策略。
+- 目录主轴和运行环境边界。
+- React 组件文件命名（仅 React 项目）。
+- 导出、Barrel 和跨模块导入策略。
+- `type` / `interface` 默认偏好及运行时验证方式。
+- 文件大小预算和超限治理方式。
+- 测试框架、命名、共置及 CI 必跑范围。
+- 格式化、Lint、类型检查、构建和提交前门禁。
+- 例外批准、TODO 与迁移记录方式。
+
+### 阶段 4：生成前确认
+
+问答结束后，向用户展示一份简洁的“规范决策摘要”，必须包含：
+
+- 自动识别的仓库事实。
+- 用户确认的选择。
+- 使用默认值的项目。
+- 需要保留的历史例外。
+- 即将创建或更新的文件列表。
+
+只有在用户确认摘要后，才写入项目文件。若用户已经在同一消息中明确要求直接生成，可完成摘要后直接写入，不重复确认。
+
+### 阶段 5：生成项目专属 Skill
+
+按 `references/17-generation-contract.md` 和 `templates/project-skill/` 生成。
+
+生成要求：
+
+- 项目 Skill 必须是当前仓库专属内容，不得包含与项目无关的框架章节。
+- `SKILL.md` 保持精简，只包含适用范围、优先级、核心不可违背规则、参考路由和执行要求。
+- 详细规则写入 `references/`，按任务最小化读取。
+- 每条重要规则标记来源：`仓库事实`、`用户确认`、`默认基线` 或 `兼容例外`。
+- 固定默认原则必须进入对应模块，不能只写在总览。
+- 文件大小阈值应结合仓库分布和用户决定，不直接硬编码通用数值。
+- 对遗留项目使用 Ratchet 策略，不强迫一次性重构全部代码。
+- 不覆盖用户已有项目 Skill；若已存在，先读取并合并，保留项目特有条款，并展示变更摘要。
+
+### 阶段 6：创建重定向 Skill
+
+必须创建以下两个入口。
+
+正式兼容入口：
+
+```text
+.agents/skills/typescript--standards/SKILL.md
+```
+
+内容必须只有一句话：
+
+```md
+本文件仅用于路径兼容；必须立即读取并完整遵循项目根目录下的 `.agents/skills/typescript-standards/SKILL.md`。
+```
+
+Claude 入口：
+
+```text
+.claude/skills/typescript-standards/SKILL.md
+```
+
+内容必须只有一句话：
+
+```md
+必须先读取并完整遵循项目根目录下的 `.agents/skills/typescript--standards/SKILL.md`，禁止在未读取该文件时执行任何 TypeScript 相关任务。
+```
+
+### 阶段 7：验证
+
+生成后必须验证：
+
+- 正式 Skill 路径存在。
+- `SKILL.md` YAML Frontmatter 合法，`name` 为 `typescript-standards`。
+- 主 Skill 引用的所有 `references/` 文件都存在。
+- 没有保留孤立的 `15-orca-derived-observations.md`。
+- 七项固定默认原则已分散进入对应模块。
+- `.claude` 的 `SKILL.md` 恰好只有一句话。
+- 双连字符兼容入口存在且只包含一句话。
+- 项目专属规范没有复制不适用的框架或运行环境规则。
+- 用户确认的决定与生成内容一致。
+- 不存在 `typescript--standards` 与 `typescript-standards` 相互循环引用。
+
+最后报告：创建、更新、保留和未能验证的文件。
+
+## 参考路由
+
+| 任务 | 读取文档 |
+|---|---|
+| 规则优先级和固定默认原则 | `references/00-governance-and-fixed-defaults.md` |
+| 仓库扫描与项目画像 | `references/01-project-discovery.md` |
+| 用户问答和决策收敛 | `references/02-interview-workflow.md` |
+| 目录、边界、局部平铺 | `references/03-project-architecture-and-directory-layout.md` |
+| 文件、目录和标识符命名 | `references/04-file-directory-and-symbol-naming.md` |
+| 模块、导入、导出和依赖 | `references/05-modules-imports-exports-and-dependencies.md` |
+| TypeScript 类型系统 | `references/06-typescript-type-system.md` |
+| 函数、异步、错误和资源 | `references/07-functions-async-errors-and-resources.md` |
+| 注释、JSDoc 和文档 | `references/08-comments-jsdoc-and-documentation.md` |
+| 测试策略和共置 | `references/09-testing-strategy.md` |
+| React 和前端 | `references/10-react-and-frontend.md` |
+| Node、CLI 和跨平台 | `references/11-node-cli-and-cross-platform.md` |
+| 格式、Lint、文件大小 | `references/12-formatting-lint-and-complexity.md` |
+| 配置、依赖和质量门禁 | `references/13-configuration-dependencies-and-ci.md` |
+| 安全、性能和国际化 | `references/14-security-performance-and-i18n.md` |
+| Git、PR 和交付 | `references/15-git-review-and-delivery.md` |
+| 遗留迁移和例外 | `references/16-adoption-exceptions-and-migration.md` |
+| 输出目录和文件合同 | `references/17-generation-contract.md` |
+
+完整索引见 `references/README.md`。

package/template/skills/typescript-standards-builder/examples/sample-generated-tree.md

@@ -0,0 +1,30 @@
+# 生成后的项目结构示例
+
+```text
+.agents/
+└── skills/
+    ├── typescript-standards/
+    │   ├── SKILL.md
+    │   └── references/
+    │       ├── 00-project-profile.md
+    │       ├── 01-architecture-and-layout.md
+    │       ├── 02-naming-and-files.md
+    │       ├── 03-modules-and-dependencies.md
+    │       ├── 04-type-system.md
+    │       ├── 05-functions-async-errors.md
+    │       ├── 06-comments-and-documentation.md
+    │       ├── 07-testing.md
+    │       ├── 08-framework-specific.md
+    │       ├── 09-tooling-and-quality-gates.md
+    │       ├── 10-review-checklist.md
+    │       └── 11-decisions-and-exceptions.md
+    └── typescript--standards/
+        └── SKILL.md
+
+.claude/
+└── skills/
+    └── typescript-standards/
+        └── SKILL.md
+```
+
+实际项目可裁剪不适用的主题文件，但不得删除项目画像、检查清单和决策例外记录。

package/template/skills/typescript-standards-builder/examples/sample-interview-decisions.md

@@ -0,0 +1,26 @@
+# 问答决策示例
+
+## 自动识别
+
+- pnpm Workspace。
+- ESM。
+- React + Node.js。
+- Vitest 单元测试已与源码共置。
+- ESLint 和 Prettier 已在 CI 中运行。
+
+## 用户确认
+
+- 运行环境第一层隔离，环境内部按领域组织。
+- React 业务组件使用 `PascalCase.tsx`。
+- 默认命名导出，Barrel 仅用于包公共入口。
+- 默认使用 `type`，扩展契约使用 `interface`。
+- 普通 TS/TSX 文件软上限分别为 320/420 行。
+- 历史超限文件使用 Ratchet，不立即全量整改。
+
+## 默认基线
+
+- 领域内部局部平铺。
+- 文件名具体。
+- 注释解释 WHY。
+- 单元测试共置。
+- CI 必跑格式、Lint、类型、测试和构建。

package/template/skills/typescript-standards-builder/manifest.txt

@@ -0,0 +1,29 @@
+README.md
+SKILL.md
+examples/sample-generated-tree.md
+examples/sample-interview-decisions.md
+references/00-governance-and-fixed-defaults.md
+references/01-project-discovery.md
+references/02-interview-workflow.md
+references/03-project-architecture-and-directory-layout.md
+references/04-file-directory-and-symbol-naming.md
+references/05-modules-imports-exports-and-dependencies.md
+references/06-typescript-type-system.md
+references/07-functions-async-errors-and-resources.md
+references/08-comments-jsdoc-and-documentation.md
+references/09-testing-strategy.md
+references/10-react-and-frontend.md
+references/11-node-cli-and-cross-platform.md
+references/12-formatting-lint-and-complexity.md
+references/13-configuration-dependencies-and-ci.md
+references/14-security-performance-and-i18n.md
+references/15-git-review-and-delivery.md
+references/16-adoption-exceptions-and-migration.md
+references/17-generation-contract.md
+references/README.md
+templates/agents-compat-skill/SKILL.md
+templates/claude-skill/SKILL.md
+templates/project-skill/SKILL.md.template
+templates/project-skill/references/00-project-profile.md.template
+templates/project-skill/references/10-review-checklist.md
+templates/project-skill/references/11-decisions-and-exceptions.md.template

package/template/skills/typescript-standards-builder/references/00-governance-and-fixed-defaults.md

@@ -0,0 +1,77 @@
+# 治理、优先级与固定默认原则
+
+## 规范词义
+
+- **必须**：影响正确性、安全、类型边界、资源生命周期或团队一致性的硬要求。
+- **应当**：绝大多数情况下适用；偏离时必须有明确理由。
+- **建议**：默认推荐，可根据规模、框架和团队能力调整。
+- **禁止**：高概率制造缺陷、隐藏风险或降低维护性的做法。
+
+## 冲突优先级
+
+1. 用户在本次规范问答中确认的决定。
+2. 平台、框架、协议、代码生成器和公共 API 的硬约束。
+3. 仓库已生效配置、CI 与自动检查。
+4. 当前模块一致且可解释的局部惯例。
+5. 本 Skill 的固定默认原则。
+6. 其他通用建议。
+
+## 固定默认原则
+
+以下原则已得到用户认可，应直接纳入项目规范；只有发现硬冲突时才提问：
+
+### 1. 领域内部局部平铺
+
+- 小型、职责明确的领域目录优先直接放置实现文件。
+- 不为每个文件创建同名目录。
+- 只有形成稳定子领域、独立生命周期或明显浏览负担时才增加子目录。
+- 平铺不是全仓库无结构，而是在清晰边界内部减少无意义层级。
+
+### 2. 文件名具体
+
+- 文件名必须表达领域和职责。
+- `utils.ts`、`helpers.ts`、`common.ts`、`misc.ts` 不得作为不相关能力的收容区。
+- 无法给文件起具体名称，通常意味着职责尚未拆清。
+
+### 3. 控制文件体积
+
+- 普通 TypeScript、React、测试和脚本采用不同的大小预算。
+- 阈值是代码审查与拆分触发器，不是为了满足数字而机械拆文件。
+- 历史超限文件使用 Ratchet：新改动不得继续无边界增长。
+
+### 4. 注释关注 WHY
+
+- 注释解释兼容性、性能、安全、平台差异、协议约束和非直观业务原因。
+- 不逐行翻译代码，不用注释掩盖模糊命名和职责混合。
+
+### 5. 工具链形成门禁
+
+- 格式化、Lint、类型检查、测试和构建必须形成稳定命令与 CI 门禁。
+- 底层工具可以替换，但职责名称和检查结果保持稳定。
+- 不得通过关闭核心规则、扩大 `any`、删除或跳过测试来获得表面通过。
+
+### 6. 测试靠近实现
+
+- 单元测试与源码共置，随实现一起移动和重命名。
+- 跨模块集成、契约和 E2E 测试集中管理。
+- 缺陷修复优先先写可复现的回归测试。
+
+### 7. 不机械复制
+
+- 不把 Electron 目录强加给普通 Web 或 Node 项目。
+- 不把某个格式化工具的选项当作永恒标准。
+- 不把通用阈值直接作为项目绝对数字。
+- 应保留背后的目标：边界清晰、职责具体、类型严格、质量自动化、修改可验证。
+
+## 事实优先但不纵容风险
+
+历史一致性不能为以下问题背书：
+
+- 不可信输入未经验证。
+- 敏感信息泄漏。
+- 监听器、Timer、连接或进程无法清理。
+- `any` 向公共 API 传播。
+- 循环依赖或跨运行环境非法导入。
+- 删除测试、关闭规则或放宽配置来隐藏失败。
+
+对遗留问题采用渐进治理，不要求无关的大规模重写。