@namewta/speculo 0.1.21 → 0.2.0

package/template/skills/scaffold-exercises/references/lint-and-git.md

@@ -1,54 +0,0 @@
-# Lint And Git
-
-## Lint 命令
-
-默认验证命令：
-
-```bash
-pnpm ai-hero-cli internal lint
-```
-
-如果项目文档或用户指定了其他命令，使用项目命令。
-
-## Lint 规则摘要
-
-linter 通常会检查：
-
-- 每个练习都有子文件夹，例如 `problem/`、`solution/`、`explainer/`
-- 至少存在 `problem/`、`explainer/` 或 `explainer.1/` 之一
-- 主子文件夹中存在非空 `readme.md`
-- 没有 `.gitkeep`
-- 没有 `speaker-notes.md`
-- `readme.md` 中没有失效链接
-- `readme.md` 中没有 `pnpm run exercise`
-- 每个含代码的子文件夹都有超过 1 行的 `main.ts`
-
-## 修复流程
-
-1. 运行 lint。
-2. 根据错误补齐目录、`readme.md` 或需要的 `main.ts`。
-3. 删除不允许的 `.gitkeep` 或 `speaker-notes.md`，但只删除本次创建或用户明确要求处理的文件。
-4. 修复失效链接或记录需要用户确认的链接变更。
-5. 重跑 lint，直到通过或出现外部阻塞。
-
-## 移动或重命名练习
-
-重新编号或移动练习时使用 `git mv`，保留 git 历史。
-
-示例：
-
-```bash
-git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
-```
-
-移动后更新数字前缀并重新运行 lint。
-
-## 提交
-
-只有用户或调用方明确要求提交时才运行 `git commit`。
-
-提交前检查：
-
-- `git status --short`
-- 只包含本次练习脚手架相关改动，或提交命令明确指定路径
-- lint 已通过，或 commit message/交付说明中写明未通过原因

package/template/skills/speculo-write/SKILL.md

@@ -1,56 +0,0 @@
----
-id: speculo-write
-type: skill
-name: Speculo Write
-description: 创建或改造 Speculo workflows、skills、commands 的原子能力；当用户要求根据参考项目、外部技能、当前规范或产品意图，设计、迁移、融合、更新 Speculo 资产时使用。
----
-
-# Speculo Write
-
-创作任何 Speculo 资产的根本美德是**可预测性**——让代理每次运行采用相同的*过程*（而非相同输出）。本 skill 自带全部 Speculo 规范（路径、frontmatter、持久化）与质量杠杆（`references/authoring-quality-levers.md`），并以身作则遵守它们。
-
-## 何时使用
-
-当任务是新增、迁移、融合或改造 Speculo 的 `workflows/`、`skills/`、`commands/`、配套模板、引用资料或 `speculo/.speculo/` 状态骨架时使用。
-
-典型触发：
-
-- “把这个外部 skill 迁移进 Speculo”
-- “给 dev 加一个 review workflow”
-- “做一个一次性归档 command”
-- “把这几个旧技能融合成一个原子 skill”
-
-## 输入
-
-- 用户目标、成功标准、目标受众、约束和参考项目路径
-- 现有同类资产：`template/workflows/<cat>/`、`template/skills/`、`template/commands/`
-- 外部源材料：旧技能、参考 workflow、临时目录、README 索引、脚本、模板
-
-本 skill 自带全部 Speculo 规范，已内化到下方 `references/`，**编写时不外读仓库 `docs/`**。
-
-## 输出
-
-- 合规的 Speculo workflow、skill 或 command 资产
-- 必要的 `references/`、workflow phase 文件、workflow `_templates/` 或 command 内联模板
-- 必要的 `speculo/.speculo/` 初始骨架或状态索引更新建议
-- 文档、测试和残留路径检查清单
-
-## 执行步骤
-
-1. **判定资产类型** —— workflow、skill、command，或组合。规则见 `references/asset-selection-sop.md`。
-2. **读取同类资产** —— 看目标目录里现有资产的真实写法，对齐风格，不直接套用外部技能格式。
-3. **提取可复用行为** —— 从参考材料保留核心内容（触发、输入输出、铁律、边界、失败恢复、模板），只规范化路径、frontmatter、产物和渐进披露；跨资产共享的规范**引用单一事实源、不复制**。
-4. **设计文件结构** —— 入口、别名、状态字段、产物路径和验证清单；按**信息层级**（步骤 / 文件内参考 / 已披露参考）排布，保持入口阶梯顶部清晰，能下推就下推（见 `references/authoring-quality-levers.md`）。
-5. **实施** —— 实施前确认不会覆盖用户已有改动；用**主导词**锚定执行与调用，完成准则做到可检验且在重要处穷尽；实施后同步索引、文档和测试。
-6. **验证** —— 旧路径和旧工具名没有回流，运行项目测试或记录无法运行原因；对照 `references/authoring-quality-levers.md` 的失败模式与空操作测试逐句修剪；提交前过一遍 `references/validation-checklist.md`。
-
-## 渐进披露
-
-- `references/authoring-quality-levers.md`：贯穿全程的质量理论——可预测性、主导词、信息层级、完成标准、何时拆分、修剪与失败模式；设计结构、措辞、修剪和验收时读取。
-- `references/asset-selection-sop.md`：判断应做 workflow、skill 还是 command 时读取。
-- `references/workflow-authoring-sop.md`：创建或改造 workflow、phase、template、索引和状态字段时读取。
-- `references/skill-authoring-sop.md`：创建原子 skill、迁移外部技能、拆分 references 时读取。
-- `references/command-authoring-sop.md`：创建单步 command、调用 skill、设计归档产物时读取。
-- `references/persistence-contract-sop.md`：需要 `.status.json` schema、目录命名、frontmatter 最小集或写入责任时读取。
-- `references/migration-sop.md`：从 `temp/skills`、参考项目或旧 workflow 迁移能力时读取。
-- `references/validation-checklist.md`：提交前检查 frontmatter、路径、模板、`speculo/.speculo/`、测试和旧路径残留时读取。

