@namewta/speculo 0.1.0

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

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

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

@@ -0,0 +1,101 @@
+# 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/<cat>/<change>/`
+- command 产物：`.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
+- 项目规则：`.speculo/.config/RULES.md`
+- 项目经验：`.speculo/.config/LESSONS.md`
+- 项目上下文：`.speculo/.config/context/`
+- 项目 ADR：`.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、内置指引或模板
+
+## 索引与测试
+
+迁移完成后同步：
+
+- 分类 `00-INDEX.md`
+- `.speculo/<cat>-status.json` 初始骨架
+- `.speculo/archive/<cat>/.gitkeep`
+- 项目若有 docs quick reference / architecture / adopting 等索引，按需更新
+- CLI tests 的 asset copying 断言
+
+## 残留扫描
+
+按源项目情况扫描旧绑定，例如：
+
+```bash
+rg "\.specforge|\.docs-sync-state|docs/adr/|根目录.*CONTEXT" speculo docs
+```
+
+扫描命令应随迁移来源调整，目标是确认旧规范没有回流。

package/speculo/skills/speculo-write/references/persistence-contract-sop.md

@@ -0,0 +1,123 @@
+# Persistence Contract SOP
+
+`.status.json` schema、目录命名、frontmatter 最小集与写入责任的内化规范。
+本文把 Speculo 持久化契约内化进本 skill，编写资产时**不读仓库 `docs/`**。
+
+## 目录命名
+
+| 类别 | 模式 | 例 |
+|------|------|---|
+| Change 目录 | `YYYY-MM-DD-<kebab-name>` | `2026-05-28-user-auth` |
+| Command 产物目录 | `YYYY-MM-DD-<cmd-name>-<topic>` | `2026-05-28-debug-login-500` |
+| 归档目录 | `archive/<cat>/<YYYY-MM>/<change-name>/` | `archive/dev/2026-05/2026-05-20-payment-flow/` |
+
+`<cat>` 只能是 `dev`、`doc`、`ops`。
+
+## `.status.json` 元字段（框架强制）
+
+每个 change 的状态写在 `.speculo/<cat>/<change>/.status.json`：
+
+```jsonc
+{
+  "name":           "string, change 目录名",
+  "category":       "string, dev | doc | ops",
+  "change_status":  "string, active | completed | archived",
+  "execution_mode": "string, 由 workflow 自治声明的命名预设",
+  "created_at":     "string, ISO 8601",
+  "updated_at":     "string, ISO 8601",
+  "current_phase":  "string, 当前 phase id",
+  "phase_history": [
+    {
+      "phase":        "string, phase id",
+      "entered_at":   "string, ISO 8601",
+      "completed_at": "string|null, ISO 8601",
+      "status":       "string, pending | in-progress | completed | skipped | revisited"
+    }
+  ]
+}
+```
+
+workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行者写入**同一份** `.status.json`，不另开文件。
+
+## 顶层索引 schema（薄）
+
+```jsonc
+// .speculo/<cat>-status.json
+{
+  "active": [
+    { "name": "string", "current_phase": "string", "updated_at": "string, ISO 8601" }
+  ]
+}
+```
+
+- 归档后变更**必须从 active 段移除**。
+- 索引可重建：扫 `.speculo/<cat>/*/.status.json` 即可重建。
+- 全局 `STATUS.json` **不物理存在**。
+
+## Frontmatter 最小集
+
+Frontmatter **仅承载发现元数据**（这是什么、叫什么、关于什么）。phases / 模板 / 依赖 / 调用 skill / 状态扩展字段 / 入口协议一律写进 Markdown 正文，用相对路径链接与小标题做渐进披露。
+
+```yaml
+# workflow
+id: <category>/<name>   # 必填，全局唯一
+category: dev|doc|ops   # 必填
+name: <人类可读名>       # 必填
+description: <一句话>    # 必填
+keywords: [...]         # 可选
+
+# command
+id: <name>              # 必填，唯一
+type: command           # 必填，固定值
+name: <人类可读名>       # 必填
+description: <一句话>    # 必填
+keywords: [...]         # 可选
+
+# skill
+id: <name>              # 必填，唯一
+type: skill             # 必填，固定值
+name: <人类可读名>       # 必填
+description: <一句话>    # 必填
+```
+
+## Template 不需要 Frontmatter
+
+模板顶部用一段引用说明声明归属，占位符一律 `[TODO: ...]`：
+
+```markdown
+> **服务工作流：** `<相对路径>`
+> **产物文件名：** `<filename>`
+
+# <标题>
+
+## <章节>
+[TODO: 具体填写指引]
+```
+
+## 相对路径强约束
+
+正文引用的 skill / template / 其它 workflow / phase 子文档**必须用相对路径**，禁止裸 id 或绝对路径。
+
+## 写入责任
+
+| 文件 | 用户可写 | AI 可写 |
+|------|---------|---------|
+| `.speculo/.config/RULES.md` | ✅ | ❌ |
+| `.speculo/.config/LESSONS.md` | ⚠️ 可追加 | ✅ workflow 末尾追加 |
+| `.speculo/.config/context/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
+| `.speculo/.config/adr/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
+| `.speculo/<cat>/<change>/*.md` | ⚠️ | ✅ |
+| `.speculo/<cat>/<change>/.status.json` | ❌ | ✅ |
+| `.speculo/*-status.json` | ❌ | ✅ |
+
+**skill 不在此表**：skill 不直接写任何 `.speculo/` 或 `.status.json`，持久化由调用它的 workflow 或 command 负责。
+
+## 新分类骨架
+
+新增 `<cat>` 分类时初始化：
+
+- `.speculo/<cat>-status.json`（`{ "active": [] }`）
+- `.speculo/<cat>/.gitkeep`
+- `.speculo/archive/<cat>/.gitkeep`
+
+项目级长期资料放 `.speculo/.config/`（`RULES.md`、`LESSONS.md`、`context/`、`adr/`），不要新增项目根 state 文件。

