@specpow/framework 0.5.10 → 0.5.11

package/.specpow/skills/planning-apply-change/SKILL.md

@@ -1,194 +0,0 @@
----
-name: planning-apply-change
-description: 执行变更实现。融合 OpenSpec apply + Superpowers SDD 引擎。这是最关键的融合点 — 用 SDD 子代理驱动方式执行 OpenSpec 定义的任务。
----
-
-# 应用变更 (Apply Change)
-
-使用 SDD (子代理驱动开发) 引擎执行 OpenSpec 变更中的任务。
-
-**这是 SpecPow 的核心融合点：**
-- OpenSpec 提供任务定义和规范约束
-- Superpowers SDD 提供高质量的执行引擎
-
-## 输入
-
-可选指定变更名称（如 `/apply-change add-auth`）。如果省略，从对话上下文推断或提示选择。
-
-## 流程
-
-### 1. 选择变更
-
-如果提供了名称，使用它。否则：
-- 从对话上下文推断
-- 如果只有一个活跃变更，自动选择
-- 如果有歧义，运行 `specpow list --json` 让用户选择
-
-总是宣布："使用变更: <name>"
-
-### 2. 检查状态并理解 Schema
-
-```bash
-specpow status --change <name> --json
-```
-
-理解：
-- `schemaName`: 使用的工作流
-- `changeRoot`: 变更目录
-- 哪个工件包含任务（通常是 "tasks"）
-
-### 3. 获取应用指令
-
-```bash
-specpow instructions apply --change <name> --json
-```
-
-返回：
-- `contextFiles`: 工件 ID 或文件路径数组
-- 进度（总数、完成、剩余）
-- 任务列表及状态
-- `context`: 项目约束（必须考虑但不复制到文件）
-
-### 4. 读取上下文文件
-读取 `contextFiles` 中列出的所有文件：
-- proposal.md — 理解为什么做
-- specs/ — 理解行为契约（审查时会验证）
-- design.md — 理解技术方案
-- tasks.md — 理解要做什么
-
-### 5. 初始化 SDD 引擎
-
-```
-使用 SDD 引擎执行计划。
-[设置: 工作区已验证]
-[读取计划文件: tasks.md]
-[创建工作区 .specpow/sdd/<plan-name>/]
-[初始化账本]
-[为所有任务创建 todo]
-```
-
-### 6. 执行任务循环（SDD 驱动）
-对每个待处理任务：
-
-#### a. 提取任务简报
-```bash
-# 提取任务的完整文本到独立文件
-scripts/task-brief tasks.md <N>
-```
-
-#### b. 分发实现者子代理
-
-构建分发 prompt，包含：
-1. 一行项目背景
-2. 简报路径（"先读这个 — 它是你的需求"）
-3. 来自前置任务的接口信息
-4. OpenSpec 规范约束（从 specs/ 中提取）
-5. 报告文件路径
-
-**关键：不粘贴历史任务的累积摘要。每个子代理只需要自己的任务简报。**
-
-#### c. 实现者执行
-实现者子代理：
-1. 读取简报
-2. 实现代码
-3. 编写测试（TDD）
-4. 提交
-5. 自审
-6. 写入报告文件
-
-#### d. 生成审查包并分发审查者
-```bash
-# 生成审查包（diff 文件）
-scripts/review-package PLAN_FILE BASE HEAD
-```
-
-分发任务审查子代理，提供：
-- 简报路径
-- 报告路径
-- 审查包路径
-- OpenSpec 规范约束（用于验证合规性）
-
-#### e. 处理审查结果
-
-- **通过**: 记录到账本，继续下一任务
-- **不通过**: 进入修复循环
-
-#### f. 修复循环（最多 5 轮）
-
-- **Rounds 1-3**: 恢复原始实现者
-- **Rounds 4-5**: 分发全新实现者，使用更强模型
-
-每轮：
-1. 实现者修复
-2. 重新运行测试
-3. 范围限定的重新审查
-4. 记录到账本
-
-#### g. 断路器（5 轮后）
-如果仍有开放发现：
-- 审查者误报 → 停放（代码保留）
-- 真实但无下游依赖 → 停放（延迟修复）
-- 真实且承载依赖 → STOP，报告 BLOCKED
-
-### 7. 最终审查
-所有任务完成后：
-```bash
-scripts/review-package PLAN_FILE MERGE_BASE HEAD
-```
-
-分发最终审查（使用最强模型），审查整个分支。
-
-### 8. 完成
-
-- 更新 tasks.md 中的任务状态（YAML 格式：`status: done`；Checkbox 格式：`- [x]`）
-- 删除 SDD 工作区
-- 提示使用 `finish-branch` 技能
-
-## 输出格式
-
-```
-## 实现 <change-name> (schema: <schema-name>)
-
-正在处理任务 3/7: <任务描述>
-[...实现中...]
-✓ 任务完成
-
-正在处理任务 4/7: <任务描述>
-[...实现中...]
-✓ 任务完成
-```
-
-## 护栏
-
-- 持续推进直到完成或被阻塞
-- 开始前总是读取上下文文件
-- 任务不明确时暂停询问
-- 实现发现问题时暂停建议更新工件
-- 保持代码变更最小化和聚焦
-- 完成后立即更新任务勾选状态
-- 遇到错误或阻塞时暂停 — 不要猜测
-
-## 关键融合点
-
-**OpenSpec 规范约束注入到 SDD 子代理：**
-
-实现者的 prompt 中包含：
-```
-规范约束（来自 specs/<capability>/spec.md）：
-- REQ-001: 系统必须 <行为>
-- REQ-002: 系统必须 <行为>
-
-审查时将验证这些约束是否被满足。
-```
-
-这确保实现不仅代码正确，还符合规范定义的行为契约。
-
-## 合理化防御表
-
-| 借口 | 现实 |
-|------|------|
-| "我可以直接在主会话中实现" | 主会话上下文会被污染。用子代理。 |
-| "审查太慢了" | 没有审查的循环只是未验证的折腾。 |
-| "账本记录是多余的" | 账本是压缩后存活的东西。没有它你会重复已完成的任务。 |
-| "修复很小，跳过重新审查" | 未审查的修复是回归的方式。每轮都以重新审查结束。 |
-| "规范约束不重要" | 规范是行为契约。审查会验证。 |

