@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.
- package/README.md +2 -2
- package/package.json +1 -1
- package/template/canonical/README.md +208 -63
- package/template/canonical/canonical-person-steelman-deliberation.md +518 -0
- package/template/skills/engineering-standards-builder/README.md +43 -0
- package/template/skills/engineering-standards-builder/SKILL.md +233 -0
- package/template/skills/engineering-standards-builder/examples/README.md +15 -0
- package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/build.gradle.kts +5 -0
- package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/expected.json +12 -0
- package/template/skills/engineering-standards-builder/examples/fallback/kotlin-gradle/src/main/kotlin/example/App.kt +2 -0
- package/template/skills/engineering-standards-builder/examples/go/service/.golangci.yml +3 -0
- package/template/skills/engineering-standards-builder/examples/go/service/cmd/api/main.go +3 -0
- package/template/skills/engineering-standards-builder/examples/go/service/expected.json +23 -0
- package/template/skills/engineering-standards-builder/examples/go/service/go.mod +3 -0
- package/template/skills/engineering-standards-builder/examples/go/service/internal/service/service.go +2 -0
- package/template/skills/engineering-standards-builder/examples/go/service/internal/service/service_test.go +3 -0
- package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/expected.json +22 -0
- package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/pom.xml +12 -0
- package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/src/main/java/dev/speculo/orders/OrdersApplication.java +7 -0
- package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/src/test/java/dev/speculo/orders/OrdersApplicationTest.java +3 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/.github/workflows/ci.yml +11 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/package.json +11 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/src/App.vue +2 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/apps/web/tsconfig.json +8 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/expected.json +22 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/package.json +11 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/pnpm-workspace.yaml +2 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/orders/pom.xml +12 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/orders/src/main/java/dev/speculo/orders/OrdersApplication.java +7 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/worker/go.mod +3 -0
- package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/services/worker/main.go +2 -0
- package/template/skills/engineering-standards-builder/examples/rust/workspace/Cargo.toml +7 -0
- package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/cli/Cargo.toml +8 -0
- package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/cli/src/main.rs +1 -0
- package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/core/Cargo.toml +5 -0
- package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/core/src/lib.rs +3 -0
- package/template/skills/engineering-standards-builder/examples/rust/workspace/expected.json +14 -0
- package/template/skills/engineering-standards-builder/examples/rust/workspace/rust-toolchain.toml +3 -0
- package/template/skills/engineering-standards-builder/examples/typescript/react-vite/expected.json +21 -0
- package/template/skills/engineering-standards-builder/examples/typescript/react-vite/package.json +20 -0
- package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/App.test.tsx +2 -0
- package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/App.tsx +1 -0
- package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/main.tsx +3 -0
- package/template/skills/engineering-standards-builder/examples/typescript/react-vite/tsconfig.json +10 -0
- package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/expected.json +22 -0
- package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/package.json +21 -0
- package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.test.ts +2 -0
- package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/App.vue +7 -0
- package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/src/main.ts +4 -0
- package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/tsconfig.json +11 -0
- package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/vite.config.ts +2 -0
- package/template/skills/engineering-standards-builder/manifest.txt +112 -0
- package/template/skills/engineering-standards-builder/references/go/00-detection-and-scope.md +37 -0
- package/template/skills/engineering-standards-builder/references/go/01-language-and-idioms.md +34 -0
- package/template/skills/engineering-standards-builder/references/go/02-modules-packages-and-layout.md +34 -0
- package/template/skills/engineering-standards-builder/references/go/03-errors-context-and-concurrency.md +38 -0
- package/template/skills/engineering-standards-builder/references/go/04-testing-tooling-quality-gates.md +46 -0
- package/template/skills/engineering-standards-builder/references/go/README.md +9 -0
- package/template/skills/engineering-standards-builder/references/java/00-detection-and-scope.md +40 -0
- package/template/skills/engineering-standards-builder/references/java/01-language-packages-and-api.md +35 -0
- package/template/skills/engineering-standards-builder/references/java/02-build-modules-and-dependencies.md +39 -0
- package/template/skills/engineering-standards-builder/references/java/03-errors-nullability-resources-concurrency.md +36 -0
- package/template/skills/engineering-standards-builder/references/java/04-testing-tooling-quality-gates.md +36 -0
- package/template/skills/engineering-standards-builder/references/java/README.md +10 -0
- package/template/skills/engineering-standards-builder/references/java/frameworks/spring-boot.md +74 -0
- package/template/skills/engineering-standards-builder/references/rules/00-governance-and-precedence.md +52 -0
- package/template/skills/engineering-standards-builder/references/rules/01-project-discovery.md +79 -0
- package/template/skills/engineering-standards-builder/references/rules/02-evidence-topology-and-scope.md +87 -0
- package/template/skills/engineering-standards-builder/references/rules/03-interview-and-decisions.md +77 -0
- package/template/skills/engineering-standards-builder/references/rules/04-architecture-and-dependency-boundaries.md +58 -0
- package/template/skills/engineering-standards-builder/references/rules/05-files-directories-and-naming.md +53 -0
- package/template/skills/engineering-standards-builder/references/rules/06-apis-errors-resources-and-concurrency.md +53 -0
- package/template/skills/engineering-standards-builder/references/rules/07-documentation-and-comments.md +46 -0
- package/template/skills/engineering-standards-builder/references/rules/08-testing-strategy.md +45 -0
- package/template/skills/engineering-standards-builder/references/rules/09-security-configuration-and-data.md +44 -0
- package/template/skills/engineering-standards-builder/references/rules/10-performance-observability-and-i18n.md +36 -0
- package/template/skills/engineering-standards-builder/references/rules/11-tooling-quality-gates-and-ci.md +69 -0
- package/template/skills/engineering-standards-builder/references/rules/12-git-review-and-delivery.md +46 -0
- package/template/skills/engineering-standards-builder/references/rules/13-adoption-exceptions-and-ratchets.md +60 -0
- package/template/skills/engineering-standards-builder/references/rules/14-generation-contract.md +105 -0
- package/template/skills/engineering-standards-builder/references/rules/15-validation-contract.md +65 -0
- package/template/skills/engineering-standards-builder/references/rules/16-language-adapter-contract.md +55 -0
- package/template/skills/engineering-standards-builder/references/rules/README.md +23 -0
- package/template/skills/engineering-standards-builder/references/rust/00-detection-and-scope.md +38 -0
- package/template/skills/engineering-standards-builder/references/rust/01-language-api-and-safety.md +35 -0
- package/template/skills/engineering-standards-builder/references/rust/02-crates-workspaces-and-layout.md +36 -0
- package/template/skills/engineering-standards-builder/references/rust/03-errors-ownership-and-concurrency.md +37 -0
- package/template/skills/engineering-standards-builder/references/rust/04-testing-tooling-quality-gates.md +44 -0
- package/template/skills/engineering-standards-builder/references/rust/README.md +9 -0
- package/template/skills/engineering-standards-builder/references/typescript/00-detection-and-scope.md +58 -0
- package/template/skills/engineering-standards-builder/references/typescript/01-language-and-type-system.md +49 -0
- package/template/skills/engineering-standards-builder/references/typescript/02-modules-packages-and-runtime-boundaries.md +49 -0
- package/template/skills/engineering-standards-builder/references/typescript/03-functions-async-errors-resources.md +42 -0
- package/template/skills/engineering-standards-builder/references/typescript/04-testing-tooling-quality-gates.md +51 -0
- package/template/skills/engineering-standards-builder/references/typescript/README.md +27 -0
- package/template/skills/engineering-standards-builder/references/typescript/app-types/cli.md +11 -0
- package/template/skills/engineering-standards-builder/references/typescript/app-types/library.md +11 -0
- package/template/skills/engineering-standards-builder/references/typescript/frameworks/react.md +71 -0
- package/template/skills/engineering-standards-builder/references/typescript/frameworks/vue.md +131 -0
- package/template/skills/engineering-standards-builder/references/typescript/runtimes/browser.md +15 -0
- package/template/skills/engineering-standards-builder/references/typescript/runtimes/electron.md +25 -0
- package/template/skills/engineering-standards-builder/references/typescript/runtimes/node.md +13 -0
- package/template/skills/engineering-standards-builder/scripts/discover-project.mjs +957 -0
- package/template/skills/engineering-standards-builder/scripts/self-test.mjs +203 -0
- package/template/skills/engineering-standards-builder/scripts/sync-manifest.mjs +105 -0
- package/template/skills/engineering-standards-builder/scripts/validate-builder.mjs +255 -0
- package/template/skills/engineering-standards-builder/scripts/validate-generated-skill.mjs +286 -0
- package/template/skills/engineering-standards-builder/templates/README.md +18 -0
- package/template/skills/engineering-standards-builder/templates/compatibility/agents-typescript--standards.md +6 -0
- package/template/skills/engineering-standards-builder/templates/compatibility/agents-typescript-standards.md +6 -0
- package/template/skills/engineering-standards-builder/templates/compatibility/claude-engineering-standards.md +6 -0
- package/template/skills/engineering-standards-builder/templates/compatibility/claude-typescript-standards.md +6 -0
- package/template/skills/engineering-standards-builder/templates/project-skill/SKILL.md.template +26 -0
- package/template/skills/engineering-standards-builder/templates/project-skill/references/project/00-project-profile.md.template +26 -0
- package/template/skills/engineering-standards-builder/templates/project-skill/references/project/01-module-map.md.template +27 -0
- package/template/skills/engineering-standards-builder/templates/project-skill/references/project/02-decisions-and-exceptions.md.template +31 -0
- package/template/skills/engineering-standards-builder/templates/project-skill/references/project/review-checklist.md.template +14 -0
- package/template/skills/source-code-zip-skill/SKILL.md +343 -0
- package/template/skills/source-code-zip-skill/scripts/zip_source_code.py +638 -0
- package/template/workflows/person/INDEX.md +1 -0
- package/template/workflows/person/S-steelman-deliberation/S-steelman-deliberation.md +218 -0
- package/template/workflows/person/S-steelman-deliberation/_templates/decision-template.md +51 -0
- package/template/workflows/person/S-steelman-deliberation/_templates/steelman-dossier-template.md +96 -0
- package/template/workflows/person/S-steelman-deliberation/deliberate.md +127 -0
- package/template/workflows/person/S-steelman-deliberation/evidence-gate.md +37 -0
- package/template/workflows/person/S-steelman-deliberation/judge.md +69 -0
- package/template/workflows/person/S-steelman-deliberation/tools/validate-steelman-change.mjs +697 -0
- package/template/skills/typescript-standards-builder/README.md +0 -53
- package/template/skills/typescript-standards-builder/SKILL.md +0 -245
- package/template/skills/typescript-standards-builder/examples/sample-generated-tree.md +0 -30
- package/template/skills/typescript-standards-builder/examples/sample-interview-decisions.md +0 -26
- package/template/skills/typescript-standards-builder/manifest.txt +0 -29
- package/template/skills/typescript-standards-builder/references/00-governance-and-fixed-defaults.md +0 -77
- package/template/skills/typescript-standards-builder/references/01-project-discovery.md +0 -100
- package/template/skills/typescript-standards-builder/references/02-interview-workflow.md +0 -129
- package/template/skills/typescript-standards-builder/references/03-project-architecture-and-directory-layout.md +0 -84
- package/template/skills/typescript-standards-builder/references/04-file-directory-and-symbol-naming.md +0 -92
- package/template/skills/typescript-standards-builder/references/05-modules-imports-exports-and-dependencies.md +0 -63
- package/template/skills/typescript-standards-builder/references/06-typescript-type-system.md +0 -64
- package/template/skills/typescript-standards-builder/references/07-functions-async-errors-and-resources.md +0 -42
- package/template/skills/typescript-standards-builder/references/08-comments-jsdoc-and-documentation.md +0 -51
- package/template/skills/typescript-standards-builder/references/09-testing-strategy.md +0 -58
- package/template/skills/typescript-standards-builder/references/10-react-and-frontend.md +0 -39
- package/template/skills/typescript-standards-builder/references/11-node-cli-and-cross-platform.md +0 -31
- package/template/skills/typescript-standards-builder/references/12-formatting-lint-and-complexity.md +0 -58
- package/template/skills/typescript-standards-builder/references/13-configuration-dependencies-and-ci.md +0 -71
- package/template/skills/typescript-standards-builder/references/14-security-performance-and-i18n.md +0 -32
- package/template/skills/typescript-standards-builder/references/15-git-review-and-delivery.md +0 -28
- package/template/skills/typescript-standards-builder/references/16-adoption-exceptions-and-migration.md +0 -61
- package/template/skills/typescript-standards-builder/references/17-generation-contract.md +0 -104
- package/template/skills/typescript-standards-builder/references/README.md +0 -37
- package/template/skills/typescript-standards-builder/templates/agents-compat-skill/SKILL.md +0 -1
- package/template/skills/typescript-standards-builder/templates/claude-skill/SKILL.md +0 -1
- package/template/skills/typescript-standards-builder/templates/project-skill/SKILL.md.template +0 -34
- package/template/skills/typescript-standards-builder/templates/project-skill/references/00-project-profile.md.template +0 -17
- package/template/skills/typescript-standards-builder/templates/project-skill/references/10-review-checklist.md +0 -23
- 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,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
|
+
}
|
package/template/skills/engineering-standards-builder/examples/java/spring-boot-maven/expected.json
ADDED
|
@@ -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
|
+
}
|
package/template/skills/engineering-standards-builder/examples/polyglot/monorepo/expected.json
ADDED
|
@@ -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,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
|
+
}
|
package/template/skills/engineering-standards-builder/examples/rust/workspace/crates/cli/src/main.rs
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
fn main() { println!("{}", fixture_core::value()); }
|
package/template/skills/engineering-standards-builder/examples/typescript/react-vite/expected.json
ADDED
|
@@ -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
|
+
}
|
package/template/skills/engineering-standards-builder/examples/typescript/react-vite/package.json
ADDED
|
@@ -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
|
+
}
|
package/template/skills/engineering-standards-builder/examples/typescript/react-vite/src/App.tsx
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export function App() { return <button type="button">Hello</button> }
|
package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/expected.json
ADDED
|
@@ -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
|
+
}
|
package/template/skills/engineering-standards-builder/examples/typescript/vue-vite/package.json
ADDED
|
@@ -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
|
+
}
|