@namewta/speculo 0.3.3 → 0.4.0

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-standards-builder` | Interview-driven generator that produces a project-specific TypeScript/JS/React/Node standards skill |
+| `writing-great-skills` | Authoring guidance for agent skills |
 
 ### 2 Workflow Packages
 

package/package.json

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

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 传播。
+- 循环依赖或跨运行环境非法导入。
+- 删除测试、关闭规则或放宽配置来隐藏失败。
+
+对遗留问题采用渐进治理，不要求无关的大规模重写。

package/template/skills/typescript-standards-builder/references/01-project-discovery.md

@@ -0,0 +1,100 @@
+# 项目发现与仓库事实分析
+
+生成规范前必须先建立项目画像。不要凭技术栈名称猜测实际规则。
+
+## 根目录与范围
+
+确认：
+
+- Git 或 Workspace 根目录。
+- 规范覆盖整个仓库、某个应用还是某些包。
+- 自动生成、Vendored、迁移冻结或第三方目录。
+- 是否存在多个互相独立的 TypeScript 工程。
+
+## 优先读取文件
+
+按存在情况检查：
+
+```text
+package.json
+pnpm-workspace.yaml
+yarn.lock / pnpm-lock.yaml / package-lock.json
+nx.json / turbo.json
+ tsconfig*.json
+eslint.config.* / .eslintrc*
+.oxlintrc* / biome.json* / .prettierrc* / oxfmt*
+vitest.config.* / jest.config.* / playwright.config.*
+AGENTS.md / CLAUDE.md / CONTRIBUTING.md
+.github/workflows/* / .gitlab-ci.yml
+```
+
+## 结构采样
+
+至少查看：
+
+- `src/`、`apps/`、`packages/` 的两到三个代表性领域。
+- 普通 `.ts`、React `.tsx`、测试、声明文件和脚本。
+- 公共入口、`index.ts`、路径别名和跨包导入。
+- 运行环境边界，如 Web、Node、Electron、Worker、CLI。
+- 最大或高频修改文件，判断职责和大小分布。
+
+## 工具链事实
+
+记录：
+
+- 包管理器及版本。
+- ESM、CommonJS 或 Bundler 模块模式。
+- TypeScript 版本和严格选项。
+- 格式化与 Lint 工具。
+- 测试框架、浏览器测试和覆盖率工具。
+- 构建、代码生成、发布和 CI 命令。
+- Git Hooks 与暂存文件检查。
+
+## 规范冲突识别
+
+把发现分为：
+
+### 已确定
+
+例如：
+
+- 所有普通文件已经统一使用 `kebab-case.ts`。
+- React 文件统一使用 `PascalCase.tsx`。
+- 单元测试全部为 `*.test.ts` 并与源码共置。
+- `strict` 已启用。
+
+这些事实不需要再问用户。
+
+### 不一致
+
+例如：
+
+- 同一领域混用技术目录和领域目录。
+- `type` 与 `interface` 无规律混用。
+- 测试一部分共置、一部分集中。
+- ESLint 与 Oxlint 同时存在但职责不清。
+
+这些问题进入用户问答。
+
+### 缺失
+
+例如：
+
+- 没有 CI 类型检查。
+- 没有文件大小预算。
+- 没有例外流程。
+- 没有跨运行环境依赖限制。
+
+缺失项应给出推荐默认值，再由用户确认高影响选择。
+
+## 代表性统计
+
+条件允许时，统计而不是凭印象判断：
+
+- `.ts`、`.tsx`、测试文件行数分位数。
+- 模糊文件名数量。
+- `any`、`@ts-ignore`、规则禁用数量。
+- 单元测试共置比例。
+- Barrel 文件和循环依赖情况。
+
+统计只用于形成推荐，不自动做大规模整改。