package/speculo/skills/speculo-write/references/skill-authoring-sop.md

@@ -0,0 +1,195 @@
+# Skill Authoring SOP
+
+本文是 Speculo 原子 skill 的编写规范，复刻通用「编写技能」流程并收敛到 Speculo 约束。
+本文已内化全部所需规范；编写 skill 时**不读仓库 `docs/`**，只读本 skill 的 `references/`。
+
+## 流程
+
+1. **收集需求** —— 向用户确认：
+   - 这个 skill 覆盖什么任务 / 领域？
+   - 应该处理哪些具体用例？
+   - 这是可复用的原子能力，还是该升级为 workflow、退化为 command？判定见 `asset-selection-sop.md`。
+   - 需要可执行脚本，还是只需要指令？
+   - 有没有外部源技能要迁移？迁移规则见 `migration-sop.md`。
+
+2. **起草 skill** —— 创建：
+   - `SKILL.md`，含 Speculo frontmatter 与五个固定章节。
+   - `SKILL.md` 接近 500 行时，把细节拆进 `references/`。
+   - 需要确定性操作时，加 `scripts/`。
+
+3. **与用户审查** —— 展示草稿并问：
+   - 覆盖你的用例了吗？
+   - 有遗漏或不清楚的地方吗？
+   - 哪些章节该更详细 / 更简洁？
+
+## 入口结构
+
+skill 放在：
+
+```text
+speculo/skills/<name>/SKILL.md
+```
+
+目录名用 lowercase kebab-case。整个 skill 目录必须**自包含**：复制到任何项目、只读 `SKILL.md` 即可判断是否使用、需要哪些输入、产生什么输出，不依赖本仓库的 `docs/` 或任何外部文件。
+
+```text
+<name>/
+├── SKILL.md              # 主指令（必需）
+├── references/           # 详细规范 / 变体（按需）
+│   └── <task>-sop.md
+├── scripts/              # 确定性工具脚本（按需）
+└── examples/             # 示例输入输出（按需）
+```
+
+## Frontmatter
+
+```yaml
+---
+id: <name>
+type: skill
+name: <人类可读名>
+description: <一句话能力说明；含触发场景，第三人称，可与相近 skill 区分>
+---
+```
+
+description 是 **agent 决定加载哪个 skill 时唯一能看到的内容**，会和其它已装 skill 一起出现在系统提示里。给 agent 刚好够用的信息：(1) 提供什么能力，(2) 何时 / 为何触发（具体关键词、上下文、文件类型）。
+
+格式：
+
+- 最多 1024 字符
+- 第三人称
+- 第一句：做什么
+- 第二句：「当 [具体触发条件] 时使用」
+
+**好的例子**：
+
+```
+创建或改造 Speculo workflows、skills、commands 的原子能力；当用户要求迁移外部技能或新增 workflow / skill / command 时使用。
+```
+
+**坏例子**：
+
+```
+帮助处理技能。
+```
+
+坏例子让 agent 无法把这个 skill 和其它 authoring 类 skill 区分开。
+
+## 正文结构
+
+`SKILL.md` 保持精简，五个固定章节：
+
+- `## 何时使用`
+- `## 输入`
+- `## 输出`
+- `## 执行步骤`
+- `## 渐进披露`
+
+模板：
+
+```markdown
+---
+id: <name>
+type: skill
+name: <人类可读名>
+description: <能力 + 触发场景，第三人称>
+---
+
+# <技能名>
+
+## 何时使用
+
+[触发场景；列几条典型用户请求]
+
+## 输入
+
+[需要的输入。本 skill 自带规范，不外读 docs/]
+
+## 输出
+
+[产生什么产物 / 决策 / 检查清单]
+
+## 执行步骤
+
+1. [最小可工作主流程]
+2. ...
+
+## 渐进披露
+
+- `references/<task>-sop.md`：<何时读取>
+```
+
+## 渐进披露
+
+所有 reference 都从 `SKILL.md` 直接引用，**单层**，不做多层隐藏。
+
+拆分 reference 的条件：
+
+- `SKILL.md` 接近 500 行
+- 内容覆盖多个主题或变体（例如不同资产类型的写法）
+- 细节只在特定场景才需要
+- 源材料较长，但可以按需读取
+
+reference 文件用 kebab-case，**按任务而非来源**命名（`workflow-authoring-sop.md`，不是 `from-specforge.md`）。
+
+## 何时添加脚本
+
+**加 `scripts/`**，当操作确定且反复执行：
+
+- frontmatter 校验
+- 路径残留扫描
+- 模板命名检查
+- JSON schema 检查
+
+脚本比反复生成代码更省 token、更可靠，且失败可以显式处理。
+
+**不加 `scripts/`**，当能力主要是判断 / 设计 / 策略 / 协作：
+
+- 规范判断
+- 文档结构设计
+- 迁移和融合策略
+- 人机协作 SOP
+
+## 迁移外部 Skill
+
+迁移时**保留**：
+
+- 触发场景
+- 关键输入输出
+- 铁律、边界、失败处理
+- 可复用命令、检查表、模板片段
+
+迁移时**改写**：
+
+- 外部工具名绑定
+- 旧目录布局
+- 旧 state 路径
+- 不符合 Speculo frontmatter 的元数据
+- 直接写 `.speculo/` 的行为描述
+
+多个源技能融合为一个原子 skill 时：入口 `SKILL.md` 只留统一触发与主流程，源技能细节按主题拆进 `references/`，合并重复铁律并保留更严格者。
+
+## 持久化边界
+
+skill **禁止**直接写：
+
+- `.speculo/<cat>/<change>/`
+- `.speculo/*-status.json`
+- `.status.json`
+
+如果某能力需要持久化，把写入责任交给调用它的 workflow 或 command，并在 skill 输出里提供可归档摘要。完整写入责任表见 `persistence-contract-sop.md`。
+
+## 审查清单
+
+起草后检查：
+
+- [ ] description 含触发条件（「当……时使用」），可与相近 skill 区分
+- [ ] frontmatter 是 Speculo 最小集（`id` / `type: skill` / `name` / `description`）
+- [ ] `SKILL.md` 含五个固定章节，整体精简（细节已外移）
+- [ ] reference 单层引用，按任务命名
+- [ ] **自包含**：不引用 `docs/` 或仓库外文件
+- [ ] skill 不直接写 `.speculo/` 或 `.status.json`，持久化交给调用方
+- [ ] 没有 README / INSTALLATION / CHANGELOG 等冗余文件
+- [ ] 没有时效性信息、旧项目路径、旧工具名或绝对路径绑定
+- [ ] 术语一致、含具体示例、引用只有一层深度
+- [ ] 若是内置资产，CLI tests 覆盖复制该 skill

