npm - @namewta/speculo - Versions diffs - 0.1.7 → 0.1.8 - Mend

@namewta/speculo 0.1.7 → 0.1.8

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 (399) hide show

package/README.md CHANGED Viewed

@@ -17,8 +17,7 @@ Speculo 是一套结构化文档框架。它通过可复制的 `commands/`、`wo
 仓库同时提供一个很小的 CLI：
-- `speculo init [target]`：把框架资产安装到目标项目；遇到已有文件冲突时失败，不覆盖。
-- `speculo update [target]`：覆盖目标项目的 `commands/`、`skills/`、`workflows/`；保留 `.speculo/` 下的状态和产物。
+- `speculo init [target]`：把框架资产安装到目标项目。若 `speculo/` 不存在则全新安装全部资产（冲突时失败）；若已存在则自动更新 `commands/`、`skills/`、`workflows/` 并保留 `.speculo/` 状态和产物。
 ## 仓库布局
@@ -28,7 +27,7 @@ Speculo/
 ├── docs/                       # 框架文档
 ├── src/                        # speculo CLI
 ├── test/                       # CLI 测试
-└── speculo/                    # 包内框架资产源
+└── template/                   # 包内框架资产源
     ├── commands/               # 一次性独立命令
     ├── workflows/              # 多阶段工作流
     ├── skills/                 # command 可调用的可复用 skill
@@ -41,14 +40,14 @@ Speculo/
 # 全局安装 CLI（npm 包名为 @namewta/speculo，命令名为 speculo）
 npm install -g @namewta/speculo
-# 安装框架资产到目标项目
+# 安装框架资产到目标项目（首次）
 speculo init my-project
-# 更新框架资产，不覆盖 .speculo 状态
-speculo update my-project
+# 后续更新框架资产（speculo/ 已存在时自动进入更新模式，不覆盖 .speculo 状态）
+speculo init my-project
 ```
-`init` 会带上 `.speculo/.config/RULES.md` 和 `.speculo/.config/LESSONS.md` 作为最小项目规则/经验库；`update` 不会覆盖它们。
+首次 `init` 会带上 `.speculo/.config/RULES.md` 和 `.speculo/.config/LESSONS.md` 作为最小项目规则/经验库；后续执行不会覆盖它们。
 详见 [docs/adopting.md](docs/adopting.md)。

