SpecPow Framework

Spec-Powered AI Development Framework 融合 OpenSpec 规范驱动 + Superpowers 执行引擎的企业级 AI 辅助编程框架

核心理念

OpenSpec 确保"做正确的事"（Do the right thing），Superpowers 确保"把事做正确"（Do the thing right）。

SpecPow 将两者融合，形成从需求探索到代码交付的全链路 AI 辅助开发框架：

维度	来源	能力
规划严谨性	OpenSpec	工件图引擎 + Delta 规范 + 苏格拉底式探索
执行高质量	Superpowers	SDD 子代理驱动 + TDD 强制 + 5轮审查循环
追溯完整性	两者融合	规范变更历史 + 执行账本 + 审查包
平台广泛性	两者融合	22+ 种 AI 工具适配器
业务贴合性	企业定制	9 个业务 Agent 覆盖全栈
智能上下文	Trellis	Hook 注入 + 跨会话记忆 + 工作流状态追踪

架构分层

┌─────────────────────────────────────────────────────────────────┐
│                    用户触发层 (21 个 CLI 命令)                     │
│  init · explore · propose · status · apply · verify · archive   │
│  validate-specs · execute · review · debug · update · config    │
│  schemas · store · doctor · migrate · sdd · channel · memory    │
│  workflow · hook-run                                            │
│  支持 --json 输出（Agent Contract）                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    规划层 (OpenSpec 工件图引擎)                   │
│  proposal → specs → design → tasks                              │
│  · Delta 规范系统（结构化合并）  · 工件依赖 DAG  · 验证器         │
│  · Context/Rules 注入  · 三层 Schema 解析                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    执行层 (双模式 SDD 引擎)                       │
│  ┌─ 模式 A: SDD Engine (默认) ─┐  ┌─ 模式 B: Host-Driven ──┐   │
│  │ TypeScript 编排              │  │ 宿主 Agent 原生工具     │   │
│  │ controller.ts → AICaller    │  │ task-manifest.json      │   │
│  │ → claude CLI 子进程         │  │ → SKILL.md 指令驱动     │   │
│  └─────────────────────────────┘  └─────────────────────────┘   │
│  · TDD 强制 (RED-GREEN-REFACTOR)  · 5轮修复断路器               │
│  · 进度账本（两种模式共享）        · 模型配置可化                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    能力层 (35 个技能)                              │
│  Bootstrap(1) + Meta(3) + Planning(10) + Execution(11) + Business(9) + CLI Router(1) = 35  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    智能层 (v0.2.0 新增)                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │  Hook    │ │  Memory  │ │ Channel  │ │ Workflow State   │   │
│  │ 4-hook   │ │ 跨会话   │ │ 多代理   │ │ [workflow-state] │   │
│  │ 管道     │ │ 记忆     │ │ 协作     │ │ 状态标签         │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    基础设施层                                     │
│  22+ 种 AI 工具适配器 · Git 操作 · 模板引擎 · 配置管理            │
│  模板哈希增量更新 · Core SDK 子路径导出                           │
└─────────────────────────────────────────────────────────────────┘

快速开始

# 安装依赖
pnpm install

# 构建
pnpm build

# 初始化项目
specpow init

# 探索需求
specpow explore "我需要一个用户管理模块"

# 创建变更提案
specpow propose add-user-management

# 查看状态（支持 JSON 输出）
specpow status --json

# 执行实现（SDD 引擎驱动，默认模式）
specpow apply

# Host-Driven 模式（宿主 Agent 原生 subagent 工具执行）
specpow apply --host-driven

# 验证 Delta Spec 名称匹配
specpow validate-specs --change add-user-management

# 并行执行（使用 git worktree）
specpow apply --parallel

# 验证规范合规性
specpow verify

# 归档变更
specpow archive

SDK 子路径导出 (v0.2.0)

SpecPow 支持模块化导入，按需使用各子系统：

// SDD 执行引擎
import { SDDController } from '@specpow/framework/sdd';

// 工件图引擎
import { ArtifactGraph } from '@specpow/framework/artifact-graph';

