@namewta/speculo 0.1.21 → 0.2.0

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

@@ -1,165 +0,0 @@
-# Workflow Authoring SOP
-
-phase 的切分、完成准则与措辞遵循 `authoring-quality-levers.md` 的质量杠杆（**按序列拆分**隐藏后续步骤防过早完成、**完成标准**可检验且穷尽、**主导词**锚定调用与执行）；本文只补 workflow 特有的结构与路径约束。
-
-## 入口结构
-
-workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`person`。`ops` 是预留分类，只有 `.speculo` 骨架和 workflow 分类同时落地后才能启用。
-
-目录和入口文件必须同名：
-
-```text
-template/workflows/<cat>/<entry>/<entry>.md
-```
-
-主线 workflow 使用数字前缀，如 `01-grill-with-docs`。横向 workflow 使用字母前缀，如 `H-diagnose`、`R-review`、`D-docs-sync`。
-
-## Frontmatter
-
-入口 frontmatter 只承载发现元数据：
-
-```yaml
----
-id: <cat>/<name>
-category: <cat>
-name: <人类可读名>
-description: <一句话用途>
-keywords: [<关键词>]
----
-```
-
-禁止把 phases、模板、依赖、状态字段写进 frontmatter。
-
-## 正文必备章节
-
-入口正文必须包含：
-
-- `## 阶段`
-- `## 依赖`
-- `## 状态扩展字段`
-- `## 完成与状态更新`
-
-阶段条目必须写清：
-
-- 稳定 phase id（kebab-case，用于 `current_phase`）
-- 规范 phase 文件
-- 模板路径
-- 产物文件名
-- 完成准则
-- 可选 agent 文件（若该 phase 支持隔离执行）
-
-## Phase 文件
-
-phase 文件不需要 frontmatter。每个 phase 文件写清：
-
-- 输入
-- 产物
-- 填写引导
-- 边界
-- 完成准则
-
-phase 文件只放该阶段执行所需内容，不重复入口文件的全局说明。
-
-## Workflow Agents
-
-适合隔离执行、并行审查或反自证验证的 phase 可以创建：
-
-```text
-template/workflows/<cat>/<entry>/agents/<name>-agent.md
-```
-
-Agent 文件需要 frontmatter：
-
-```yaml
----
-id: <cat>/<entry>/<agent-name>
-type: agent
-name: <人类可读名>
-description: <一句话说明该 agent 何时用于隔离执行>
----
-```
-
-正文必须包含：
-
-- `## 使命`
-- `## 输入契约`
-- `## 执行规范`
-- `## 产物与状态`
-- `## 边界`
-
-Agent 引用同目录 phase 文件、模板和 skill，不复制大段规范正文。Agent 只可写它声明的 phase 产物和 `.status.json` 扩展字段，不写 `change_status`。入口 `## 阶段` 必须列出对应 agent 相对路径。
-
-## 模板
-
-模板放在：
-
-```text
-template/workflows/<cat>/_templates/
-```
-
-命名：
-
-```text
-<name>-<artifact>-template.md
-```
-
-模板不写 frontmatter，顶部用归属说明：
-
-```markdown
-> **服务工作流：** `../<entry>/<entry>.md`
-> **产物文件名：** `<artifact>.md`
-```
-
-模板占位符必须使用 `[TODO: ...]`。
-
-## 持久化路径
-
-workflow 产物写入：
-
-```text
-speculo/.speculo/<cat>/<change>/
-```
-
-当前 change 的状态写入：
-
-```text
-speculo/.speculo/<cat>/<change>/.status.json
-```
-
-顶层 active 索引写入：
-
-```text
-speculo/.speculo/<cat>-status.json
-```
-
-项目级规则、经验、上下文和 ADR 使用：
-
-```text
-speculo/.speculo/.config/RULES.md
-speculo/.speculo/.config/LESSONS.md
-speculo/.speculo/.config/context/
-speculo/.speculo/.config/adr/
-```
-
-不要把新状态放到项目根目录。`.status.json` 元字段、顶层索引 schema 和写入责任表见 `persistence-contract-sop.md`。
-
-`current_phase` 使用入口 `## 阶段` 声明的稳定 phase id；首个 workflow 进入 change 时写入 `execution_mode`。只有收尾 workflow 或 `archive` 命令可写 `change_status: completed | archived`，普通 workflow 只写自治状态字段。
-
-## 索引与文档同步
-
-新增 workflow 后检查：
-
-- 对应分类的 `AGENTS.md` 是否需要新增别名
-- `speculo/.speculo/<cat>-status.json` 和 `speculo/.speculo/<cat>/.gitkeep` 是否存在
-- `speculo/.speculo/archive/<cat>/.gitkeep` 是否存在
-- 项目若有 `docs/quick-reference.md` 等入口索引，是否需要新增条目
-- CLI tests 是否需要断言复制新入口
-
-## 完成线
-
-- 入口 frontmatter 合规
-- 正文必备章节齐全
-- 所有跨文件引用使用相对路径
-- 非模板文件不残留无说明 TODO
-- 模板只保留 `[TODO: ...]` 占位符
-- `pnpm test` 通过或记录无法运行原因

