specwf 0.2.2 → 0.3.0

package/dist/templates/commands/init.md

@@ -1,37 +0,0 @@
-# 初始化项目
-
-运行 `specwf init` 创建 specwf/ 目录结构 + platform.yml + state.md。
-
-## 存量项目
-
-已有代码的项目使用 brownfield 模式：
-
-```bash
-specwf init --brownfield
-```
-
-CLI 创建目录结构后，**agent 需使用 specwf 子代理并行执行以下任务**：
-
-1. **Codebase Mapping**（`specwf-researcher`）— 分析技术栈、模块结构、依赖关系
-   - 产出: `specwf/research/STACK.md` + `specwf/research/ARCHITECTURE.md`
-2. **Spec Bootstrap**（`specwf-researcher`）— 从核心模块提取行为契约
-   - 产出: `specwf/specs/<domain>/spec.md`（标记 BOOTSTRAPPED）
-
-使用 task 工具 fan-out 两个 specwf-researcher 并行执行。
-
-## 上下文
-
-```bash
-specwf context init
-specwf state
-```
-
-可参考 @specwf/conventions/coding.md。
-
-## 下一步
-
-完成后：
-
-```bash
-specwf continue
-```

package/dist/templates/commands/milestone.md

@@ -1,27 +0,0 @@
-# 里程碑管理
-
-切换或创建 Milestone。
-
-## 上下文
-
-```bash
-specwf state
-```
-
-## 操作
-
-```bash
-# 切换到指定 milestone
-specwf state set-milestone <id>
-
-# 切换到指定 phase
-specwf state set-phase <id>
-```
-
-可参考 @specwf/roadmap.md 查看 milestone 列表。
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/plan.md

@@ -1,22 +0,0 @@
-# Change 设计
-
-使用 specwf-planner agent 设计技术方案、拆分任务、预写 delta-specs。
-
-## 上下文
-
-```bash
-specwf context plan
-specwf state
-```
-
-## 产出
-
-- design.md（技术方案）
-- tasks.md（任务清单，标注 TDD type）
-- specs/<domain>/spec.md（delta-specs）
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/research-phase.md

@@ -1,20 +0,0 @@
-# Phase 调研
-
-对当前 phase 的实现路径进行调研。使用 specwf-researcher agent。
-
-## 上下文
-
-```bash
-specwf context research-phase
-specwf state
-```
-
-## 产出
-
-写入当前 phase 目录下的 research.md。
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/research.md

@@ -1,24 +0,0 @@
-# 项目技术调研
-
-并行调研多个技术方向。使用 task 工具 fan-out specwf-researcher agent。
-
-## 上下文
-
-```bash
-specwf context research
-specwf state
-```
-
-## 产出
-
-写入 @specwf/research/ 目录：
-- @specwf/research/stack.md
-- @specwf/research/architecture.md
-- @specwf/research/pitfalls.md
-- @specwf/research/summary.md
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/review.md

@@ -1,20 +0,0 @@
-# 三重审查
-
-规格审查 + 质量审查 + 目标审查，batch tasks[3] 并行。
-
-## 上下文
-
-```bash
-specwf context review
-specwf state
-```
-
-## 门控
-
-全部通过才进 verify。
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/roadmap.md

@@ -1,23 +0,0 @@
-# 路线图拆分
-
-将项目拆分为 Milestone × Phase。
-
-## 上下文
-
-```bash
-specwf context roadmap
-specwf state
-```
-
-可参考 @specwf/requirements.md。
-
-## 产出
-
-更新 @specwf/roadmap.md。
-
-## 下一步
-
-```bash
-specwf state set-milestone <第一个 milestone id>
-specwf continue
-```

package/dist/templates/commands/ship.md

