@namewta/speculo 0.3.3 → 0.4.0

package/template/skills/typescript-standards-builder/references/12-formatting-lint-and-complexity.md

@@ -0,0 +1,58 @@
+# 格式化、Lint 与复杂度
+
+## 工具统一风格
+
+格式由仓库选定的 Prettier、Oxfmt、Biome 或其他工具自动完成。代码评审不争论工具已经确定的空格、换行和引号。
+
+具体选项必须从现有配置或用户问答生成，不机械复制某个项目的完整格式配置。
+
+## 文件大小预算
+
+这是固定默认原则：普通 TypeScript、React、测试和脚本使用不同预算。
+
+通用起点：
+
+| 文件类型 | 可作为初始推荐的软上限 |
+|---|---:|
+| 普通 `.ts` | 300 行 |
+| React `.tsx` | 400 行 |
+| 测试 | 600～800 行 |
+| 构建或生成脚本 | 600 行 |
+| 函数 | 40～60 行 |
+
+生成项目规范时必须结合仓库实际分位数和用户选择调整。数字是审查触发器，不是机械裁决。
+
+超限时检查：
+
+- 是否混合多个职责或抽象层级。
+- 分支、状态和依赖是否过多。
+- 是否可分离解析、验证、I/O、领域规则或 UI 展示。
+- 拆分后能否得到具体文件名。
+
+禁止为了满足行数把代码拆进 `helpers.ts`。
+
+## Ratchet
+
+历史超限文件不要求一次性重写，但：
+
+- 新变更不得继续无边界增长。
+- 每次触及时应提取一项明确职责或降低复杂度。
+- CI 可只阻止新增超限，而不一次阻塞全部历史文件。
+
+## Lint 覆盖
+
+至少覆盖：
+
+- 未使用变量和导入。
+- 浮动 Promise。
+- 不可达和重复分支。
+- React Hooks 规则。
+- 显式 `any` 和不安全断言。
+- 类型导入一致性。
+- Switch 穷尽检查。
+- 循环依赖和禁止跨层导入。
+- 文件大小、嵌套和复杂度。
+
+## 禁用规则
+
+规则禁用必须精确到最小范围、指明规则名、解释 WHY，并在临时例外中附删除条件。禁止文件级关闭核心类型、Hooks、Promise 或安全规则来掩盖问题。

package/template/skills/typescript-standards-builder/references/13-configuration-dependencies-and-ci.md

@@ -0,0 +1,71 @@
+# 配置、依赖与自动化质量门禁
+
+## 工具链必须形成门禁
+
+这是固定默认原则。项目至少应通过稳定命令覆盖：
+
+- 格式检查。
+- Lint。
+- TypeScript 类型检查。
+- 单元测试。
+- 构建。
+
+按项目增加集成、契约、E2E、安全、许可证、包体积、依赖边界和本地化检查。
+
+底层工具可替换，但推荐保持稳定脚本职责：
+
+```text
+format
+format:check
+lint
+typecheck
+test
+build
+check
+```
+
+## CI 顺序
+
+常用顺序：
+
+```text
+install
+  → format:check
+  → lint
+  → typecheck
+  → unit tests
+  → build
+  → integration/e2e
+```
+
+实际顺序可并行优化，但不得省略项目确认的核心门禁。
+
+## 禁止绕过
+
+不得通过以下方式获得表面通过：
+
+- 删除或长期跳过失败测试。
+- 关闭核心 Lint 规则。
+- 扩大 `any` 或强制断言。
+- 无计划放宽 TypeScript 配置。
+- 降低测试范围隐藏回归。
+- 忽略构建或代码生成失败。
+
+## TypeScript 配置
+
+- 多运行环境使用独立配置或项目引用。
+- 共享基线放在根配置。
+- 浏览器和 Node 的 `lib`、`types`、模块解析隔离。
+- 不为解决单个文件问题全局放宽配置。
+
+## 依赖
+
+- 运行时包进入 `dependencies`。
+- 构建、测试、类型和格式工具进入 `devDependencies`。
+- 锁文件提交，`packageManager` 固定工具和版本。
+- 新依赖评估维护、体积、许可证、安全和平台兼容性。
+- 不为一个简单函数引入大型依赖。
+
+## 本地钩子
+
+提交前钩子可只处理暂存文件以保证速度；完整类型检查、测试和构建由 CI 负责。项目规范必须写清本地与 CI 的职责边界。

package/template/skills/typescript-standards-builder/references/14-security-performance-and-i18n.md