package/speculo/skills/speculo-write/references/validation-checklist.md

@@ -0,0 +1,73 @@
+# Validation Checklist
+
+## 结构检查
+
+- [ ] 新 asset 路径符合 `speculo/workflows/`、`speculo/skills/` 或 `speculo/commands/` 约定
+- [ ] workflow 入口文件名与目录名一致
+- [ ] skill 入口命名为 `SKILL.md`
+- [ ] command 是单个 `.md` 文件
+- [ ] reference 文件都被入口直接引用
+- [ ] 没有 README、INSTALLATION、CHANGELOG 等冗余 skill 文件
+
+## Frontmatter 检查
+
+- [ ] workflow frontmatter 只包含发现元数据
+- [ ] skill frontmatter 包含 `id`、`type: skill`、`name`、`description`
+- [ ] command frontmatter 包含 `id`、`type: command`、`name`、`description`，可选 `keywords`
+- [ ] 没有把 phases、templates、depends_on、status_extensions 写进 frontmatter
+
+## Workflow 检查
+
+- [ ] 入口正文包含 `## 阶段`
+- [ ] 入口正文包含 `## 依赖`
+- [ ] 入口正文包含 `## 状态扩展字段`
+- [ ] 入口正文包含 `## 完成与状态更新`
+- [ ] 每个 phase 文件写清输入、产物、填写引导、边界、完成准则
+- [ ] 模板放在对应分类 `_templates/`
+- [ ] 模板顶部有服务 workflow 和产物文件名
+- [ ] 模板占位符为 `[TODO: ...]`
+
+## Skill 检查
+
+- [ ] `SKILL.md` 能让 agent 判断何时触发
+- [ ] 输入、输出、执行步骤清晰
+- [ ] 大段细节放入 `references/`
+- [ ] 自包含：不引用 `docs/` 或仓库外文件，复制后只读 `SKILL.md` 即可用
+- [ ] skill 不直接写 `.speculo/` 或 `.status.json`
+- [ ] 如果需要持久化，明确由调用方 workflow 或 command 负责
+
+## Command 检查
+
+- [ ] 归档路径位于 `.speculo/commands/`
+- [ ] 调用 skill 使用相对路径
+- [ ] 破坏性操作要求用户确认
+- [ ] 产物模板内联且使用 `[TODO: ...]`
+
+## `.speculo/` 检查
+
+- [ ] 新分类有 `.speculo/<cat>-status.json`
+- [ ] 新分类有 `.speculo/<cat>/.gitkeep`
+- [ ] 新分类有 `.speculo/archive/<cat>/.gitkeep`
+- [ ] 项目级长期上下文写入 `.speculo/.config/context/`
+- [ ] 项目级 ADR 写入 `.speculo/.config/adr/`
+- [ ] 没有新增项目根 state 文件
+
+## 文档与测试
+
+> 以下索引文件是 Speculo 仓库内的下游同步目标；项目无这些文件时跳过对应项。
+
+- [ ] 项目若有 `docs/quick-reference.md`，包含新入口
+- [ ] 项目若有 `docs/Speculo-architecture.md`，需要时更新内置结构
+- [ ] 项目若有 `docs/adopting.md`，需要时更新安装后目录
+- [ ] CLI tests 断言 `speculo init` 会复制新内置资产
+- [ ] `pnpm test` 通过
+
+## 残留检查
+
+按迁移来源选择关键词扫描：
+
+```bash
+rg "\.specforge|\.docs-sync-state|docs/adr/|根目录.*CONTEXT" speculo docs
+```
+
+命中结果必须逐条判断：历史说明可保留，执行规范和路径约定不能保留旧值。