// Delta Spec 解析与合并
import { parseDelta, mergeDeltaSpec, ArchiveEngine } from '@specpow/framework/archive';

// Hook 自动上下文注入
import { HookRegistry, getDefaultRegistry } from '@specpow/framework/hooks';

// 跨会话记忆系统
import { createMemoryManager, extractKeywords, detectPhase } from '@specpow/framework/memory';

// Channel 多代理协作
import { createChannelRuntime, Supervisor } from '@specpow/framework/channel';

// 工作流状态标签
import { stageToTag, parseWorkflowStateTag, inferStageFromPath } from '@specpow/framework/workflow-state';

// 全局配置
import { GlobalConfigManager } from '@specpow/framework/config';

// AI 工具适配器
import { AdapterRegistry, createAdapter } from '@specpow/framework/command-generation';

可用子路径

子路径	说明
@specpow/framework	主入口（命名空间导出）
@specpow/framework/sdd	SDD 执行引擎
@specpow/framework/artifact-graph	工件图 DAG
@specpow/framework/archive	Delta Spec 解析与合并
@specpow/framework/hooks	Hook 自动上下文注入
@specpow/framework/memory	跨会话记忆系统
@specpow/framework/channel	Channel 多代理协作
@specpow/framework/workflow-state	工作流状态标签
@specpow/framework/config	全局配置管理
@specpow/framework/command-generation	AI 工具适配器

工作流 Schema

Schema	工件流	场景
spec-driven	proposal → specs → design → tasks → apply	通用规格驱动开发
crud-module	proposal → spec → design → tasks → apply	CRUD 模块生成（前后端 8 任务）
bug-fix	proposal → analysis → fix-plan → tasks → apply	缺陷修复

三层 Schema 解析：项目级 → 用户级（~/.specpow/schemas/）→ 包内置

Context & Rules 注入 (v0.2.0)

在 .specpow/config.json 中配置项目上下文和规则：

// .specpow/config.json
{
  "context": "这是一个 React/TypeScript 项目，使用 Node.js 20+, PostgreSQL, Redis",
  "rules": {
    "proposal": [
      "提案不超过2页",
      "必须包含安全影响评估"
    ],
    "specs": [
      "使用 SHALL/MUST 表述需求",
      "每个需求至少2个场景"
    ],
    "design": [
      "必须包含数据库 ER 图",
      "API 设计遵循 RESTful 规范"
    ]
  }
}

Hook 自动上下文注入 (v0.2.0)

SpecPow 通过 4-hook 管道自动注入上下文：

Hook	触发时机	注入内容
SessionStart	会话开始	项目概览、活跃变更状态、工作流阶段
UserPromptSubmit	用户提交提示	当前工作流状态标签、相关记忆
PreToolUse	工具调用前	工具拦截、工作流上下文注入
PostToolUse	工具调用后	结果记录、阶段转换检测

// .specpow/hooks/hooks.json
{
  "hooks": {
    "SessionStart": [{ "matcher": "", "command": "npx --yes specpow hook-run session-start" }],
    "UserPromptSubmit": [{ "matcher": "", "command": "npx --yes specpow hook-run workflow-state" }],
    "PreToolUse": [{ "matcher": "", "command": "npx --yes specpow hook-run pre-tool-use" }],
    "PostToolUse": [{ "matcher": "", "command": "npx --yes specpow hook-run post-tool-use" }]
  }
}

跨会话记忆系统 (v0.2.0)

索引过去的 AI 会话日志，支持关键词搜索、阶段切片、相关性评分：

import { createMemoryManager } from '@specpow/framework/memory';

const memory = createMemoryManager(projectRoot);

// 索引会话
await memory.indexSession(sessionLog);

// 搜索记忆
const results = await memory.search({
  keywords: ['authentication', 'login'],
  phases: ['apply'],
  limit: 10
});

// 获取最近记忆
const recent = await memory.getRecent(20);

// 获取统计信息
const stats = await memory.getStats();

Channel 多代理协作 (v0.2.0)

事件源多代理运行时，支持 Supervisor 模式：

