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 注入 + 跨会话记忆 + 工作流状态追踪
安装即生效	v0.9.1	postinstall 自动注册 hooks，无需手动 init

安装即生效

# 全局安装
npm install -g respecpow

# 安装完成后，自动注册 hooks 到 AI 工具
# 支持 CodeBuddy 和 Claude Code

效果：安装后启动 AI 工具，SpecPow 自动生效，所有编码任务强制走工件图流程。

工作流程

用户安装 specpow
    │
    ▼
npm 触发 postinstall 脚本
    │
    ▼
自动检测 CodeBuddy / Claude Code
    │
    ▼
注册 4 个 hooks 到全局配置
    │
    ▼
用户启动 AI 工具
    │
    ▼
SessionStart hook 触发
    │
    ▼
注入工件图强制规则到 AI 上下文
    │
    ▼
AI 收到编码任务时，必须先：
1. 列出可用 Schema
2. 让用户选择
3. propose → apply

快速开始

# 安装（自动注册 hooks）
npm install -g respecpow

# 探索需求
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

架构分层

┌─────────────────────────────────────────────────────────────────┐
│                    用户触发层 (23 个 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 子路径导出                           │
└─────────────────────────────────────────────────────────────────┘

工作流 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/）→ 包内置

Hook 自动上下文注入

SpecPow 通过 4-hook 管道自动注入上下文，安装时自动注册到 AI 工具：

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

自动注册机制：

• npm install 时触发 postinstall 脚本
• 自动检测 CodeBuddy / Claude Code 全局配置
• 注册 hooks 到 ~/.codebuddy/settings.json 或 ~/.claude/settings.json
• 无需手动运行 respecpow init

工件图强制模式

所有编码任务必须先走工件图流程，不可直接编码：

用户："帮我加个用户登录功能"
    │
    ▼
AI 识别为编码任务
    │
    ▼
执行 specpow schema --json
    │
    ▼
向用户展示可用工件图：
  1. spec-driven - 通用规范驱动
  2. crud-module - CRUD 模块专用
  3. bug-fix - Bug 修复专用
  ...
    │
    ▼
用户选择 → specpow propose <name> --schema <selected>
    │
    ▼
按 instruction 逐个填充工件
    │
    ▼
工件图完整 → specpow apply

三档模式（可配置）：

模式	行为	配置
suggest	不强制，AI 自由行动	workflow.mode: "suggest"
enforce（默认）	强制走工件图，用户可覆盖	workflow.mode: "enforce"
strict	强制走工件图，不可跳过	workflow.mode: "strict"

SDK 子路径导出

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

// SDD 执行引擎
import { SDDController } from 'respecpow/sdd';

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

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

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

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

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

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

// 全局配置
import { GlobalConfigManager } from 'respecpow/config';

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

可用子路径

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

Context & Rules 注入

在 .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 规范"
    ]
  }
}

跨会话记忆系统

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

import { createMemoryManager } from 'respecpow/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();

Memory Auto Adapter

自动从 Claude Code 和 CodeBuddy 读取会话日志并索引，实现跨会话记忆能力：

# 自动索引所有数据源（Claude Code + CodeBuddy）
specpow memory auto-index

# 查看检测到的数据源
specpow memory sources

# 索引阶段摘要文件
specpow memory index-summary .specpow/memory/summaries/my-change-explore.md

# 预览记忆注入内容
specpow memory preview-injection --change my-change --phase apply

# 增强查询（支持多种选项）
specpow memory preview-injection --phase apply \
  --all-phases \                    # 查询所有阶段
  --keywords "适配器,会话,索引" \    # 自定义关键词
  --user-input "实现功能" \          # 用户输入增强
  --task-description "任务描述" \    # 任务描述增强
  --files "src/file.ts"             # 涉及文件增强

支持的数据源：

• Claude Code: ~/.claude/projects/{project}/{sessionId}.jsonl
• CodeBuddy: %LOCALAPPDATA%/CodeBuddyExtension/Data/{userId}/JetBrains/{userId}/history/{projectHash}/

记忆注入器：支持 Token 预算控制，按阶段差异化注入：

• explore: 300 tokens
• propose: 500 tokens
• apply: 400 tokens
• verify: 200 tokens

Channel 多代理协作

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

import { createChannelRuntime, Supervisor } from 'respecpow/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'
);

工作流状态标签

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

import { stageToTag, parseWorkflowStateTag, inferStageFromPath } from 'respecpow/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 结构化合并

借鉴 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 比较，已同步则跳过

模板哈希增量更新

respecpow 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

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/	/respecpow:explore
Cursor	.cursor/rules/	/respecpow-explore
GitHub Copilot	.github/copilot-instructions.md	/respecpow-explore
CodeBuddy	.codebuddy/commands/	/respecpow-explore
Codex	.codex/instructions.md	/respecpow-explore
Gemini CLI	.gemini/instructions.md	/respecpow:explore
Amazon Q	.amazonq/commands/	@respecpow-explore
Cline	.cline/rules/	/respecpow-explore
Continue	.continue/config.md	/respecpow-explore
Windsurf	.windsurf/rules/	/respecpow-explore
Trae	.trae/rules/	/respecpow-explore
Kiro	.kiro/steering/	/respecpow-explore
Qwen	.qwen/instructions.md	/respecpow-explore
Kimi	.kimi/instructions.md	/respecpow-explore
GitHub Copilot Workspace	.github/copilot/	/respecpow-explore
Roo Code	.roo/rules/	/respecpow-explore
Auggie	.auggie/instructions.md	/respecpow-explore
Bob	.bob/rules/	/respecpow-explore
Crush	.crush/instructions.md	/respecpow-explore
Devin	.devin/commands/	@respecpow-explore
Junie	.junie/rules/	/respecpow-explore
Qoder	.qoder/instructions.md	/respecpow-explore

项目结构

specpow/
├── bin/                        # CLI 入口 (specpow.js)
├── src/
│   ├── cli/                    # Commander.js 命令注册
│   ├── commands/               # 23 个命令实现（支持 --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）
├── scripts/
│   └── postinstall.js          # 安装后自动注册 hooks
├── .specpow/
│   ├── schemas/                # 3 套工作流 Schema + 模板
│   ├── skills/                 # 35 个技能（SKILL.md）
│   ├── agents/                 # Agent 定义（通过技能实现）
│   └── hooks/                  # Hook 自动上下文注入
├── test/                       # 860 个测试用例
└── docs/                       # 使用指南

开发

# 安装依赖
pnpm install

# 开发模式（watch）
pnpm dev

# 构建
pnpm build

# 运行测试
pnpm test

# 代码检查
pnpm lint

技术栈

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

License

MIT