package/.specpow/skills/planning-archive-change/SKILL.md

@@ -1,53 +0,0 @@
----
-name: planning-archive-change
-description: SpecPow planning-archive-change skill
----
-
-# 归档变更
-
-> 将已完成的变更归档到主规范中
-
-## 触发条件
-
-- 变更所有任务已完成
-- 用户提到"归档"/"archive"
-- 分支合并后
-
-## 铁律
-
-1. **验证先行** — 所有任务必须已完成
-2. **合并规范** — Delta 规范合并到主规范
-3. **保留记录** — 归档文件保留完整工件
-
-## 工作流
-
-### 1. 检查完成度
-```bash
-# 单变更时自动检测
-specpow status
-
-# 多变更时指定名称
-specpow status --change <change-name>
-```
-确认所有任务已完成：
-- YAML Frontmatter 格式：`status: done` 或 `status: completed`
-- Markdown Checkbox 格式：`- [x]`
-
-### 2. 执行归档
-```bash
-# 单变更时自动检测，无需指定名称
-specpow archive
-
-# 多变更时指定名称
-specpow archive --change <change-name>
-```
-
-### 3. 验证归档
-- 确认变更目录已移入 archive/
-- 确认主规范已更新
-- 确认归档报告已生成
-
-## 红旗
-
-- 任务未完成 → 先完成所有任务
-- 验证未通过 → 先通过 verify

package/.specpow/skills/planning-explore/SKILL.md