package/template/skills/speculo-write/references/asset-selection-sop.md

@@ -1,67 +0,0 @@
-# Asset Selection SOP
-
-## 目标
-
-把用户的“做一个能力”翻译成 Speculo 的正确资产形态：workflow、skill、command，或它们的组合。
-
-> **粒度即拆分成本**（见 `authoring-quality-levers.md`「何时拆分」）：把流程切成 workflow 的多个 phase，是为了把**后续步骤**移出视野、防过早完成（**按序列拆分**）；把能力抽成可复用 skill，是为了独立触达、值回其 `description` 常驻系统提示的负载（**按调用拆分**）。每次切割都有成本，只在物有所值时拆。
-
-## 判定规则
-
-### 做 Workflow
-
-选择 workflow，当能力满足任一条件：
-
-- 多阶段交付，需要 phase 文件、产物模板和 `.status.json`
-- 产物属于一次 change，需要写 `speculo/.speculo/<cat>/<change>/`
-- 会跨多轮对话推进，或需要 `current_phase`、`phase_history`
-- 是业务流程、开发流程、文档流程或运维流程
-
-分类：
-
-- `dev`：开发、PRD、TDD、review、docs-sync、诊断、issue 分解
-- `doc`：文章、素材、文档写作、编辑、塑形
-- `ops`：运维、发布、巡检、外部系统操作的多阶段流程
-
-### 做 Skill
-
-选择 skill，当能力满足任一条件：
-
-- 是 command 或 workflow 可复用的原子能力
-- 复制到其他项目仍能工作
-- 需要 `references/` 渐进披露
-- 不拥有独立持久化根目录；文件型持久化由调用方提供 `speculo/.speculo/...` 目标路径，或返回内容给调用方写入
-- 是工具集成、领域知识、决策 SOP 或可复用操作手册
-
-### 做 Command
-
-选择 command，当能力满足全部条件：
-
-- 单步动作或短流程
-- 不需要 phase 状态机
-- 产物只归档到 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
-- 可以调用 skill，但不需要 workflow 的 change 生命周期
-
-### 做组合
-
-- command 触发 skill：例如一次性报告、归档、状态聚合
-- workflow 内嵌 skill：例如发布 workflow 调用 GitHub/npm 原子能力
-- workflow 融合旧 skill：当旧 skill 只服务某个 workflow，不再作为根 skill 分发
-
-## 反例
-
-- 不要把多阶段、有状态的流程塞进 skill。
-- 不要让 skill 自行选择 `speculo/.speculo/`、`temp/`、系统临时目录或项目根目录作为持久化位置。
-- 不要为一次性命令创建 workflow。
-- 不要把 workflow-only 方法保留为根 skill，除非会被多个入口复用。
-
-## 输出决策
-
-在实施前写清：
-
-- 资产类型
-- 目标路径
-- 入口 id / alias
-- 持久化路径
-- 是否需要模板、references、scripts
-- 需要同步的索引、文档和测试