package/template/vendor/codebase-design/DEEPENING.md

@@ -1,37 +0,0 @@
-# 深化（Deepening）
-
-如何在给定依赖关系的情况下，安全地深化一组浅模块。假定使用 [SKILL.md](SKILL.md) 中的术语——**module（模块）**、**interface（接口）**、**seam（接缝）**、**adapter（适配器）**。
-
-## 依赖分类
-
-在评估深化候选时，对其依赖进行分类。分类决定了深化后的模块如何跨接缝进行测试。
-
-### 1. 进程内（In-process）
-
-纯计算、内存状态、无 I/O。始终可深化——合并模块，直接通过新接口进行测试。不需要适配器。
-
-### 2. 本地可替换（Local-substitutable）
-
-具有本地测试替代方案的依赖（Postgres 用 PGLite、内存文件系统）。如果存在替代方案则可深化。深化后的模块在测试套件中运行替代方案进行测试。接缝是内部的；模块外部接口处没有端口。
-
-### 3. 远程但自有（Remote but owned）（端口与适配器）
-
-跨网络边界的自有服务（微服务、内部 API）。在接缝处定义一个**端口（port）**（接口）。深度模块拥有逻辑；传输层作为**适配器（adapter）**注入。测试使用内存适配器。生产环境使用 HTTP/gRPC/队列适配器。
-
-推荐形式：*"在接缝处定义一个端口，为生产环境实现 HTTP 适配器，为测试实现内存适配器，这样即使逻辑部署跨网络，仍位于一个深度模块中。"*
-
-### 4. 真正外部（True external）（Mock）
-
-你无法控制的第三方服务（Stripe、Twilio 等）。深化后的模块将外部依赖作为注入端口接收；测试提供 mock 适配器。
-
-## 接缝纪律
-
-- **一个适配器意味着假设的接缝。两个适配器才意味着真正的接缝。** 除非至少有两个适配器是合理的（通常是生产 + 测试），否则不要引入端口。单适配器接缝只是间接层。
-- **内部接缝 vs 外部接缝。** 深度模块可以有内部接缝（对其实现私有，由其自身测试使用）以及其接口处的外部接缝。不要因为测试使用了内部接缝就通过接口暴露它们。
-
-## 测试策略：替换，而非叠加
-
-- 一旦深化模块接口层面的测试存在，浅模块的旧单元测试就成为废料——删除它们。
-- 在深化模块的接口层面编写新测试。**接口就是测试面**。
-- 测试通过接口断言可观察的结果，而非内部状态。
-- 测试应能经受内部重构——它们描述的是行为，而非实现。如果一个测试在实现变更时必须随之改变，那它就是在测试接口背后的内容。

package/template/vendor/codebase-design/DESIGN-IT-TWICE.md