@@ -0,0 +1,32 @@
+# 安全、性能与国际化
+
+## 安全
+
+- 外部输入在边界验证。
+- 路径防止目录穿越。
+- SQL 和命令使用参数化接口。
+- HTML 输出转义，谨慎处理原始 HTML。
+- URL、重定向、文件类型和消息来源校验。
+- 不将 Token、密码、Cookie、私钥和完整个人信息写入日志。
+- 不把秘密放入浏览器 Bundle。
+- 权限判断集中管理，前端隐藏按钮不能替代服务端鉴权。
+
+## 性能
+
+- 不做没有测量依据的微优化。
+- 优先减少算法复杂度、I/O 次数和大型对象复制。
+- 大列表、日志和文件采用分页、流式、窗口化或虚拟化。
+- 缓存定义键、容量、淘汰、失效和一致性策略。
+- Timer、监听器和缓存都有上限与清理。
+- 非直观性能优化使用简短 WHY 注释并配回归或基准测试。
+
+## 国际化
+
+仅在项目有多语言需求时生成：
+
+- 用户可见文本不散落为硬编码字符串。
+- 文案键按领域命名。
+- 插值使用命名参数。
+- 不用字符串拼接构造自然语言句子。
+- 日期、数字、货币和复数使用国际化 API。
+- 错误日志与用户提示分离。

package/template/skills/typescript-standards-builder/references/15-git-review-and-delivery.md

@@ -0,0 +1,28 @@
+# Git、代码评审与交付
+
+## 提交与 PR
+
+- 一个提交和 PR 聚焦一个逻辑主题。
+- 不混入无关全仓库格式化。
+- 缺陷修复提供回归测试。
+- UI 变化提供截图或录屏。
+- 说明背景、方案、风险和验证方式。
+- 评估跨平台、性能、安全和兼容性影响。
+
+提交格式可采用仓库已有约定；没有约定时推荐 Conventional Commits。
+
+## 评审优先级
+
+1. 正确性、安全和数据损坏。
+2. 外部输入和类型边界。
+3. 资源泄漏、竞态、取消和错误处理。
+4. 架构边界、循环依赖和公共 API。
+5. 测试缺口。
+6. 文件职责、大小和命名。
+7. 纯风格建议。
+
+每条问题包含位置、风险、触发条件和修复方向。不要把个人偏好描述成缺陷。
+
+## 门禁
+
+合并前执行项目确认的格式、Lint、类型、测试和构建检查。无法执行的项目必须明确报告，不得声称已通过。

package/template/skills/typescript-standards-builder/references/16-adoption-exceptions-and-migration.md

@@ -0,0 +1,61 @@
+# 落地、例外与迁移
+
+## 不机械复制
+
+项目规范只生成实际适用的内容：
+
+- 普通 Web 项目不生成 Electron 主进程规则。
+- 非 React 项目不生成 Hook 和组件约定。
+- 已使用 Biome/Oxc 的项目不强行切换到 ESLint/Prettier。
+- 生成器管理的目录保留生成器约定。
+- 通用行数阈值必须结合仓库实际调整。
+
+复制的是目标：边界清晰、职责具体、类型严格、质量自动化、修改可验证。
+
+## 例外
+
+例外必须：
+
+1. 有具体技术原因。
+2. 范围尽可能小。
+3. 在代码、配置、决策记录或 PR 中说明。
+4. 不破坏核心安全和类型边界。
+5. 临时例外有负责人、退出条件和任务编号。
+6. 经评审确认。
+
+## 遗留项目
+
+推荐阶段：
+
+### 1. 建立事实和命令
+
+固定包管理器和锁文件，建立稳定 `format:check`、`lint`、`typecheck`、`test`、`build`。
+
+### 2. 阻止新增债务
+
+- 新文件遵守具体命名和大小预算。
+- 新 API 不传播 `any`。
+- 新边界输入必须验证。
+- 缺陷修复补回归测试。
+
+### 3. 触及治理
+
+修改旧文件时降低复杂度、拆出纯逻辑、补测试、清理循环依赖和万能工具文件。
+
+### 4. 专项迁移
+
+分模块开启严格选项、迁移目录、引入项目引用和依赖边界检查。
+
+## Ratchet 指标
+
+可跟踪：
+
+- 超限文件数量不增加。
+- `any` 和 `@ts-ignore` 不增加。
+- 循环依赖不增加。
+- 跳过测试不增加。
+- Lint 警告基线只下降。
+
+## 大规模重命名
+
+仅在用户明确确认时进行，使用独立变更，不混入功能修改，并验证大小写敏感文件系统、导入、测试、文档和构建。

package/template/skills/typescript-standards-builder/references/17-generation-contract.md