package/template/skills/speculo-write/references/authoring-quality-levers.md

@@ -1,61 +0,0 @@
-# Authoring Quality Levers
-
-把「编写出色技能」的领域模型内化到 Speculo 资产创作（workflow / skill / command）。**所有杠杆都服务一个根本美德：可预测性**——让代理每次运行采用相同的*过程*（而非相同的输出）。成本与可维护性是它的症状，不是对手。
-
-本文是质量理论的**单一事实源**：`skill-authoring-sop.md`、`workflow-authoring-sop.md`、`command-authoring-sop.md`、`validation-checklist.md` 按需引用本文，不复述其内容。
-
-## 主导词（Leading Word）
-
-一个已存在于模型预训练中的紧凑概念（如 *lesson*、*fog of war*、*tracer bullet*；Speculo 里的*切片 / 接缝 / 红绿重构 / 门控 / 深模块*），代理运行资产时用它思考。作为一个 token 反复出现（而非整句），用最少 token 锚定整个行为区域。
-
-它两次服务可预测性：在正文锚定**执行**（每次遇到该词都采取相同行为）；在 `description` 与别名里锚定**调用**（同一个词出现在提示、文档、代码里，代理更可靠地触发该资产）。
-
-- 优先用预训练已有的词；自造词不招募任何先验，要用定义 token 付费。
-- 在 `description`、phase 名、完成准则里用你*真正会用来唤起该资产*的主导词。
-- 把「在三处拼写出的三元组」「用一句话指一个想法」折叠成一个 token。
-
-## 信息层级（Information Hierarchy）
-
-内容按代理需要它的紧迫程度排成**一个阶梯**，由两次切分产生：
-
-1. **步骤**——入口里的有序操作（workflow 的 `## 阶段`、skill 的 `## 执行步骤`）。主层级。每个步骤以**完成标准**结束。
-2. **文件内参考**——入口里随手查阅的定义 / 规则 / 事实。次层级。常是合法的扁平同级集合（审查类技能每条规则平级，不是坏味道）。
-3. **已披露参考**——推到 `references/` 或 phase 文件，经**上下文指针**按需加载。
-
-不是每个资产都有步骤：可以全是步骤、全是参考、或两者兼有。保持阶梯顶部清晰，能下推就下推。
-
-**渐进披露**＝沿阶梯下移以保护层级（主要不是 token 优化）。由**分支**授权：只把*部分*运行才需要的材料推到指针后，每条路径都需要的内联。**上下文指针的措辞**（而非目标）决定代理何时、多可靠地取用——指针对必备材料触发不可靠时，先改措辞，失败才内联。
-
-**就近放置（Co-location）**：一个概念的定义、规则、注意事项放在同一标题下，而非散落——读一部分就连带看到相邻内容。与「重复」相反：重复是一个含义出现在多处，散落是一个含义被拆到多处。
-
-## 完成标准（Completion Criterion）
-
-告诉代理一个工作单元已完成的判断条件。两个属性使它成为杠杆，而不只是质量指标：
-
-- **可检验**：代理能区分完成与未完成吗？模糊的界限（「理解达到」）让代理宣布完成并滑向下一步（**过早完成**）。
-- **穷尽**：「每个修改过的模型都已纳入」强于「生成变更列表」。穷尽轴*不受步骤限制*，也约束扁平参考（「每条规则都已应用」）——这正是无步骤资产仍能驱动彻底**调研工作**的力量。
-
-最强的完成标准既可检验又穷尽。Speculo 的「`xxx.md` 无残留 `[TODO:]`」是可检验的最低线；在重要处补穷尽项。
-
-## 何时拆分
-
-每次切割都消耗成本，只在物有所值时拆：
-
-- **按序列拆分**——当一个步骤的**后续步骤**诱使代理匆忙了事（过早完成）时，把序列拆成两段、把后续步骤移出视野。这正是 Speculo 把 workflow 切成 phase、把 phase 隔离到独立文件的原因。注意反面：把序列并回一个文件，会把后续步骤暴露给当前步骤。
-- **按复用 / 调用拆分**——当一段能力会被多个入口复用，或需要独立触发时，抽成 skill。你为它的 `description`（常驻系统提示）付出代价，因此这种独立触达必须值回票价。判定细节见 `asset-selection-sop.md`。
-
-## 修剪
-
-- **单一事实来源**：每个含义只存在于唯一权威位置，改行为只需一处编辑。跨资产共享的规范放进被引用的单一文件（如 `vendor/codebase-design`、本文），引用方**不复制**。
-- **相关性**：逐行问「它是否仍影响资产行为？」——越短的资产越容易保持相关。
-- **空操作测试**：逐*句*问「相对默认行为，这句改变了什么吗？」模型默认就会做的事＝空操作，付出负载却什么都没说。果断删整句，而非修剪词语。弱主导词（代理本就 thorough 时还说 *be thorough*）是空操作——换更强的词（*relentless*），而非换技术。
-
-## 失败模式
-
-用于诊断资产问题：
-
-- **过早完成**——步骤真正完成前就收尾，注意力滑向「完成态」。先锐化完成标准（廉价、局部）；只有当它本质模糊*且*确实观察到匆忙时，才用序列拆分隐藏后续步骤（且只在真正的上下文边界——command 交接 / 子代理派发——才有效，内联的引用清不掉后续步骤）。
-- **重复**——同一含义有多个事实来源。涨维护成本与 token，并夸大该含义在阶梯上的权重。是主导词的意外逆操作（主导词有意重复一个 *token* 而非*含义*）。
-- **沉积**——陈旧层因「加安全、删有风险」而堆积，得钻过它们才找到仍有效的内容。无修剪纪律资产的默认命运。
-- **蔓延**——单纯太长（即便每行都鲜活、独特）。解药是信息层级：把参考推到指针后，按分支或序列拆分。
-- **空操作**——见上「修剪」。

