spec-superflow

Name: spec-superflow
Author: MageByte-Zero

Verified

源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件。17 平台支持，9 skills，Spec-first，契约驱动。

555stars

56forks

JavaScript

Installation

# Add to your Claude Code skills
git clone https://github.com/MageByte-Zero/spec-superflow

Getting Started

Guides for using cli tools skills like spec-superflow.

Getting Started with AI Skills
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
SkillsLLM Features Guide
Voting, bookmarks, comments, comparison pages, and security scanning explained.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.

Security ReportVerified

Last scanned: 6/30/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-06-30T07:54:01.235Z",
  "npmAuditRan": true,
  "pipAuditRan": true,
  "promptInjectionRan": true
}

README.md

Frequently Asked Questions

What is spec-superflow?

spec-superflow is an open-source cli tools skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by MageByte-Zero. 源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件。17 平台支持，9 skills，Spec-first，契约驱动。. It has 555 GitHub stars.

Is spec-superflow safe to use?

Yes. spec-superflow passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install spec-superflow?

Clone the repository with "git clone https://github.com/MageByte-Zero/spec-superflow" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is spec-superflow written in?

spec-superflow is primarily written in JavaScript. It is open-source under MageByte-Zero on GitHub, so you can review or fork the full source.

Are there alternatives to spec-superflow?

Yes. SkillsLLM lists many other CLI Tools skills you can browse and compare side by side. Open the CLI Tools category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh spec-superflow against similar tools.

LLM Engineer for Beginners

Ship LLM features to production - prompts, RAG, structured outputs, evaluation

39 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

Popular in CLI Tools

Top skills in this category by stars

ui-ux-pro-max-skill

by nextlevelbuilder

An AI SKILL that provide design intelligence for building professional UI/UX multiple platforms

107,079

cc-lens chorus

快速开始

安装后，告诉 Agent 一句话即可启动：

用 workflow-start 开始

Agent 会自动检查当前工件目录，内容级判断（不看文件时间戳，而是比较 proposal 范围 vs 契约意图锁）你处于哪个阶段，然后路由到正确的下一个 skill。

启动新的变更 → 用 workflow-start 开始
恢复旧的变更 → 继续上次的工作流
不确定当前状态 → 帮我看看现在该干什么

安装

Claude Code（Marketplace）

Claude Code 的主流方式是插件 marketplace：

/plugin marketplace add MageByte-Zero/spec-superflow
/plugin install spec-superflow@spec-superflow
/plugin update spec-superflow@spec-superflow

Marketplace 安装自动加载 hooks，每次新会话自动注入上下文。

Cursor（Skills 目录 / GitHub 导入）

# 方式一：通过 ssf CLI
npx spec-superflow@latest install-cursor

# 方式二：直接运行脚本
curl -fsSL https://raw.githubusercontent.com/MageByte-Zero/spec-superflow/main/scripts/install-cursor.mjs | node -

Cursor 原生发现 .cursor/skills/、.agents/skills/、~/.cursor/skills/ 等目录，也可以在 Customize → Rules → Remote Rule (Github) 导入。脚本会自动部署 skills、scripts、docs 等运行时依赖。

OpenAI Codex CLI / App

Codex 的主流方式是 Plugin Directory / marketplace。本仓库已提供 .codex-plugin/plugin.json 和 .agents/plugins/marketplace.json。

# 在 Codex CLI 中打开插件目录
codex
/plugins

# 或添加社区 marketplace 后安装
codex plugin marketplace add hashgraph-online/awesome-codex-plugins
codex plugin add spec-superflow@awesome-codex-plugins

# 直接从指定 release tag 安装（不等待社区镜像同步）
codex plugin marketplace add MageByte-Zero/spec-superflow --ref v0.9.0
codex plugin add spec-superflow@spec-superflow

# 升级并验证社区 marketplace 安装
codex plugin marketplace upgrade awesome-codex-plugins
codex plugin add spec-superflow@awesome-codex-plugins
codex plugin list | rg spec-superflow

Codex App 打开 Plugins 面板，安装或启用 spec-superflow。通过 CLI 安装或升级后，重启 Codex App 并新开会话；旧会话不会热加载 skills。

GitHub Copilot CLI

copilot plugin marketplace add MageByte-Zero/spec-superflow
copilot plugin install spec-superflow@spec-superflow

Gemini CLI

gemini extensions install https://github.com/MageByte-Zero/spec-superflow
gemini extensions update spec-superflow   # 升级