package/dist/src/cli.js CHANGED Viewed

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { initSpeculo, updateSpeculo } from "./index.js";
+import { initSpeculo } from "./index.js";
 function usage() {
     return [
         "Usage:",
         "  speculo init [target]",
-        "  speculo update [target]",
         "",
         "Commands:",
-        "  init    Install .speculo, commands, skills, and workflows under speculo/. Fails on conflicts.",
-        "  update  Replace commands, skills, and workflows under speculo/. Keeps .speculo untouched."
+        "  init    Install speculo assets under speculo/. If speculo/ does not exist,",
+        "          copies .speculo, commands, skills, and workflows with conflict detection.",
+        "          If speculo/ already exists, refreshes commands, skills, and workflows",
+        "          while preserving .speculo/ user state."
     ].join("\n");
 }
 async function main(argv) {
@@ -29,14 +30,23 @@ async function main(argv) {
     try {
         if (command === "init") {
             const result = await initSpeculo(target, { packageRoot });
-            console.log(`Speculo initialized in ${result.target}`);
-            for (const copied of result.copied ?? []) {
-                console.log(`copied ${copied}`);
+            if (result.mode === 'init') {
+                console.log(`Speculo initialized in ${result.target}`);
+                for (const copied of result.copied ?? []) {
+                    console.log(`copied ${copied}`);
+                }
+            }
+            else {
+                console.log(`Speculo updated in ${result.target}`);
+                for (const updated of result.updated ?? []) {
+                    console.log(`updated ${updated}`);
+                }
             }
             return 0;
         }
         if (command === "update") {
-            const result = await updateSpeculo(target, { packageRoot });
+            console.error("Warning: `speculo update` is deprecated. Use `speculo init` instead.");
+            const result = await initSpeculo(target, { packageRoot });
             console.log(`Speculo updated in ${result.target}`);
             for (const updated of result.updated ?? []) {
                 console.log(`updated ${updated}`);

package/dist/src/cli.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,~~aAAa,EAAE,~~MAAM,YAAY,CAAC;~~AAExD~~,SAAS,KAAK;IACZ,OAAO;QACL,QAAQ;QACR,yBAAyB;QACzB,~~2BAA2B;QAC3B,~~EAAE;QACF,WAAW;QACX,~~iGAAiG~~;~~QACjG~~,~~6FAA6F~~;~~KAC9F~~,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,IAAc;IAChC,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;IAEzC,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;QACrB,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,wBAAwB,KAAK,EAAE,CAAC,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAE9E,IAAI,CAAC;QACH,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YAC1D,OAAO,CAAC,GAAG,CAAC,0BAA0B,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;~~YACvD~~,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;~~gBACzC~~,OAAO,CAAC,GAAG,CAAC,UAAU,MAAM,EAAE,CAAC,CAAC;~~YAClC~~,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QAED,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,MAAM,~~aAAa~~,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;~~YAC5D~~,OAAO,CAAC,GAAG,CAAC,sBAAsB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YACnD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBAC3C,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;QAC7C,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC"}
1	+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 export type SpeculoCommandResult = {
     target: string;
+    mode: 'init' | 'update';
     copied?: string[];
     updated?: string[];
 };
@@ -7,4 +8,3 @@ export type SpeculoOptions = {
     packageRoot?: string;
 };
 export declare function initSpeculo(targetArg?: string, options?: SpeculoOptions): Promise<SpeculoCommandResult>;
-export declare function updateSpeculo(targetArg?: string, options?: SpeculoOptions): Promise<SpeculoCommandResult>;

package/dist/src/index.js CHANGED Viewed

@@ -7,7 +7,7 @@ const UPDATE_ASSETS = ["commands", "skills", "workflows"];
 // mirroring the package layout — never scattered into the target root.
 const INSTALL_SUBDIR = "speculo";
 function assetRoot(packageRoot) {
-    return join(packageRoot, "speculo");
+    return join(packageRoot, "template");
 }
 function installRoot(target) {
     return join(target, INSTALL_SUBDIR);
@@ -15,7 +15,7 @@ function installRoot(target) {
 async function ensureAssetSource(packageRoot, asset) {
     const source = join(assetRoot(packageRoot), asset);
     if (!(await pathExists(source))) {
-        throw new Error(`Missing packaged Speculo asset: speculo/${asset}`);
+        throw new Error(`Missing packaged Speculo asset: template/${asset}`);
     }
     return source;
 }
@@ -29,7 +29,7 @@ async function collectConflicts(root, assets) {
     }
     return conflicts;
 }
-export async function initSpeculo(targetArg = ".", options = {}) {
+async function initFresh(targetArg = ".", options = {}) {
     const target = resolve(targetArg);
     const packageRoot = resolve(options.packageRoot ?? process.cwd());
     const root = installRoot(target);
@@ -48,9 +48,9 @@ export async function initSpeculo(targetArg = ".", options = {}) {
         await cp(source, destination, { recursive: true, force: false, errorOnExist: true });
         copied.push(asset);
     }
-    return { target, copied };
+    return { target, mode: 'init', copied };
 }
-export async function updateSpeculo(targetArg = ".", options = {}) {
+async function initOverwrite(targetArg = ".", options = {}) {
     const target = resolve(targetArg);
     const packageRoot = resolve(options.packageRoot ?? process.cwd());
     const root = installRoot(target);
@@ -63,6 +63,16 @@ export async function updateSpeculo(targetArg = ".", options = {}) {
         await cp(source, destination, { recursive: true, force: true });
         updated.push(asset);
     }
-    return { target, updated };
+    return { target, mode: 'update', updated };
+}
+export async function initSpeculo(targetArg = ".", options = {}) {
+    const target = resolve(targetArg);
+    const root = installRoot(target);
+    if (await pathExists(root)) {
+        const result = await initOverwrite(targetArg, options);
+        return { ...result, mode: 'update' };
+    }
+    const result = await initFresh(targetArg, options);
+    return { ...result, mode: 'init' };
 }
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;~~AAYxC~~,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;AAC7E,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;AAEnE,wEAAwE;AACxE,uEAAuE;AACvE,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC,SAAS,SAAS,CAAC,WAAmB;IACpC,OAAO,IAAI,CAAC,WAAW,EAAE,~~SAAS~~,CAAC,CAAC;~~AACtC~~,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,~~2CAA2C~~,KAAK,EAAE,CAAC,CAAC;~~IACtE~~,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,~~MAAM,CAAC,~~KAAK,UAAU,~~WAAW~~,~~CAC/B~~,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,SAAS,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC5D,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;IAC5B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,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,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;~~AAC5B~~,CAAC;AAED,~~MAAM,CAAC,~~KAAK,UAAU,aAAa,~~CACjC~~,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;IAC7B,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,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,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;~~AAC7B~~,CAAC"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "files": [
     "dist/src",
-    "speculo"
+    "template"
   ],
   "keywords": [
     "speculo",

package/{speculo → template}/.speculo/.config/RULES.md RENAMED Viewed

@@ -7,5 +7,6 @@
 ## Rules
 - [TODO: 添加项目必须遵守的规则。]
-- 所有 Speculo change 目录必须以 `YYYY-MM-DD-<kebab-name>` 命名（例：`2026-06-12-user-auth`）。详见 `speculo/docs/persistence-contract.md` §0。
+- **Rule 0 — 持久化铁律：所有 Speculo workflow、command、skill 的输出和持久化内容，必须且只能存放在 `speculo/.speculo/` 目录中。绝对禁止写入 `temp/`、系统临时目录、项目根目录的 `.speculo/` 或其他任何非规范位置。**
+- 所有 Speculo change 目录必须以 `YYYY-MM-DD-<kebab-name>` 命名（例：`2026-06-12-user-auth`）。
 - 所有 Speculo command 产物目录必须以 `YYYY-MM-DD-<cmd-name>-<topic>` 命名。

package/{speculo → template}/.speculo/dev/docs-sync-state.json RENAMED Viewed

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "skill": "docs-sync",
-  "state_path": ".speculo/dev/docs-sync-state.json",
+  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
   "tracked_docs": [],
   "last_sync_sha": null,
   "last_sync_short": null,

package/{speculo → template}/commands/archive.md RENAMED Viewed

@@ -12,13 +12,12 @@ keywords: [archive, 归档, 清理]
 ## 归档路径模式
-产物目录：`../.speculo/commands/<YYYY-MM-DD>-archive-<topic>/`
+产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-archive-<topic>/`
-报告文件：`../.speculo/commands/<YYYY-MM-DD>-archive-<topic>/report.md`
+报告文件：`speculo/.speculo/commands/<YYYY-MM-DD>-archive-<topic>/report.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从归档范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `changes`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-archive-<topic>/report.md`。
 - 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 ## 调用的 skills
@@ -27,15 +26,15 @@ keywords: [archive, 归档, 清理]
 ## 执行步骤
-1. 扫描 `../.speculo/<cat>/*/.status.json`，当前内置分类至少包括 `dev` 与 `doc`，仅选择 `change_status: completed` 的 change。
-2. 排除已经位于 `../.speculo/archive/` 下的目录；若目标归档路径已存在，标记为冲突并停止，不覆盖。
+1. 扫描 `speculo/.speculo/<cat>/*/.status.json`，当前内置分类至少包括 `dev` 与 `doc`，仅选择 `change_status: completed` 的 change。
+2. 排除已经位于 `speculo/.speculo/archive/` 下的目录；若目标归档路径已存在，标记为冲突并停止，不覆盖。
 3. 列出待归档清单：源路径、目标路径、当前分类、`updated_at`、最后 phase、是否仍在 `<cat>-status.json active[]`。
 4. 向用户展示清单并等待明确确认。没有确认时只输出计划，不移动目录、不改索引。
 5. 用户确认后逐项执行：
-   - 创建 `../.speculo/archive/<cat>/<YYYY-MM>/`
-   - 移动 change 目录到 `../.speculo/archive/<cat>/<YYYY-MM>/<change-name>/`
-   - 从对应 `../.speculo/<cat>-status.json` 的 `active[]` 删除该 change
-   - 写入本次命令报告 `../.speculo/commands/<YYYY-MM-DD>-archive-<topic>/report.md`
+   - 创建 `speculo/.speculo/archive/<cat>/<YYYY-MM>/`
+   - 移动 change 目录到 `speculo/.speculo/archive/<cat>/<YYYY-MM>/<change-name>/`
+   - 从对应 `speculo/.speculo/<cat>-status.json` 的 `active[]` 删除该 change
+   - 写入本次命令报告 `speculo/.speculo/commands/<YYYY-MM-DD>-archive-<topic>/report.md`
 6. 若任一移动失败，停止后续移动，报告已完成与未完成清单；不要回滚已经成功移动的目录，除非用户明确要求。
 ## 产物模板（report.md）

package/{speculo → template}/commands/caveman.md RENAMED Viewed

@@ -10,13 +10,12 @@ keywords: [caveman, brief, tokens, 简洁]
 ## 归档路径模式
-可选产物目录：`../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/`
+可选产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/`
-模式报告：`../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`
+模式报告：`speculo/.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从用户请求提取，使用小写 kebab-case；无法判断时使用 `mode`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`。
 - 禁止把模式报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 （通常只改变对话风格，不需要持久化。）
@@ -30,7 +29,7 @@ keywords: [caveman, brief, tokens, 简洁]
 1. 读取 `../skills/caveman/SKILL.md`。
 2. 根据用户意图启用或关闭压缩沟通模式。
 3. 若用户只要求启用模式，在对话中确认当前模式即可，不写文件。
-4. 若用户要求记录模式切换，把报告写入 `../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`。
+4. 若用户要求记录模式切换，把报告写入 `speculo/.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`。
 ## 产物模板（mode.md，可选）

package/{speculo → template}/commands/grill-me.md RENAMED Viewed

@@ -10,13 +10,12 @@ keywords: [grill, 追问, pressure-test, 方案]
 ## 归档路径模式
-可选产物目录：`../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/`
+可选产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/`
-报告文件：`../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`
+报告文件：`speculo/.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从被压力测试的计划或决策主题提取，使用小写 kebab-case；无法判断时使用 `decision`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`。
 - 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 ## 调用的 skills
@@ -28,7 +27,7 @@ keywords: [grill, 追问, pressure-test, 方案]
 1. 读取 `../skills/grill-me/SKILL.md`。
 2. 先探索可从仓库确认的事实。
 3. 对无法从仓库确认且会改变决策树的问题，每次只问一个。
-4. 用户要求持久化时，把已确认决策和开放问题写入 `../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`。
+4. 用户要求持久化时，把已确认决策和开放问题写入 `speculo/.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`。
 ## 产物模板（report.md，可选）

package/{speculo → template}/commands/handoff.md RENAMED Viewed

@@ -10,13 +10,12 @@ keywords: [handoff, 交接, summary, resume]
 ## 归档路径模式
-产物目录：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`
+产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`
-交接文件：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`
+交接文件：`speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从用户目标或交接主题提取，使用小写 kebab-case；无法判断时使用 `session`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
 - 禁止把交接文档写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 ## 调用的 skills
@@ -27,8 +26,8 @@ keywords: [handoff, 交接, summary, resume]
 1. 读取 `../skills/handoff/SKILL.md`。
 2. 按 `../skills/handoff/SKILL.md` 要求，生成脱敏交接文档。
-3. 创建规范命令产物目录 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`。
-4. 把交接正文写入 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
+3. 创建规范命令产物目录 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`。
+4. 把交接正文写入 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
 5. 删除 API key、密码、PII 和其他敏感信息；不要复制 PRD、计划、ADR、issue、commit、diff 或其他已有产物正文。
 6. 返回 `handoff.md` 路径、3-5 条摘要和推荐技能清单。

package/{speculo → template}/commands/retro.md RENAMED Viewed

@@ -12,13 +12,12 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 ## 归档路径模式
-产物目录：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`
+产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`
-报告文件：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`
+报告文件：`speculo/.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从复盘范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`。
 - 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 ## 调用的 skills
@@ -28,9 +27,9 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 ## 执行步骤
-1. 读取 `../skills/speculo-retro/SKILL.md`，按其规范采集信号（对话上下文、`../.speculo/commands/`、`../.speculo/<cat>/<change>/.status.json`、`../.speculo/.config/LESSONS.md`）并深度分析。
+1. 读取 `../skills/speculo-retro/SKILL.md`，按其规范采集信号（对话上下文、`speculo/.speculo/commands/`、`speculo/.speculo/<cat>/<change>/.status.json`、`speculo/.speculo/.config/LESSONS.md`）并深度分析。
 2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
-3. 创建规范命令产物目录 `../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`，把复盘结论写入 `report.md`。
+3. 创建规范命令产物目录 `speculo/.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`，把复盘结论写入 `report.md`。
 4. **解析目标仓库**：默认框架反馈上游 `NAMEWTA/Speculo`；用户在请求中显式指定其他 `owner/repo` 时覆盖默认。无论如何，在调用 `gh` 前回显解析到的 `owner/repo`，让用户确认或改正。
 5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
 6. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标 `owner/repo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
@@ -49,7 +48,7 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 [TODO: 本次复盘覆盖的 command / workflow 与时间/会话范围。]
 ## 信号来源
-[TODO: 列出采集到的证据出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、LESSONS。]
+[TODO: 列出采集到的证据出处：对话节点、`speculo/.speculo/...` 产物路径、`.status.json` 字段、LESSONS。]
 ## 改进提案
 [TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / 建议改动 / 验收标准 / 受影响资产 / 去重结论。]

package/{speculo → template}/commands/scaffold-exercises.md RENAMED Viewed

@@ -12,13 +12,12 @@ keywords: [exercises, scaffold, course, lint, 练习]
 ## 归档路径模式
-产物目录：`../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/`
+产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/`
-报告文件：`../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`
+报告文件：`speculo/.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从章节、练习或课程主题提取，使用小写 kebab-case；无法判断时使用 `exercises`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`。
 - 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 ## 调用的 skills
@@ -33,7 +32,7 @@ keywords: [exercises, scaffold, course, lint, 练习]
 4. 等待用户明确确认；没有确认时只输出计划，不创建目录、不提交 git。
 5. 用户确认后执行创建、lint 和修复循环。
 6. 只有用户明确要求时才执行 git commit。
-7. 写入 `../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`。
+7. 写入 `speculo/.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`。
 ## 产物模板（report.md）

package/{speculo → template}/commands/status.md RENAMED Viewed

@@ -10,13 +10,12 @@ keywords: [status, 状态, 进度]
 ## 归档路径模式
-可选产物目录：`../.speculo/commands/<YYYY-MM-DD>-status-<topic>/`
+可选产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/`
-快照文件：`../.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`
+快照文件：`speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从状态范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `snapshot`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`。
 - 禁止把状态快照写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 （若仅是回显报告、不需要持久化时可不归档）
@@ -27,15 +26,15 @@ keywords: [status, 状态, 进度]
 ## 执行步骤
-1. 读取已存在的 `../.speculo/<cat>-status.json`，当前内置分类至少包括 `dev` 与 `doc`。缺失时报告缺失路径，并建议按 `docs/adopting.md` 重新运行 `speculo init`，或创建空索引 `{"active":[]}`。
-2. 对每个索引的 `active[]` 条目，读取 `../.speculo/<cat>/<change>/.status.json`。读取失败时把该 change 标记为 `broken-index`，不要擅自删除索引项。
-3. 扫描 `../.speculo/<cat>/*/.status.json`，找出 `change_status: completed` 且尚未位于 `../.speculo/archive/` 的待归档 change。
+1. 读取已存在的 `speculo/.speculo/<cat>-status.json`，当前内置分类至少包括 `dev` 与 `doc`。缺失时报告缺失路径，建议重新运行 `speculo init`，或创建空索引 `{"active":[]}`。
+2. 对每个索引的 `active[]` 条目，读取 `speculo/.speculo/<cat>/<change>/.status.json`。读取失败时把该 change 标记为 `broken-index`，不要擅自删除索引项。
+3. 扫描 `speculo/.speculo/<cat>/*/.status.json`，找出 `change_status: completed` 且尚未位于 `speculo/.speculo/archive/` 的待归档 change。
 4. 聚合输出：
    - 各分类 active 数量、completed 待归档数量、broken-index 数量
    - 最近更新的 5 个 change（按 `updated_at` 倒序）
    - 当前可能阻塞项：`phase_history` 最后一项为 `blocked`，或 `updated_at` 超过 14 天未变化
    - 推荐下一步：优先处理 broken-index，其次处理 blocked，再推荐继续最近 active change 的 `current_phase`
-5. 用户要求持久化快照时，把报告写入 `../.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`；否则只在对话中返回。
+5. 用户要求持久化快照时，把报告写入 `speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`；否则只在对话中返回。
 ## 产物模板（snapshot.md，可选）

package/{speculo → template}/commands/write-a-skill.md RENAMED Viewed

@@ -10,13 +10,12 @@ keywords: [skill, create, write, 技能]
 ## 归档路径模式
-产物目录：`../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/`
+产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/`
-报告文件：`../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`
+报告文件：`speculo/.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从 skill 名称或用户主题提取，使用小写 kebab-case；无法判断时使用 `skill`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`。
 - 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 ## 调用的 skills
@@ -29,7 +28,7 @@ keywords: [skill, create, write, 技能]
 2. 先收集技能用途、触发条件、输入输出、脚本需求和示例需求。
 3. 写文件前列出将创建或修改的路径，并等待用户明确确认。
 4. 用户确认后，按 Speculo 契约创建 `../skills/<name>/SKILL.md` 及可选 `references/`、`scripts/`、`examples/`。
-5. 把设计摘要、影响路径和验证结果写入 `../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`。
+5. 把设计摘要、影响路径和验证结果写入 `speculo/.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`。
 ## 产物模板（report.md）

package/{speculo → template}/skills/caveman/SKILL.md RENAMED Viewed

@@ -23,7 +23,7 @@ description: 启用或关闭超压缩沟通模式以降低 token 消耗；当用
 - 保留技术准确性的压缩回复风格
 - 必要时对安全风险、不可逆操作或多步骤顺序使用完整清晰表达
-- 不产生 `.speculo/` 或 `.status.json` 持久化产物
+- 不产生 `speculo/.speculo/` 或 `.status.json` 持久化产物
 ## 执行步骤

package/{speculo → template}/skills/github-npm-ops/SKILL.md RENAMED Viewed

@@ -17,7 +17,7 @@ description: GitHub 仓库运营与 npm 发布原子能力；用于 issue/PR/CI/
 - npm 包信息：`package.json`、包名、版本、发布分支、是否 scoped
 - 发布流水线文件：通常是 `.github/workflows/release.yml`
 - CHANGELOG 类文档路径，默认优先识别 `CHANGELOG.md` 或 `CHANGELOGS.md`
-- 可选：调用方 workflow 提供的 `.speculo/dev/docs-sync-state.json` 与 docs-sync 报告
+- 可选：调用方 workflow 提供的 `speculo/.speculo/dev/docs-sync-state.json` 与 docs-sync 报告
 ## 输出
@@ -31,7 +31,7 @@ description: GitHub 仓库运营与 npm 发布原子能力；用于 issue/PR/CI/
 1. 先判定任务类型：日常治理、发布基础设施搭建、正式发版、失败恢复。
 2. 发布类任务先执行只读前置检查：分支、工作区、远端、`gh auth`、Node/包管理器、`release.yml`、tag 冲突、docs-sync state。
-3. 需要同步对外文档时，交给调用方读取 `../workflows/dev/D-docs-sync/D-docs-sync.md`；本 skill 不自行选择持久化目录，只把结果交给调用方写入其声明的 `.speculo/...` 规范路径。
+3. 需要同步对外文档时，交给调用方读取 `../workflows/dev/D-docs-sync/D-docs-sync.md`；本 skill 不自行选择持久化目录，只把结果交给调用方写入其声明的 `speculo/.speculo/...` 规范路径。
 4. 正式发版必须保证 release commit 同时包含版本 bump 与 CHANGELOG 迁移，并且 tag 精确指向 release commit。
 5. release workflow 必须包含 tag/package version 校验、质量闸、可选 npm publish、CHANGELOG release notes 注入、GitHub Release 创建。
 6. 发布完成后做三端验证：workflow success、GitHub Release 非 draft 且正文非空、如流水线包含 npm publish 则 `npm view` 版本与 dist-tag 一致。

package/{speculo → template}/skills/github-npm-ops/references/failure-recovery.md RENAMED Viewed

@@ -109,7 +109,7 @@ git push origin vX.Y.Z
 #    在 [X.Y.(Z+1)] 段落开头加一句 "supersedes vX.Y.Z due to <根因>"
 ```
-**错误码映射**：场景 D 通常是上游错误溢出（场景 B/C 处理不当后果），不单独列 E 码；流程上要求**事后复盘**，把可复用根因输出给调用方 workflow，由其追加到 `.speculo/.config/LESSONS.md`（本 skill 不自行选择持久化目录）。
+**错误码映射**：场景 D 通常是上游错误溢出（场景 B/C 处理不当后果），不单独列 E 码；流程上要求**事后复盘**，把可复用根因输出给调用方 workflow，由其追加到 `speculo/.speculo/.config/LESSONS.md`（本 skill 不自行选择持久化目录）。
 ---

package/{speculo → template}/skills/github-npm-ops/references/preflight-checklist.md RENAMED Viewed

@@ -16,7 +16,7 @@
 | 7 | 包管理器 | `pnpm --version` (或 `npm` / `yarn`) | 版本 ≥ 仓库 lockfile 隐含版本 | 安装匹配版本；不要随意切换包管理器 |
 | 8 | release.yml 存在 | `test -f .github/workflows/release.yml` | 文件存在 | 转 `github-ops` skill 的 `references/workflow-yaml-reference.md` 先落该文件 |
 | 9 | release.yml 形态 | 见 [publish-detection.md](publish-detection.md) | 输出 `PUBLISH_TO_NPM=true` 或 `false` | 见 publish-detection 文档的判定矩阵 |
-| 10 | docs-sync state | `test -f .speculo/dev/docs-sync-state.json && jq . .speculo/dev/docs-sync-state.json` | 解析成功且 `last_sync_sha != null` | 不存在 → 走 `dev/D-docs-sync` workflow 的「首次运行」分支；存在但损坏 → 修复 JSON |
+| 10 | docs-sync state | `test -f speculo/.speculo/dev/docs-sync-state.json && jq . speculo/.speculo/dev/docs-sync-state.json` | 解析成功且 `last_sync_sha != null` | 不存在 → 走 `dev/D-docs-sync` workflow 的「首次运行」分支；存在但损坏 → 修复 JSON |
 | 11 | tag 名称冲突 | `git rev-parse vX.Y.Z 2>/dev/null` | 退出码非 0（tag 不存在） | 同 tag 已存在：先确认是否真的失败需要重发；若是则 `git tag -d` + `git push origin :refs/tags/vX.Y.Z`，否则 bump 到下一版本 |
 ## 失败处理总策略

package/{speculo → template}/skills/github-npm-ops/references/release-notes-injection.md RENAMED Viewed

@@ -88,7 +88,7 @@ GitHub Release 的正文(body)**事后可改**(tag 不可改、npm 包不可改
 ### 3.1 命令行(推荐)
-`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
+`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
 ```bash
 VERSION="0.0.10"

package/{speculo → template}/skills/github-npm-ops/references/release-pipeline.md RENAMED Viewed

@@ -5,7 +5,7 @@
 ## Iron Law
 - 禁止提交破坏构建的代码；release 前必须运行仓库声明的 lint / test / build 或等价质量闸。
-- docs-sync 必须由调用方按 `workflows/dev/D-docs-sync/D-docs-sync.md` 执行，基于 `.speculo/dev/docs-sync-state.json#last_sync_sha..HEAD` 的 git diff。
+- docs-sync 必须由调用方按 `workflows/dev/D-docs-sync/D-docs-sync.md` 执行，基于 `speculo/.speculo/dev/docs-sync-state.json#last_sync_sha..HEAD` 的 git diff。
 - tag 必须精确指向 release commit，即包含 `package.json` version bump 与 CHANGELOG 迁移的 commit；禁止指向后续 docs / state commit。
 - npm 已成功上传后，同一 version 不可重发；不要通过删 tag 或 unpublish 试图覆盖。
@@ -18,7 +18,7 @@
 - Node 与包管理器满足仓库声明
 - `.github/workflows/release.yml` 存在
 - 已确定 `PUBLISH_TO_NPM=true | false`
-- `.speculo/dev/docs-sync-state.json` 存在且可解析；不存在时转 `dev/D-docs-sync` 首次运行流程
+- `speculo/.speculo/dev/docs-sync-state.json` 存在且可解析；不存在时转 `dev/D-docs-sync` 首次运行流程
 - 目标 tag `vX.Y.Z` 不存在，除非正在执行明确的失败恢复
 任一项不通过就停止，输出修复建议。

package/{speculo → template}/skills/github-npm-ops/references/version-bump-flow.md RENAMED Viewed

@@ -46,7 +46,7 @@ head -30 CHANGELOGS.md
  - [0.0.9](https://github.com/owner/repo/releases/tag/v0.0.9)
 ```
-完整 CHANGELOG 契约见 [docs-sync skill](../../docs-sync/SKILL.md) 或 docs-sync 的 changelog-contract.md。
+完整 CHANGELOG 契约见 `../../../workflows/dev/D-docs-sync/changelog-contract.md`。
 ## 2. bump package.json
@@ -180,7 +180,7 @@ git push origin v0.0.10
 npm 已上线 → **不要**改版本号,只补后续动作。
-下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
+下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
 ```bash
 notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"

package/{speculo → template}/skills/handoff/SKILL.md RENAMED Viewed

@@ -22,14 +22,14 @@ description: 将当前对话压缩成交接文档；当用户需要另一个 age
 ## 输出
-- 保存到规范命令产物目录的脱敏交接文档：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`
+- 保存到规范命令产物目录的脱敏交接文档：`speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`
 - 文档路径、主题目录名和命名依据
 - 3-5 条极简摘要
 - 推荐技能清单
 ## 命名与位置
-- 交接文档必须写入调用方命令产物目录：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
+- 交接文档必须写入调用方命令产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从用户目标、项目名、变更名或下一次会话重点提取，使用小写 kebab-case；无法判断时使用 `session`。
 - 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
@@ -41,7 +41,7 @@ description: 将当前对话压缩成交接文档；当用户需要另一个 age
 2. 删除 API key、密码、token、个人身份信息和其他敏感内容。
 3. 不复制 PRD、计划、ADR、issue、commit、diff 或其他已有产物正文；改用路径、URL 或 commit 引用。
 4. 添加 `推荐技能` 部分，列出下一个 agent 应优先读取或调用的技能。
-5. 创建 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`，并把交接文档写入其中的 `handoff.md`。
+5. 创建 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`，并把交接文档写入其中的 `handoff.md`。
 6. 返回文档路径、主题目录名、3-5 条极简摘要和推荐技能清单。
 ## references/ 与 scripts/

package/{speculo → template}/skills/scaffold-exercises/SKILL.md RENAMED Viewed

@@ -33,7 +33,7 @@ description: 创建课程章节与练习目录骨架并验证 lint；当用户
 4. 为每个变体创建最小但非空的 `readme.md`。
 5. 运行 lint；按 `references/lint-and-git.md` 迭代修复，直到通过或记录阻塞。
 6. 仅在用户或调用方明确要求时提交 git。
-7. 不自行选择持久化目录；需要归档时，由调用方 command 或 workflow 写入其声明的 `.speculo/...` 规范路径。
+7. 不自行选择持久化目录；需要归档时，由调用方 command 或 workflow 写入其声明的 `speculo/.speculo/...` 规范路径。
 ## 渐进披露