@@ -1,36 +0,0 @@
-# 交付
-
-## Phase ship
-
-创建 PR + 更新 @specwf/state.md。
-
-PR 正文应包含：
-- Phase scope 概述
-- 包含的 change 列表（每个 change 的 scope 摘要 + 产出文件）
-- 变更统计（文件数、行数）
-- 测试覆盖状态（vitest run 结果）
-- Checklist（所有 change 已 verify passed、已 archive）
-
-## Milestone ship
-
-发布 release tag + 更新 @specwf/project.md 版本号。
-
-Release notes 应包含：
-- 版本号与里程碑名称
-- 变更总览（按 phase 分组）
-- Breaking changes（如有）
-- Git diff 统计（+/- 行数、文件数）
-- 测试结果汇总
-
-## 上下文
-
-```bash
-specwf state
-specwf continue change <last-change-name>
-```
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/split.md

@@ -1,16 +0,0 @@
-# Change 拆分
-
-将 phase 拆分为多个 change，确定依赖图。
-
-## 上下文
-
-```bash
-specwf context split
-specwf state
-```
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/verify.md

@@ -1,22 +0,0 @@
-# 测试验证
-
-运行测试，诊断根因，路由回环。
-
-## 上下文
-
-```bash
-specwf context verify
-specwf state
-```
-
-## 回环路由
-
-- 计划缺陷 → `specwf continue`（回 plan）
-- 实现缺陷 → 回 apply 重实现
-- 规格缺陷 → 标记 spec 待修
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/skills/adhoc.md

@@ -1,53 +0,0 @@
-# 创建临时 Change 工作流指引
-
-## 概述
-
-临时 Change 是与 milestone/phase 无关的独立变更，直接走标准 Change 循环。适用于紧急修复、独立改进等场景。
-
-## 前置条件
-
-- specwf 项目已初始化
-- 变更名称已确定
-
-## 执行步骤
-
-### 1. 创建 change 目录
-
-```bash
-specwf change new <name>
-```
-
-自动生成：
-- `specwf/changes/<name>/proposal.md`
-- `specwf/changes/<name>/design.md`
-- `specwf/changes/<name>/tasks.md`
-- `specwf/changes/<name>/specs/` 目录
-
-### 2. 填写 proposal.md
-
-### 3. 继续推进
-
-```bash
-specwf continue
-```
-
-## 产物
-
-- proposal.md / design.md / tasks.md
-- state.md adhoc 记录
-
-## 验证
-
-- [ ] change 目录存在
-- [ ] 模板文件已生成
-- [ ] specwf state 能看到新 change
-
-## 常见陷阱
-
-- 临时 change 归档后统一存放在 specwf/archive/ 下
-- 临时 change 不走 milestone/phase 的 discuss/research-phase/split 流程
-- 如果需要关联到 phase，使用 `specwf change new --phase <id>`
-
-## 参考
-
-- specwf 工作流设计中的「临时 Change」章节

package/dist/templates/skills/apply.md

