@namewta/speculo 0.7.4 → 0.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/README.md +2 -2
  2. package/package.json +1 -1
  3. package/template/canonical/README.md +208 -63
  4. package/template/canonical/canonical-person-steelman-deliberation.md +518 -0
  5. package/template/canonical/canonical-specdev-goal-plan.md +436 -68
  6. package/template/skills/engineering-standards-builder/README.md +43 -0
  7. package/template/skills/engineering-standards-builder/SKILL.md +233 -0
  8. package/template/skills/engineering-standards-builder/examples/README.md +15 -0
  9. package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/build.gradle.kts +5 -0
  10. package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/expected.json +12 -0
  11. package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/src/main/kotlin/example/App.kt +2 -0
  12. package/template/skills/engineering-standards-builder/examples/go/service/.golangci.yml +3 -0
  13. package/template/skills/engineering-standards-builder/examples/go/service/cmd/api/main.go +3 -0
  14. package/template/skills/engineering-standards-builder/examples/go/service/expected.json +23 -0
  15. package/template/skills/engineering-standards-builder/examples/go/service/go.mod +3 -0
  16. package/template/skills/engineering-standards-builder/examples/go/service/internal/service/service.go +2 -0
  17. package/template/skills/engineering-standards-builder/examples/go/service/internal/service/service_test.go +3 -0
  18. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/expected.json +22 -0
  19. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/pom.xml +12 -0
  20. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/src/main/java/dev/speculo/orders/OrdersApplication.java +7 -0
  21. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/src/test/java/dev/speculo/orders/OrdersApplicationTest.java +3 -0
  22. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/.github/workflows/ci.yml +11 -0
  23. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/package.json +11 -0
  24. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/src/App.vue +2 -0
  25. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/tsconfig.json +8 -0
  26. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/expected.json +22 -0
  27. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/package.json +11 -0
  28. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/pnpm-workspace.yaml +2 -0
  29. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/orders/pom.xml +12 -0
  30. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/orders/src/main/java/dev/speculo/orders/OrdersApplication.java +7 -0
  31. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/worker/go.mod +3 -0
  32. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/worker/main.go +2 -0
  33. package/template/skills/engineering-standards-builder/examples/rust/workspace/Cargo.toml +7 -0
  34. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/cli/Cargo.toml +8 -0
  35. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/cli/src/main.rs +1 -0
  36. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/core/Cargo.toml +5 -0
  37. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/core/src/lib.rs +3 -0
  38. package/template/skills/engineering-standards-builder/examples/rust/workspace/expected.json +14 -0
  39. package/template/skills/engineering-standards-builder/examples/rust/workspace/rust-toolchain.toml +3 -0
  40. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/expected.json +21 -0
  41. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/package.json +20 -0
  42. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/App.test.tsx +2 -0
  43. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/App.tsx +1 -0
  44. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/main.tsx +3 -0
  45. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/tsconfig.json +10 -0
  46. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/expected.json +22 -0
  47. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/package.json +21 -0
  48. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.test.ts +2 -0
  49. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.vue +7 -0
  50. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/main.ts +4 -0
  51. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/tsconfig.json +11 -0
  52. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/vite.config.ts +2 -0
  53. package/template/skills/engineering-standards-builder/manifest.txt +112 -0
  54. package/template/skills/engineering-standards-builder/references/go/00-detection-and-scope.md +37 -0
  55. package/template/skills/engineering-standards-builder/references/go/01-language-and-idioms.md +34 -0
  56. package/template/skills/engineering-standards-builder/references/go/02-modules-packages-and-layout.md +34 -0
  57. package/template/skills/engineering-standards-builder/references/go/03-errors-context-and-concurrency.md +38 -0
  58. package/template/skills/engineering-standards-builder/references/go/04-testing-tooling-quality-gates.md +46 -0
  59. package/template/skills/engineering-standards-builder/references/go/README.md +9 -0
  60. package/template/skills/engineering-standards-builder/references/java/00-detection-and-scope.md +40 -0
  61. package/template/skills/engineering-standards-builder/references/java/01-language-packages-and-api.md +35 -0
  62. package/template/skills/engineering-standards-builder/references/java/02-build-modules-and-dependencies.md +39 -0
  63. package/template/skills/engineering-standards-builder/references/java/03-errors-nullability-resources-concurrency.md +36 -0
  64. package/template/skills/engineering-standards-builder/references/java/04-testing-tooling-quality-gates.md +36 -0
  65. package/template/skills/engineering-standards-builder/references/java/README.md +10 -0
  66. package/template/skills/engineering-standards-builder/references/java/frameworks/spring-boot.md +74 -0
  67. package/template/skills/engineering-standards-builder/references/rules/00-governance-and-precedence.md +52 -0
  68. package/template/skills/engineering-standards-builder/references/rules/01-project-discovery.md +79 -0
  69. package/template/skills/engineering-standards-builder/references/rules/02-evidence-topology-and-scope.md +87 -0
  70. package/template/skills/engineering-standards-builder/references/rules/03-interview-and-decisions.md +77 -0
  71. package/template/skills/engineering-standards-builder/references/rules/04-architecture-and-dependency-boundaries.md +58 -0
  72. package/template/skills/engineering-standards-builder/references/rules/05-files-directories-and-naming.md +53 -0
  73. package/template/skills/engineering-standards-builder/references/rules/06-apis-errors-resources-and-concurrency.md +53 -0
  74. package/template/skills/engineering-standards-builder/references/rules/07-documentation-and-comments.md +46 -0
  75. package/template/skills/engineering-standards-builder/references/rules/08-testing-strategy.md +45 -0
  76. package/template/skills/engineering-standards-builder/references/rules/09-security-configuration-and-data.md +44 -0
  77. package/template/skills/engineering-standards-builder/references/rules/10-performance-observability-and-i18n.md +36 -0
  78. package/template/skills/engineering-standards-builder/references/rules/11-tooling-quality-gates-and-ci.md +69 -0
  79. package/template/skills/engineering-standards-builder/references/rules/12-git-review-and-delivery.md +46 -0
  80. package/template/skills/engineering-standards-builder/references/rules/13-adoption-exceptions-and-ratchets.md +60 -0
  81. package/template/skills/engineering-standards-builder/references/rules/14-generation-contract.md +105 -0
  82. package/template/skills/engineering-standards-builder/references/rules/15-validation-contract.md +65 -0
  83. package/template/skills/engineering-standards-builder/references/rules/16-language-adapter-contract.md +55 -0
  84. package/template/skills/engineering-standards-builder/references/rules/README.md +23 -0
  85. package/template/skills/engineering-standards-builder/references/rust/00-detection-and-scope.md +38 -0
  86. package/template/skills/engineering-standards-builder/references/rust/01-language-api-and-safety.md +35 -0
  87. package/template/skills/engineering-standards-builder/references/rust/02-crates-workspaces-and-layout.md +36 -0
  88. package/template/skills/engineering-standards-builder/references/rust/03-errors-ownership-and-concurrency.md +37 -0
  89. package/template/skills/engineering-standards-builder/references/rust/04-testing-tooling-quality-gates.md +44 -0
  90. package/template/skills/engineering-standards-builder/references/rust/README.md +9 -0
  91. package/template/skills/engineering-standards-builder/references/typescript/00-detection-and-scope.md +58 -0
  92. package/template/skills/engineering-standards-builder/references/typescript/01-language-and-type-system.md +49 -0
  93. package/template/skills/engineering-standards-builder/references/typescript/02-modules-packages-and-runtime-boundaries.md +49 -0
  94. package/template/skills/engineering-standards-builder/references/typescript/03-functions-async-errors-resources.md +42 -0
  95. package/template/skills/engineering-standards-builder/references/typescript/04-testing-tooling-quality-gates.md +51 -0
  96. package/template/skills/engineering-standards-builder/references/typescript/README.md +27 -0
  97. package/template/skills/engineering-standards-builder/references/typescript/app-types/cli.md +11 -0
  98. package/template/skills/engineering-standards-builder/references/typescript/app-types/library.md +11 -0
  99. package/template/skills/engineering-standards-builder/references/typescript/frameworks/react.md +71 -0
  100. package/template/skills/engineering-standards-builder/references/typescript/frameworks/vue.md +131 -0
  101. package/template/skills/engineering-standards-builder/references/typescript/runtimes/browser.md +15 -0
  102. package/template/skills/engineering-standards-builder/references/typescript/runtimes/electron.md +25 -0
  103. package/template/skills/engineering-standards-builder/references/typescript/runtimes/node.md +13 -0
  104. package/template/skills/engineering-standards-builder/scripts/discover-project.mjs +957 -0
  105. package/template/skills/engineering-standards-builder/scripts/self-test.mjs +203 -0
  106. package/template/skills/engineering-standards-builder/scripts/sync-manifest.mjs +105 -0
  107. package/template/skills/engineering-standards-builder/scripts/validate-builder.mjs +255 -0
  108. package/template/skills/engineering-standards-builder/scripts/validate-generated-skill.mjs +286 -0
  109. package/template/skills/engineering-standards-builder/templates/README.md +18 -0
  110. package/template/skills/engineering-standards-builder/templates/compatibility/agents-typescript--standards.md +6 -0
  111. package/template/skills/engineering-standards-builder/templates/compatibility/agents-typescript-standards.md +6 -0
  112. package/template/skills/engineering-standards-builder/templates/compatibility/claude-engineering-standards.md +6 -0
  113. package/template/skills/engineering-standards-builder/templates/compatibility/claude-typescript-standards.md +6 -0
  114. package/template/skills/engineering-standards-builder/templates/project-skill/SKILL.md.template +26 -0
  115. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/00-project-profile.md.template +26 -0
  116. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/01-module-map.md.template +27 -0
  117. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/02-decisions-and-exceptions.md.template +31 -0
  118. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/review-checklist.md.template +14 -0
  119. package/template/skills/source-code-zip/SKILL.md +568 -0
  120. package/template/skills/source-code-zip/scripts/zip_source_code.js +1363 -0
  121. package/template/workflows/person/INDEX.md +1 -0
  122. package/template/workflows/person/S-steelman-deliberation/S-steelman-deliberation.md +218 -0
  123. package/template/workflows/person/S-steelman-deliberation/_templates/decision-template.md +51 -0
  124. package/template/workflows/person/S-steelman-deliberation/_templates/steelman-dossier-template.md +96 -0
  125. package/template/workflows/person/S-steelman-deliberation/deliberate.md +127 -0
  126. package/template/workflows/person/S-steelman-deliberation/evidence-gate.md +37 -0
  127. package/template/workflows/person/S-steelman-deliberation/judge.md +69 -0
  128. package/template/workflows/person/S-steelman-deliberation/tools/validate-steelman-change.mjs +697 -0
  129. package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +88 -27
  130. package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md +121 -9
  131. package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md +10 -7
  132. package/template/workflows/specdev/common/skills/subagent-delivery/references/source-package.md +229 -9
  133. package/template/skills/typescript-standards-builder/README.md +0 -53
  134. package/template/skills/typescript-standards-builder/SKILL.md +0 -245
  135. package/template/skills/typescript-standards-builder/examples/sample-generated-tree.md +0 -30
  136. package/template/skills/typescript-standards-builder/examples/sample-interview-decisions.md +0 -26
  137. package/template/skills/typescript-standards-builder/manifest.txt +0 -29
  138. package/template/skills/typescript-standards-builder/references/00-governance-and-fixed-defaults.md +0 -77
  139. package/template/skills/typescript-standards-builder/references/01-project-discovery.md +0 -100
  140. package/template/skills/typescript-standards-builder/references/02-interview-workflow.md +0 -129
  141. package/template/skills/typescript-standards-builder/references/03-project-architecture-and-directory-layout.md +0 -84
  142. package/template/skills/typescript-standards-builder/references/04-file-directory-and-symbol-naming.md +0 -92
  143. package/template/skills/typescript-standards-builder/references/05-modules-imports-exports-and-dependencies.md +0 -63
  144. package/template/skills/typescript-standards-builder/references/06-typescript-type-system.md +0 -64
  145. package/template/skills/typescript-standards-builder/references/07-functions-async-errors-and-resources.md +0 -42
  146. package/template/skills/typescript-standards-builder/references/08-comments-jsdoc-and-documentation.md +0 -51
  147. package/template/skills/typescript-standards-builder/references/09-testing-strategy.md +0 -58
  148. package/template/skills/typescript-standards-builder/references/10-react-and-frontend.md +0 -39
  149. package/template/skills/typescript-standards-builder/references/11-node-cli-and-cross-platform.md +0 -31
  150. package/template/skills/typescript-standards-builder/references/12-formatting-lint-and-complexity.md +0 -58
  151. package/template/skills/typescript-standards-builder/references/13-configuration-dependencies-and-ci.md +0 -71
  152. package/template/skills/typescript-standards-builder/references/14-security-performance-and-i18n.md +0 -32
  153. package/template/skills/typescript-standards-builder/references/15-git-review-and-delivery.md +0 -28
  154. package/template/skills/typescript-standards-builder/references/16-adoption-exceptions-and-migration.md +0 -61
  155. package/template/skills/typescript-standards-builder/references/17-generation-contract.md +0 -104
  156. package/template/skills/typescript-standards-builder/references/README.md +0 -37
  157. package/template/skills/typescript-standards-builder/templates/agents-compat-skill/SKILL.md +0 -1
  158. package/template/skills/typescript-standards-builder/templates/claude-skill/SKILL.md +0 -1
  159. package/template/skills/typescript-standards-builder/templates/project-skill/SKILL.md.template +0 -34
  160. package/template/skills/typescript-standards-builder/templates/project-skill/references/00-project-profile.md.template +0 -17
  161. package/template/skills/typescript-standards-builder/templates/project-skill/references/10-review-checklist.md +0 -23
  162. package/template/skills/typescript-standards-builder/templates/project-skill/references/11-decisions-and-exceptions.md.template +0 -19
  163. package/template/workflows/specdev/common/skills/subagent-delivery/references/github-checkpoints.md +0 -24