@@ -1,44 +0,0 @@
-# 设计两次（Design It Twice）
-
-当用户想要为选定的深化候选探索替代接口时，使用此并行子代理模式。基于"设计两次"（Ousterhout）——你的第一个想法不太可能是最好的。
-
-使用 [SKILL.md](SKILL.md) 中的术语——**module（模块）**、**interface（接口）**、**seam（接缝）**、**adapter（适配器）**、**leverage（杠杆）**。
-
-## 流程
-
-### 1. 界定问题空间
-
-在生成子代理之前，为选定候选编写面向用户的问题空间说明：
-
-- 任何新接口需要满足的约束
-- 它将依赖的依赖项，以及它们属于哪个类别（参见 [DEEPENING.md](DEEPENING.md)）
-- 一个粗略的说明性代码草图，用于将约束具体化——不是提案，只是将约束变得具体的方式
-
-将此展示给用户，然后立即进入第 2 步。用户在子代理并行工作时阅读和思考。
-
-### 2. 生成子代理
-
-使用 Agent 工具并行生成 3 个以上的子代理。每个子代理必须为深化后的模块生成一个**截然不同**的接口。
-
-为每个子代理提供一个单独的技术概要（文件路径、耦合细节、来自 [DEEPENING.md](DEEPENING.md) 的依赖类别、接缝背后的内容）。该概要独立于第 1 步中面向用户的问题空间说明。给每个代理不同的设计约束：
-
-- 代理 1："最小化接口——目标是最多 1–3 个入口点。最大化每个入口点的杠杆效应。"
-- 代理 2："最大化灵活性——支持多种用例和扩展。"
-- 代理 3："针对最常见调用方优化——让默认情况变得简单。"
-- 代理 4（如适用）："围绕端口与适配器设计跨接缝依赖。"
-
-在概要中同时包含 [SKILL.md](SKILL.md) 词汇和 CONTEXT.md 词汇，以便每个子代理在命名时与架构语言和项目的领域语言保持一致。
-
-每个子代理输出：
-
-1. 接口（类型、方法、参数——加上不变量、排序、错误模式）
-2. 使用示例，展示调用方如何使用
-3. 实现隐藏在接缝背后的内容
-4. 依赖策略和适配器（参见 [DEEPENING.md](DEEPENING.md)）
-5. 权衡——杠杆效应高的地方，薄弱的地方
-
-### 3. 展示与比较
-
-依次展示设计，以便用户逐一消化，然后用文字进行比较。通过**深度**（接口层面的杠杆效应）、**局部性**（变更集中的位置）和**接缝位置**进行对比。
-
-比较后，给出你自己的推荐：你认为哪个设计最强以及为什么。如果来自不同设计的元素可以很好地组合，提出一个混合方案。要有明确的观点——用户想要的是一个强有力的解读，而不是一份菜单。

package/template/vendor/codebase-design/SKILL.md