@@ -1,99 +0,0 @@
----
-name: planning-explore
-description: 苏格拉底式需求探索。在任何编码之前激活。探索上下文、提问、提出方案、但不产生承诺。融合 Superpowers brainstorming + OpenSpec explore。
----
-
-# 需求探索(Explore)
-
-在任何编码之前激活此技能。通过苏格拉底式设计精炼，帮助你和用户就要构建什么达成一致。
-
-## 铁律
-
-```
-没有完成探索就开始编码 = 在错误方向上高速前进。
-```
-
-## 何时使用
-
-- 用户说"让我们构建 X"/"我需要一个 Y"/"帮我做 Z"
-- 任何涉及新功能、修改、修复的请求
-- 你不确定完整范围时
-
-## 流程
-
-### 阶段 1: 探索上下文
-1. 读取相关代码文件、文档、现有规范
-2. 理解当前架构和约束
-3. 识别影响范围
-
-### 阶段 2: 苏格拉底式提问
-逐个提问（不要一次问多个）：
-
-- "这个功能的核心用户场景是什么？"
-- "现有的 X 模块会受到影响吗？"
-- "你期望的数据流是什么样的？"
-- "有没有性能/安全方面的约束？"
-- "这个功能的边界在哪里？什么不做？"
-
-### 阶段 3: 提出方案
-
-提出 2-3 种方案，每种包含：
-- 方案描述
-- 优点
-- 缺点
-- 预估工作量
-
-### 阶段 4: 分段展示设计
-
-将设计分段展示给用户：
-1. 数据模型
-2. 接口设计
-3. 模块划分
-4. 关键实现路径
-
-每段获得用户确认后再继续。
-
-### 阶段 5: 写设计文档
-将确认的设计写入文档：
-```
-.specpow/openspec/changes/<change-name>/exploration.md
-```
-
-### 阶段 6: 自审
-
-检查设计文档：
-- [ ] 是否覆盖了所有用户场景？
-- [ ] 是否与现有架构一致？
-- [ ] 是否有遗漏的边界情况？
-- [ ] 是否明确了非目标？
-
-### 阶段 7: 用户审核
-
-将设计文档展示给用户最终审核。
-
-### 阶段 8: 转入 propose
-
-用户确认后，提示使用 `propose` 技能创建正式的变更提案。
-
-## 视觉伴侣（计划中）
-
-对于复杂或 UI 相关设计，未来将支持启动视觉伴侣服务，在浏览器中展示 HTML mockup 和图表。
-
-> 此功能尚未实现，当前请使用文字描述和 ASCII 图表辅助设计沟通。
-
-## 合理化防御表
-
-| 借口 | 现实 |
-|------|------|
-| "这个很简单，不需要探索" | 简单的事经常隐藏复杂性。探索它。 |
-| "用户已经说得很清楚了" | 用户说的和他们想要的经常不同。提问验证。 |
-| "我可以直接开始编码" | 编码是最后一步，不是第一步。 |
-| "探索太慢了" | 返工更慢。 |
-| "我知道该怎么做" | 知道 ≠ 验证过。走流程。 |
-
-## 红旗
-
-如果你有以下想法，STOP：
-- "我应该直接开始写代码" → 还没探索
-- "这个需求很清楚" → 你确定吗？提问验证
-- "用户会不耐烦" → 5 分钟的探索节省 5 小时的返工

package/.specpow/skills/planning-onboard/SKILL.md

@@ -1,60 +0,0 @@
----
-name: planning-onboard
-description: SpecPow planning-onboard skill
----
-
-# 项目入门
-
-> 新成员加入项目时的引导流程
-
-## 触发条件
-
-- 新成员首次使用项目
-- 用户提到"入门"/"onboard"/"新手"
-
-## 工作流
-
-### 1. 环境检查
-```bash
-specpow doctor
-```
-确保所有检查通过。
-
-### 2. 了解项目结构
-- 阅读 README.md
-- 浏览 schemas/ 了解工作流
-- 浏览 skills/ 了解可用技能
-
-### 3. 第一个变更
-```bash
-# 探索项目
-specpow explore
-
-# 创建一个小变更
-specpow propose "修复xxx问题"
-
-# 查看状态
-specpow status
-
-# 执行变更
-specpow apply
-```
-
-### 4. 常用命令速查
-| 命令 | 用途 |
-|------|------|
-| `specpow explore` | 探索项目上下文 |
-| `specpow propose` | 创建变更提案 |
-| `specpow status` | 查看变更状态 |
-| `specpow apply` | 执行变更 |
-| `specpow verify` | 验证变更 |
-| `specpow archive` | 归档变更 |
-| `specpow doctor` | 健康检查 |
-
-## 关键概念
-
-1. **变更（Change）** — 一次完整的功能开发/修复
-2. **工件（Artifact）** — proposal/spec/design/tasks 四件套
-3. **Schema** — 定义工件流和模板
-4. **技能（Skill）** — AI 的行为指南
-5. **SDD** — 子代理驱动开发

package/.specpow/skills/planning-propose/SKILL.md