@@ -0,0 +1,43 @@
1
+ # Engineering Standards Builder(稳定 ID:engineering-standards-builder)
2
+
3
+ 这是 `template/skills/engineering-standards-builder` 的可直接替换版本。目录名和 frontmatter `name` 保持不变,以避免破坏 Speculo 当前的 Skill 清单与调用方;能力已经升级为跨语言项目工程规范生成器。
4
+
5
+ ## 能力范围
6
+
7
+ - 运行前先扫描整个仓库并建立可追溯的 Project Inventory。
8
+ - 支持单项目、Workspace、Monorepo 和多语言 Monorepo。
9
+ - 内置 TypeScript/JavaScript、React、Vue、Java、Spring Boot、Go、Rust 规则包。
10
+ - 通用规则位于 `references/rules/`;语言规则物理隔离。
11
+ - 只生成当前项目实际适用的规则,不复制无关技术栈内容。
12
+ - 通过 `scripts/` 提供只读发现、manifest 校验、Builder 校验和生成结果校验。
13
+ - `examples/` 是自测试 fixture,不是装饰样例。
14
+
15
+ ## 安装
16
+
17
+ 删除仓库中的旧目录:
18
+
19
+ ```text
20
+ template/skills/engineering-standards-builder
21
+ ```
22
+
23
+ 将本目录完整复制到相同位置。不要只复制 `SKILL.md`,因为 references、scripts、templates 和 examples 都是运行合同的一部分。
24
+
25
+ ## 自校验
26
+
27
+ 在本目录执行:
28
+
29
+ ```bash
30
+ node scripts/sync-manifest.mjs --root . --check
31
+ node scripts/validate-builder.mjs --root .
32
+ node scripts/self-test.mjs --root .
33
+ ```
34
+
35
+ ## 生成目标
36
+
37
+ 新 canonical 项目规范为:
38
+
39
+ ```text
40
+ .agents/skills/engineering-standards/
41
+ ```
42
+
43
+ 旧的 `typescript-standards` 与 `typescript--standards` 仅作为需要时生成的单向兼容入口。这样既保留旧项目可用性,又避免继续把跨语言规范命名为 TypeScript 规范。
@@ -0,0 +1,233 @@
1
+ ---
2
+ name: engineering-standards-builder
3
+ description: 生成工程规范:先探索仓库技术架构,再通过最少必要问答,为 TypeScript/JavaScript、React、Vue、Java/Spring Boot、Go、Rust 及多语言 Monorepo 生成项目专属的代码、目录、测试、工具链与交付规范 Skill。
4
+ ---
5
+
6
+ # Engineering Standards Builder
7
+
8
+ `engineering-standards-builder` 是为现有调用方保留的稳定 Skill ID;它生成的规范已经是跨语言的 **Engineering Standards**,不再以 TypeScript 或 React 为中心。
9
+
10
+ 本 Skill 是一个“规范编译器”:
11
+
12
+ ```text
13
+ 仓库事实
14
+ + 用户明确决策
15
+ + 适用的通用规则
16
+ + 适用的语言/框架/运行时规则
17
+ - 不适用规则
18
+ - 已记录例外
19
+ = 当前项目专属工程规范 Skill
20
+ ```
21
+
22
+ 详细知识按分支渐进读取。不得在开始时一次加载全部 `references/`。
23
+
24
+ ## 最终产物
25
+
26
+ 默认 canonical 输出:
27
+
28
+ ```text
29
+ .agents/skills/engineering-standards/
30
+ ├── SKILL.md
31
+ └── references/
32
+ ├── project/
33
+ │ ├── 00-project-profile.md
34
+ │ ├── 01-module-map.md
35
+ │ └── 02-decisions-and-exceptions.md
36
+ ├── rules/
37
+ ├── typescript/ # 仅项目实际使用时
38
+ ├── java/ # 仅项目实际使用时
39
+ ├── go/ # 仅项目实际使用时
40
+ └── rust/ # 仅项目实际使用时
41
+ ```
42
+
43
+ 兼容入口只能单向指向 canonical,不能复制规范正文或形成循环:
44
+
45
+ ```text
46
+ .agents/skills/typescript-standards/SKILL.md
47
+ .agents/skills/typescript--standards/SKILL.md
48
+ .claude/skills/engineering-standards/SKILL.md
49
+ .claude/skills/typescript-standards/SKILL.md
50
+ ```
51
+
52
+ 仅在对应 Agent 目录已存在、用户要求兼容,或仓库已有旧路径时创建兼容入口。
53
+
54
+ ## 执行过程
55
+
56
+ ### 1. 锁定根目录、模式与写入边界
57
+
58
+ 确定:
59
+
60
+ - 真实仓库或 Workspace 根目录;
61
+ - 覆盖整个仓库、指定模块还是指定路径;
62
+ - `create`、`refresh`、`merge` 或 `dry-run` 模式;
63
+ - 生成代码、第三方镜像、Vendor、构建输出与冻结区域;
64
+ - 已存在的工程规范、`AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING.md` 和架构文档。
65
+
66
+ 发生冲突时读取 [`references/rules/00-governance-and-precedence.md`](references/rules/00-governance-and-precedence.md)。路径与作用域判定读取 [`references/rules/02-evidence-topology-and-scope.md`](references/rules/02-evidence-topology-and-scope.md)。
67
+
68
+ 未经明确授权,阶段 1~4 只读。不得执行项目安装、构建、测试、生成器或网络脚本来“探测”技术栈。
69
+
70
+ **完成标准**:根目录解析为真实路径;扫描范围、排除范围、运行模式、已有规范位置与允许写入位置均已记录。
71
+
72
+ ### 2. 先搜索探索整个项目
73
+
74
+ 先运行确定性扫描器,再进行人工语义抽样:
75
+
76
+ ```bash
77
+ node <skill-root>/scripts/discover-project.mjs \
78
+ --root <project-root> \
79
+ --pretty \
80
+ --output .engineering/project-inventory.json
81
+ ```
82
+
83
+ 扫描合同与补充检查见 [`references/rules/01-project-discovery.md`](references/rules/01-project-discovery.md)。扫描器是事实基线,不替代源码、CI 和架构文档抽样。`--output` 只接受根目录内路径;需要外部临时文件时省略该参数并由调用方捕获 stdout。
84
+
85
+ 必须建立:
86
+
87
+ - 仓库拓扑:单项目、Workspace、Monorepo、多模块或多语言 Monorepo;
88
+ - 每个模块的路径、语言、框架、运行时、构建系统、测试系统和交付物;
89
+ - 源码根、测试根、公开入口、生成目录和边界;
90
+ - 已生效的格式化、静态检查、类型检查、测试、构建与 CI 命令;
91
+ - 每项判断的证据路径、置信度、冲突和未知项;
92
+ - 代表性源码样本,而不是只读取 manifest。
93
+
94
+ **完成标准**:每个可编辑模块都有唯一 scope;每项技术判断可追溯到证据;生成/Vendor/构建目录已排除;冲突和未知项均已列出;此时尚未向用户询问仓库中已经能确定的事实。
95
+
96
+ ### 3. 按作用域装配规则包
97
+
98
+ 始终读取通用规则;随后只读取与模块事实匹配的语言、框架、运行时和应用类型参考。
99
+
100
+ 装配顺序:
101
+
102
+ ```text
103
+ references/rules/*
104
+ → references/<language>/*
105
+ → references/<language>/frameworks/*
106
+ → references/<language>/runtimes/*
107
+ → references/<language>/app-types/*
108
+ → 当前项目决策与例外
109
+ ```
110
+
111
+ 完整索引:
112
+
113
+ - [通用规则](references/rules/README.md)
114
+ - [TypeScript / JavaScript](references/typescript/README.md)
115
+ - [Java](references/java/README.md)
116
+ - [Go](references/go/README.md)
117
+ - [Rust](references/rust/README.md)
118
+
119
+ 分支路由:
120
+
121
+ | 识别事实 | 读取 |
122
+ |---|---|
123
+ | 所有项目 | `references/rules/04`~`13` 中与任务相关的文件 |
124
+ | TypeScript/JavaScript | `references/typescript/00`~`04` |
125
+ | React | `references/typescript/frameworks/react.md` |
126
+ | Vue | `references/typescript/frameworks/vue.md` |
127
+ | 浏览器、Node、Electron | 对应 `references/typescript/runtimes/*` |
128
+ | CLI 或发布库 | 对应 `references/typescript/app-types/*` |
129
+ | Java | `references/java/00`~`04` |
130
+ | Spring Boot | `references/java/frameworks/spring-boot.md` |
131
+ | Go | `references/go/00`~`04` |
132
+ | Rust | `references/rust/00`~`04` |
133
+ | 未内置语言 | `references/rules/16-language-adapter-contract.md` 的 fallback |
134
+
135
+ 一个模块出现 `.vue` 文件不能让整个仓库继承 Vue 规则;根目录存在 `package.json` 也不能让 Java、Go 或 Rust 模块继承 Node 规则。
136
+
137
+ **完成标准**:每个待采用规则包都有匹配证据和明确 scope;所有不适用包均已排除;通用层没有语言专属实现被误用。
138
+
139
+ ### 4. 只解决无法由事实确定的高影响决策
140
+
141
+ 读取 [`references/rules/03-interview-and-decisions.md`](references/rules/03-interview-and-decisions.md)。
142
+
143
+ 仅询问会改变生成结果的问题,例如:
144
+
145
+ - 新代码立即强制还是存量 Ratchet;
146
+ - 模块边界、公开 API 和允许的依赖方向;
147
+ - 仓库中真实存在冲突的目录、命名、测试或工具链选择;
148
+ - React/Vue、Spring Boot、Go 或 Rust 的版本迁移与兼容边界;
149
+ - 临时例外的所有者、到期条件和删除条件。
150
+
151
+ 每个问题:
152
+
153
+ 1. 先给出仓库证据;
154
+ 2. 给出推荐默认值及理由;
155
+ 3. 提供 2~4 个可执行选项;
156
+ 4. 记录用户选择、适用 scope 和来源;
157
+ 5. 不重复询问已回答或已由仓库确认的事项。
158
+
159
+ 用户已明确要求直接生成时,使用可解释默认值并把不确定项记录为“待确认”,不再额外阻塞写入。
160
+
161
+ **完成标准**:所有会改变目录、公共 API、强制级别、迁移策略或 CI 门禁的未知项均已决策或显式登记为待确认;没有固定数量的形式化问题。
162
+
163
+ ### 5. 生成前形成可审查计划
164
+
165
+ 展示:
166
+
167
+ - 项目模块地图与技术栈;
168
+ - 将采用和排除的规则包;
169
+ - 仓库事实、用户决策、默认建议和兼容例外;
170
+ - 当前状态、目标状态及迁移阶段;
171
+ - 将创建、合并、保留、移动或删除的文件;
172
+ - 将运行的验证命令。
173
+
174
+ 用户在同一请求中已经授权实施时,展示摘要后直接写入,不重复要求确认。
175
+
176
+ **完成标准**:每个即将写入的文件都有来源和用途;没有未声明覆盖;兼容入口方向唯一。
177
+
178
+ ### 6. 生成或合并项目专属 Skill
179
+
180
+ 读取:
181
+
182
+ - [`references/rules/14-generation-contract.md`](references/rules/14-generation-contract.md)
183
+ - [生成模板索引](templates/README.md)
184
+ - 对应的语言/框架 references
185
+
186
+ 生成原则:
187
+
188
+ - canonical 只有 `.agents/skills/engineering-standards/` 一份;
189
+ - `SKILL.md` 只保留每次执行必须读取的流程、作用域和路由;
190
+ - 详细规则按 `project/`、`rules/`、语言与框架分层;
191
+ - 只生成当前项目实际使用的语言、框架与运行时目录;
192
+ - 每条重要规则包含 `Scope`、`Level`、`Source`、`Verification`;
193
+ - 项目真实命令来自仓库事实或用户确认,不能凭空创造;
194
+ - `refresh`/`merge` 保留用户决策、公共 API、项目特有规则和未到期例外;
195
+ - 存量代码采用 Ratchet,不借生成规范发动无关的大规模重写。
196
+
197
+ **完成标准**:生成树可由项目事实和决策完整解释;没有不适用章节;canonical 内容仅存在一份;所有旧入口单向路由。
198
+
199
+ ### 7. 验证并报告
200
+
201
+ 先运行生成 Skill 验证器:
202
+
203
+ ```bash
204
+ node <skill-root>/scripts/validate-generated-skill.mjs \
205
+ --root <project-root> \
206
+ --strict
207
+ ```
208
+
209
+ 验证合同见 [`references/rules/15-validation-contract.md`](references/rules/15-validation-contract.md)。
210
+
211
+ 随后只运行仓库已经定义且本次允许执行的质量门禁。不得为获得通过而删除测试、关闭核心规则、放宽类型/编译配置或扩大例外。
212
+
213
+ 最终报告:
214
+
215
+ - 创建、更新、保留和删除的文件;
216
+ - 实际采用与排除的规则包;
217
+ - 运行的命令、退出码和关键结果;
218
+ - 未执行或无法验证的项目门禁及原因;
219
+ - 待确认决策、临时例外与后续删除条件。
220
+
221
+ **完成标准**:静态引用、frontmatter、scope、兼容路由和选择性生成全部通过;项目门禁通过,或阻塞证据包含命令、退出码、路径和影响。
222
+
223
+ ## Builder 自校验
224
+
225
+ 维护本 Skill 本身时,fixture 合同见 [examples/README.md](examples/README.md),并运行:
226
+
227
+ ```bash
228
+ node scripts/sync-manifest.mjs --root . --check
229
+ node scripts/validate-builder.mjs --root .
230
+ node scripts/self-test.mjs --root .
231
+ ```
232
+
233
+ 脚本均无第三方依赖、接受显式根目录、拒绝路径越界,并提供 `--help`。
@@ -0,0 +1,15 @@
1
+ # 自测试 Fixtures
2
+
3
+ 这些目录由 `scripts/self-test.mjs` 自动发现:每个含 `expected.json` 的目录都是一个扫描输入与断言合同。它们不是复制到用户项目的示例代码。
4
+
5
+ 覆盖范围:
6
+
7
+ - `typescript/vue-vite/`:Vue 3、TypeScript、Vite、Pinia、Vitest;
8
+ - `typescript/react-vite/`:React、TypeScript、Vite、Vitest;
9
+ - `java/spring-boot-maven/`:Java、Maven、Spring Boot、JUnit、Testcontainers;
10
+ - `go/service/`:Go module、`cmd`、`internal`、测试与 lint 配置;
11
+ - `rust/workspace/`:Cargo virtual workspace、library 与 CLI crate;
12
+ - `polyglot/monorepo/`:Vue、Spring Boot、Go 的模块隔离;
13
+ - `fallback/kotlin-gradle/`:未内置语言只进入通用 fallback,不误套 Java 适配器。
14
+
15
+ 新增适配器必须增加 fixture、`expected.json` 和 self-test 断言。
@@ -0,0 +1,5 @@
1
+ plugins {
2
+ kotlin("jvm") version "2.2.0"
3
+ }
4
+
5
+ repositories { mavenCentral() }
@@ -0,0 +1,12 @@
1
+ {
2
+ "topology": "single-project",
3
+ "module": {
4
+ "path": ".",
5
+ "languages": ["kotlin"],
6
+ "buildSystems": ["gradle"],
7
+ "runtimes": ["jvm"]
8
+ },
9
+ "languages": ["kotlin"],
10
+ "buildSystems": ["gradle"],
11
+ "absentAdapters": ["java"]
12
+ }
@@ -0,0 +1,2 @@
1
+ package example
2
+ fun main() = println("fallback")
@@ -0,0 +1,3 @@
1
+ package main
2
+ import "example.com/orders/internal/service"
3
+ func main() { service.Run() }
@@ -0,0 +1,23 @@
1
+ {
2
+ "topology": "single-project",
3
+ "module": {
4
+ "path": ".",
5
+ "languages": [
6
+ "go"
7
+ ],
8
+ "frameworks": [],
9
+ "buildSystems": [
10
+ "go-modules"
11
+ ],
12
+ "testSystems": [
13
+ "go-test"
14
+ ],
15
+ "runtimes": [
16
+ "native"
17
+ ],
18
+ "applicationTypes": [
19
+ "service",
20
+ "cli"
21
+ ]
22
+ }
23
+ }
@@ -0,0 +1,3 @@
1
+ module example.com/orders
2
+
3
+ go 1.24
@@ -0,0 +1,3 @@
1
+ package service
2
+ import "testing"
3
+ func TestRun(t *testing.T) { Run() }
@@ -0,0 +1,22 @@
1
+ {
2
+ "topology": "single-project",
3
+ "module": {
4
+ "path": ".",
5
+ "languages": [
6
+ "java"
7
+ ],
8
+ "frameworks": [
9
+ "spring-boot"
10
+ ],
11
+ "buildSystems": [
12
+ "maven"
13
+ ],
14
+ "testSystems": [
15
+ "junit",
16
+ "testcontainers"
17
+ ],
18
+ "runtimes": [
19
+ "jvm"
20
+ ]
21
+ }
22
+ }
@@ -0,0 +1,12 @@
1
+ <project xmlns="http://maven.apache.org/POM/4.0.0">
2
+ <modelVersion>4.0.0</modelVersion>
3
+ <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>4.0.0</version></parent>
4
+ <groupId>dev.speculo</groupId><artifactId>orders</artifactId><version>1.0.0</version>
5
+ <properties><java.version>21</java.version></properties>
6
+ <dependencies>
7
+ <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
8
+ <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
9
+ <dependency><groupId>org.testcontainers</groupId><artifactId>junit-jupiter</artifactId><scope>test</scope></dependency>
10
+ </dependencies>
11
+ <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
12
+ </project>
@@ -0,0 +1,7 @@
1
+ package dev.speculo.orders;
2
+ import org.springframework.boot.SpringApplication;
3
+ import org.springframework.boot.autoconfigure.SpringBootApplication;
4
+ @SpringBootApplication
5
+ public class OrdersApplication {
6
+ public static void main(String[] args) { SpringApplication.run(OrdersApplication.class, args); }
7
+ }
@@ -0,0 +1,3 @@
1
+ package dev.speculo.orders;
2
+ import org.junit.jupiter.api.Test;
3
+ class OrdersApplicationTest { @Test void starts() {} }
@@ -0,0 +1,11 @@
1
+ name: ci
2
+ on: [push, pull_request]
3
+ jobs:
4
+ verify:
5
+ runs-on: ubuntu-latest
6
+ steps:
7
+ - uses: actions/checkout@v4
8
+ - run: pnpm run build
9
+ - run: mvn -f services/orders/pom.xml test
10
+ - run: go test ./...
11
+ working-directory: services/worker
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "web",
3
+ "private": true,
4
+ "dependencies": {
5
+ "vue": "^3.5.0"
6
+ },
7
+ "devDependencies": {
8
+ "typescript": "^5.9.0",
9
+ "vite": "^7.0.0"
10
+ }
11
+ }
@@ -0,0 +1,2 @@
1
+ <script setup lang="ts">const msg = "web"</script>
2
+ <template><main>{{ msg }}</main></template>
@@ -0,0 +1,8 @@
1
+ {
2
+ "compilerOptions": {
3
+ "strict": true
4
+ },
5
+ "include": [
6
+ "src"
7
+ ]
8
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "topology": "polyglot-monorepo",
3
+ "minimumModules": 4,
4
+ "languages": [
5
+ "typescript",
6
+ "java",
7
+ "go"
8
+ ],
9
+ "frameworks": [
10
+ "vue",
11
+ "spring-boot"
12
+ ],
13
+ "buildSystems": [
14
+ "vite",
15
+ "maven",
16
+ "go-modules"
17
+ ],
18
+ "ciResponsibilities": [
19
+ "build-or-package",
20
+ "test"
21
+ ]
22
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "polyglot-fixture",
3
+ "private": true,
4
+ "workspaces": [
5
+ "apps/*"
6
+ ],
7
+ "packageManager": "pnpm@10.0.0",
8
+ "scripts": {
9
+ "check": "echo fixture"
10
+ }
11
+ }
@@ -0,0 +1,12 @@
1
+ <project xmlns="http://maven.apache.org/POM/4.0.0">
2
+ <modelVersion>4.0.0</modelVersion>
3
+ <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>4.0.0</version></parent>
4
+ <groupId>dev.speculo</groupId><artifactId>polyglot-orders</artifactId><version>1.0.0</version>
5
+ <properties><java.version>21</java.version></properties>
6
+ <dependencies>
7
+ <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
8
+ <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
9
+ <dependency><groupId>org.testcontainers</groupId><artifactId>junit-jupiter</artifactId><scope>test</scope></dependency>
10
+ </dependencies>
11
+ <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
12
+ </project>
@@ -0,0 +1,7 @@
1
+ package dev.speculo.orders;
2
+ import org.springframework.boot.SpringApplication;
3
+ import org.springframework.boot.autoconfigure.SpringBootApplication;
4
+ @SpringBootApplication
5
+ public class OrdersApplication {
6
+ public static void main(String[] args) { SpringApplication.run(OrdersApplication.class, args); }
7
+ }
@@ -0,0 +1,7 @@
1
+ [workspace]
2
+ members = ["crates/core", "crates/cli"]
3
+ resolver = "3"
4
+
5
+ [workspace.package]
6
+ edition = "2024"
7
+ rust-version = "1.85"
@@ -0,0 +1,8 @@
1
+ [package]
2
+ name = "fixture-cli"
3
+ version = "0.1.0"
4
+ edition.workspace = true
5
+ rust-version.workspace = true
6
+
7
+ [dependencies]
8
+ fixture-core = { path = "../core" }
@@ -0,0 +1 @@
1
+ fn main() { println!("{}", fixture_core::value()); }
@@ -0,0 +1,5 @@
1
+ [package]
2
+ name = "fixture-core"
3
+ version = "0.1.0"
4
+ edition.workspace = true
5
+ rust-version.workspace = true
@@ -0,0 +1,3 @@
1
+ pub fn value() -> u32 { 42 }
2
+
3
+ #[cfg(test)] mod tests { #[test] fn value_is_stable() { assert_eq!(super::value(), 42); } }
@@ -0,0 +1,14 @@
1
+ {
2
+ "topology": "workspace",
3
+ "minimumModules": 3,
4
+ "languages": [
5
+ "rust"
6
+ ],
7
+ "frameworks": [],
8
+ "buildSystems": [
9
+ "cargo"
10
+ ],
11
+ "testSystems": [
12
+ "cargo-test"
13
+ ]
14
+ }
@@ -0,0 +1,3 @@
1
+ [toolchain]
2
+ channel = "1.85"
3
+ components = ["rustfmt", "clippy"]
@@ -0,0 +1,21 @@
1
+ {
2
+ "topology": "single-project",
3
+ "module": {
4
+ "path": ".",
5
+ "languages": [
6
+ "typescript"
7
+ ],
8
+ "frameworks": [
9
+ "react"
10
+ ],
11
+ "buildSystems": [
12
+ "vite"
13
+ ],
14
+ "testSystems": [
15
+ "vitest"
16
+ ],
17
+ "runtimes": [
18
+ "browser"
19
+ ]
20
+ }
21
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "react-vite-fixture",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "typecheck": "tsc --noEmit",
7
+ "test": "vitest run",
8
+ "build": "vite build"
9
+ },
10
+ "dependencies": {
11
+ "react": "^19.0.0",
12
+ "react-dom": "^19.0.0"
13
+ },
14
+ "devDependencies": {
15
+ "typescript": "^5.9.0",
16
+ "vite": "^7.0.0",
17
+ "vitest": "^3.0.0",
18
+ "eslint": "^9.0.0"
19
+ }
20
+ }
@@ -0,0 +1,2 @@
1
+ import { describe, expect, it } from 'vitest'
2
+ describe('fixture', () => { it('works', () => expect(true).toBe(true)) })
@@ -0,0 +1 @@
1
+ export function App() { return <button type="button">Hello</button> }
@@ -0,0 +1,3 @@
1
+ import { createRoot } from 'react-dom/client'
2
+ import { App } from './App'
3
+ createRoot(document.body).render(<App />)
@@ -0,0 +1,10 @@
1
+ {
2
+ "compilerOptions": {
3
+ "strict": true,
4
+ "jsx": "react-jsx",
5
+ "module": "ESNext"
6
+ },
7
+ "include": [
8
+ "src"
9
+ ]
10
+ }