@@ -1,134 +0,0 @@
-# Change 实现工作流指引
-
-## 概述
-
-按 tasks.md 实现代码。TDD 强制执行：type:behavior 任务必须走 RED→GREEN→REFACTOR 循环。
-
-Apply 阶段由 specwf-executor agent 在隔离环境中执行，支持多任务分组并发和原子提交。
-
-## 前置条件
-
-- plan 阶段已完成，tasks.md、design.md、delta-specs 已就位
-- specwf context apply 已获取上下文
-- 隔离环境已准备（git worktree 或 OMP isolated mode）
-
-## 执行步骤
-
-### 1. 读取上下文
-
-运行 \`specwf context apply\`：
-- design.md — 技术方案
-- tasks.md — 实现清单
-- delta-specs — 行为契约
-- 依赖的 specs/ — 已有全局规范
-
-### 2. 分组执行
-
-根据 tasks.md 中的依赖关系分组，每组作为一次提交（或一组相关提交）：
-
-**组内串行**：依赖关系强制顺序
-**组间并行**：无依赖的任务由不同 executor agent 并行执行
-
-\`\`\`
-# 分组示例
-Group 1（并行）: task A, task B（无依赖）
-├── task A → 代码 + 测试 → commit
-└── task B → 代码 + 测试 → commit
-
-Group 2（串行）: task C → task D
-├── task C → 代码 + 测试 → commit
-└── task D → 代码 + 测试 → commit
-\`\`\`
-
-### 3. TDD 执行流程（type:behavior 任务）
-
-每个 type:behavior 任务严格执行：
-
-**RED — 写失败测试**
-\`\`\`
-1. 根据 delta-spec 的 SHALL/MUST 条目编写测试
-2. 测试应该明确断言行为契约
-3. 运行测试 → 预期失败（红色）
-4. 提交消息格式: \`test(<domain>): add failing test for <feature>\`
-\`\`\`
-
-**GREEN — 最小实现**
-\`\`\`
-1. 写恰好让测试通过的最少量代码
-2. 不要过度工程，不要提前优化
-3. 运行测试 → 预期通过（绿色）
-4. 提交消息格式: \`feat(<domain>): implement <feature>\`
-\`\`\`
-
-**REFACTOR — 重构改进**
-\`\`\`
-1. 在测试保护下重构代码结构
-2. 测试应该仍然通过
-3. 提交消息格式: \`refactor(<domain>): improve <aspect>\`
-4. REFACTOR 不改变行为，不修改测试
-\`\`\`
-
-### 4. 原子提交协议
-
-每个任务完成后执行原子提交：
-
-\`\`\`
-# 提交原则
-- 每个提交是一个逻辑单元，可独立 review
-- RED/GREEN/REFACTOR 每个阶段至少一个提交
-- 不混合不同任务的改动在一个提交中
-- 提交消息使用 Conventional Commits 格式
-
-# 提交消息格式
-<type>(<scope>): <description>
-
-[optional body — why]
-\`\`\`
-
-### 5. 非 TDD 任务（type:config/refactor/docs/scaffolding）
-
-直接实现，单次提交即可：
-\`\`\`
-chore(config): add ESLint rule for ...
-docs(api): add JSDoc to ...
-refactor(core): extract validateInput helper
-\`\`\`
-
-### 6. 各组完成检查
-
-每组完成后运行：
-- [ ] 所有测试通过
-- [ ] 代码风格一致（运行 formatter）
-- [ ] delta-specs 中的每个 SHALL/MUST 有对应测试覆盖
-- [ ] 无 lint 错误
-- [ ] 无死代码/注释掉的代码
-
-## 产物
-
-- 实现代码（按 design.md 和 delta-specs）
-- 测试代码（type:behavior 任务）
-- 原子提交记录
-
-## 验证
-
-- [ ] 所有 type:behavior 任务已完成 RED→GREEN→REFACTOR
-- [ ] 所有非 TDD 任务已实现
-- [ ] 所有测试通过
-- [ ] 每个 delta-spec 的 SHALL/MUST 有对应测试
-- [ ] 代码无 lint/类型错误
-
-## 常见陷阱
-
-- GREEN 阶段只做「恰好通过」的实现 — 不要提前写 REFACTOR 的内容
-- 不要在 RED 和 GREEN 之间插入无关改动
-- 不要跳过 RED 直接写实现 — 先写测试再写代码
-- 如果测试无法先写（IO 密集型、UI 代码），标注为 \`type:refactor\` 或 \`type:scaffolding\`
-- 一个提交涵盖多个不相关改动 → 无法原子回滚
-- 跨 change 共享代码使用依赖约定或 key_links，不要复制粘贴
-
-## 参考
-
-- TDD (Test-Driven Development) by Kent Beck
-- Conventional Commits 规范
-- GSD Core 的 execute phase
-- OpenSpec 的 atomic commit 协议

package/dist/templates/skills/archive.md

@@ -1,109 +0,0 @@
-# 归档工作流指引
-
-## 概述
-
-Change 循环的收尾阶段。负责两件事：(1) 将 delta-specs 确定性合并到全局 specs/；(2) 从代码 diff 中提取新的行为和约束，回灌到 specs/ 中。
-
-归档完成后，Change 的工作永久记录在 specs/ 中，供后续 Change 参考和使用。
-
-## 前置条件
-
-- verify 阶段已通过（passed 状态）
-- 合并目标分支的准备已完成（ship 阶段前）
-
-## 执行步骤
-
-### 1. 读取上下文
-
-读取以下文件清单：
-\`\`\`
-changes/<change-name>/specs/<domain>/spec.md  — delta-specs
-specs/<domain>/spec.md                         — 全局 specs（目标）
-changes/<change-name>/tasks.md                 — 任务清单（确认 REFACTOR 阶段可以删除的实现细节 delta）
-changes/<change-name>/VERIFICATION.md          — 验证报告（确认哪些通过了）
-\`\`\`
-
-### 2. Delta-Spec 合并
-
-将 delta-specs 合并到全局 specs/ 中：
-
-**合并规则**：
-- **新增条目**：直接追加到对应域名的 specs/ 文件中
-- **修改条目**：替换或修订全局 specs/ 中的对应 ID
-- **删除条目**：从全局 specs/ 中移除（标记 \`[DELETED: <change-name>]\`）
-- **冲突**：如果全局 specs/ 中的条目与 delta-spec 矛盾，标记 \`[CONFLICT: <change-name>]\` 并列出冲突双方
-
-**合并流程**：
-\`\`\`
-1. 读取 changes/<change>/specs/ 下的所有 spec 文件
-2. 对每个文件：
-   a. 按 SHALL/MUST 编号索引
-   b. 对全局 specs/ 执行新增/修改/删除
-   c. 记录变更日志在 spec 文件头部
-3. 处理冲突（见冲突规则）
-4. 写入更新后的 specs/
-\`\`\`
-
-### 3. 代码认知提取
-
-从代码 diff 中提取未在 delta-specs 中预写的行为和约束：
-
-**提取来源**：
-- 新增的函数、方法、模块的公共 API（类型签名、注释、实现）
-- 测试中隐含的行为约束（如「一个用户只有一个 active session」）
-- 配置文件、常量中的业务规则
-- 错误消息中体现的领域概念
-
-**提取规则**：
-- **系统行为**（什么是系统做的） → 提取为 SHALL 条目
-- **业务约束**（必须遵守的限制） → 提取为 MUST 条目
-- **用户可见行为**（API 响应格式、错误码） → 提取为 SHOULD 条目
-- **实现细节**（内部变量名、helper 函数） → 不提取
-
-**AUTO-EXTRACTED 标记**：
-每个自动提取的条目在末尾添加：
-\`\`\`
-# AUTO-EXTRACTED from <change-name> on <timestamp>
-# Source: <file>:<line>
-\`\`\`
-
-标记的目的是：
-- 标识是工具自动生成的，不是人工编写的
-- 便于后续人工 review 时定位和验证
-- 在后续归档中，如果人工 review 确认正确，移除 \`AUTO-EXTRACTED\` 标记
-
-### 4. 最终检查
-
-- [ ] 所有 delta-specs 已合并或标记冲突
-- [ ] 已扫描代码 diff 并提取认知
-- [ ] 提取的条目有 \`AUTO-EXTRACTED\` 标记
-- [ ] 全局 specs/ 文件无格式损坏
-- [ ] change 目录保留为历史记录（不删除）
-
-## 产物
-
-- \`specs/<domain>/spec.md\`（更新） — 合并后的全局规范
-- \`specs/<domain>/spec.md\`（追加） — 代码认知提取后的新增条目
-
-## 验证
-
-- [ ] delta-specs 已正确合并到全局 specs/
-- [ ] 冲突已标记 \`[CONFLICT: <change>]\` 且列出双方
-- [ ] 代码提取条目有 \`AUTO-EXTRACTED\` 标记
-- [ ] 全局 specs/ 可被 parseSpec 读取（无格式错误）
-- [ ] change 目录保留
-
-## 常见陷阱
-
-- 不要删除 change 目录 — 它是 git 历史之外的辅助审计轨迹
-- 不要覆盖全局 specs/ — 只追加、替换对应 ID、或标记删除
-- 代码提取不是 code review — 提取行为契约，不是判断代码好坏
-- 提取要克制 — 只有「系统行为/约束」才提取，「实现方式」不提取
-- AUTO-EXTRACTED 条目需要人肉 review 确认，不是最终版
-- 如果一个 extract 发现的行为明确违反现有 specs/ 或 conventions/，额外标记 \`[FLAG: conflict with <existing-spec-ref>]\`
-
-## 参考
-
-- OpenSpec 的 delta-merge 流程
-- Trellis 的代码认知回灌概念（仅参考）
-- GSD Core 的 archive 阶段

package/dist/templates/skills/continue.md

@@ -1,97 +0,0 @@
-# 自动推进工作流指引
-
-## 概述
-
-读取 STATE.md，由状态机确定当前状态，自动触发对应的下一个 slash command。
-
-Continue 是整个工作流的自动导航器。它不执行任何业务逻辑，只负责判断「现在该做什么」并触发。
-
-## 前置条件
-
-- specwf/STATE.md 存在且格式正确
-- specwf 已初始化
-
-## 执行步骤
-
-### 1. 读取 STATE.md
-
-\`\`\`
-specwf state
-\`\`\`
-
-STATE.md 包含：
-- 当前 milestone / phase / change 的位置
-- 各个实体的状态
-- 下一步提示（如果有）
-
-### 2. 查询特定 change 的状态
-
-\`\`\`
-specwf continue change <name>
-\`\`\`
-
-查询指定 change 或临时 change 的当前状态和下一步建议。
-
-### 3. 状态机匹配
-
-根据 STATE.md 数据，状态引擎自动匹配合法转移。每个步骤对应一个 slash command：
-
-| 层级 | 当前步骤 | 下一步命令 | 子代理 |
-|------|---------|-----------|--------|
-| 项目层 | initialized | /specwf:grill | — |
-| 项目层 | requirements-defined | /specwf:research | researcher |
-| 项目层 | researched | /specwf:roadmap | — |
-| 项目层 | roadmap-defined | /specwf:discuss | — |
-| Phase | phase-discuss | /specwf:research-phase | researcher |
-| Phase | phase-research | /specwf:split | — |
-| Phase | phase-split 后 | /specwf:plan → apply → review → verify → archive | 各步对应 subagent |
-| Phase | change-archived | /specwf:ship | — |
-| Phase | phase-shipped | /specwf:ship（milestone）或 /specwf:discuss（下一 phase）| — |
-| 临时 change | adhoc-proposal | /specwf:plan | planner |
-
-完整的状态转移表见 `src/types/state.ts`。
-
-### 3. 输出下一步
-
-输出格式：
-\`\`\`
-# Continue 结果
-
-## 当前状态
-- Project: <name>
-- Milestone: <ms-name>（<status>）
-- Phase: <ph-name>（<status>）
-- Change: <change-name>（<status>）
-
-## 下一步
-- 命令: /specwf:<next-step>
-- 前置条件: ...
-\`\`\`
-
-### 4. 触发（可选）
-
-如果配置了 \`auto_advance: true\`，自动加载对应的 skill 并开始执行。
-
-## 产物
-
-- （无永久文件输出）
-- 控制台输出下一步建议（或自动触发）
-
-## 验证
-
-- [ ] 正确识别当前状态
-- [ ] 正确匹配下一步
-- [ ] STATE.md 格式可解析
-- [ ] 无状态机死循环风险
-
-## 常见陷阱
-
-- 如果 STATE.md 内容不完整或格式损坏，不要猜测 — 提示用户运行 \`specwf init\` 或手动修复
-- 如果多个 change 存在且状态不一致，优先处理最深的未完成 change
-- 不要自动推进跳过 review → verify → archive 的流程（review 必须由用户触发来确认质量）
-- auto_advance 模式不跳过 review — 只是自动触发 review 命令，仍需要 reviewer agent
-
-## 参考
-
-- state-machine 模块的状态转换表
-- OMP 的 continue 命令设计