package/template/skills/speculo-write/references/command-authoring-sop.md

@@ -1,98 +0,0 @@
-# Command Authoring SOP
-
-## 入口结构
-
-command 是单个 Markdown 文件：
-
-```text
-template/commands/<name>.md
-```
-
-只要需要多阶段状态机、多个子规范或跨天交付，就升级为 workflow。
-
-## Frontmatter
-
-```yaml
----
-id: <name>
-type: command
-name: <人类可读名>
-description: <一句话用途>
-keywords: [<关键词>]
----
-```
-
-frontmatter 只写发现元数据。调用 skill、产物路径和破坏性边界写正文。
-
-## 正文结构
-
-command 正文包含：
-
-- `## 归档路径模式`
-- `## 调用的 skills`
-- `## 执行步骤`
-- `## 产物模板`
-
-产物路径默认：
-
-```text
-speculo/.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/
-```
-
-在 command 文件中写路径时，使用 `speculo/.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`。命令产物禁止写入 `temp/`、系统临时目录、项目根目录或其它非 Speculo 规范位置。
-
-## 调用 Skill
-
-如需复用 skill，用相对路径列出：
-
-```markdown
-- `../skills/<name>/SKILL.md`：<何时读取>
-```
-
-skill 输出如需持久化，归档到 command 产物目录。command 可以把 skill 返回内容写入该目录；若 skill 负责生成文件，command 必须显式提供规范目标路径。禁止 skill 默认写入 `temp/`、系统临时目录或项目根目录。
-
-## 破坏性操作
-
-涉及目录移动、删除、外部 API、发布或归档时，command 必须：
-
-1. 先列影响清单
-2. 明确将修改哪些路径或外部资源
-3. 等待用户确认
-4. 执行后写报告
-
-没有确认时只输出计划，不执行破坏性动作。
-
-## 内联模板
-
-command 产物模板内联在文件末尾。模板占位符使用 `[TODO: ...]`。
-
-适合内联模板的产物：
-
-- status 快照
-- archive 报告
-- handoff 文档
-- 一次性操作报告
-
-不适合 command 的产物：
-
-- 多阶段 PRD
-- TDD log
-- 文档同步状态
-- 跨多轮写作稿件
-
-这些应由 workflow 管理。
-
-## 更新检查
-
-新增 command 后检查：
-
-- 项目若有 `docs/quick-reference.md` 等入口索引，是否需要新增条目
-- README 内置入口列表
-- CLI tests 是否需要断言复制该 command
-- 是否需要新增 command 调用的 skill
-- 归档路径是否位于 `speculo/.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`
-- 被调用 skill 是否没有自选 `temp/`、系统临时目录或项目根目录作为持久化位置
-
-`speculo/.speculo/commands/` 归档路径、frontmatter 最小集与写入责任见 `persistence-contract-sop.md`；`description`、完成准则与修剪的质量杠杆见 `authoring-quality-levers.md`。
-
-涉及 `.config` 清理、删除或合并的命令参考 `template/commands/config-prune.md`：默认 dry-run，执行破坏性操作前必须列清单并等待用户确认。