@@ -0,0 +1,104 @@
+# 项目 Skill 生成合同
+
+## 正式规范源
+
+唯一正式源：
+
+```text
+.agents/skills/typescript-standards/
+```
+
+该目录至少包含：
+
+- `SKILL.md`
+- `references/00-project-profile.md`
+- 与项目实际技术栈相关的主题参考文档。
+- `references/10-review-checklist.md`
+- `references/11-decisions-and-exceptions.md`
+
+## 主 Skill 内容
+
+Frontmatter：
+
+```yaml
+---
+name: typescript-standards
+description: 当前项目专属的 TypeScript 编码、目录、测试与工程质量规范。处理本项目中的 TypeScript、React、Node.js、构建、测试、重构和代码审查任务时必须使用。
+---
+```
+
+正文保持精简，包含：
+
+- 项目和适用范围。
+- 规则优先级。
+- 8～12 条核心不可违背规则。
+- 参考文档路由。
+- 修改代码前后的检查流程。
+- 例外处理入口。
+
+不要把全部规范塞回主文件。
+
+## 项目画像
+
+`00-project-profile.md` 应记录：
+
+- 项目类型和主要框架。
+- 运行环境和包边界。
+- 包管理器、模块系统和 TypeScript 配置。
+- 格式、Lint、测试、构建和 CI 工具。
+- 自动生成和豁免目录。
+- 规范适用范围。
+
+## 规则来源标记
+
+每个主题文件应在顶部列出规则来源：
+
+```md
+> 来源：仓库事实 + 用户确认 + 默认基线
+```
+
+兼容例外写入 `11-decisions-and-exceptions.md`，不要散落为无法追踪的隐式规则。
+
+## 精简与裁剪
+
+- 非 React 项目不生成 React 章节。
+- 非 Node 项目不生成 Node/CLI 章节。
+- 没有国际化需求时不生成国际化规则。
+- 不复制未采用工具的配置示例。
+- 保留固定默认原则对应的实际规则，但使用项目自己的阈值、命名和命令。
+
+## 重定向文件
+
+`.agents/skills/typescript--standards/SKILL.md`：
+
+```md
+本文件仅用于路径兼容；必须立即读取并完整遵循项目根目录下的 `.agents/skills/typescript-standards/SKILL.md`。
+```
+
+`.claude/skills/typescript-standards/SKILL.md`：
+
+```md
+必须先读取并完整遵循项目根目录下的 `.agents/skills/typescript--standards/SKILL.md`，禁止在未读取该文件时执行任何 TypeScript 相关任务。
+```
+
+两个文件均必须恰好一句话，不添加 Frontmatter。
+
+## 更新已有 Skill
+
+若目标目录已存在：
+
+1. 读取当前主 Skill、引用文档和例外记录。
+2. 将仓库新事实与旧决定区分。
+3. 保留仍有效的项目特有规则。
+4. 对冲突规则询问用户，不静默覆盖。
+5. 更新决策记录和修订日期。
+6. 报告新增、修改、删除和保留内容。
+
+## 验证
+
+- 主 Skill Frontmatter 可解析。
+- 所有相对引用存在。
+- 无孤立或重复规范文件。
+- 没有独立 Orca 附录。
+- 固定默认原则已进入对应主题。
+- 两个重定向文件内容完全符合合同。

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

@@ -0,0 +1,37 @@
+# Reference Index
+
+本目录是生成项目专属 TypeScript Standards Skill 的知识源。主入口按任务最小化读取。
+
+## 工作流
+
+- `00-governance-and-fixed-defaults.md`：优先级和已确认的固定默认原则。
+- `01-project-discovery.md`：读取仓库事实并建立项目画像。
+- `02-interview-workflow.md`：自适应用户问答。
+- `17-generation-contract.md`：输出目录、文件内容和验证合同。
+
+## 规范模块
+
+- `03-project-architecture-and-directory-layout.md`
+- `04-file-directory-and-symbol-naming.md`
+- `05-modules-imports-exports-and-dependencies.md`
+- `06-typescript-type-system.md`
+- `07-functions-async-errors-and-resources.md`
+- `08-comments-jsdoc-and-documentation.md`
+- `09-testing-strategy.md`
+- `10-react-and-frontend.md`
+- `11-node-cli-and-cross-platform.md`
+- `12-formatting-lint-and-complexity.md`
+- `13-configuration-dependencies-and-ci.md`
+- `14-security-performance-and-i18n.md`
+- `15-git-review-and-delivery.md`
+- `16-adoption-exceptions-and-migration.md`
+
+原先独立的 `15-orca-derived-observations.md` 已取消。其第 2～8 项已分别融入：
+
+- 局部平铺 → `03`
+- 具体文件名 → `04`
+- 文件体积 → `12`
+- WHY 注释 → `08`
+- 自动化门禁 → `13`
+- 测试共置 → `09`
+- 不机械复制 → `00`、`03`、`16`

