@namewta/speculo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# Speculo
+
+> 以结构化文档驱动 AI Coding 的标准化赋能体系  
+> **SDD (Specification-Driven Development for AI)**
+
+[![CI](https://github.com/NAMEWTA/Speculo/actions/workflows/ci.yml/badge.svg)](https://github.com/NAMEWTA/Speculo/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@namewta/speculo.svg)](https://www.npmjs.com/package/@namewta/speculo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/node/v/@namewta/speculo.svg)](./package.json)
+
+**版本：** v2.3  
+**核心原则：** 工具无关 · CLI 接入 · workflow 自治
+
+## 这是什么
+
+Speculo 是一套结构化文档框架。它通过可复制的 `commands/`、`workflows/`、`skills/` 和 `.speculo/` 状态骨架，让 AI Coding 在不同工具中按标准化、可追溯、可复用的方式执行开发、文档和运维任务。
+
+仓库同时提供一个很小的 CLI：
+
+- `speculo init [target]`：把框架资产安装到目标项目；遇到已有文件冲突时失败，不覆盖。
+- `speculo update [target]`：覆盖目标项目的 `commands/`、`skills/`、`workflows/`；保留 `.speculo/` 下的状态和产物。
+
+## 仓库布局
+
+```text
+Speculo/
+├── README.md
+├── docs/                       # 框架文档
+├── src/                        # speculo CLI
+├── test/                       # CLI 测试
+└── speculo/                    # 包内框架资产源
+    ├── commands/               # 一次性独立命令
+    ├── workflows/              # 多阶段工作流
+    ├── skills/                 # command 可调用的可复用 skill
+    └── .speculo/               # 项目状态与产物骨架
+```
+
+## 三分钟接入
+
+```bash
+# 全局安装 CLI（npm 包名为 @namewta/speculo，命令名为 speculo）
+npm install -g @namewta/speculo
+
+# 安装框架资产到目标项目
+speculo init my-project
+
+# 更新框架资产，不覆盖 .speculo 状态
+speculo update my-project
+```
+
+`init` 会带上 `.speculo/.config/RULES.md` 和 `.speculo/.config/LESSONS.md` 作为最小项目规则/经验库；`update` 不会覆盖它们。
+
+详见 [docs/adopting.md](docs/adopting.md)。
+
+## 内置入口
+
+- `workflows/dev/00-INDEX.md`：开发工作流导航
+- `workflows/dev/01-grill-with-docs/01-grill-with-docs.md`：领域澄清与决策拷问
+- `workflows/dev/02-prd/02-prd.md`：全景理解与 PRD
+- `workflows/dev/03-tdd/03-tdd.md`：TDD 实现
+- `workflows/dev/I-to-issues/I-to-issues.md`：`dev/I` 垂直切片分解
+- `workflows/dev/H-diagnose/H-diagnose.md`：`dev/H` hotfix / diagnose
+- `workflows/dev/R-review/R-review.md`：`dev/R` 双维度 diff 审查
+- `workflows/dev/D-docs-sync/D-docs-sync.md`：`dev/D` git diff 驱动文档同步
+- `workflows/doc/00-INDEX.md`：文档写作 workflow 导航
+- `commands/status.md`：聚合当前状态
+- `commands/archive.md`：归档 completed change
+- `commands/{caveman,grill-me,handoff,write-a-skill,scaffold-exercises}.md`：生产力命令
+
+## 开发
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+运行环境锁定为 Node `22.22.3`、pnpm `11.1.3`。
+
+## 文档导航
+
+- 使用者必读：[adopting.md](docs/adopting.md) · [quick-reference.md](docs/quick-reference.md)
+- 架构原理：[Speculo-architecture.md](docs/Speculo-architecture.md)
+- 机器契约：[persistence-contract.md](docs/persistence-contract.md)
+- 扩展开发：[workflow-authoring.md](docs/workflow-authoring.md) · [skill-authoring.md](docs/skill-authoring.md) · [command-authoring.md](docs/command-authoring.md)
+
+## License
+
+[MIT](./LICENSE) © wta

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { initSpeculo, updateSpeculo } from "./index.js";
+function usage() {
+    return [
+        "Usage:",
+        "  speculo init [target]",
+        "  speculo update [target]",
+        "",
+        "Commands:",
+        "  init    Copy .speculo, commands, skills, and workflows. Fails on conflicts.",
+        "  update  Replace commands, skills, and workflows. Keeps .speculo untouched."
+    ].join("\n");
+}
+async function main(argv) {
+    const [command, targetArg, extra] = argv;
+    if (!command || command === "--help" || command === "-h") {
+        console.log(usage());
+        return command ? 0 : 1;
+    }
+    if (extra) {
+        console.error(`Unexpected argument: ${extra}`);
+        console.error(usage());
+        return 1;
+    }
+    const target = resolve(targetArg ?? ".");
+    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+    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}`);
+            }
+            return 0;
+        }
+        if (command === "update") {
+            const result = await updateSpeculo(target, { packageRoot });
+            console.log(`Speculo updated in ${result.target}`);
+            for (const updated of result.updated ?? []) {
+                console.log(`updated ${updated}`);
+            }
+            return 0;
+        }
+        console.error(`Unknown command: ${command}`);
+        console.error(usage());
+        return 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        return 1;
+    }
+}
+const exitCode = await main(process.argv.slice(2));
+process.exitCode = exitCode;
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export type SpeculoCommandResult = {
+    target: string;
+    copied?: string[];
+    updated?: string[];
+};
+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

@@ -0,0 +1,60 @@
+import { cp, mkdir, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathExists } from "./utils.js";
+const INIT_ASSETS = [".speculo", "commands", "skills", "workflows"];
+const UPDATE_ASSETS = ["commands", "skills", "workflows"];
+function assetRoot(packageRoot) {
+    return join(packageRoot, "speculo");
+}
+async function ensureAssetSource(packageRoot, asset) {
+    const source = join(assetRoot(packageRoot), asset);
+    if (!(await pathExists(source))) {
+        throw new Error(`Missing packaged Speculo asset: speculo/${asset}`);
+    }
+    return source;
+}
+async function collectConflicts(target, assets) {
+    const conflicts = [];
+    for (const asset of assets) {
+        const destination = join(target, asset);
+        if (await pathExists(destination)) {
+            conflicts.push(destination);
+        }
+    }
+    return conflicts;
+}
+export async function initSpeculo(targetArg = ".", options = {}) {
+    const target = resolve(targetArg);
+    const packageRoot = resolve(options.packageRoot ?? process.cwd());
+    await mkdir(target, { recursive: true });
+    const conflicts = await collectConflicts(target, INIT_ASSETS);
+    if (conflicts.length > 0) {
+        throw new Error([
+            "Speculo init refused to overwrite existing paths:",
+            ...conflicts.map((conflict) => `- ${conflict}`)
+        ].join("\n"));
+    }
+    const copied = [];
+    for (const asset of INIT_ASSETS) {
+        const source = await ensureAssetSource(packageRoot, asset);
+        const destination = join(target, asset);
+        await cp(source, destination, { recursive: true, force: false, errorOnExist: true });
+        copied.push(asset);
+    }
+    return { target, copied };
+}
+export async function updateSpeculo(targetArg = ".", options = {}) {
+    const target = resolve(targetArg);
+    const packageRoot = resolve(options.packageRoot ?? process.cwd());
+    await mkdir(target, { recursive: true });
+    const updated = [];
+    for (const asset of UPDATE_ASSETS) {
+        const source = await ensureAssetSource(packageRoot, asset);
+        const destination = join(target, asset);
+        await rm(destination, { recursive: true, force: true });
+        await cp(source, destination, { recursive: true, force: true });
+        updated.push(asset);
+    }
+    return { target, updated };
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/utils.d.ts

@@ -0,0 +1 @@
+export declare function pathExists(path: string): Promise<boolean>;

package/dist/src/utils.js

@@ -0,0 +1,11 @@
+import { access } from "node:fs/promises";
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@namewta/speculo",
+  "version": "0.1.0",
+  "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
+  "type": "module",
+  "bin": {
+    "speculo": "./dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test dist/test/*.test.js",
+    "pretest": "pnpm build",
+    "check": "pnpm build && pnpm test",
+    "verify-bin": "node scripts/verify-bin.mjs",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "files": [
+    "dist/src",
+    "speculo"
+  ],
+  "keywords": [
+    "speculo",
+    "sdd",
+    "spec-driven-development",
+    "ai-coding",
+    "workflows",
+    "skills",
+    "cli",
+    "scaffolding"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NAMEWTA/Speculo.git"
+  },
+  "homepage": "https://github.com/NAMEWTA/Speculo#readme",
+  "bugs": {
+    "url": "https://github.com/NAMEWTA/Speculo/issues"
+  },
+  "license": "MIT",
+  "author": "wta",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "pnpm@11.1.3",
+  "engines": {
+    "node": "22.22.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "typescript": "^5.8.3"
+  }
+}

package/speculo/.speculo/.config/LESSONS.md

@@ -0,0 +1,9 @@
+# Lessons
+
+记录跨任务可复用的经验、踩坑和反模式。
+
+workflow 收尾时，如果发现对后续任务有复用价值的经验，可以在用户允许或项目规则允许的情况下追加到本文件。
+
+## Lessons
+
+- [TODO: 添加已验证、可复用的经验。]

package/speculo/.speculo/.config/RULES.md

@@ -0,0 +1,9 @@
+# Project Rules
+
+记录跨所有 Speculo workflow 必须遵守的项目硬约束。
+
+本文件由用户维护。AI 可以读取并遵守，但不得自动修改，除非用户明确要求。
+
+## Rules
+
+- [TODO: 添加项目必须遵守的规则。]

package/speculo/.speculo/.config/adr/.gitkeep

@@ -0,0 +1 @@
+

package/speculo/.speculo/.config/context/.gitkeep

@@ -0,0 +1 @@
+

package/speculo/.speculo/archive/doc/.gitkeep

@@ -0,0 +1 @@
+

package/speculo/.speculo/dev/docs-sync-state.json

@@ -0,0 +1,14 @@
+{
+  "schema_version": 1,
+  "skill": "docs-sync",
+  "state_path": ".speculo/dev/docs-sync-state.json",
+  "tracked_docs": [],
+  "last_sync_sha": null,
+  "last_sync_short": null,
+  "last_sync_commit_subject": null,
+  "last_sync_commit_date": null,
+  "last_sync_run_at": null,
+  "previous_sync_sha": null,
+  "total_syncs": 0,
+  "synced_docs": []
+}

package/speculo/.speculo/dev-status.json

@@ -0,0 +1,3 @@
+{
+  "active": []
+}

package/speculo/.speculo/doc/.gitkeep

@@ -0,0 +1 @@
+

package/speculo/.speculo/doc-status.json

@@ -0,0 +1,3 @@
+{
+  "active": []
+}

package/speculo/commands/archive.md

@@ -0,0 +1,53 @@
+---
+id: archive
+type: command
+name: Archive Changes
+description: 归档已完成的 change 到 archive/<cat>/<YYYY-MM>/
+keywords: [archive, 归档, 清理]
+---
+
+# Archive 命令
+
+⚠️ **本命令是破坏性目录移动操作。AI 必须先列出待归档清单并征求用户确认才能执行。**
+
+## 归档路径模式
+
+产物归档至：`../.speculo/commands/<YYYY-MM-DD>-archive-<topic>/`
+
+## 调用的 skills
+
+无
+
+## 执行步骤
+
+1. 扫描 `../.speculo/<cat>/*/.status.json`，当前内置分类至少包括 `dev` 与 `doc`，仅选择 `change_status: completed` 的 change。
+2. 排除已经位于 `../.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`
+6. 若任一移动失败，停止后续移动，报告已完成与未完成清单；不要回滚已经成功移动的目录，除非用户明确要求。
+
+## 产物模板（report.md）
+
+> **服务命令：** `archive.md`
+> **产物文件名：** `report.md`
+
+```markdown
+# Archive Report
+
+## 执行时间
+[TODO: ISO 时间戳]
+
+## 归档清单
+[TODO: 列出本次归档的所有 change，格式 "<source-path> → <dest-path>"]
+
+## 用户确认记录
+[TODO: 记录用户确认的原始内容]
+
+## 执行结果
+[TODO: 成功 / 失败 / 部分成功]
+```

package/speculo/commands/caveman.md

@@ -0,0 +1,43 @@
+---
+id: caveman
+type: command
+name: Caveman Mode
+description: 启用或关闭超压缩沟通模式
+keywords: [caveman, brief, tokens, 简洁]
+---
+
+# Caveman 命令
+
+## 归档路径模式
+
+可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/`
+（通常只改变对话风格，不需要持久化。）
+
+## 调用的 skills
+
+- `../skills/caveman/SKILL.md` — 用户要求启用、关闭或检查 caveman mode 时读取。
+
+## 执行步骤
+
+1. 读取 `../skills/caveman/SKILL.md`。
+2. 根据用户意图启用或关闭压缩沟通模式。
+3. 若用户只要求启用模式，在对话中确认当前模式即可，不写文件。
+4. 若用户要求记录模式切换，把报告写入 `../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`。
+
+## 产物模板（mode.md，可选）
+
+> **服务命令：** `caveman.md`
+> **产物文件名：** `mode.md`
+
+```markdown
+# Caveman Mode
+
+## 时间
+[TODO: ISO 8601 时间戳。]
+
+## 动作
+[TODO: 记录启用、关闭或检查模式。]
+
+## 用户原始请求
+[TODO: 记录触发命令的用户请求摘要。]
+```

package/speculo/commands/grill-me.md

@@ -0,0 +1,42 @@
+---
+id: grill-me
+type: command
+name: Grill Me
+description: 对计划或设计进行逐问式压力测试
+keywords: [grill, 追问, pressure-test, 方案]
+---
+
+# Grill Me 命令
+
+## 归档路径模式
+
+可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/`
+
+## 调用的 skills
+
+- `../skills/grill-me/SKILL.md` — 用户要求拷问计划、设计或决策时读取。
+
+## 执行步骤
+
+1. 读取 `../skills/grill-me/SKILL.md`。
+2. 先探索可从仓库确认的事实。
+3. 对无法从仓库确认且会改变决策树的问题，每次只问一个。
+4. 用户要求持久化时，把已确认决策和开放问题写入 `../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`。
+
+## 产物模板（report.md，可选）
+
+> **服务命令：** `grill-me.md`
+> **产物文件名：** `report.md`
+
+```markdown
+# Grill Me Report
+
+## 主题
+[TODO: 记录被压力测试的计划或设计。]
+
+## 已确认决策
+[TODO: 列出已确认决策和用户确认依据。]
+
+## 开放问题
+[TODO: 列出仍未解决的问题、推荐答案和阻塞原因。]
+```

package/speculo/commands/handoff.md

@@ -0,0 +1,42 @@
+---
+id: handoff
+type: command
+name: Handoff
+description: 生成脱敏交接文档，供另一个 agent 或会话接手
+keywords: [handoff, 交接, summary, resume]
+---
+
+# Handoff 命令
+
+## 归档路径模式
+
+可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`
+
+## 调用的 skills
+
+- `../skills/handoff/SKILL.md` — 需要把当前对话压缩成交接文档时读取。
+
+## 执行步骤
+
+1. 读取 `../skills/handoff/SKILL.md`。
+2. 按 source skill 要求，把交接文档保存到用户操作系统临时目录，而不是当前工作区。
+3. 删除 API key、密码、PII 和其他敏感信息。
+4. 若用户要求项目内留痕，只把交接文档路径、摘要和推荐技能写入 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/pointer.md`。
+
+## 产物模板（pointer.md，可选）
+
+> **服务命令：** `handoff.md`
+> **产物文件名：** `pointer.md`
+
+```markdown
+# Handoff Pointer
+
+## 临时文件路径
+[TODO: 记录操作系统临时目录中的交接文档路径。]
+
+## 摘要
+[TODO: 用 3-5 条概括交接内容，不复制敏感信息。]
+
+## 推荐技能
+[TODO: 列出下一个 agent 推荐读取的 skill。]
+```

package/speculo/commands/scaffold-exercises.md

@@ -0,0 +1,50 @@
+---
+id: scaffold-exercises
+type: command
+name: Scaffold Exercises
+description: 创建课程练习目录骨架并运行练习 lint
+keywords: [exercises, scaffold, course, lint, 练习]
+---
+
+# Scaffold Exercises 命令
+
+⚠️ **本命令会创建或移动项目文件，且 source skill 可能执行 git commit。AI 必须先列出影响清单并征求用户确认才能执行。**
+
+## 归档路径模式
+
+产物归档至：`../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/`
+
+## 调用的 skills
+
+- `../skills/scaffold-exercises/SKILL.md` — 用户要求创建课程章节或练习桩时读取。
+
+## 执行步骤
+
+1. 读取 `../skills/scaffold-exercises/SKILL.md`。
+2. 解析章节、练习、编号、名称、变体类型和目标路径。
+3. 列出将创建、移动或提交的路径，以及将运行的 lint / git 命令。
+4. 等待用户明确确认；没有确认时只输出计划，不创建目录、不提交 git。
+5. 用户确认后执行创建、lint 和修复循环。
+6. 只有用户明确要求时才执行 git commit。
+7. 写入 `../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`。
+
+## 产物模板（report.md）
+
+> **服务命令：** `scaffold-exercises.md`
+> **产物文件名：** `report.md`
+
+```markdown
+# Scaffold Exercises Report
+
+## 影响清单
+[TODO: 列出将创建或移动的章节、练习和变体路径。]
+
+## 用户确认
+[TODO: 记录用户确认执行的原始内容摘要。]
+
+## 执行结果
+[TODO: 记录目录创建、lint、修复和可选 git commit 结果。]
+
+## 后续事项
+[TODO: 列出仍需补充内容、失败 lint 或阻塞原因。]
+```