平台	安装方式	状态
Cline	`npx spec-superflow@latest install-cline`	已提供安装器
Kiro	`npx spec-superflow@latest install-kiro`	已提供安装器
Windsurf	`npx spec-superflow@latest install-windsurf`	已提供安装器
Qwen Code	`npx spec-superflow@latest install-qwen`	已提供安装器
Amazon Q Developer	`npx spec-superflow@latest install-amazon-q`	已提供安装器
Roo Code	`npx spec-superflow@latest install-roocode`	已提供安装器
Continue	`npx spec-superflow@latest install-continue`	已提供安装器
Pi	`npx spec-superflow@latest install-pi`	已提供安装器
Qoder	`npx spec-superflow@latest install-qoder`	已提供安装器
OpenCode	`.opencode/plugins/spec-superflow.js` 或 `.agents/skills -> skills/`	已提供入口
WorkBuddy	`npx spec-superflow@latest install-workbuddy`	已提供安装器
Trae IDE / TRAE Work	`.trae/skills/`、`~/.trae/skills/` 或上传 zip/.skill	手动/导入

CLI 工具链

npm install -g spec-superflow    # 全局安装
npx spec-superflow list          # 或通过 npx 使用

命令	功能
`ssf list`	列出所有 changes 及状态
`ssf validate <dir>`	验证工件完整性
`ssf doctor`	健康检查（版本、hooks、skills、文档一致性）
`ssf version <semver>`	一键同步版本号到所有 manifest
`ssf state <sub> <dir>`	管理 `.spec-superflow.yaml` 状态文件
`ssf inject <dir>`	生成 phase-guard 产物；仅在检测到单一平台标记时可省略 `--platforms`
`ssf audit <dir>`	生成决策点审计报告
`ssf checkpoint save <dir> --task <id> --next <text>`	保存任务级会话恢复点
`ssf checkpoint list <dir>`	列出 checkpoint 及 stale 状态
`ssf checkpoint show <dir> <id>`	查看单个恢复点
`ssf handoff create <dir> --type <type> ...`	创建 prototype/research/experiment handoff
`ssf handoff list <dir>`	列出 handoff 生命周期状态
`ssf handoff finish <dir> <id>`	校验 handoff 结果
`ssf handoff resolve <dir> <id> --decision <decision>`	记录显式 handoff 决策
`ssf execution recommend <dir> ...`	基于任务量、wave 和工作流列出可用执行方式并给出推荐
`ssf execution plan <dir> ...`	在用户确认选择后，为 full/hotfix 保存受 guard 保护的执行计划
`ssf execution show <dir> [--json]`	查看并校验当前执行计划、wave 与 receipt
`ssf execution revise <dir> ...`	将已有计划保留/升级为 SDD，并生成新 revision；不允许降级
`ssf execution review <dir> ...`	为一个计划 wave 记录 review receipt
`ssf install-cursor`	部署到 Cursor `.cursor/` 目录
`ssf install-workbuddy`	部署到 WorkBuddy marketplace 插件（含 skills/rules/runtime）
`ssf install-cline`	部署到 Cline `.cline/` + `.clinerules/`
`ssf install-kiro`	部署到 Kiro `.kiro/` + `.kiro/steering/`
`ssf install-windsurf`	部署到 Windsurf `.windsurf/` + `.windsurf/rules/`
`ssf install-qwen`	部署到 Qwen Code `.qwen/` + `.qwen/rules/`
`ssf install-amazon-q`	部署到 Amazon Q `.amazonq/` + `.amazonq/rules/`
`ssf install-roocode`	部署到 Roo Code `.roo/` + `.roo/rules/`
`ssf install-continue`	部署到 Continue `.continue/` + `.continue/rules/`
`ssf install-pi`	部署到 Pi `.pi/skills/`（无规则目录）
`ssf install-qoder`	部署到 Qoder `.qoder/` + `.qoder/rules/`

版本

当前版本：v0.10.0
v0.9.1 highlights：DP-4 执行模式推荐、跨 17 个平台的 portable runtime，以及无插件根路径的 raw-package smoke；详见 CHANGELOG.md
v0.9.0 highlights：支持 Node 20/22、model profiles 只读解析，以及 code-reviewer 的最小性审查
自包含插件，不需要运行时安装 OpenSpec 或 Superpowers
上游来源：Fission-AI/OpenSpec 和 obra/superpowers
版本历史见 CHANGELOG.md

ssf inject 示例：

ssf inject changes/my-change --platforms cursor
ssf inject changes/my-change --platforms all

省略 --platforms 时，只有在项目中恰好检测到一个平台标记时才会自动写入；如果检测到多个平台，必须显式指定 --platforms <platform> 或 --platforms all。

会话恢复与可选 prototype：

ssf checkpoint save changes/my-change --task 1.1 --next "Run focused tests"
ssf checkpoint list changes/my-change
ssf handoff create changes/my-change --type research --objective "Compare approaches" --expected-output "Recommendation" --acceptance "Evidence recorded"

