@namewta/speculo 0.1.18 → 0.1.20
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 +11 -4
- package/dist/src/index.js +17 -9
- package/dist/src/index.js.map +1 -1
- package/package.json +1 -1
- package/template/.speculo/.config/LESSONS.md +1 -1
- package/template/.speculo/.config/RULES.md +0 -1
- package/template/.speculo/AGENTS.md +30 -0
- package/template/.speculo/archive/AGENTS.md +28 -0
- package/template/.speculo/dev/docs-sync-state.json +3 -3
- package/template/commands/archive.md +2 -2
- package/template/commands/config-prune.md +59 -0
- package/template/commands/status.md +1 -1
- package/template/skills/config-prune/SKILL.md +66 -0
- package/template/skills/github-npm-ops/references/release-pipeline.md +2 -2
- package/template/skills/speculo-write/references/command-authoring-sop.md +2 -0
- package/template/skills/speculo-write/references/migration-sop.md +1 -1
- package/template/skills/speculo-write/references/persistence-contract-sop.md +3 -3
- package/template/skills/speculo-write/references/validation-checklist.md +1 -0
- package/template/skills/speculo-write/references/workflow-authoring-sop.md +2 -2
- package/template/skills/worktree-isolation/SKILL.md +1 -1
- package/template/workflows/dev/03-tdd/03-tdd.md +16 -0
- package/template/workflows/dev/03-tdd/tdd-loop.md +4 -2
- package/template/workflows/dev/03-tdd/tdd-plan.md +10 -7
- package/template/workflows/dev/{00-INDEX.md → AGENTS.md} +16 -7
- package/template/workflows/dev/D-docs-sync/D-docs-sync.md +47 -21
- package/template/workflows/dev/D-docs-sync/config-contract.md +75 -0
- package/template/workflows/dev/D-docs-sync/docs-sync-diff.md +40 -4
- package/template/workflows/dev/D-docs-sync/docs-sync-finish.md +11 -7
- package/template/workflows/dev/D-docs-sync/docs-sync-state.md +23 -8
- package/template/workflows/dev/D-docs-sync/docs-sync-update.md +22 -13
- package/template/workflows/dev/D-docs-sync/knowledge-extract.md +66 -0
- package/template/workflows/dev/D-docs-sync/state-json-schema.md +41 -24
- package/template/workflows/dev/M-domain-modeling/ADR-FORMAT.md +26 -1
- package/template/workflows/dev/_templates/docs-sync-report-template.md +21 -5
- package/template/workflows/dev/_templates/docs-sync-state-template.json +4 -4
- package/template/workflows/dev/_templates/tdd-log-template.md +3 -0
- package/template/workflows/dev/_templates/tdd-plan-template.md +3 -0
- package/template/workflows/doc/{00-INDEX.md → AGENTS.md} +14 -5
- package/template/workflows/person/{00-INDEX.md → AGENTS.md} +14 -5
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
[](./LICENSE)
|
|
9
9
|
[](./package.json)
|
|
10
10
|
|
|
11
|
-
**版本：** v2.
|
|
11
|
+
**版本：** v2.6
|
|
12
12
|
**核心原则：** 工具无关 · CLI 接入 · workflow 自治
|
|
13
13
|
|
|
14
14
|
## 这是什么
|
|
@@ -31,6 +31,7 @@ Speculo/
|
|
|
31
31
|
├── commands/ # 一次性独立命令
|
|
32
32
|
├── workflows/ # 多阶段工作流
|
|
33
33
|
├── skills/ # command 可调用的可复用 skill
|
|
34
|
+
├── vendor/ # 原生第三方 AgentSkills 收集目录
|
|
34
35
|
└── .speculo/ # 项目状态与产物骨架
|
|
35
36
|
```
|
|
36
37
|
|
|
@@ -53,17 +54,23 @@ speculo init my-project
|
|
|
53
54
|
|
|
54
55
|
## 内置入口
|
|
55
56
|
|
|
56
|
-
- `workflows/dev/
|
|
57
|
+
- `workflows/dev/AGENTS.md`：开发工作流导航
|
|
57
58
|
- `workflows/dev/01-grill-with-docs/01-grill-with-docs.md`：领域澄清与决策拷问
|
|
58
59
|
- `workflows/dev/02-prd/02-prd.md`：全景理解与 PRD
|
|
59
60
|
- `workflows/dev/03-tdd/03-tdd.md`：TDD 实现
|
|
60
61
|
- `workflows/dev/I-to-issues/I-to-issues.md`：`dev/I` 垂直切片分解
|
|
61
62
|
- `workflows/dev/H-diagnose/H-diagnose.md`：`dev/H` hotfix / diagnose
|
|
62
63
|
- `workflows/dev/R-review/R-review.md`：`dev/R` Spec / Engineering / Standards 三维度 diff 审查
|
|
63
|
-
- `workflows/dev/
|
|
64
|
-
- `workflows/
|
|
64
|
+
- `workflows/dev/M-domain-modeling/M-domain-modeling.md`：`dev/M` 主动领域建模，维护 CONTEXT 与 ADR
|
|
65
|
+
- `workflows/dev/A-improve-architecture/A-improve-architecture.md`：`dev/A` 架构深化机会扫描与 HTML 审查报告
|
|
66
|
+
- `workflows/dev/D-docs-sync/D-docs-sync.md`：`dev/D` 基于 git diff、归档产物和 `.config` 生命周期同步文档/知识资产
|
|
67
|
+
- `workflows/doc/AGENTS.md`：文档写作 workflow 导航
|
|
68
|
+
- `workflows/person/AGENTS.md`：人物方法论 workflow 导航
|
|
69
|
+
- `.speculo/AGENTS.md`：状态骨架、项目知识和归档的读取指引
|
|
70
|
+
- `.speculo/archive/AGENTS.md`：已完成 change 归档读取指引
|
|
65
71
|
- `commands/status.md`：聚合当前状态
|
|
66
72
|
- `commands/archive.md`：归档 completed change
|
|
73
|
+
- `commands/config-prune.md`：dry-run 审计 `.config` 过期知识资产
|
|
67
74
|
- `commands/{caveman,grill-me,handoff,write-a-skill,scaffold-exercises}.md`：生产力命令
|
|
68
75
|
- `commands/retro.md`：复盘 Speculo 使用痛点并经确认提改进 issue
|
|
69
76
|
|
package/dist/src/index.js
CHANGED
|
@@ -4,6 +4,8 @@ import { pathExists } from "./utils.js";
|
|
|
4
4
|
import { discoverWorkflowCatalog, promptCategorySelection, scanInstalledWorkflows, selectAllFromCatalog, isInteractive, } from "./workflows.js";
|
|
5
5
|
const INIT_ASSETS = [".speculo", "commands", "skills", "workflows", "vendor"];
|
|
6
6
|
const UPDATE_ASSETS = ["commands", "skills", "workflows"];
|
|
7
|
+
const CATEGORY_GUIDE_FILE = "AGENTS.md";
|
|
8
|
+
const LEGACY_CATEGORY_INDEX_FILE = "00-INDEX.md";
|
|
7
9
|
// Assets install under a single `speculo/` directory inside the target,
|
|
8
10
|
// mirroring the package layout — never scattered into the target root.
|
|
9
11
|
const INSTALL_SUBDIR = "speculo";
|
|
@@ -61,7 +63,7 @@ async function mergeVendor(packageRoot, root) {
|
|
|
61
63
|
}
|
|
62
64
|
/**
|
|
63
65
|
* Copy selected workflows from the template to the install root.
|
|
64
|
-
* Handles category-level metadata (
|
|
66
|
+
* Handles category-level metadata (AGENTS.md, _templates/) along with
|
|
65
67
|
* individual workflow directories.
|
|
66
68
|
*/
|
|
67
69
|
async function copyWorkflows(packageRoot, root, selection, options = {}) {
|
|
@@ -74,18 +76,24 @@ async function copyWorkflows(packageRoot, root, selection, options = {}) {
|
|
|
74
76
|
const categoriesDone = new Set();
|
|
75
77
|
for (const wf of selection.workflows) {
|
|
76
78
|
const cat = wf.category;
|
|
77
|
-
// Copy category-level
|
|
79
|
+
// Copy category-level AGENTS.md (only once per category)
|
|
78
80
|
if (!categoriesDone.has(cat)) {
|
|
79
81
|
const catDir = join(workflowsRoot, cat);
|
|
80
82
|
await mkdir(catDir, { recursive: true });
|
|
81
|
-
//
|
|
82
|
-
const
|
|
83
|
-
const
|
|
84
|
-
if (overwrite
|
|
85
|
-
await
|
|
83
|
+
// AGENTS.md
|
|
84
|
+
const guideSrc = join(templateWorkflows, cat, CATEGORY_GUIDE_FILE);
|
|
85
|
+
const guideDest = join(catDir, CATEGORY_GUIDE_FILE);
|
|
86
|
+
if (overwrite) {
|
|
87
|
+
if (await pathExists(guideDest)) {
|
|
88
|
+
await rm(guideDest, { force: true });
|
|
89
|
+
}
|
|
90
|
+
const legacyIndexDest = join(catDir, LEGACY_CATEGORY_INDEX_FILE);
|
|
91
|
+
if (await pathExists(legacyIndexDest)) {
|
|
92
|
+
await rm(legacyIndexDest, { force: true });
|
|
93
|
+
}
|
|
86
94
|
}
|
|
87
|
-
if (await pathExists(
|
|
88
|
-
await cp(
|
|
95
|
+
if (await pathExists(guideSrc)) {
|
|
96
|
+
await cp(guideSrc, guideDest, { force: overwrite, errorOnExist: !overwrite });
|
|
89
97
|
}
|
|
90
98
|
// _templates/
|
|
91
99
|
const templatesSrc = join(templateWorkflows, cat, "_templates");
|
package/dist/src/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,GAEd,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AACvF,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,GAEd,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AACvF,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;AACnE,MAAM,mBAAmB,GAAG,WAAW,CAAC;AACxC,MAAM,0BAA0B,GAAG,aAAa,CAAC;AAEjD,wEAAwE;AACxE,uEAAuE;AACvE,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC,SAAS,SAAS,CAAC,WAAmB;IACpC,OAAO,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACtC,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,WAAmB,EAAE,KAAa;IACjE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC;IACnD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,4CAA4C,KAAK,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAyB;IACrE,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtC,IAAI,MAAM,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAClC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CAAC,WAAmB,EAAE,IAAY;IAC1D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAExC,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,SAAS;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,uBAAuB;QAC7D,MAAM,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAC1B,WAAmB,EACnB,IAAY,EACZ,SAA4B,EAC5B,UAAmC,EAAE;IAErC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC9C,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAE7C,MAAM,KAAK,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEhD,wDAAwD;IACxD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IAEzC,KAAK,MAAM,EAAE,IAAI,SAAS,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC;QAExB,yDAAyD;QACzD,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;YACxC,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAEzC,YAAY;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,EAAE,GAAG,EAAE,mBAAmB,CAAC,CAAC;YACnE,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;YACpD,IAAI,SAAS,EAAE,CAAC;gBACd,IAAI,MAAM,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;oBAChC,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACvC,CAAC;gBACD,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;gBACjE,IAAI,MAAM,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;oBACtC,MAAM,EAAE,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC7C,CAAC;YACH,CAAC;YACD,IAAI,MAAM,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC/B,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;YAChF,CAAC;YAED,cAAc;YACd,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;YAChE,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YACjD,IAAI,SAAS,IAAI,CAAC,MAAM,UAAU,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;gBACnD,MAAM,EAAE,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,CAAC;YACD,IAAI,MAAM,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;gBACnC,MAAM,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;YACzG,CAAC;YAED,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAED,8BAA8B;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,iBAAiB,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAEjD,IAAI,SAAS,IAAI,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YAC5C,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;QAED,IAAI,MAAM,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;YACzF,MAAM,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,WAAmB,EACnB,IAAY,EACZ,OAAuB,EACvB,IAAuB;IAEvB,oDAAoD;IACpD,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,SAAS,CAAC;IAC3B,CAAC;IAED,6CAA6C;IAC7C,IAAI,OAAO,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,WAAW,CAAC,CAAC;QAC3D,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,mBAAmB;IACnB,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAE3D,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,0EAA0E;QAC1E,IAAI,SAAS,GAAyC,EAAE,CAAC;QACzD,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,qCAAqC;QACvC,CAAC;QACD,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACxE,OAAO,uBAAuB,CAAC,OAAO,EAAE,EAAE,qBAAqB,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,wCAAwC;IACxC,OAAO,uBAAuB,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,SAAS,GAAG,GAAG,EACf,UAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAEjC,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,iDAAiD;IACjD,uDAAuD;IACvD,MAAM,iBAAiB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;IAClE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb;YACE,mDAAmD;YACnD,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC;SAChD,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,mCAAmC;IACnC,KAAK,MAAM,KAAK,IAAI,iBAAiB,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtC,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QACrF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IAED,0BAA0B;IAC1B,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7E,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACxE,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC1C,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,SAAS,GAAG,GAAG,EACf,UAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAEjC,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,gEAAgE;IAChE,KAAK,MAAM,KAAK,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,WAAW,CAAC,EAAE,CAAC;QACjE,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtC,MAAM,EAAE,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,8DAA8D;IAC9D,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QACjE,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACxC,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,MAAM,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACnD,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,+BAA+B;IAC/B,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC/E,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7F,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAS,GAAG,GAAG,EACf,UAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAEjC,IAAI,MAAM,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACrC,CAAC"}
|
package/package.json
CHANGED
|
@@ -6,7 +6,6 @@
|
|
|
6
6
|
|
|
7
7
|
## Rules
|
|
8
8
|
|
|
9
|
-
- [TODO: 添加项目必须遵守的规则。]
|
|
10
9
|
- **Rule 0 — 持久化铁律：所有 Speculo workflow、command、skill 的输出和持久化内容，必须且只能存放在 `speculo/.speculo/` 目录中。绝对禁止写入 `temp/`、系统临时目录、项目根目录的 `.speculo/` 或其他任何非规范位置。**
|
|
11
10
|
- 所有 Speculo change 目录必须以 `YYYY-MM-DD-<kebab-name>` 命名（例：`2026-06-12-user-auth`）。
|
|
12
11
|
- 所有 Speculo command 产物目录必须以 `YYYY-MM-DD-<cmd-name>-<topic>` 命名。
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Speculo State AGENTS Guide
|
|
2
|
+
|
|
3
|
+
本目录是 Speculo 运行时状态、项目知识和归档的唯一持久化根目录。所有 workflow、command 和 skill 调用方写入的持久化产物必须留在 `speculo/.speculo/` 内。
|
|
4
|
+
|
|
5
|
+
## 读取顺序
|
|
6
|
+
|
|
7
|
+
1. 先读目标分类索引：`dev-status.json`、`doc-status.json` 或 `person-status.json`。
|
|
8
|
+
2. 再按 active 条目读取对应 change 的 `.status.json`：`<cat>/<change>/.status.json`。
|
|
9
|
+
3. 需要 workflow 产物时，只读取当前 change 目录下与当前 phase 相关的文件。
|
|
10
|
+
4. 需要历史上下文时，读取 `archive/AGENTS.md` 后再扫描归档目录。
|
|
11
|
+
5. 需要项目规则、经验、领域术语或 ADR 时，读取 `.config/` 下对应文件；`RULES.md` 默认由用户维护，不自动改写。
|
|
12
|
+
|
|
13
|
+
> **配置优先：** 执行任何 workflow、command 或 skill 时，只要涉及项目硬约束、跨任务经验、领域上下文、术语定义、ADR 或决策依据，必须优先参考 `.config/` 下的内容；其中 `RULES.md` 的约束高于普通 workflow 文案。只有在用户明确要求或项目规则允许时，才可写入 `.config/`。
|
|
14
|
+
|
|
15
|
+
## 目录职责
|
|
16
|
+
|
|
17
|
+
| 路径 | 职责 |
|
|
18
|
+
|------|------|
|
|
19
|
+
| `<cat>-status.json` | 当前 active change 的薄索引，可由 `<cat>/<change>/.status.json` 重建 |
|
|
20
|
+
| `<cat>/<change>/` | 当前 change 的 workflow 产物和 `.status.json` |
|
|
21
|
+
| `commands/` | command 产生的报告、快照和一次性操作记录 |
|
|
22
|
+
| `.config/` | 项目规则、经验、context 和 ADR |
|
|
23
|
+
| `archive/` | completed change 的历史归档 |
|
|
24
|
+
|
|
25
|
+
## 写入边界
|
|
26
|
+
|
|
27
|
+
- 新 change 目录必须为 `YYYY-MM-DD-<kebab-name>`。
|
|
28
|
+
- command 产物目录必须为 `YYYY-MM-DD-<cmd-name>-<topic>`。
|
|
29
|
+
- 不要把状态写到项目根目录的裸 `.speculo/`、`temp/` 或系统临时目录。
|
|
30
|
+
- 不要把 archive 当作当前工作目录；需要恢复或迁移历史产物时，先明确说明目标和影响。
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Speculo Archive AGENTS Guide
|
|
2
|
+
|
|
3
|
+
本目录保存已完成 change 的历史归档，用于回溯决策、提取经验和支撑 docs-sync。默认只读，不作为当前工作状态。
|
|
4
|
+
|
|
5
|
+
## 目录形态
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
archive/
|
|
9
|
+
├── dev/<YYYY-MM>/<change-name>/
|
|
10
|
+
├── doc/<YYYY-MM>/<change-name>/
|
|
11
|
+
└── person/<YYYY-MM>/<change-name>/
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
- `<YYYY-MM>` 从 change 名称的日期前缀提取。
|
|
15
|
+
- `<change-name>` 必须保持原始 `YYYY-MM-DD-<kebab-name>`。
|
|
16
|
+
- 归档目录内保留该 change 原本的 `.status.json` 和产物文件。
|
|
17
|
+
|
|
18
|
+
## 读取方式
|
|
19
|
+
|
|
20
|
+
1. 先按分类和月份缩小范围，避免全量读取历史。
|
|
21
|
+
2. 读取目标归档 change 的 `.status.json`，确认 `change_status`、最后 phase 和产物路径。
|
|
22
|
+
3. 只读取与当前问题相关的归档产物；需要提取知识时，把候选写入当前 workflow 产物，由用户确认后再进入 `.config/`。
|
|
23
|
+
|
|
24
|
+
## 操作边界
|
|
25
|
+
|
|
26
|
+
- 不自动重写、删除或移动 archive 内容。
|
|
27
|
+
- 归档移动由 `speculo/commands/archive.md` 或 `speculo/workflows/dev/04-finalize/04-finalize.md` 负责。
|
|
28
|
+
- 若发现归档路径冲突、缺少 `.status.json` 或命名不符合 `YYYY-MM-DD-`，只报告问题，不自行修复。
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
|
-
"schema_version":
|
|
2
|
+
"schema_version": 2,
|
|
3
3
|
"skill": "docs-sync",
|
|
4
4
|
"state_path": "speculo/.speculo/dev/docs-sync-state.json",
|
|
5
|
-
"
|
|
5
|
+
"tracked_assets": [],
|
|
6
6
|
"last_sync_sha": null,
|
|
7
7
|
"last_sync_short": null,
|
|
8
8
|
"last_sync_commit_subject": null,
|
|
@@ -10,5 +10,5 @@
|
|
|
10
10
|
"last_sync_run_at": null,
|
|
11
11
|
"previous_sync_sha": null,
|
|
12
12
|
"total_syncs": 0,
|
|
13
|
-
"
|
|
13
|
+
"synced_assets": []
|
|
14
14
|
}
|
|
@@ -26,7 +26,7 @@ keywords: [archive, 归档, 清理]
|
|
|
26
26
|
|
|
27
27
|
## 执行步骤
|
|
28
28
|
|
|
29
|
-
1. **预扫描：** 列出 `speculo/.speculo/<cat>/`（内置分类至少包括 `dev` 与 `
|
|
29
|
+
1. **预扫描：** 列出 `speculo/.speculo/<cat>/`（内置分类至少包括 `dev`、`doc` 与 `person`）下所有符合 `YYYY-MM-DD-<kebab-name>` 格式的 change 目录。对每个目录检查 `.status.json` 是否存在：
|
|
30
30
|
- 存在且 `change_status: completed` → 加入待归档候选。
|
|
31
31
|
- 存在但 `change_status` 为其他值 → 跳过（非完成状态）。
|
|
32
32
|
- **不存在 `.status.json`** → 标记为 `broken-change: missing .status.json`，**不归档、不删除、不移动**，在清单中单独列出并跳过。
|
|
@@ -35,7 +35,7 @@ keywords: [archive, 归档, 清理]
|
|
|
35
35
|
- **待归档：** 源路径、目标路径、当前分类、`updated_at`、最后 phase、是否仍在 `<cat>-status.json active[]`。
|
|
36
36
|
- **broken-change：** 缺少 `.status.json` 的 change 目录路径。
|
|
37
37
|
- **冲突：** 目标路径已存在的 change。
|
|
38
|
-
4. 向用户展示清单并等待明确确认。没有确认时只输出计划，不移动目录、不改索引。对于 `broken-change`，提示用户需先通过对应 workflow 入口（`dev/
|
|
38
|
+
4. 向用户展示清单并等待明确确认。没有确认时只输出计划，不移动目录、不改索引。对于 `broken-change`，提示用户需先通过对应 workflow 入口（`dev/AGENTS.md`、`doc/AGENTS.md` 或 `person/AGENTS.md`）补建 `.status.json`，或将 `change_status` 手动置为 `completed` 后再归档。
|
|
39
39
|
5. 用户确认后逐项执行（仅对待归档项）：
|
|
40
40
|
- 创建 `speculo/.speculo/archive/<cat>/<YYYY-MM>/`
|
|
41
41
|
- 移动 change 目录到 `speculo/.speculo/archive/<cat>/<YYYY-MM>/<change-name>/`
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: config-prune
|
|
3
|
+
type: command
|
|
4
|
+
name: Config Prune
|
|
5
|
+
description: dry-run 审计 .config 中可安全删除或合并的过期知识资产
|
|
6
|
+
keywords: [config-prune, config, adr, context, lessons, rules, prune, 清理]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Config Prune 命令
|
|
10
|
+
|
|
11
|
+
⚠️ **默认 dry-run。** 本命令涉及 `.config` 知识资产删除或合并，AI 必须先列出候选清单并征求用户确认。没有确认时只写报告，不删除、不重命名、不改 RULES。
|
|
12
|
+
|
|
13
|
+
## 归档路径模式
|
|
14
|
+
|
|
15
|
+
产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-config-prune-<topic>/`
|
|
16
|
+
|
|
17
|
+
报告文件：`speculo/.speculo/commands/<YYYY-MM-DD>-config-prune-<topic>/report.md`
|
|
18
|
+
|
|
19
|
+
- `<YYYY-MM-DD>` 使用当前日期。
|
|
20
|
+
- `<topic>` 从清理范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `config`。
|
|
21
|
+
- 禁止把报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
|
|
22
|
+
|
|
23
|
+
## 调用的 skills
|
|
24
|
+
|
|
25
|
+
- `../skills/config-prune/SKILL.md` — dry-run 审计 .config 知识资产过期项、生成分组候选清单时读取。
|
|
26
|
+
|
|
27
|
+
## 执行步骤
|
|
28
|
+
|
|
29
|
+
1. 读取 `../skills/config-prune/SKILL.md`，按其执行步骤与边界执行 config-prune 审计。
|
|
30
|
+
2. 创建规范命令产物目录 `speculo/.speculo/commands/<YYYY-MM-DD>-config-prune-<topic>/`。
|
|
31
|
+
3. 把 skill 返回的候选清单、证据、风险、用户确认记录和执行结果写入 `report.md`（使用下方产物模板）。
|
|
32
|
+
4. 返回 `report.md` 路径和 3-5 条摘要。
|
|
33
|
+
|
|
34
|
+
## 产物模板（report.md）
|
|
35
|
+
|
|
36
|
+
> **服务命令：** `config-prune.md`
|
|
37
|
+
> **产物文件名：** `report.md`
|
|
38
|
+
|
|
39
|
+
```markdown
|
|
40
|
+
# Config Prune Report
|
|
41
|
+
|
|
42
|
+
## 执行时间
|
|
43
|
+
[TODO: ISO 时间戳]
|
|
44
|
+
|
|
45
|
+
## 模式
|
|
46
|
+
[TODO: dry-run / confirmed]
|
|
47
|
+
|
|
48
|
+
## 扫描范围
|
|
49
|
+
[TODO: 列出读取的 .config 路径、引用扫描命令和排除目录]
|
|
50
|
+
|
|
51
|
+
## 候选清单
|
|
52
|
+
[TODO: 按 delete / merge / rewrite / keep / needs-confirmation 分组列出候选、证据和风险]
|
|
53
|
+
|
|
54
|
+
## 用户确认记录
|
|
55
|
+
[TODO: dry-run 时写无确认；执行时记录用户确认的原始要点]
|
|
56
|
+
|
|
57
|
+
## 执行结果
|
|
58
|
+
[TODO: 成功 / 失败 / 部分成功；列出实际改动和跳过项]
|
|
59
|
+
```
|
|
@@ -26,7 +26,7 @@ keywords: [status, 状态, 进度]
|
|
|
26
26
|
|
|
27
27
|
## 执行步骤
|
|
28
28
|
|
|
29
|
-
1. 读取已存在的 `speculo/.speculo/<cat>-status.json`，当前内置分类至少包括 `dev` 与 `
|
|
29
|
+
1. 读取已存在的 `speculo/.speculo/<cat>-status.json`，当前内置分类至少包括 `dev`、`doc` 与 `person`。缺失时报告缺失路径，建议重新运行 `speculo init`，或创建空索引 `{"active":[]}`。
|
|
30
30
|
2. 对每个索引的 `active[]` 条目，读取 `speculo/.speculo/<cat>/<change>/.status.json`。读取失败时把该 change 标记为 `broken-index`，不要擅自删除索引项。
|
|
31
31
|
3. 扫描 `speculo/.speculo/<cat>/*/.status.json`，找出 `change_status: completed` 且尚未位于 `speculo/.speculo/archive/` 的待归档 change。
|
|
32
32
|
4. 聚合输出：
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: config-prune
|
|
3
|
+
type: skill
|
|
4
|
+
name: Config Prune
|
|
5
|
+
description: dry-run 审计 .config 中可安全删除或合并的过期知识资产，生成分组候选清单；当用户要求清理 .config、prune config、审计知识资产过期项、或通过 command/config-prune 调用时使用。
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Config Prune
|
|
9
|
+
|
|
10
|
+
⚠️ **默认 dry-run。** 本 skill 涉及 `.config` 知识资产删除或合并，必须先列出候选清单并征求用户确认。没有确认时只输出候选清单，不删除、不重命名、不改 RULES。
|
|
11
|
+
|
|
12
|
+
## 何时使用
|
|
13
|
+
|
|
14
|
+
- 用户要求"清理 .config"、"prune 配置"、"审计 ADR/CONTEXT/LESSONS 过期项"
|
|
15
|
+
- 用户要求"看看哪些知识资产可以删"、"检查过期的 ADR"
|
|
16
|
+
- 被 `commands/config-prune.md` 或 `workflows/dev/D-docs-sync` 等调用方委托执行审计
|
|
17
|
+
- 本 skill 只负责分析与生成候选清单，不自行删除文件、不自行写报告；持久化由调用方负责
|
|
18
|
+
|
|
19
|
+
## 输入
|
|
20
|
+
|
|
21
|
+
- `.config` 资产路径：`speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`；缺失路径记录为 `missing`，不自动创建
|
|
22
|
+
- 仓库引用扫描命令：
|
|
23
|
+
```bash
|
|
24
|
+
rg -n "ADR-[0-9]{4}|[0-9]{4}-[a-z0-9-]+\\.md|CONTEXT|LESSONS|RULES" .
|
|
25
|
+
```
|
|
26
|
+
排除 `node_modules/`、`dist/`、`.git/` 等生成或依赖目录
|
|
27
|
+
- 用户确认状态（dry-run 或 confirmed）
|
|
28
|
+
|
|
29
|
+
## 输出
|
|
30
|
+
|
|
31
|
+
- 按 `delete | merge | rewrite | keep | needs-confirmation` 分组的候选清单
|
|
32
|
+
- 每个候选包含：来源、证据、风险
|
|
33
|
+
- 不产生文件型持久化产物；结构化结果返回给调用方写入
|
|
34
|
+
|
|
35
|
+
## 执行步骤
|
|
36
|
+
|
|
37
|
+
1. 读取 `speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`；缺失路径记录为 `missing`，不自动创建。
|
|
38
|
+
2. 扫描当前仓库引用：
|
|
39
|
+
```bash
|
|
40
|
+
rg -n "ADR-[0-9]{4}|[0-9]{4}-[a-z0-9-]+\\.md|CONTEXT|LESSONS|RULES" .
|
|
41
|
+
```
|
|
42
|
+
排除 `node_modules/`、`dist/`、`.git/` 等生成或依赖目录。
|
|
43
|
+
3. 生成 dry-run 候选，至少包含：
|
|
44
|
+
- 指向不存在 ADR 的正文引用或索引行。
|
|
45
|
+
- 标记为 superseded 且超过 30 天、无活跃引用的 ADR。
|
|
46
|
+
- 只含 `.gitkeep`、TODO、空占位或模板说明的长期知识文件。
|
|
47
|
+
- CONTEXT 中当前代码、文档和归档均无证据支撑的术语。
|
|
48
|
+
- LESSONS 中重复、过期、只适用单次任务或已被 RULES/ADR 吸收的经验。
|
|
49
|
+
4. 按 `delete | merge | rewrite | keep | needs-confirmation` 分组输出完整清单；每个候选必须包含来源、证据和风险。
|
|
50
|
+
5. 如果用户没有明确确认，停止在 dry-run 候选清单。
|
|
51
|
+
6. 用户确认后，只执行确认清单中的操作：
|
|
52
|
+
- 删除文件前再次检查路径仍位于 `speculo/.speculo/.config/`。
|
|
53
|
+
- 修改 `RULES.md` 前必须确认具体条目；不能批量隐式改规则。
|
|
54
|
+
- 执行后列出实际改动和跳过项。
|
|
55
|
+
|
|
56
|
+
## 边界
|
|
57
|
+
|
|
58
|
+
- 不删除仍被代码、文档、归档或 active change 引用的 ADR / CONTEXT。
|
|
59
|
+
- 不把低信号归档内容写回长期知识资产。
|
|
60
|
+
- 不自动解决领域术语冲突；冲突项交给 `../workflows/dev/M-domain-modeling/M-domain-modeling.md`。
|
|
61
|
+
- 不修改 docs-sync state；由 `../workflows/dev/D-docs-sync/D-docs-sync.md` 推进基线。
|
|
62
|
+
- 不自行选择持久化位置；文件型产物由调用方写入规范路径。
|
|
63
|
+
|
|
64
|
+
## 渐进披露
|
|
65
|
+
|
|
66
|
+
无 `references/`；本 skill 的完整执行规则已在入口中。
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
## Phase 2 — Docs Sync
|
|
34
34
|
|
|
35
35
|
- 由调用方执行 `workflows/dev/D-docs-sync/D-docs-sync.md`。
|
|
36
|
-
- 只修改 tracked
|
|
36
|
+
- 只修改 tracked assets 中需要同步的文档或知识资产。
|
|
37
37
|
- CHANGELOG 类文档只写 `[Unreleased]`，保留该段落。
|
|
38
38
|
- 本阶段不推进 docs-sync state 到 release commit；最终基线推进放到 Phase 6。
|
|
39
39
|
|
|
@@ -92,7 +92,7 @@ npm view "<package-name>" dist-tags
|
|
|
92
92
|
|
|
93
93
|
- `last_sync_sha` 推进到 `RELEASE_COMMIT_SHA`。
|
|
94
94
|
- `previous_sync_sha` 使用推进前的 `last_sync_sha`。
|
|
95
|
-
- `
|
|
95
|
+
- `synced_assets` 使用 Phase 2 实际修改的资产列表；空同步为 `[]`。
|
|
96
96
|
|
|
97
97
|
调用方把 state 推进作为 release tag 之后的普通 docs commit，tag 不移动；写入机制（原子写、schema 校验）由 D-docs-sync workflow 负责。
|
|
98
98
|
|
|
@@ -94,3 +94,5 @@ command 产物模板内联在文件末尾。模板占位符使用 `[TODO: ...]`
|
|
|
94
94
|
- 被调用 skill 是否没有自选 `temp/`、系统临时目录或项目根目录作为持久化位置
|
|
95
95
|
|
|
96
96
|
`speculo/.speculo/commands/` 归档路径、frontmatter 最小集与写入责任见 `persistence-contract-sop.md`；`description`、完成准则与修剪的质量杠杆见 `authoring-quality-levers.md`。
|
|
97
|
+
|
|
98
|
+
涉及 `.config` 清理、删除或合并的命令参考 `template/commands/config-prune.md`：默认 dry-run，执行破坏性操作前必须列清单并等待用户确认。
|
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
```jsonc
|
|
72
72
|
{
|
|
73
73
|
"name": "string, change 目录名",
|
|
74
|
-
"category": "string, dev | doc | ops",
|
|
74
|
+
"category": "string, dev | doc | person | ops",
|
|
75
75
|
"change_status": "string, active | completed | archived",
|
|
76
76
|
"execution_mode": "string, 由 workflow 自治声明的命名预设",
|
|
77
77
|
"created_at": "string, ISO 8601",
|
|
@@ -112,7 +112,7 @@ Frontmatter **仅承载发现元数据**（这是什么、叫什么、关于什
|
|
|
112
112
|
```yaml
|
|
113
113
|
# workflow
|
|
114
114
|
id: <category>/<name> # 必填，全局唯一
|
|
115
|
-
category: dev|doc|ops # 必填
|
|
115
|
+
category: dev|doc|person|ops # 必填
|
|
116
116
|
name: <人类可读名> # 必填
|
|
117
117
|
description: <一句话> # 必填
|
|
118
118
|
keywords: [...] # 可选
|
|
@@ -162,7 +162,7 @@ description: <一句话> # 必填
|
|
|
162
162
|
| `speculo/.speculo/<cat>/<change>/*.md` | ⚠️ | ✅ |
|
|
163
163
|
| `speculo/.speculo/<cat>/<change>/.status.json` | ❌ | ✅ |
|
|
164
164
|
| `speculo/.speculo/*-status.json` | ❌ | ✅ |
|
|
165
|
-
| `speculo/.speculo/dev/docs-sync-state.json` | ❌ | ✅ `dev/D-docs-sync`
|
|
165
|
+
| `speculo/.speculo/dev/docs-sync-state.json` | ❌ | ✅ `dev/D-docs-sync` 原子写入；保存 tracked assets 与 git diff 基线 |
|
|
166
166
|
|
|
167
167
|
**skill 不拥有独立持久化根目录**：skill 需要生成持久化文件时，必须使用调用方 command / workflow 声明的 `speculo/.speculo/...` 规范目标路径，或返回内容由调用方写入。禁止 skill 自行选择 `temp/`、系统临时目录、项目根目录或额外 state 文件作为持久化位置。
|
|
168
168
|
|
|
@@ -4,7 +4,7 @@ phase 的切分、完成准则与措辞遵循 `authoring-quality-levers.md` 的
|
|
|
4
4
|
|
|
5
5
|
## 入口结构
|
|
6
6
|
|
|
7
|
-
workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`ops`。
|
|
7
|
+
workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`person`、`ops`。
|
|
8
8
|
|
|
9
9
|
目录和入口文件必须同名：
|
|
10
10
|
|
|
@@ -116,7 +116,7 @@ speculo/.speculo/.config/adr/
|
|
|
116
116
|
|
|
117
117
|
新增 workflow 后检查：
|
|
118
118
|
|
|
119
|
-
- 对应分类的 `
|
|
119
|
+
- 对应分类的 `AGENTS.md` 是否需要新增别名
|
|
120
120
|
- `speculo/.speculo/<cat>-status.json` 和 `speculo/.speculo/<cat>/.gitkeep` 是否存在
|
|
121
121
|
- `speculo/.speculo/archive/<cat>/.gitkeep` 是否存在
|
|
122
122
|
- 项目若有 `docs/quick-reference.md` 等入口索引，是否需要新增条目
|
|
@@ -20,7 +20,7 @@ description: 在独立 git worktree 中隔离推进一个 change 的原子能力
|
|
|
20
20
|
## 输入
|
|
21
21
|
|
|
22
22
|
- 当前 git 仓库与**当前分支**（启用隔离时即记为 base 分支）
|
|
23
|
-
- 当前 change 目录名（`YYYY-MM-DD-<kebab>`）与其分类 `<cat>`（dev | doc | ops）
|
|
23
|
+
- 当前 change 目录名（`YYYY-MM-DD-<kebab>`）与其分类 `<cat>`（dev | doc | person | ops）
|
|
24
24
|
- 用户的隔离意图（是否显式请求）
|
|
25
25
|
- 仓库 `.gitignore`
|
|
26
26
|
|
|
@@ -10,6 +10,22 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
|
|
|
10
10
|
|
|
11
11
|
本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 红绿重构、测试、mock 与重构指引内置在本 workflow 目录中；**深模块、接口、接缝、适配器的设计词汇与原则统一引用 `vendor/codebase-design`，本工作流不再复制**（见下「渐进披露」）。
|
|
12
12
|
|
|
13
|
+
## 执行前 Git 基线
|
|
14
|
+
|
|
15
|
+
开始 TDD 计划或写代码前，必须先查看当前目录所在仓库和分支的 git 情况：
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
git branch --show-current
|
|
19
|
+
git status --short --branch
|
|
20
|
+
git diff --stat
|
|
21
|
+
git diff --cached --stat
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- 把当前分支、dirty/staged/untracked 摘要记录到 `tdd/<phase-id>/tdd-plan.md`；进入实现循环后如状态变化，记录到 `implementation-log.md`。
|
|
25
|
+
- 默认把已有改动视为用户或上一阶段留下的工作，不回退、不覆盖、不格式化无关文件。
|
|
26
|
+
- 如果本阶段需要修改的文件已存在未知改动，先核对 diff；无法判断归属或改动会重叠时，停止并询问用户。
|
|
27
|
+
- 若仓库不是 git 仓库或命令无法运行，记录失败原因和可见文件状态，再继续后续判断。
|
|
28
|
+
|
|
13
29
|
## 内置指引
|
|
14
30
|
|
|
15
31
|
### 核心原则
|
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
- `tdd-plan.md`
|
|
6
6
|
- `slices.md` 或用户确认的切片顺序
|
|
7
|
+
- `tdd-plan.md` 中记录的执行前 git 基线；每轮开始前核对本轮触及文件是否存在未知改动
|
|
7
8
|
- `03-tdd.md` 中的内置 TDD 指引和同目录辅助文档
|
|
8
9
|
|
|
9
10
|
## 产物
|
|
@@ -17,8 +18,8 @@
|
|
|
17
18
|
2. RED：写一个通过公共接口验证行为的失败测试。
|
|
18
19
|
3. GREEN：写最少实现使当前测试通过。
|
|
19
20
|
4. REFACTOR：只在绿色状态下整理设计。
|
|
20
|
-
5.
|
|
21
|
-
6.
|
|
21
|
+
5. 每轮记录测试名、失败信号、实现摘要、重构摘要、验证命令和 git 状态变化摘要。
|
|
22
|
+
6. 每轮检查：测试描述行为而非实现；测试只使用公共接口；测试能经受内部重构；代码是当前测试的最少实现；没有添加推测性功能；**未触碰本切片「保留/不动」清单**；引用代码以现场为准（不照搬切片行号）；未覆盖未知 dirty/staged 改动。
|
|
22
23
|
|
|
23
24
|
## 边界
|
|
24
25
|
|
|
@@ -26,6 +27,7 @@
|
|
|
26
27
|
- 不使用内部实现细节作为主要断言。
|
|
27
28
|
- 不在 RED 状态下重构。
|
|
28
29
|
- 不触碰本切片「保留/不动」清单（冻结常量 / 共享依赖 / 邻近功能）。
|
|
30
|
+
- 不回退、覆盖或格式化与本切片无关的已有改动。
|
|
29
31
|
|
|
30
32
|
## 完成准则
|
|
31
33
|
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
- `prd.md`、`slices.md`、`diagnosis.md` 或用户明确任务
|
|
6
6
|
- 多阶段：本阶段对应切片的 **保留/不动**、**关键核实结论**、**验收切片** 与 §4 横切铁律（`slices.md`）
|
|
7
7
|
- 项目测试命令、现有测试样式和公共接口
|
|
8
|
+
- 当前仓库 git 基线：分支、`git status --short --branch`、`git diff --stat`、`git diff --cached --stat`
|
|
8
9
|
- `03-tdd.md` 中的内置 TDD 指引（含「消费 slices 切片契约」）和同目录辅助文档
|
|
9
10
|
|
|
10
11
|
## 产物
|
|
@@ -13,13 +14,14 @@
|
|
|
13
14
|
|
|
14
15
|
## 填写引导
|
|
15
16
|
|
|
16
|
-
1. 遵循 `03-tdd.md` 的内置 TDD
|
|
17
|
-
2.
|
|
18
|
-
3.
|
|
19
|
-
4.
|
|
20
|
-
5.
|
|
21
|
-
6.
|
|
22
|
-
7.
|
|
17
|
+
1. 遵循 `03-tdd.md` 的内置 TDD 指引，并先完成「执行前 Git 基线」检查。
|
|
18
|
+
2. 在计划中记录当前分支、dirty/staged/untracked 摘要和 diff stat；已有改动默认视为用户工作，不能回退或覆盖。
|
|
19
|
+
3. 按需读取同目录 `tests.md` / `mocking.md`，以及设计词汇单一事实源 `../../../vendor/codebase-design/`（`SKILL.md` 深模块与可测试接口设计、`DEEPENING.md` 依赖类别与接缝、`DESIGN-IT-TWICE.md` 备选接口）。
|
|
20
|
+
4. 与用户确认公共接口、最重要的行为和测试覆盖优先级。
|
|
21
|
+
5. 拆出第一个 tracing slice，避免水平切片。
|
|
22
|
+
6. 探索代码库时使用项目领域术语表，确保测试名称和接口词汇与项目语言一致，并尊重触及区域的 ADR。
|
|
23
|
+
7. 写任何代码前确认接口变更、优先测试的行为、deep module 机会、可测试接口设计和行为列表。
|
|
24
|
+
8. **承载切片契约**：把本阶段对应切片的 **保留/不动** 与 **关键核实结论** 记入计划作为实现约束；切片行号为近似、以现场代码为准（现场核对）；存疑分支按 `../I-to-issues/issues-slices.md`「存疑时的提问协议」一次一问、带推荐、逐步锁定。
|
|
23
25
|
|
|
24
26
|
## 边界
|
|
25
27
|
|
|
@@ -29,6 +31,7 @@
|
|
|
29
31
|
## 完成准则
|
|
30
32
|
|
|
31
33
|
- 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 slices 须与 `<phase>` 的 `id` 一致）
|
|
34
|
+
- 已记录执行前 git 基线和未知/重叠改动处理结论
|
|
32
35
|
- 多阶段：已记录本切片 **保留/不动** 约束与 **现场核对** 结论
|
|
33
36
|
- `tdd-plan.md` 无残留 `[TODO:]`
|
|
34
37
|
- `.status.json` 的 `implementation_status` 为 `planned`
|