package/template/skills/typescript-standards-builder/templates/agents-compat-skill/SKILL.md

@@ -0,0 +1 @@
+本文件仅用于路径兼容；必须立即读取并完整遵循项目根目录下的 `.agents/skills/typescript-standards/SKILL.md`。

package/template/skills/typescript-standards-builder/templates/claude-skill/SKILL.md

@@ -0,0 +1 @@
+必须先读取并完整遵循项目根目录下的 `.agents/skills/typescript--standards/SKILL.md`，禁止在未读取该文件时执行任何 TypeScript 相关任务。

package/template/skills/typescript-standards-builder/templates/project-skill/SKILL.md.template

@@ -0,0 +1,34 @@
+---
+name: typescript-standards
+description: {{PROJECT_NAME}} 项目专属的 TypeScript 编码、目录、测试与工程质量规范。处理本项目中的 TypeScript 相关任务时必须使用。
+---
+
+# {{PROJECT_NAME}} TypeScript Standards
+
+> 规范范围：{{SCOPE}}
+> 最近确认：{{DATE}}
+
+## 优先级
+
+1. 本轮用户明确决定。
+2. 平台、框架、协议和公共 API 硬约束。
+3. 当前仓库配置与 CI。
+4. 本 Skill 的项目规则。
+
+## 核心规则
+
+{{CORE_RULES}}
+
+## 工作流程
+
+修改代码前：读取 `references/00-project-profile.md` 及与任务相关的最小参考文档。
+
+修改代码后：运行项目规定的格式、Lint、类型、测试和构建命令；无法执行时明确报告。
+
+## 参考路由
+
+{{REFERENCE_ROUTING}}
+
+## 例外
+
+所有例外记录在 `references/11-decisions-and-exceptions.md`。不得通过扩大 `any`、关闭核心规则或删除测试绕过门禁。

package/template/skills/typescript-standards-builder/templates/project-skill/references/00-project-profile.md.template

@@ -0,0 +1,17 @@
+# 项目画像
+
+> 来源：仓库事实 + 用户确认
+
+- 项目名称：{{PROJECT_NAME}}
+- 规范范围：{{SCOPE}}
+- 项目类型：{{PROJECT_TYPES}}
+- 运行环境：{{RUNTIMES}}
+- 包管理器：{{PACKAGE_MANAGER}}
+- 模块系统：{{MODULE_SYSTEM}}
+- TypeScript：{{TSCONFIG_SUMMARY}}
+- 格式化：{{FORMATTER}}
+- Lint：{{LINTER}}
+- 测试：{{TEST_TOOLS}}
+- 构建：{{BUILD_TOOLS}}
+- CI：{{CI_SUMMARY}}
+- 自动生成或豁免目录：{{EXCLUDED_PATHS}}

package/template/skills/typescript-standards-builder/templates/project-skill/references/10-review-checklist.md

@@ -0,0 +1,23 @@
+# TypeScript 代码评审检查清单
+
+## 架构和命名
+
+- [ ] 文件位于正确运行环境和领域。
+- [ ] 领域内部保持局部平铺，没有无意义单文件目录。
+- [ ] 文件名具体，没有万能 `utils`、`helpers`、`common`。
+- [ ] 依赖方向正确，没有新增循环依赖。
+
+## 类型和实现
+
+- [ ] 外部输入已验证，未传播 `any`。
+- [ ] 公共函数和契约类型明确。
+- [ ] Promise、错误、取消和资源清理完整。
+- [ ] 注释解释 WHY，而非复述代码。
+- [ ] 文件和函数未无理由超过项目预算。
+
+## 测试和交付
+
+- [ ] 单元测试与实现共置。
+- [ ] 缺陷修复包含回归测试。
+- [ ] 格式、Lint、类型、测试和构建门禁通过。
+- [ ] 未通过关闭规则或跳过测试绕过失败。

package/template/skills/typescript-standards-builder/templates/project-skill/references/11-decisions-and-exceptions.md.template

@@ -0,0 +1,19 @@
+# 决策与例外记录
+
+## 用户确认决定
+
+{{USER_DECISIONS}}
+
+## 使用的默认基线
+
+{{DEFAULT_DECISIONS}}
+
+## 仓库事实
+
+{{REPOSITORY_FACTS}}
+
+## 兼容例外
+
+{{EXCEPTIONS}}
+
+每项临时例外必须包含原因、负责人或任务编号、适用范围和删除条件。