@@ -1,114 +0,0 @@
----
-name: codebase-design
-description: 设计深层模块的共享词汇。适用于用户想要设计或改进模块接口、寻找深化机会、决定接缝位置、使代码更可测试或对 AI 更可导航，或其他技能需要深层模块词汇的场景。
----
-
-# 代码库设计
-
-设计**深层模块**：大量行为隐藏在小型接口之后，放置在清晰的接缝处，通过该接口可测试。在任何设计或重构代码的地方使用这套语言和原则。目标是为调用者提供杠杆，为维护者提供局部性，为所有人提供可测试性。
-
-## 词汇表
-
-严格使用这些术语——不要替换为"组件"、"服务"、"API"或"边界"。一致的语言是全部要点。
-
-**模块**——任何有接口和实现的东西。刻意与规模无关：一个函数、类、包或跨层切片。*避免*：单元、组件、服务。
-
-**接口**——调用者正确使用模块必须知道的一切：类型签名，还有不变量、排序约束、错误模式、所需配置和性能特征。*避免*：API、签名（太窄——它们仅指向类型层面的表面）。
-
-**实现**——模块内部的内容，其代码体。区别于**适配器**：一个东西可以是一个小适配器带大实现（一个 Postgres 仓库）或一个大适配器带小实现（一个内存假对象）。当接缝是主题时用"适配器"；否则用"实现"。
-
-**深度**——接口处的杠杆：调用者（或测试）每学习单位接口能运用的行为量。一个模块是**深的**，当大量行为隐藏在小型接口之后；是**浅的**，当接口几乎和实现一样复杂。
-
-**接缝** *(Michael Feathers)*——一个可以在不编辑该处的情况下改变行为的地方；模块接口所在的*位置*。接缝放在哪里是其自身的设计决策，区别于接缝后面是什么。*避免*：边界（被 DDD 的有界上下文过载）。
-
-**适配器**——在接缝处满足接口的具体事物。描述*角色*（它填补哪个槽位），而非实质（里面是什么）。
-
-**杠杆**——调用者从深度中获得的东西：每学习单位接口获得更多能力。一个实现付出，在 N 个调用点和 M 个测试中获得回报。
-
-**局部性**——维护者从深度中获得的东西：变更、bug、知识和验证集中在一处，而不是分散在调用者中。一处修复，处处修复。
-
-## 深 vs 浅
-
-**深层模块** = 小接口 + 大量实现：
-
-```
-┌─────────────────────┐
-│   小型接口          │  ← 少数方法，简单参数
-├─────────────────────┤
-│                     │
-│   深层实现          │  ← 复杂逻辑隐藏
-│                     │
-└─────────────────────┘
-```
-
-**浅层模块** = 大接口 + 少量实现（应避免）：
-
-```
-┌─────────────────────────────────┐
-│       大型接口                  │  ← 许多方法，复杂参数
-├─────────────────────────────────┤
-│  薄实现                         │  ← 只是传递
-└─────────────────────────────────┘
-```
-
-设计接口时，问：
-
-- 我能减少方法数量吗？
-- 我能简化参数吗？
-- 我能隐藏更多复杂性在内部吗？
-
-## 原则
-
-- **深度是接口的属性，而非实现的属性。** 一个深层模块可以在内部由小型、可 mock、可替换的部件组成——它们只是不是接口的一部分。一个模块可以有**内部接缝**（对其实现私有，由其自己的测试使用）以及其接口处的**外部接缝**。
-- **删除测试。** 想象删除该模块。如果复杂性消失，它就是个传递。如果复杂性在 N 个调用者中重新出现，它就在赚取它的价值。
-- **接口就是测试表面。** 调用者和测试跨越同一接缝。如果你想测试到接口*之外*，模块的形状可能不对。
-- **一个适配器意味着假设的接缝。两个适配器意味着真实的接缝。** 除非某物确实在接缝处变化，否则不要引入接缝。
-
-## 为可测试性设计
-
-好的接口使测试变得自然：
-
-1. **接受依赖，而非创建依赖。**
-
-   ```typescript
-   // 可测试
-   function processOrder(order, paymentGateway) {}
-
-   // 难以测试
-   function processOrder(order) {
-     const gateway = new StripeGateway();
-   }
-   ```
-
-2. **返回结果，而非产生副作用。**
-
-   ```typescript
-   // 可测试
-   function calculateDiscount(cart): Discount {}
-
-   // 难以测试
-   function applyDiscount(cart): void {
-     cart.total -= discount;
-   }
-   ```
-
-3. **小表面积。** 更少的方法 = 需要更少的测试。更少的参数 = 更简单的测试设置。
-
-## 关系
-
-- 一个**模块**有且仅有一个**接口**（它呈现给调用者和测试的表面）。
-- **深度**是**模块**的属性，对照其**接口**来衡量。
-- **接缝**是模块**接口**所在之处。
-- **适配器**位于**接缝**处并满足**接口**。
-- **深度**为调用者产生**杠杆**，为维护者产生**局部性**。
-
-## 拒绝的框架
-
-- **深度为实现行数与接口行数之比**（Ousterhout）：奖励填充实现。我们改用深度作为杠杆。
-- **"接口"作为 TypeScript `interface` 关键字或类的公共方法**：太窄——这里的接口包括调用者必须知道的每个事实。
-- **"边界"**：被 DDD 的有界上下文过载。说**接缝**或**接口**。
-
-## 深入探索
-
-- **给定依赖深化一个集群**——参见 [DEEPENING.md](DEEPENING.md)：依赖类别、接缝规范和替换而非分层的测试。
-- **探索替代接口**——参见 [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)：启动并行子代理以几种截然不同的方式设计接口，然后比较深度、局部性和接缝位置。