@@ -1,156 +0,0 @@
----
-name: planning-propose
-description: 创建变更提案。生成 proposal + specs + design + tasks 全套工件。融合 OpenSpec propose + brainstorming 前置验证。
----
-
-# 变更提案 (Propose)
-
-创建完整的变更提案，包含所有规划工件。
-
-**规划边界**: 此工作流只创建规划工件。即使用户要求构建，也不要在此阶段开始实现。等工件完成后，等待新的用户请求来启动 apply 工作流。
-
-## 前置条件
-
-- 已完成 `explore` 技能（或已有明确的需求描述）
-
-## 输入
-
-用户的请求应包含：变更名称（kebab-case）或要构建的内容描述。
-
-## 流程
-
-### 1. 理解请求并澄清歧义
-如果未提供明确输入，询问用户：
-> "你想要做什么变更？描述你想要构建或修复的内容。"
-
-从描述中派生 kebab-case 名称（如 "add user authentication" → `add-user-auth`）。
-
-**重要**: 不要在理解用户想要什么之前继续。
-如果请求包含会实质性影响范围的歧义，先询问用户。
-
-### 2. 确定工作流 Schema
-
-使用配置的默认 Schema（spec-driven），除非用户明确要求不同的工作流。
-
-### 3. 创建变更目录
-
-```bash
-specpow propose <name>
-```
-
-或手动创建：
-```
-openspec/changes/<name>/
-├── proposal.md
-├── specs/
-│   └── <capability>/spec.md
-├── design.md (可选，小变更可跳过)
-└── tasks.md
-```
-
-### 4. 获取工件构建顺序
-
-```bash
-specpow status --change <name> --json
-```
-
-解析 JSON 获取：
-- `applyRequires`: 实施前需要的工件 ID 数组
-- `artifacts`: 所有工件列表，含状态和依赖关系
-
-### 5. 按依赖顺序创建每个工件
-使用 todo 列表跟踪进度。
-按依赖顺序循环（无待处理依赖的工件优先）。
-
-#### a. 对于每个 `ready` 状态的工件：
-1. 获取指令：
-   ```bash
-   specpow instructions <artifact-id> --change <name> --json
-   ```
-
-2. 指令 JSON 包含：
-   - `context`: 项目背景（约束，不要复制到输出中）
-   - `rules`: 工件特定规则（约束，不要复制到输出中）
-   - `template`: 输出文件的结构
-   - `instruction`: Schema 特定指导
-   - `resolvedOutputPath`: 输出路径
-
-3. 读取已完成的依赖文件获取上下文（总是从磁盘重新读取）
-
-4. 使用 `template` 作为结构创建工件文件
-
-5. 应用 `context` 和 `rules` 作为约束 — 但不要复制到文件中
-
-#### b. 继续直到所有必需工件都存在：
-- 创建每个工件后，重新运行 `specpow status`
-- 必需集合 = `applyRequires` 加上所有传递依赖
-- 跳过仅在 `status` 报告为 `skipped` 时的工件
-
-### 6. 显示最终状态
-```bash
-specpow status --change <name>
-```
-
-## 工件创建指南
-
-### proposal.md
-- 回答：为什么做？解决什么？成功标准？
-- 包含影响范围和非目标
-
-### specs/<capability>/spec.md
-- 使用 Delta 格式：ADDED/MODIFIED/REMOVED/RENAMED
-- 规范是行为契约，不是实现计划
-- 每个需求必须可验证（Given/When/Then）
-
-### design.md
-- 架构决策（ADR 格式）
-- 模块划分和接口定义
-- 数据模型
-- 小变更可跳过
-
-### tasks.md
-- 每个任务 2-5 分钟
-- 包含精确文件路径
-- 包含完整代码或明确修改指令
-- 包含验证步骤
-- 任务之间尽量独立
-- 使用 YAML Frontmatter 格式（推荐）：
-
-```yaml
----
-tasks:
-  - number: 1
-    title: <任务标题>
-    files:
-      - path/to/file.ts
-    description: |
-      <精确的实现指令>
-    verification: <验证步骤>
-    dependsOn: []
-    estimatedEffort: S  # S | M | L
----
-```
-
-## 输出
-
-完成后总结：
-- 变更名称和位置
-- 创建的工件列表
-- "实施所需的所有工件已就绪。"
-- 提示："工件已准备好审核。准备好后，运行 `/apply-change` 或让我应用此变更。"
-
-## 护栏
-
-- 此工作流只授权规划。不要实现变更
-- 创建工件前总是读取依赖工件
-- 询问会实质性改变范围的歧义
-- 验证每个工件文件存在后再继续
-
-## 合理化防御表
-
-| 借口 | 现实 |
-|------|------|
-| "我可以直接开始编码" | 没有规划就编码 = 返工 |
-| "规范太正式了" | 规范是对齐工具，不是官僚主义 |
-| "任务列表没必要" | SDD 引擎需要精确的任务定义 |
-| "设计文档太重量级" | 小变更可以跳过，大变更不行 |