import { createChannelRuntime, Supervisor } from '@specpow/framework/channel';

// 创建运行时
const runtime = createChannelRuntime({
  channelId: 'dev-team',
  name: '开发团队'
});

// 创建 Supervisor
const supervisor = new Supervisor(runtime, {
  assignmentStrategy: 'round_robin',  // 轮询 | 最少忙碌 | 优先级
  maxConcurrentTasks: 5,
  taskTimeout: 300000
});

// 注册 Worker
await supervisor.registerWorker({
  id: 'worker-1',
  name: '实现者',
  role: 'worker',
  status: 'idle',
  lastActiveAt: Date.now()
});

// 分配任务
const taskId = await supervisor.assignTask(
  '实现用户认证模块',
  { specs: ['auth.spec.md'] },
  'supervisor'
);

工作流状态标签 (v0.2.0)

Trellis 风格的 [workflow-state:xxx] 标签，用于 AI 追踪工作流进度：

import { stageToTag, parseWorkflowStateTag, inferStageFromPath } from '@specpow/framework/workflow-state';

// 生成标签
const tag = stageToTag('apply');  // [workflow-state:apply]

// 解析标签
const state = parseWorkflowStateTag('[workflow-state:apply:task-3-of-5]');
// → { stage: 'apply', taskProgress: { current: 3, total: 5 } }

// 从路径推断阶段
const stage = inferStageFromPath('.specpow/skills/planning-explore/SKILL.md');
// → 'explore'

Delta Spec 结构化合并 (v0.2.0)

借鉴 OpenSpec 的结构化合并算法，支持 ADDED/MODIFIED/REMOVED/RENAMED 操作：

Delta 格式：
## ADDED Requirements
### Requirement: 新功能A
系统应支持功能A。

## MODIFIED Requirements
### Requirement: 已有功能B
系统应增强功能B。

## REMOVED Requirements
### Requirement: 废弃功能C

## RENAMED Requirements
### Requirement: 旧名称 → 新名称

合并顺序：RENAMED → REMOVED → MODIFIED → ADDED
冲突检测：跨段冲突、重复名称、RENAMED+REMOVED 矛盾
幂等性：normalizeBlockRaw 比较，已同步则跳过

模板哈希增量更新 (v0.2.0)

specpow init 支持增量更新，保护用户修改：

.specpow/.template-hashes.json
{
  "__version": 1,
  "hashes": {
    "schemas/spec-driven/schema.yaml": "sha256hex...",
    "skills/execution-tdd/SKILL.md": "sha256hex..."
  }
}

更新逻辑：
1. 计算新模板哈希
2. 对比存储哈希
3. 未修改 → 跳过
4. 用户修改过 → 创建 .new 文件
5. 框架更新 → 覆盖

技能体系（35 个）

分类	数量	技能
Bootstrap	1	using-specpow
Meta	3	meta-using-skills、meta-writing-skills、meta-create-skill
Planning	10	explore、propose、apply-change、verify-change、archive-change、write-plans、write-specs、write-design、onboard、update-change
Execution	11	subagent-driven-dev、tdd、systematic-debugging、parallel-agents、finish-branch、git-worktrees、requesting-review、receiving-review、verification-before-completion、sdd-orchestrator、subagent-dispatch
Business	9	java-codegen、ui-codegen、db-design、prd-writer、deploy-check、doc-sync、menu-register、test-gen、code-review
CLI Router	1	cli-router

Agent 体系（8 个）

类别	Agent	职责
规划	prd-agent	用户原始需求 → 结构化 PRD
规划	db-designer-agent	PRD → DDL + 索引 + 状态码
执行	java-codegen-agent	Entity → Mapper → Service → Controller
执行	ui-codegen-agent	Vue2 + View Design 页面生成
质量	test-agent	JUnit5 + Mockito 测试生成
质量	review-agent	结构化代码审查报告
控制	sdd-controller	子代理编排 + 审查循环 + 账本
运维	deploy-agent	部署检查 + 滚动/蓝绿/金丝雀发布

SDD 执行引擎

