@namewta/speculo 0.7.4 → 0.7.5

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 (157) 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/skills/engineering-standards-builder/README.md +43 -0
  6. package/template/skills/engineering-standards-builder/SKILL.md +233 -0
  7. package/template/skills/engineering-standards-builder/examples/README.md +15 -0
  8. package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/build.gradle.kts +5 -0
  9. package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/expected.json +12 -0
  10. package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/src/main/kotlin/example/App.kt +2 -0
  11. package/template/skills/engineering-standards-builder/examples/go/service/.golangci.yml +3 -0
  12. package/template/skills/engineering-standards-builder/examples/go/service/cmd/api/main.go +3 -0
  13. package/template/skills/engineering-standards-builder/examples/go/service/expected.json +23 -0
  14. package/template/skills/engineering-standards-builder/examples/go/service/go.mod +3 -0
  15. package/template/skills/engineering-standards-builder/examples/go/service/internal/service/service.go +2 -0
  16. package/template/skills/engineering-standards-builder/examples/go/service/internal/service/service_test.go +3 -0
  17. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/expected.json +22 -0
  18. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/pom.xml +12 -0
  19. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/src/main/java/dev/speculo/orders/OrdersApplication.java +7 -0
  20. package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/src/test/java/dev/speculo/orders/OrdersApplicationTest.java +3 -0
  21. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/.github/workflows/ci.yml +11 -0
  22. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/package.json +11 -0
  23. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/src/App.vue +2 -0
  24. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/tsconfig.json +8 -0
  25. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/expected.json +22 -0
  26. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/package.json +11 -0
  27. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/pnpm-workspace.yaml +2 -0
  28. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/orders/pom.xml +12 -0
  29. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/orders/src/main/java/dev/speculo/orders/OrdersApplication.java +7 -0
  30. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/worker/go.mod +3 -0
  31. package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/worker/main.go +2 -0
  32. package/template/skills/engineering-standards-builder/examples/rust/workspace/Cargo.toml +7 -0
  33. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/cli/Cargo.toml +8 -0
  34. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/cli/src/main.rs +1 -0
  35. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/core/Cargo.toml +5 -0
  36. package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/core/src/lib.rs +3 -0
  37. package/template/skills/engineering-standards-builder/examples/rust/workspace/expected.json +14 -0
  38. package/template/skills/engineering-standards-builder/examples/rust/workspace/rust-toolchain.toml +3 -0
  39. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/expected.json +21 -0
  40. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/package.json +20 -0
  41. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/App.test.tsx +2 -0
  42. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/App.tsx +1 -0
  43. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/main.tsx +3 -0
  44. package/template/skills/engineering-standards-builder/examples/typescript/react-vite/tsconfig.json +10 -0
  45. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/expected.json +22 -0
  46. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/package.json +21 -0
  47. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.test.ts +2 -0
  48. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.vue +7 -0
  49. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/main.ts +4 -0
  50. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/tsconfig.json +11 -0
  51. package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/vite.config.ts +2 -0
  52. package/template/skills/engineering-standards-builder/manifest.txt +112 -0
  53. package/template/skills/engineering-standards-builder/references/go/00-detection-and-scope.md +37 -0
  54. package/template/skills/engineering-standards-builder/references/go/01-language-and-idioms.md +34 -0
  55. package/template/skills/engineering-standards-builder/references/go/02-modules-packages-and-layout.md +34 -0
  56. package/template/skills/engineering-standards-builder/references/go/03-errors-context-and-concurrency.md +38 -0
  57. package/template/skills/engineering-standards-builder/references/go/04-testing-tooling-quality-gates.md +46 -0
  58. package/template/skills/engineering-standards-builder/references/go/README.md +9 -0
  59. package/template/skills/engineering-standards-builder/references/java/00-detection-and-scope.md +40 -0
  60. package/template/skills/engineering-standards-builder/references/java/01-language-packages-and-api.md +35 -0
  61. package/template/skills/engineering-standards-builder/references/java/02-build-modules-and-dependencies.md +39 -0
  62. package/template/skills/engineering-standards-builder/references/java/03-errors-nullability-resources-concurrency.md +36 -0
  63. package/template/skills/engineering-standards-builder/references/java/04-testing-tooling-quality-gates.md +36 -0
  64. package/template/skills/engineering-standards-builder/references/java/README.md +10 -0
  65. package/template/skills/engineering-standards-builder/references/java/frameworks/spring-boot.md +74 -0
  66. package/template/skills/engineering-standards-builder/references/rules/00-governance-and-precedence.md +52 -0
  67. package/template/skills/engineering-standards-builder/references/rules/01-project-discovery.md +79 -0
  68. package/template/skills/engineering-standards-builder/references/rules/02-evidence-topology-and-scope.md +87 -0
  69. package/template/skills/engineering-standards-builder/references/rules/03-interview-and-decisions.md +77 -0
  70. package/template/skills/engineering-standards-builder/references/rules/04-architecture-and-dependency-boundaries.md +58 -0
  71. package/template/skills/engineering-standards-builder/references/rules/05-files-directories-and-naming.md +53 -0
  72. package/template/skills/engineering-standards-builder/references/rules/06-apis-errors-resources-and-concurrency.md +53 -0
  73. package/template/skills/engineering-standards-builder/references/rules/07-documentation-and-comments.md +46 -0
  74. package/template/skills/engineering-standards-builder/references/rules/08-testing-strategy.md +45 -0
  75. package/template/skills/engineering-standards-builder/references/rules/09-security-configuration-and-data.md +44 -0
  76. package/template/skills/engineering-standards-builder/references/rules/10-performance-observability-and-i18n.md +36 -0
  77. package/template/skills/engineering-standards-builder/references/rules/11-tooling-quality-gates-and-ci.md +69 -0
  78. package/template/skills/engineering-standards-builder/references/rules/12-git-review-and-delivery.md +46 -0
  79. package/template/skills/engineering-standards-builder/references/rules/13-adoption-exceptions-and-ratchets.md +60 -0
  80. package/template/skills/engineering-standards-builder/references/rules/14-generation-contract.md +105 -0
  81. package/template/skills/engineering-standards-builder/references/rules/15-validation-contract.md +65 -0
  82. package/template/skills/engineering-standards-builder/references/rules/16-language-adapter-contract.md +55 -0
  83. package/template/skills/engineering-standards-builder/references/rules/README.md +23 -0
  84. package/template/skills/engineering-standards-builder/references/rust/00-detection-and-scope.md +38 -0
  85. package/template/skills/engineering-standards-builder/references/rust/01-language-api-and-safety.md +35 -0
  86. package/template/skills/engineering-standards-builder/references/rust/02-crates-workspaces-and-layout.md +36 -0
  87. package/template/skills/engineering-standards-builder/references/rust/03-errors-ownership-and-concurrency.md +37 -0
  88. package/template/skills/engineering-standards-builder/references/rust/04-testing-tooling-quality-gates.md +44 -0
  89. package/template/skills/engineering-standards-builder/references/rust/README.md +9 -0
  90. package/template/skills/engineering-standards-builder/references/typescript/00-detection-and-scope.md +58 -0
  91. package/template/skills/engineering-standards-builder/references/typescript/01-language-and-type-system.md +49 -0
  92. package/template/skills/engineering-standards-builder/references/typescript/02-modules-packages-and-runtime-boundaries.md +49 -0
  93. package/template/skills/engineering-standards-builder/references/typescript/03-functions-async-errors-resources.md +42 -0
  94. package/template/skills/engineering-standards-builder/references/typescript/04-testing-tooling-quality-gates.md +51 -0
  95. package/template/skills/engineering-standards-builder/references/typescript/README.md +27 -0
  96. package/template/skills/engineering-standards-builder/references/typescript/app-types/cli.md +11 -0
  97. package/template/skills/engineering-standards-builder/references/typescript/app-types/library.md +11 -0
  98. package/template/skills/engineering-standards-builder/references/typescript/frameworks/react.md +71 -0
  99. package/template/skills/engineering-standards-builder/references/typescript/frameworks/vue.md +131 -0
  100. package/template/skills/engineering-standards-builder/references/typescript/runtimes/browser.md +15 -0
  101. package/template/skills/engineering-standards-builder/references/typescript/runtimes/electron.md +25 -0
  102. package/template/skills/engineering-standards-builder/references/typescript/runtimes/node.md +13 -0
  103. package/template/skills/engineering-standards-builder/scripts/discover-project.mjs +957 -0
  104. package/template/skills/engineering-standards-builder/scripts/self-test.mjs +203 -0
  105. package/template/skills/engineering-standards-builder/scripts/sync-manifest.mjs +105 -0
  106. package/template/skills/engineering-standards-builder/scripts/validate-builder.mjs +255 -0
  107. package/template/skills/engineering-standards-builder/scripts/validate-generated-skill.mjs +286 -0
  108. package/template/skills/engineering-standards-builder/templates/README.md +18 -0
  109. package/template/skills/engineering-standards-builder/templates/compatibility/agents-typescript--standards.md +6 -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/claude-engineering-standards.md +6 -0
  112. package/template/skills/engineering-standards-builder/templates/compatibility/claude-typescript-standards.md +6 -0
  113. package/template/skills/engineering-standards-builder/templates/project-skill/SKILL.md.template +26 -0
  114. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/00-project-profile.md.template +26 -0
  115. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/01-module-map.md.template +27 -0
  116. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/02-decisions-and-exceptions.md.template +31 -0
  117. package/template/skills/engineering-standards-builder/templates/project-skill/references/project/review-checklist.md.template +14 -0
  118. package/template/skills/source-code-zip-skill/SKILL.md +343 -0
  119. package/template/skills/source-code-zip-skill/scripts/zip_source_code.py +638 -0
  120. package/template/workflows/person/INDEX.md +1 -0
  121. package/template/workflows/person/S-steelman-deliberation/S-steelman-deliberation.md +218 -0
  122. package/template/workflows/person/S-steelman-deliberation/_templates/decision-template.md +51 -0
  123. package/template/workflows/person/S-steelman-deliberation/_templates/steelman-dossier-template.md +96 -0
  124. package/template/workflows/person/S-steelman-deliberation/deliberate.md +127 -0
  125. package/template/workflows/person/S-steelman-deliberation/evidence-gate.md +37 -0
  126. package/template/workflows/person/S-steelman-deliberation/judge.md +69 -0
  127. package/template/workflows/person/S-steelman-deliberation/tools/validate-steelman-change.mjs +697 -0
  128. package/template/skills/typescript-standards-builder/README.md +0 -53
  129. package/template/skills/typescript-standards-builder/SKILL.md +0 -245
  130. package/template/skills/typescript-standards-builder/examples/sample-generated-tree.md +0 -30
  131. package/template/skills/typescript-standards-builder/examples/sample-interview-decisions.md +0 -26
  132. package/template/skills/typescript-standards-builder/manifest.txt +0 -29
  133. package/template/skills/typescript-standards-builder/references/00-governance-and-fixed-defaults.md +0 -77
  134. package/template/skills/typescript-standards-builder/references/01-project-discovery.md +0 -100
  135. package/template/skills/typescript-standards-builder/references/02-interview-workflow.md +0 -129
  136. package/template/skills/typescript-standards-builder/references/03-project-architecture-and-directory-layout.md +0 -84
  137. package/template/skills/typescript-standards-builder/references/04-file-directory-and-symbol-naming.md +0 -92
  138. package/template/skills/typescript-standards-builder/references/05-modules-imports-exports-and-dependencies.md +0 -63
  139. package/template/skills/typescript-standards-builder/references/06-typescript-type-system.md +0 -64
  140. package/template/skills/typescript-standards-builder/references/07-functions-async-errors-and-resources.md +0 -42
  141. package/template/skills/typescript-standards-builder/references/08-comments-jsdoc-and-documentation.md +0 -51
  142. package/template/skills/typescript-standards-builder/references/09-testing-strategy.md +0 -58
  143. package/template/skills/typescript-standards-builder/references/10-react-and-frontend.md +0 -39
  144. package/template/skills/typescript-standards-builder/references/11-node-cli-and-cross-platform.md +0 -31
  145. package/template/skills/typescript-standards-builder/references/12-formatting-lint-and-complexity.md +0 -58
  146. package/template/skills/typescript-standards-builder/references/13-configuration-dependencies-and-ci.md +0 -71
  147. package/template/skills/typescript-standards-builder/references/14-security-performance-and-i18n.md +0 -32
  148. package/template/skills/typescript-standards-builder/references/15-git-review-and-delivery.md +0 -28
  149. package/template/skills/typescript-standards-builder/references/16-adoption-exceptions-and-migration.md +0 -61
  150. package/template/skills/typescript-standards-builder/references/17-generation-contract.md +0 -104
  151. package/template/skills/typescript-standards-builder/references/README.md +0 -37
  152. package/template/skills/typescript-standards-builder/templates/agents-compat-skill/SKILL.md +0 -1
  153. package/template/skills/typescript-standards-builder/templates/claude-skill/SKILL.md +0 -1
  154. package/template/skills/typescript-standards-builder/templates/project-skill/SKILL.md.template +0 -34
  155. package/template/skills/typescript-standards-builder/templates/project-skill/references/00-project-profile.md.template +0 -17
  156. package/template/skills/typescript-standards-builder/templates/project-skill/references/10-review-checklist.md +0 -23
  157. package/template/skills/typescript-standards-builder/templates/project-skill/references/11-decisions-and-exceptions.md.template +0 -19
@@ -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
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "topology": "single-project",
3
+ "module": {
4
+ "path": ".",
5
+ "languages": [
6
+ "typescript"
7
+ ],
8
+ "frameworks": [
9
+ "vue",
10
+ "pinia"
11
+ ],
12
+ "buildSystems": [
13
+ "vite"
14
+ ],
15
+ "testSystems": [
16
+ "vitest"
17
+ ],
18
+ "runtimes": [
19
+ "browser"
20
+ ]
21
+ }
22
+ }
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "vue-vite-fixture",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "typecheck": "vue-tsc --noEmit",
7
+ "test": "vitest run",
8
+ "build": "vite build"
9
+ },
10
+ "dependencies": {
11
+ "vue": "^3.5.0",
12
+ "pinia": "^3.0.0"
13
+ },
14
+ "devDependencies": {
15
+ "typescript": "^5.9.0",
16
+ "vite": "^7.0.0",
17
+ "vitest": "^3.0.0",
18
+ "vue-tsc": "^3.0.0",
19
+ "eslint-plugin-vue": "^10.0.0"
20
+ }
21
+ }