package/template/skills/speculo-write/references/migration-sop.md

@@ -1,101 +0,0 @@
-# Migration SOP
-
-## 目标
-
-把外部技能、旧 workflow、参考项目资产或临时目录内容，迁移成符合当前 Speculo 规范的 workflow、skill 或 command。
-
-## 读取顺序
-
-1. 读取本 skill 对应资产类型的 `references/`（`workflow-authoring-sop.md` / `skill-authoring-sop.md` / `command-authoring-sop.md` / `persistence-contract-sop.md`），规范已内化，不读仓库 `docs/`。
-2. 读取目标分类或同类资产的入口文件，对齐真实写法。
-3. 读取参考项目或源技能的 README / index，确定源材料边界。
-4. 只读取与本次迁移相关的源文件，不批量导入无关内容。
-
-## 提取原则
-
-保留源材料中的：
-
-- 核心行为
-- 触发条件
-- 输入输出
-- 铁律和边界
-- 失败恢复
-- 有价值的模板和检查表
-
-压缩或删除：
-
-- 来源项目宣传语
-- 安装说明
-- 与 Speculo 无关的目录说明
-- 已被当前规范替代的元数据
-- 重复内容
-
-## 规范化规则
-
-### 路径
-
-把旧路径改成当前 Speculo 路径：
-
-- change 产物：`speculo/.speculo/<cat>/<change>/`
-- command 产物：`speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
-- 项目规则：`speculo/.speculo/.config/RULES.md`
-- 项目经验：`speculo/.speculo/.config/LESSONS.md`
-- 项目上下文：`speculo/.speculo/.config/context/`
-- 项目 ADR：`speculo/.speculo/.config/adr/`
-
-不要创建新的项目根 state 文件，除非当前规范明确允许。
-
-### Frontmatter
-
-把外部 frontmatter 收敛成 Speculo 最小集：
-
-- workflow：`id`、`category`、`name`、`description`、`keywords`
-- skill：`id`、`type: skill`、`name`、`description`
-- command：`id`、`type: command`、`name`、`description`、`keywords`
-
-### 渐进披露
-
-大段背景放入：
-
-- workflow phase 文件
-- workflow `_templates/`
-- skill `references/`
-- command 内联模板
-
-不要把长 reference 塞进入口文件。
-
-## 融合规则
-
-多个源技能融合为一个原子 skill 时：
-
-- 入口 `SKILL.md` 只保留统一触发、输入输出和主流程
-- 源技能细节按主题拆到 `references/`
-- 去掉源技能之间互相引用的旧路径
-- 合并重复铁律，保留更严格者
-- 明确调用方负责持久化
-
-多个源技能融合进 workflow 时：
-
-- 把 workflow-only 方法内置到 workflow 目录
-- 不再作为根 skill 分发
-- 每个源技能能力变成 phase、内置指引或模板
-
-## 索引与测试
-
-迁移完成后同步：
-
-- 分类 `AGENTS.md`
-- `speculo/.speculo/<cat>-status.json` 初始骨架
-- `speculo/.speculo/archive/<cat>/.gitkeep`
-- 项目若有 docs quick reference / architecture / adopting 等索引，按需更新
-- CLI tests 的 asset copying 断言
-
-## 残留扫描
-
-按源项目情况扫描旧绑定，例如：
-
-```bash
-rg "\.specforge|\.docs-sync-state|docs/adr/|根目录.*CONTEXT" speculo docs
-```
-
-扫描命令应随迁移来源调整，目标是确认旧规范没有回流。