SDD (Subagent-Driven Development) 是核心执行引擎，融合 Superpowers 方法论：

┌─ Phase 1: TDD RED ────────────────────────────────────┐
│  TestWriter 子代理生成失败测试                          │
│  确认全部失败 → RED 确认                                │
└────────────────────────────────────────────────────────┘
                          │
┌─ Phase 2: 实现 ───────────────────────────────────────┐
│  实现者子代理（全新上下文）                              │
│  遵循 RED-GREEN-REFACTOR 使测试通过                    │
└────────────────────────────────────────────────────────┘
                          │
┌─ Phase 3: 审查 ───────────────────────────────────────┐
│  审查者子代理：三阶段裁决                               │
│  ① 规范合规  ② 代码质量  ③ TDD 合规                    │
└────────────────────────────────────────────────────────┘
                          │
┌─ Phase 4: 修复循环（≤5 轮）──────────────────────────┐
│  R1-3: 恢复原始实现者                                  │
│  R4-5: 全新实现者 + 升级模型                           │
│  断路器: 5 轮后裁定（停放 / 阻塞）                      │
└────────────────────────────────────────────────────────┘
                          │
┌─ Phase 5: 账本记录 ──────────────────────────────────┐
│  进度账本支持断点续跑                                   │
│  停放发现延迟到最终审查处理                              │
└────────────────────────────────────────────────────────┘

关键设计原则（来自 Superpowers）：

• 控制器不自己修复代码（保持上下文干净）
• 所有产物通过文件传递（不占用上下文窗口）
• 信任账本而非记忆（上下文压缩后账本是唯一真相）
• 每任务全新子代理（上下文隔离）

支持的 AI 工具（22 种）

工具	适配方式	调用风格
Claude Code	.claude/commands/	/specpow:explore
Cursor	.cursor/rules/	/specpow-explore
GitHub Copilot	.github/copilot-instructions.md	/specpow-explore
CodeBuddy	.codebuddy/rules/	/specpow-explore
Codex	.codex/instructions.md	/specpow-explore
Gemini CLI	.gemini/instructions.md	/specpow:explore
Amazon Q	.amazonq/commands/	@specpow-explore
Cline	.cline/rules/	/specpow-explore
Continue	.continue/config.md	/specpow-explore
Windsurf	.windsurf/rules/	/specpow-explore
Trae	.trae/rules/	/specpow-explore
Kiro	.kiro/steering/	/specpow-explore
Qwen	.qwen/instructions.md	/specpow-explore
Kimi	.kimi/instructions.md	/specpow-explore
GitHub Copilot Workspace	.github/copilot/	/specpow-explore
Roo Code	.roo/rules/	/specpow-explore
Auggie	.auggie/instructions.md	/specpow-explore
Bob	.bob/rules/	/specpow-explore
Crush	.crush/instructions.md	/specpow-explore
Devin	.devin/commands/	@specpow-explore
Junie	.junie/rules/	/specpow-explore
Qoder	.qoder/instructions.md	/specpow-explore

项目结构

