@namewta/speculo 0.3.2 → 0.3.4

package/README.md

@@ -49,7 +49,7 @@ After initialization, the target project gains the following AI agent-callable a
 | `retro` | Retrospective analysis with `gh issue` creation |
 | `status` | Summary of installed workflows, active changes, and anomalies |
 
-### 6 Skills
+### 7 Skills
 
 | Skill | Purpose |
 |---|---|
@@ -58,7 +58,8 @@ After initialization, the target project gains the following AI agent-callable a
 | `docs-sync` | Core documentation audit and synchronization |
 | `github-npm-ops` | GitHub issue/PR triage and npm operations |
 | `speculo-retro` | Retrospective analysis |
-| `dev-worktree` | Git worktree isolation for development |
+| `typescript-engineering-standards` | Progressive TypeScript/JS/React/Node engineering standards with references, templates, and examples |
+| `writing-great-skills` | Authoring guidance for agent skills |
 
 ### 2 Workflow Packages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Workflow-packaged specification-driven development assets with install, update, and migration tooling.",
   "type": "module",
   "bin": {

package/template/canonical/canonical-specdev-wayfinder.md

@@ -13,7 +13,12 @@
 - 若本地项目提供 Speculo Node 校验器，可运行它补充结构校验；纯网页环境按本文内联的 schema、Ready 清单和完成标准逐项核对，并明确记录未运行的自动校验。
 - 提交、推送、合并、部署、发布、归档移动和不可逆迁移仍需用户明确授权。
 
-Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场景。它保留共享地图、多会话领取、研究型 Ticket 和决策型 Ticket 的能力，但禁止把产品实现伪装成调查。
+Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场景。它先命名**目标**，再把通往目标的路线绘制成一张**共享地图**——由一组可领取的调查 Ticket 组成，逐个关闭高影响未知项，直到路线清晰。地图刻意保持不完整：看得清的决策落成 Ticket，看不清的留在**战争迷雾**里，随每次调查完成而逐步散去。
+
+## 两条核心纪律
+
+- **规划而非执行**：本 work 产出的是**决策**，不是交付物。当你产生“顺手把它实现掉”的冲动时，通常意味着你已经走到了地图边缘——那是交接给实现 work 的信号，而不是继续动手的理由。用户可在地图笔记中显式授权把执行纳入地图，否则一律只产出决策。
+- **以名称指代**：共享地图和每个调查 Ticket 都是有标题的实体。凡是人会读到的叙述，一律用**名称**指代（如“调查：登录态跨域刷新策略”），而不是裸编号（`INV-03`）或裸路径。ID 与路径作为链接附在名称里，不单独充当称呼。一屏 `INV-03、INV-04、INV-05` 无法阅读。
 
 ## 产物
 
@@ -36,62 +41,107 @@ Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场
 - 存在多个相互依赖的高影响未知项；
 - 需要在若干候选方案中先获得事实证据再做决定。
 
-若问题只是一个可在当前上下文通过短暂只读探索回答的事实，不创建 Wayfinder Map。
+若问题只是一个可在当前上下文通过短暂只读探索回答的事实，不创建 Wayfinder Map。若在命名目标、绘制前沿后发现根本没有迷雾——所有决策都已清楚——则不需要地图，停下并直接告知用户下一步。
+
+## 两种调用模式
+
+Wayfinder 有两种入口，可分次进行：
+
+- **绘制地图**：用户带来一个粗略想法。命名目标 → 广度优先勾勒前沿 → 建立共享地图（写好目标与笔记，已定决策留空，迷雾写入“尚未指定”）→ 创建当前可明确表述的调查 Ticket 并二次连边补齐阻塞关系 → 并行触发 research 型 AFK 调查 → 停止。绘制本身不解决任何未知项。
+- **走完地图**：用户带来一张已存在的地图（可选带指定 Ticket）。加载低分辨率地图 → 选取并领取一个前沿 Ticket → 解决它 → 记录结论、释放领取、关闭 Ticket → 浮现新 Ticket、让已可表述的迷雾毕业、把越界工作移入范围之外。
 
 ## 流程
 
-### 1. 定义目标与未知项
+### 1. 命名目标与勾勒边界
 
-写明最终目标、已知边界、当前不能决定的事项和“为什么这些未知项阻塞规划”。未知项分为：
+命名目标是第一动作，它塑造每一个后续 Ticket。写明：
+
+- **最终目标**：一到两行描述“终点长什么样”。
+- **已知边界**：当前确定的前提、约束与不变量。
+- **当前不能决定的事项**：以及“为什么这些未知项阻塞规划”。
+
+高影响未知项按**调查目的**分为四类：
 
 - **research**：答案可由代码、文档、实验或外部来源证实；
 - **decision**：事实已足够，但需要用户或架构 owner 做取舍；
 - **validation**：已有方案，需要实验验证关键可行性或风险；
 - **mapping**：需要建立调用链、数据流、依赖图或影响面。
 
-低影响实现细节不创建调查 Ticket。
+每个调查 Ticket 还需标注**执行模式**：
+
+- **AFK**（agent-only）：可由子代理独立完成，无需人类在环，典型是 research 与 mapping。
+- **HITL**（human-in-the-loop）：必须通过与用户的实时交流才能解决，代理不得替用户作答；典型是 decision，以及需要用户对原型或方案取舍反馈的 validation。
+
+低影响实现细节不创建调查 Ticket，记录为实现者可自行决定。
 
-### 2. 建立共享地图
+### 2. 战争迷雾与前沿
 
-使用 下方 `<wayfinder-map-template>` 标签 写入 `specdev/changes/{change}/wayfinder-map.md`：
+地图**刻意不完整**——不去绘制你还看不见的东西。
 
-- 每个 Ticket 只关闭一个高影响未知项；
-- 写明依赖、owner、领取状态、停止条件和结果消费方；
-- 构建调查 DAG，避免多个调查重复回答同一问题；
-- 标记可并行调查和必须串行的决策点；
-- 定义整体停止条件，不以“所有可能问题都研究完”为目标。
+- **前沿**：地图上当前 `open`、依赖已满足（unblocked）、且尚未被领取（unclaimed）的调查 Ticket 集合。走完地图时只从前沿取 Ticket。
+- **战争迷雾**：范围内、你已隐约感到会出现、但此刻还无法精确表述的决策。它们写入共享地图的“尚未指定”区，不切成 Ticket。
+- **毕业判据**：能否**此刻精确陈述这个问题**（而非能否此刻回答它）。问题已经足够锐利就立 Ticket（即使仍被阻塞）；还说不清就留在迷雾里。不要预先把迷雾切成 Ticket 大小的碎片。
 
-### 3. 领取与并行
+每解决一个 Ticket 都会驱散前方迷雾，让新可表述的问题从“尚未指定”毕业为新 Ticket。
 
-调查者开始前原子地更新 `specdev/status.json` 的 `claimed_investigations`：
+### 3. 建立共享地图
 
-- 未领取且依赖满足 → 设置 owner、session 和 claimed 时间；
-- 已领取 → 跳过并选择其他可用 Ticket；
+使用 下方 `<wayfinder-map-template>` 标签 写入 `specdev/changes/{change}/wayfinder-map.md`。地图是**索引而非仓库**：每个决策只在一处存放（对应调查 Ticket 或 Evidence），地图只给出一行摘要并链接到详情。地图包含：
+
+- **目标**：终点，一到两行。
+- **笔记**：领域、需参考的 skills、固定偏好，以及是否显式授权把执行纳入地图。
+- **调查清单**：当前所有已表述 Ticket 的索引表（含 ID、类型、执行模式、问题、依赖、领取状态、结果指针），前沿由此表投影。
+- **调查 DAG**：阻塞关系图，避免多个调查重复回答同一问题；标记可并行与必须串行的决策点。
+- **已定决策**：每关闭一个 Ticket 追加一行结论，作为“实际走过的路线”索引。
+- **尚未指定**：范围内、尚不可表述为 Ticket 的迷雾。
+- **范围之外**：见第 4 节。
+- **停止条件**：整体收敛判据，不以“所有可能问题都研究完”为目标。
+
+每个 Ticket 只关闭一个高影响未知项。
+
+### 4. 范围之外
+
+迷雾只朝目标方向聚集，目标一旦确定就固定了范围，因此超出目标的工作是**范围之外**，不是迷雾。它单独成节，列出被有意识排除的工作，写清摘要与理由。
+
+- 范围之外**永不毕业**回地图；只有在目标被重画时，作为新的 change 重新纳入。
+- 当一个已存在的 Ticket 被发现落在目标之外时，关闭它并在“范围之外”留一行摘要与原因，**不写入“已定决策”**——已定决策只记录实际走过的路线。
+
+### 5. 领取与并行
+
+调查者开始前原子地更新 `specdev/status.json` 的 `claimed_investigations`（领取即“认领”，先领取再动手）：
+
+- 未领取且依赖满足（属于前沿）→ 设置 owner、session 和 claimed 时间；
+- 已领取 → 跳过并选择其他前沿 Ticket；
 - 超过配置的 claim 超时且无进展 → 允许在记录原因后回收；
 - 完成或释放后从领取集合移除，并同步共享地图。
 
-并行调查使用独立上下文；不要复制所有调查历史，只读取共享地图、当前调查 Ticket、相关上游工件和必要代码事实。
+并行是有约束的：
+
+- **research / AFK 型调查可并行领取**，因为它们只读取事实、彼此独立，且不推进产品决策。并行调查使用独立上下文，只读取共享地图、当前调查 Ticket、相关上游工件和必要代码事实，不复制全部调查历史。
+- **decision 及其他 HITL 型 Ticket，单个会话一次只解决一个**。这类 Ticket 会实质改变方案走向、开启新的迷雾，逐个解决才能让地图稳定地生长；一次塞多个决策会污染前沿。因此除 research 型外，**同一会话不要在一轮里解决多个 HITL 型 Ticket**。
+- 用户可能在其他会话并行推进未阻塞的 Ticket，要预期对地图和领取状态的并发编辑，写回前先重读。
 
-### 4. 执行调查
+### 6. 执行调查
 
 调查默认只读。允许：
 
 - 代码搜索与静态分析；
 - 文档、规范和官方来源研究；
-- 可撤销的临时实验、最小原型或插桩；
+- 可撤销的临时实验、最小原型或插桩（原型用于让用户对“看起来/表现如何”作出反应，是手段不是最终架构）；
 - 性能测量、调用点扫描、schema 对比或兼容性验证。
 
 外部研究使用 下方 `<research>` 标签。
 
 禁止：
 
-- 顺手实现产品功能；
+- 顺手实现产品功能（想动手 = 到了地图边缘，交接而非继续）；
 - 提交未经审查的实验代码；
 - 将原型视为最终架构；
 - 在没有证据时把建议写成事实；
+- 代 HITL 型 Ticket 的用户作答；
 - 无停止条件地持续研究。
 
-### 5. 记录结果与影响
+### 7. 记录结果与影响
 
 每个调查结果区分：
 
@@ -109,11 +159,16 @@ Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场
 - `specdev/changes/{change}/ticket/NN-<ticket-name>.md`；
 - `specdev/changes/{change}/diagnosis.md`。
 
-调查完成、阻塞或释放时，同步调查 Ticket、调查 Evidence、共享地图和领取状态，并返回 investigation ID、状态及三份工件的完整路径。
+调查完成、阻塞或释放时：
+
+1. 同步调查 Ticket、调查 Evidence、领取状态；
+2. 在共享地图的“已定决策”追加一行结论索引（越界的则移入“范围之外”）；
+3. 让新可表述的迷雾从“尚未指定”毕业为新 Ticket，并二次连边补齐阻塞关系；作废或被替代的 Ticket 及时更新或删除；
+4. 返回 investigation 名称、状态及三份工件（调查 Ticket、Evidence、共享地图）的完整路径。
 
 状态使用 `open | claimed | confirmed | disproved | decision-needed | unresolved | superseded | cancelled`。
 
-### 6. 收敛与退出
+### 8. 收敛与退出
 
 当剩余未知项不再阻止目标、行为、架构、风险或验证决策时停止。根据结果进入：
 
@@ -127,12 +182,15 @@ Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场
 
 ## 完成标准
 
+- 目标已命名，并塑造了地图上的每个 Ticket；
 - 共享地图、调查 Ticket 和领取状态一致；
+- 地图作为索引，每个决策只在一处存放；
 - 每个调查只关闭一个高影响未知项；
 - 结论区分事实、实验、推断、建议和决定；
 - 来源、版本、置信度和停止条件可追踪；
-- 并行调查没有重复领取或互相覆盖；
-- 调查状态及 Ticket、Evidence、共享地图路径已返回；
+- 前沿、战争迷雾与范围之外划分清晰，迷雾按“能否精确表述”毕业；
+- 并行调查没有重复领取或互相覆盖，且未在一轮里解决多个 HITL 型 Ticket；
+- 调查状态及 Ticket、Evidence、共享地图路径已按名称返回；
 - 没有把产品实现藏在调查中；
 - 已明确下一 work 或阻塞决策。
 
@@ -156,7 +214,9 @@ Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场
 ```yaml
 artifact: investigation-ticket
 id: INV-01
+name: <简短问题名称，供人按名称指代>
 type: research
+mode: AFK
 status: open
 blocked_by: []
 owner: unassigned
@@ -164,15 +224,22 @@ claimed_by: null
 claimed_at: null
 ```
 
-# Investigation INV-01: <问题>
+# 调查：<问题名称>
+
+> 本 Ticket 只关闭**一个**高影响未知项，产出的是决策而非交付物。想“顺手实现”时即到了地图边缘，交接而非动手。
 
 - **调查文件：** `specdev/changes/{change}/investigation/INV-01-<name>.md`
 - **共享地图：** `specdev/changes/{change}/wayfinder-map.md`
 - **Evidence：** `specdev/changes/{change}/investigation/evidence/INV-01.md`
 
+## 0. 分类
+
+- **Type：** research / decision / validation / mapping
+- **模式：** AFK（子代理独立完成）/ HITL（须与用户实时交流，代理不代答）
+
 ## 1. 决策用途
 
-- 要回答或决定什么：
+- 要回答或决定什么（一个精确问题）：
 - 为什么阻塞规划：
 - 结果由哪个工件消费：
 
@@ -185,7 +252,7 @@ claimed_at: null
 ## 3. 调查契约
 
 - **允许的代码探索：** `project/relative/path/**`
-- **允许的实验：**
+- **允许的实验 / 原型：**（原型仅供用户反应，不作最终架构）
 - **禁止的产品实现：**
 - **来源优先级：**
 - **停止条件：**
@@ -193,7 +260,7 @@ claimed_at: null
 
 ## 4. 结果
 
-- **状态：** confirmed / disproved / decision-needed / unresolved / superseded
+- **状态：** confirmed / disproved / decision-needed / unresolved / superseded / cancelled
 - **结论：**
 - **证据：**
 - **置信度：** high / medium / low
@@ -202,6 +269,8 @@ claimed_at: null
 - **对 Spec 的影响：** 无 / `specdev/changes/{change}/spec.md`
 - **对 ADR 的影响：** 无 / `specdev/changes/{change}/ADR.md`
 - **对 Ticket 的影响：** 无 / `specdev/changes/{change}/ticket/NN-<ticket-name>.md`
+- **浮现的新迷雾 / 新 Ticket：**
+- **是否越界（移入范围之外）：** 否 / 是（理由：）
 - **下一步：**
 
 </investigation-ticket-template>
@@ -218,21 +287,37 @@ change: <YYYY-MM-DD-topic>
 status: active
 ```
 
-# Wayfinder Map: <目标>
+# Wayfinder Map: <目标名称>
+
+> 本地图是**索引而非仓库**：每个决策只在一处存放，地图只给一行摘要并链接到详情。凡是人会读到的叙述，用**名称**指代 Ticket，不用裸编号。
 
 - **共享地图：** `specdev/changes/{change}/wayfinder-map.md`
 - **调查目录：** `specdev/changes/{change}/investigation/`
 - **领取状态：** `specdev/status.json`
 
-## 1. 最终目标与当前边界
+## 1. 目标
+
+<终点长什么样，一到两行。目标是第一动作，塑造每一个 Ticket，并固定范围。>
+
+## 2. 笔记
+
+- **领域：**
+- **需参考的 skills：**
+- **固定偏好 / 约束：**
+- **执行授权：** 默认只产出决策不产出交付物；如需把执行纳入地图，在此显式写明。
+
+## 3. 调查清单（前沿由此表投影）
 
-## 2. 调查清单
+> 前沿 = `open` + 依赖已满足（unblocked）+ 尚未领取（unclaimed）的行。走完地图时只从前沿取 Ticket。
 
-| ID | Type | 问题 | 为什么高影响 | Blocked By | Owner/Claim | 状态 | Result |
-|---|---|---|---|---|---|---|---|
-| INV-01 | research | ... | ... | — | unassigned | open | `specdev/changes/{change}/investigation/INV-01-<name>.md` |
+| 名称 | ID | Type | 模式 | 问题 | Blocked By | Owner/Claim | 状态 | Result |
+|---|---|---|---|---|---|---|---|---|
+| 示例：登录态跨域刷新策略 | INV-01 | research | AFK | ... | — | unassigned | open | `specdev/changes/{change}/investigation/INV-01-<name>.md` |
 
-## 3. 调查 DAG
+- Type：research（可证实）/ decision（需取舍）/ validation（需实验验证）/ mapping（建立调用链/影响面）。
+- 模式：AFK（子代理独立完成，典型 research/mapping）/ HITL（须与用户实时交流，代理不代答，典型 decision）。
+
+## 4. 调查 DAG
 
 ```text
 INV-01
@@ -240,21 +325,41 @@ INV-01
   └─→ INV-03
 ```
 
-## 4. 并行与领取规则
+- 标记可并行调查与必须串行的决策点，避免多个调查重复回答同一问题。
+
+## 5. 并行与领取规则
 
 - 最大并发来自 `specdev/config.json`。
 - 当前领取集合以 `specdev/status.json` 为权威。
 - 同一调查 Ticket 只能有一个 owner/session。
-- 共享地图是状态投影，领取变更后必须同步。
+- **research / AFK 型可并行领取**；**decision 及其他 HITL 型，单会话一次只解决一个**（research 除外），逐个解决让地图稳定生长。
+- 共享地图是状态投影，领取变更后必须同步；写回前先重读，预期并发编辑。
+
+## 6. 已定决策（实际走过的路线）
 
-## 5. 决策收敛
+> 每关闭一个 Ticket 追加一行结论索引。越界工作不写这里，移入“范围之外”。
 
-| 未知项 | 当前结论 | 置信度 | 消费工件 | 是否仍阻塞 |
+| 名称 | 结论（一行） | 置信度 | 消费工件 | 详情指针 |
 |---|---|---|---|---|
 
-## 6. 停止条件
+## 7. 尚未指定（战争迷雾）
+
+> 范围内、已隐约感到会出现、但此刻还无法**精确表述**的决策。看得清就毕业成第 3 节的 Ticket，看不清就留在这里。不要预先切成 Ticket 大小的碎片。
+
+- ...
+
+## 8. 范围之外
+
+> 超出目标的工作。永不毕业回地图；目标被重画时作为新 change 处理。已存在 Ticket 若被发现越界，关闭后在此留一行摘要与理由。
+
+| 被排除的工作 | 理由 |
+|---|---|
+
+## 9. 停止条件
 
+- [ ] 目标已命名，并塑造了地图上的每个 Ticket。
 - [ ] 所有高影响未知项已 confirmed、disproved，或明确转为用户/owner 决策。
+- [ ] 战争迷雾中不再有阻塞目标、且已可精确表述却未立 Ticket 的问题。
 - [ ] 可以形成 Ready Spec、Ticket、诊断契约或架构决策。
 - [ ] 没有把产品实现留在调查 Ticket 中。
 - [ ] 所有 claim 已释放或转为明确 blocked。

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

@@ -0,0 +1,36 @@
+# TypeScript Engineering Standards Skill
+
+这是一个采用渐进式披露结构的通用 TypeScript 工程规范 Skill。
+
+## 使用方式
+
+将整个 `typescript-engineering-standards/` 目录放入支持 Skill 的目录中，并以 `SKILL.md` 作为入口。不同平台的 Skill 安装位置可能不同；保持目录内部相对路径不变即可。
+
+## 目录说明
+
+```text
+typescript-engineering-standards/
+├── SKILL.md              # 主入口：触发条件、工作流、参考路由
+├── references/           # 详细规范，按任务最小化读取
+├── templates/            # AGENTS、tsconfig、格式化、PR 与评审模板
+├── examples/             # 目录、命名、类型、注释和审查示例
+└── manifest.txt          # 包内文件清单
+```
+
+## 设计原则
+
+- `SKILL.md` 保持相对精简，不承载所有细节。
+- 详细规则按主题拆分到 `references/`。
+- 执行具体任务时只读取必要参考。
+- 模板是起点，不直接覆盖现有仓库配置。
+- 用户要求、平台约束和仓库事实优先于通用默认规则。
+
+## 推荐入口
+
+- 创建或审查项目目录：`references/01-project-architecture-and-directory-layout.md`
+- 文件和标识符命名：`references/02-file-directory-and-symbol-naming.md`
+- TypeScript 类型安全：`references/04-typescript-type-system.md`
+- 注释和 JSDoc：`references/06-comments-jsdoc-and-documentation.md`
+- 测试：`references/07-testing-strategy.md`
+- 格式化、Lint、复杂度：`references/10-formatting-lint-and-complexity.md`
+- CI 和质量门禁：`references/11-configuration-dependencies-and-ci.md`

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

@@ -0,0 +1,158 @@
+---
+name: typescript-engineering-standards
+description: 为 TypeScript、JavaScript、React、Node.js、Electron、CLI、npm 库与 Monorepo 项目提供可渐进加载的工程规范。用于新建项目、生成代码、目录设计、命名、类型建模、代码审查、重构、测试、Lint、CI、安全与质量门禁；详细规则按任务从 references/ 中最小化读取。
+---
+
+# TypeScript Engineering Standards Skill
+
+本 Skill 将 TypeScript 工程规范拆成一个轻量主入口和多个主题参考文档。执行任务时采用**渐进式披露**：先判断任务类型，再只读取必要参考，避免把全部规范一次性加入上下文。
+
+## 适用任务
+
+在以下任务中使用本 Skill：
+
+- 设计或调整 TypeScript 项目目录。
+- 创建、重命名、移动 `.ts`、`.tsx`、测试或声明文件。
+- 编写、补全、重构或审查 TypeScript/React/Node.js 代码。
+- 制定团队编码规范、`AGENTS.md`、`CONTRIBUTING.md` 或 PR 检查清单。
+- 配置 TypeScript、格式化、Lint、测试、构建与 CI。
+- 处理类型安全、异步、错误、资源清理、安全、性能或跨平台问题。
+- 对现有仓库做工程质量审计。
+
+不在以下场景机械套用：
+
+- 用户明确指定了不同规范。
+- 框架、生成器或公开 API 有不可违背的约定。
+- 任务仅是解释一段代码且不涉及代码修改或规范判断。
+
+## 规则优先级
+
+发生冲突时依次遵循：
+
+1. 用户的明确要求。
+2. 当前仓库已生效的配置、公共 API 与框架约定。
+3. 当前模块已经形成且一致的局部惯例。
+4. 本 Skill 的通用默认规则。
+
+不要为了符合本 Skill 而进行与任务无关的大规模重命名、格式化或架构迁移。发现历史问题时，区分“本次必须修复”和“建议后续治理”。
+
+## 核心执行流程
+
+### 1. 识别任务和边界
+
+先判断：
+
+- 项目类型：Web、React、Node.js、Electron、CLI、库或 Monorepo。
+- 任务类型：新建、增量开发、重构、审查、修复、规范制定或配置。
+- 运行边界：浏览器、服务端、主进程、预加载、Worker、测试环境。
+- 变更范围：单文件、单领域、跨模块或全仓库。
+
+### 2. 检查仓库事实
+
+修改现有项目时，优先检查：
+
+- `package.json` 与锁文件。
+- `tsconfig*.json`。
+- ESLint、Oxlint、Prettier、Oxfmt、Biome 等配置。
+- 测试配置与现有测试命名。
+- `src/` 目录结构、路径别名和导出方式。
+- `AGENTS.md`、`CONTRIBUTING.md`、README 与 CI 工作流。
+
+不要假设项目使用 React、ESLint、Prettier、Vitest、Zod 或某种模块系统。
+
+### 3. 最小化读取参考文档
+
+仅加载与任务直接相关的参考文档。只有进行全仓库规范设计或综合审计时，才读取多个主题。
+
+| 任务 | 首选参考 |
+|---|---|
+| 判断规则强度、处理冲突 | `references/00-standard-levels-and-precedence.md` |
+| 设计目录、拆模块、平铺策略 | `references/01-project-architecture-and-directory-layout.md` |
+| 文件、目录、变量、类型命名 | `references/02-file-directory-and-symbol-naming.md` |
+| 导入、导出、Barrel、依赖方向 | `references/03-modules-imports-exports-and-dependencies.md` |
+| 类型、`unknown`、联合、声明文件 | `references/04-typescript-type-system.md` |
+| 函数、异步、错误、资源生命周期 | `references/05-functions-async-errors-and-resources.md` |
+| 注释、JSDoc、TODO、文档 | `references/06-comments-jsdoc-and-documentation.md` |
+| 单元、集成、契约、E2E 测试 | `references/07-testing-strategy.md` |
+| React、Hook、状态、可访问性 | `references/08-react-and-frontend.md` |
+| Node.js、CLI、路径、环境变量 | `references/09-node-cli-and-cross-platform.md` |
+| 格式、Lint、文件大小、复杂度 | `references/10-formatting-lint-and-complexity.md` |
+| 配置、依赖、脚本、CI | `references/11-configuration-dependencies-and-ci.md` |
+| 安全、性能、国际化 | `references/12-security-performance-and-i18n.md` |
+| Git、PR、评审和交付 | `references/13-git-review-and-delivery.md` |
+| 老项目迁移、例外和渐进治理 | `references/14-adoption-exceptions-and-migration.md` |
+| 了解 Orca 中提炼出的工程习惯 | `references/15-orca-derived-observations.md` |
+
+完整索引见 `references/README.md`。
+
+### 4. 应用核心默认规则
+
+除非仓库事实或用户要求另有规定，默认遵守：
+
+- 先按运行环境和业务领域划分边界，领域内部局部平铺。
+- 文件名表达“领域 + 职责”，避免 `utils`、`helpers`、`common`、`misc` 等模糊名称。
+- 一个文件只有一个主要职责；不要为单个文件机械创建目录。
+- 默认使用命名导出，控制公共 API，禁止无意义全局 Barrel。
+- TypeScript 开启严格模式；外部输入先作为 `unknown` 并在边界验证。
+- 优先使用可辨识联合表达状态，使无效状态难以构造。
+- 所有 Promise、监听器、Timer、连接和进程都有明确处理与清理路径。
+- 注释解释原因、约束与权衡，不逐行翻译代码。
+- 单元测试靠近源码；跨模块集成与 E2E 测试放在独立测试目录。
+- 通过格式化、Lint、类型检查、测试和构建形成自动化门禁。
+
+### 5. 生成或修改代码
+
+生成代码时：
+
+- 遵循仓库现有模块系统和格式风格。
+- 新公开函数写明确返回类型。
+- 不引入未经请求的新框架或依赖。
+- 不用 `any`、双重断言、规则禁用或删除测试掩盖问题。
+- 需要外部验证时，在边界层完成，不把不可信类型传播到内部。
+- 修复缺陷时优先补回归测试。
+- 只修改任务相关文件，避免格式噪声。
+
+### 6. 审查和输出
+
+代码审查时按以下优先级报告：
+
+1. 正确性、安全和数据损坏风险。
+2. 类型系统未覆盖的运行时风险。
+3. 资源泄漏、竞态、取消与错误处理。
+4. 架构边界、循环依赖和公共 API。
+5. 测试缺口。
+6. 命名、文件大小和可维护性。
+7. 纯风格建议。
+
+每条问题尽量包含：位置、风险、触发条件、修复方向。不要把个人偏好描述成缺陷。
+
+## 常用模板
+
+- 精简团队规则：`templates/AGENTS.typescript.md`
+- 严格 TypeScript 基线：`templates/tsconfig.base.json`
+- 多环境项目引用：`templates/tsconfig.project-references.json`
+- 格式化基线：`templates/prettier.json`
+- 编辑器基线：`templates/.editorconfig`
+- npm 脚本示例：`templates/package-scripts.json`
+- PR 模板：`templates/pull-request-template.md`
+- 代码评审清单：`templates/code-review-checklist.md`
+
+模板是起点，不得在未检查项目工具链时直接覆盖现有配置。
+
+## 示例
+
+- 项目目录示例：`examples/project-layouts.md`
+- 命名模式示例：`examples/naming-patterns.md`
+- 类型建模示例：`examples/type-modeling-patterns.md`
+- 注释示例：`examples/comment-patterns.md`
+- 审查输出示例：`examples/review-output-example.md`
+
+## 交付要求
+
+完成任务前确认：
+
+- 变更符合当前仓库事实，而非仅符合抽象规范。
+- 必要测试和质量检查已执行，或明确说明未能执行的项目。
+- 没有增加无意义目录、模糊文件名或隐藏依赖。
+- 没有通过削弱类型、关闭规则或跳过测试来获得表面通过。
+- 输出聚焦本次任务；更广泛的治理建议单独列出，不混入必要修复。

package/template/skills/typescript-engineering-standards/examples/comment-patterns.md

@@ -0,0 +1,47 @@
+# 注释模式示例
+
+## 兼容性
+
+```ts
+// Why: Windows reports the executable path with inconsistent drive-letter casing.
+const normalizedPath = normalizeWindowsDriveLetter(executablePath)
+```
+
+## 第三方缺陷
+
+```ts
+// Why: SDK 4.2 can invoke this callback twice after cancellation.
+if (requestState.isSettled) {
+  return
+}
+```
+
+## 安全顺序
+
+```ts
+// Validate before resolving the path so traversal segments cannot escape the root.
+const safeRelativePath = parseRelativePath(input)
+```
+
+## 性能
+
+```ts
+// Keep the compiled expression outside the hot loop; this runs for every log line.
+const ansiPattern = createAnsiPattern()
+```
+
+## 不推荐
+
+```ts
+// Loop through items.
+for (const item of items) {
+  // Add the item.
+  results.push(item)
+}
+```
+
+## TODO
+
+```ts
+// TODO(PROJ-1423): Remove the v2 fallback after desktop 3.8 reaches 95% adoption.
+```

package/template/skills/typescript-engineering-standards/examples/naming-patterns.md

@@ -0,0 +1,42 @@
+# 命名示例
+
+## 从模糊名称改为具体名称
+
+| 模糊 | 推荐 |
+|---|---|
+| `utils.ts` | `shell-command-quote.ts` |
+| `helpers.ts` | `workspace-path-normalize.ts` |
+| `manager.ts` | `terminal-process-registry.ts` |
+| `handler.ts` | `payment-webhook-handler.ts` |
+| `service.ts` | `user-session-service.ts` |
+| `data.ts` | `workspace-summary.ts` |
+| `types.ts` | `payment-contract.ts` |
+| `constants.ts` | `terminal-limits.ts` |
+
+## 函数
+
+| 含义弱 | 推荐 |
+|---|---|
+| `handle()` | `handleWorkspaceClosed()` |
+| `process()` | `parseTerminalOutput()` |
+| `check()` | `validateWorkspacePath()` |
+| `getData()` | `loadUserProfile()` |
+| `doRetry()` | `retryPaymentCapture()` |
+
+## 布尔值
+
+| 含义弱 | 推荐 |
+|---|---|
+| `flag` | `shouldPersist` |
+| `enabled` | `isTelemetryEnabled` |
+| `valid` | `isWorkspacePathValid` |
+| `notReady` | `isInitializing` 或 `isReady` |
+
+## 单位
+
+| 含义弱 | 推荐 |
+|---|---|
+| `timeout` | `timeoutMs` |
+| `size` | `payloadSizeBytes` |
+| `delay` | `retryDelayMs` |
+| `limit` | `pageSizeLimit` |