Prototype 只在用户明确确认后创建；后端、CLI、配置和内部重构不会自动进入 prototype 流程。handoff 结果不会自动修改 design.md 或 tasks.md。

Delta spec 的规范路径是 specs/<capability>/spec.md；扁平的 specs/<capability>.md 和根级 specs/spec.md 不会被视为合法规范。

受 guard 保护的执行计划

对 full/hotfix，DP-4 不是一段任意文本：开始实现前必须保存并校验 current execution plan。它位于 <change>/.superpowers/sdd/execution-plan.json，不写入 execution-contract.md。先运行 ssf execution recommend，它会根据任务量和 wave 策略列出 inline、batch-inline、sdd，并给出可审计的推荐理由，同时把当前 wave 的推荐凭据保存为 <change>/.superpowers/sdd/execution-recommendation.json；Agent 必须将这些候选项和推荐展示给用户。plan 或 revise 只接受匹配当前 artifact、contract 和 wave 的凭据。用户用 --confirm 明确确认选择；若选择与推荐不同，必须额外传入 --acknowledge-recommendation 记录已知风险。Batch Inline 始终串行，绝不冒充并行。 tweak 保持轻量例外，不要求 execution plan 或 wave receipt。

ssf execution recommend changes/my-change \
  --wave foundation:parallel:1.1,1.2 \
  --wave integration:serial:2.1:foundation --json
ssf execution plan changes/my-change --mode sdd --confirm --reason "independent work" \
  --wave foundation:parallel:1.1,1.2 \
  --wave integration:serial:2.1:foundation
ssf execution show changes/my-change --json
# 将已有 inline/batch-inline 计划升级为 sdd，或重规划已有 sdd 计划；不能降级。
# 每次修订都会生成新 revision 并清除旧 review receipt。
ssf execution recommend changes/my-change \
  --wave foundation:parallel:1.1,1.2 \
  --wave integration:serial:2.1:foundation --json
ssf execution revise changes/my-change --mode sdd --confirm --reason "need parallel work" \
  --wave foundation:parallel:1.1,1.2 \
  --wave integration:serial:2.1:foundation
# 每个 wave 都先写入非空 review report，再记录 receipt。
ssf execution review changes/my-change --wave foundation --base <sha> --head <sha> \
  --report .superpowers/sdd/reviews/foundation.md --verdict pass

--report 相对于 <change> 解析，且必须位于 <change>/.superpowers/sdd/reviews/ 之下。--base 和 --head 必须是该 <change> Git 工作树中的真实 commit，且 base 必须是 head 的祖先。 <change>/.superpowers/sdd/reviews/ 的目录层级必须是物理、非符号链接目录； report 本身必须为普通、非空、非符号链接文件。

每个 wave 的 review receipt 必须是当前 revision 的 pass，依赖 wave 和 closing 才会放行；修订计划会使旧 receipt 失效。恢复、切换和手动保存等 #47 的 slash command 尚未实现，不能据此假定存在 /ssf:* 命令。

为什么需要它

用 AI 写代码时，最常碰到两个失控点：

还没想清楚要做什么，AI 就开始写代码。 你说了句"帮我加个权限控制"，它就开始改几十个文件。改到一半才发现 —— 到底要 RBAC 还是 ABAC？
规划文档写得明明白白，但执行阶段还是会跑偏。 proposal 写了、design 画了，但实现过程中没人盯着测试、没人卡 review，等到合并才发现行为不对。

spec-superflow 在这两个失控点之间建起一道硬墙： 需求澄清 → 工件沉淀（Schema 引擎验证格式）→ 执行契约桥接 → TDD + SDD + Review Gate 三重纪律强制执行 → 验证收口 → delta spec 同步防止规范腐烂。

设计原则	说明
Spec First	没有稳定的规划工件，不允许进入实现
Guarded Handoff	`execution-contract.md` 是规划到实现的唯一交接层
Strong Guardrails	实现中违反契约的行为被明确拦截并回退
Schema Validated	规划期工件经过 Schema 引擎验证
Execute Disciplined	TDD 铁律 + SDD 子代理驱动 + Review Gate
Self-Contained	不需要安装 OpenSpec 或 Superpowers，一个插件全包

适用场景

✅ 推荐： 大型功能开发、多人协作项目、长期维护项目、需要 TDD + Review Gate 的棕地项目。

❌ 不推荐： 一次性脚本/工具、纯咨询/问答。

v0.6.0 起自动模式检测：hotfix（≤2 文件，最小契约 + DP-3 后执行）和 tweak（≤4 文件，纯配置/文档，直接编辑）让小型变更也能高效使用。

核心 Skills

| # | Skill | 阶段 | 职责 | |---|--