specpow/
├── bin/                        # CLI 入口 (specpow.js)
├── src/
│   ├── cli/                    # Commander.js 命令注册
│   ├── commands/               # 21 个命令实现（支持 --json）
│   │   ├── init.ts             # 初始化 + 模板哈希增量更新
│   │   ├── explore.ts          # 苏格拉底式需求探索
│   │   ├── propose.ts          # 变更提案生成
│   │   ├── status.ts           # 工件状态 + 任务进度 + --json
│   │   ├── apply.ts            # SDD 引擎驱动执行 + --parallel
│   │   ├── verify.ts           # 5 维验证（规范/设计/任务/测试/质量）
│   │   ├── archive.ts          # 委托 ArchiveEngine 事务性归档
│   │   ├── validate-specs.ts   # Delta Spec 名称匹配验证
│   │   └── workflow/           # 工作流编排引擎
│   └── core/
│       ├── artifact-graph/     # 工件图 DAG + 拓扑排序 + 三层解析
│       ├── sdd-engine/         # SDD 控制器 + TDD + 审查循环 + 账本 + 并行分发
│       ├── archive/            # Delta Spec 结构化合并（P1-5）
│       ├── config/             # Zod 配置验证 + Context/Rules 注入（P1-7）
│       ├── init/               # AI 工具检测 + 模板哈希（P1-10）
│       ├── migration/          # 版本迁移工具
│       ├── parsers/            # tasks/specs/proposal 解析器
│       ├── store/              # 变更存储管理
│       ├── templates/          # 模板引擎 + AI 指令生成
│       ├── validation/         # Schema 验证 + Delta Spec 名称验证
│       ├── hooks/              # Hook 自动上下文注入（P2-11）
│       ├── memory/             # 跨会话记忆系统（P2-12）
│       ├── channel/            # Channel 多代理协作（P2-13）
│       ├── workflow-state.ts   # 工作流状态标签（P2-14）
│       └── command-generation/ # 22 种 AI 工具适配器（P1-9）
├── .specpow/
│   ├── schemas/                # 3 套工作流 Schema + 模板
│   ├── skills/                 # 35 个技能（SKILL.md）
│   ├── agents/                 # 8 个 Agent 定义
│   └── hooks/                  # Hook 自动上下文注入
├── scripts/                    # 辅助脚本（task-brief/review-package/sdd-workspace）
├── test/                       # 871 个测试用例
└── docs/                       # 使用指南

开发

# 安装依赖
pnpm install

# 开发模式（watch）
pnpm dev

# 构建
pnpm build

# 运行测试
pnpm test

# 代码检查
pnpm lint

技术栈

层	技术
语言	TypeScript (ESM, strict)
CLI	Commander.js
运行时验证	Zod
配置解析	yaml
终端	chalk, ora
测试	Vitest (871 tests)
包管理	pnpm

版本历史

v0.3.2 (2026-08-23)

Delta Spec 名称一致性优化：

• ✅ 主规范截断时仍注入完整需求名称清单（模板引擎 templates/index.ts）
• ✅ archive 路由失败时生成 名称未匹配 警告（engine.ts）
• ✅ 新增 specpow validate-specs 命令 — 提前验证 delta spec 名称与主规范匹配
• ✅ apply 命令增加预验证 — 执行前检测名称不匹配并警告
• ✅ planning-write-specs SKILL.md 增加"名称校验"铁律段落
• ✅ RENAMED 模板格式从表格改为箭头格式（旧名称 → 新名称）
• ✅ 新增 16 个测试用例（总计 871 个）

v0.3.1 (2026-08-18)

21 项缺陷修复（来自全面功能可运行性审查）：

IMPORTANT（4 项）：

• ✅ init --force 选项缺失 — 添加强制覆盖支持
• ✅ review --diff-file 未实际解析 diff — 实现 diff 文件解析与变更文件提取
• ✅ review --model 选项无效无警告 — 添加黄色提示
• ✅ Hook 失败被静默吞掉 — 失败 hook 的 error 信息作为 warning 输出

MODERATE（8 项）：

• ✅ formatForPlatform 忽略 platform 参数 — 根据平台返回对应格式
• ✅ migrate 失败时静默退出码 0 — 输出失败步骤 + process.exit(1)
• ✅ debug 提示不存在的 --report — 移除误导提示
• ✅ channel send 无消息类型验证 — 添加 MessageType 白名单校验
• ✅ status 任务正则仅匹配小写 [x] — 改为大小写不敏感
• ✅ verify 无变更时直接报错 — 自动检测唯一活跃变更
• ✅ init Schema/Skill 目录不存在静默返回 — 添加 console.warn 警告

MINOR（9 项）：

• ✅ channel 提示错误子命令名 — 修正为 add-worker / create-task
• ✅ session-start 技能列表仅 22/35 — 补全全部 35 个技能
• ✅ apply host-driven 写文件失败返回码 0 — return → process.exit(1)
• ✅ parseProposal 缺少 risks 解析 — 添加 Markdown 表格解析
• ✅ runTests() 同步阻塞事件循环 — execFileSync → 异步 execFile
• ✅ detectActiveChanges 重复调用 — 传参复用已计算结果
• ✅ PostToolUse 每次注入无用上下文 — 仅在有转换信号时注入
• ✅ initialize() 同步函数误用 await — 移除误导性 await