package/.specpow/skills/planning-update-change/SKILL.md

@@ -1,45 +0,0 @@
----
-name: planning-update-change
-description: SpecPow planning-update-change skill
----
-
-# 更新变更
-
-> 对已有变更进行范围调整或工件更新
-
-## 触发条件
-
-- 需求发生变化
-- 设计需要调整
-- 用户提到"更新变更"/"修改提案"
-
-## 铁律
-
-1. **记录原因** — 每次更新必须说明原因
-2. **影响分析** — 评估更新对下游工件的影响
-3. **版本标记** — 更新后的工件标注版本
-
-## 工作流
-
-### 1. 识别影响范围
-- 修改 proposal → 可能影响 specs/design/tasks
-- 修改 specs → 可能影响 design/tasks
-- 修改 design → 可能影响 tasks
-- 修改 tasks → 仅影响 tasks
-
-### 2. 级联更新
-按依赖顺序更新受影响的工件。
-
-### 3. 记录变更日志
-```markdown
-## 更新记录
-- 2026-08-10: 新增需求 REQ-005（用户要求增加导出功能）
-  - 更新 specs/spec.md: 新增 ADDED REQ-005
-  - 更新 design.md: 新增导出接口设计
-  - 更新 tasks.md: 新增 Task-006~008
-```
-
-## 红旗
-
-- 更新导致范围大幅扩大 → 重新评估可行性
-- 已部分实现 → 确认已完成部分不受影响

package/.specpow/skills/planning-verify-change/SKILL.md

@@ -1,72 +0,0 @@
----
-name: planning-verify-change
-description: SpecPow planning-verify-change skill
----
-
-# 验证变更
-
-> 验证已实现的变更是否满足规范要求
-
-## 触发条件
-
-- 任务实现完成后
-- 用户提到"验证"/"verify"/"检查"
-- apply 完成后
-
-## 铁律
-
-1. **证据驱动** — 每个检查项必须有实际证据
-2. **不自我评估** — 不能自己说"我觉得没问题"
-3. **可复现** — 验证步骤必须可复现
-
-## 验证维度
-
-### 1. 规范合规性
-- spec.md 中每个需求是否都有对应实现
-- 验收标准是否都满足
-
-### 2. 设计一致性
-- 实现是否符合 design.md 中的架构决策
-- 接口定义是否一致
-
-### 3. 任务完成度
-- tasks.md 中所有任务是否标记完成
-- 引用的文件是否都存在
-
-### 4. 测试覆盖
-- 新增代码是否有测试
-- 测试是否通过
-
-### 5. 代码质量
-- 编译通过
-- Lint 通过
-- 无安全漏洞
-
-## 使用方式
-
-```bash
-# 单变更时自动检测，无需指定名称
-specpow verify
-
-# 多变更时指定名称
-specpow verify --change <change-name>
-```
-
-## 任务格式
-
-tasks.md 支持两种格式，verify 均能正确解析：
-- **YAML Frontmatter（推荐）**：通过 `status: done` / `status: completed` / `completed: true` 判断完成
-- **Markdown Checkbox**：通过 `- [x]` 判断完成
-
-## 规范解析
-
-使用 `parseDelta` 状态机解析 spec.md，识别 ADDED / MODIFIED / REMOVED / RENAMED 四种需求操作。
-
-## 输出
-
-验证报告，包含每项检查的通过/失败状态和详细信息。
-
-## 红旗
-
-- 任何 Critical 级别失败 → 必须修复
-- 测试未通过 → 阻止归档