v0.3.0 (2026-08-15)

9 项缺陷修复与代码清理（来自全面代码审查）：

P0 关键修复（1 项）：

• ✅ Controller 未传递 commit SHA 给 ai-caller — 实现者代理现在能正确获取 git 上下文

P1 高价值修复（2 项）：

• ✅ Ledger fix-round 数据丢失 — 修复轮次历史现在正确追加而非覆盖
• ✅ design.md 未传递给 SDD 引擎 — 实现者现在能获取设计上下文

P2 中等优先级修复（4 项）：

• ✅ 模型配置死代码清理 — 移除未使用的 modelTier 字段
• ✅ 串行 apply --json 输出实现 — 两种模式均支持 JSON 输出
• ✅ projectContext 传递项目名而非原始路径 — 避免上下文污染
• ✅ ParallelDispatcher 忽略模型配置 — 并行模式现在正确使用 config.json 模型设置

P3 低优先级清理（2 项）：

• ✅ execute.ts 冗余 initialize() 调用清理
• ✅ store 选项死代码清理 — 移除 propose/status/apply 中无效的 --store 选项

v0.2.0 (2026-08-14)

P0 核心修复（4 项）：

• ✅ 模型配置从硬编码改为可配置
• ✅ 集成并行分发器到 CLI (--parallel)
• ✅ 扩展测试框架支持（自动检测）
• ✅ 三层 Schema 解析（项目 → 用户 → 包内置）

P1 高价值特性（6 项）：

• ✅ Delta Spec 结构化合并算法（ADDED/MODIFIED/REMOVED/RENAMED）
• ✅ Agent Contract — --json 输出支持
• ✅ Context & Rules 注入系统
• ✅ 交互式 Explore 模式
• ✅ 22 种 AI 工具适配器（原 6 种，新增 8 种）
• ✅ 模板哈希增量更新

P2 差异化创新（5 项）：

• ✅ Hook 自动上下文注入（4-hook 管道：SessionStart/UserPromptSubmit/PreToolUse/PostToolUse）
• ✅ 跨会话记忆系统（事件源 + 关键词索引 + SQLite/JSON 适配器）
• ✅ Channel 多代理协作（Supervisor 模式）
• ✅ 工作流状态标签 [workflow-state:xxx]
• ✅ Core SDK 子路径导出（10 个模块）

第二轮优化（11 项）：

• ✅ 四模块测试覆盖（Memory/Channel/Hook/WorkflowState）
• ✅ Delta Spec 四项增强（场景丢失守卫/能力退休/未计入内容检测/代码围栏掩码）
• ✅ 合理化防御体系扩展（11+ 行防御表 + 13 红旗 + 压力测试）
• ✅ AI 适配器扩展到 22 种（新增 GitHub Copilot Workspace/Roo Code/Auggie/Bob/Crush/Devin/Junie/Qoder）
• ✅ Hook 系统完善（PreToolUse/PostToolUse 实现）
• ✅ Hook + WorkflowState 深度集成（阶段转换钩子/状态恢复）
• ✅ 技能编写元技能（meta-create-skill）
• ✅ 版本迁移系统（迁移清单 + 自动备份）
• ✅ Memory 平台适配器扩展（SQLite + 分片 JSON）
• ✅ Memory 适配器性能优化（预编译语句/增量更新/原子写入）
• ✅ 预存缺陷修复（714 → 860 测试用例）

测试覆盖：

• 854 个测试用例（原 422 个，增长 102%）
• 37 个测试文件
• 新增测试：Memory 系统、Channel 运行时、Hook 系统、WorkflowState、Delta Spec 增强、AI 适配器扩展、迁移系统

v0.1.0

• 初始版本
• OpenSpec 工件图引擎 + Superpowers SDD 执行引擎
• 30 个技能 + 8 个 Agent
• 6 种 AI 工具适配器

License

MIT