{"id":51403082,"url":"https://github.com/magebyte-zero/spec-superflow","last_synced_at":"2026-07-04T09:00:39.815Z","repository":{"id":367473372,"uuid":"1280958966","full_name":"MageByte-Zero/spec-superflow","owner":"MageByte-Zero","description":"连通需求说清楚和代码写对路的 AI 编程工作流插件。整合 OpenSpec 规划 + Superpowers 纪律，7 平台支持，Spec-first，契约驱动。","archived":false,"fork":false,"pushed_at":"2026-07-03T12:06:47.000Z","size":511,"stargazers_count":196,"open_issues_count":1,"forks_count":13,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-07-03T12:26:44.774Z","etag":null,"topics":["7-platforms","ai-coding","claude-code","codex","copilot-cli","cursor","gemini-cli","opencode","opensource","openspec","skills","spec-driven-development","superpowers","tdd","trae","workflow"],"latest_commit_sha":null,"homepage":"https://github.com/MageByte-Zero/spec-superflow","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MageByte-Zero.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-26T05:13:03.000Z","updated_at":"2026-07-03T12:06:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MageByte-Zero/spec-superflow","commit_stats":null,"previous_names":["magebyte-zero/spec-superflow"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/MageByte-Zero/spec-superflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MageByte-Zero%2Fspec-superflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MageByte-Zero%2Fspec-superflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MageByte-Zero%2Fspec-superflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MageByte-Zero%2Fspec-superflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MageByte-Zero","download_url":"https://codeload.github.com/MageByte-Zero/spec-superflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MageByte-Zero%2Fspec-superflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35115742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["7-platforms","ai-coding","claude-code","codex","copilot-cli","cursor","gemini-cli","opencode","opensource","openspec","skills","spec-driven-development","superpowers","tdd","trae","workflow"],"created_at":"2026-07-04T09:00:17.163Z","updated_at":"2026-07-04T09:00:39.800Z","avatar_url":"https://github.com/MageByte-Zero.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003espec-superflow\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MageByte-Zero/spec-superflow/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/MageByte-Zero/spec-superflow\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/spec-superflow\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/spec-superflow\" alt=\"npm version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#快速开始\"\u003e快速开始\u003c/a\u003e |\n  \u003ca href=\"#安装\"\u003e安装\u003c/a\u003e |\n  \u003ca href=\"#为什么需要它\"\u003e为什么\u003c/a\u003e |\n  \u003ca href=\"#核心-skills\"\u003eSkills\u003c/a\u003e |\n  \u003ca href=\"#工作流\"\u003e工作流\u003c/a\u003e |\n  \u003ca href=\"docs/README_en.md\"\u003eEnglish\u003c/a\u003e |\n  \u003ca href=\"docs/showcase.html\"\u003eShowcase\u003c/a\u003e |\n  \u003ca href=\"#常见问题\"\u003eFAQ\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 快速开始\n\n安装后，告诉 Agent 一句话即可启动：\n\n```\n用 workflow-start 开始\n```\n\nAgent 会自动检查当前工件目录，**内容级判断**（不看文件时间戳，而是比较 proposal 范围 vs 契约意图锁）你处于哪个阶段，然后路由到正确的下一个 skill。\n\n- 启动新的变更 → `用 workflow-start 开始`\n- 恢复旧的变更 → `继续上次的工作流`\n- 不确定当前状态 → `帮我看看现在该干什么`\n\n## 安装\n\n### Claude Code（Marketplace）\n\nClaude Code 的主流方式是插件 marketplace：\n\n```bash\n/plugin marketplace add MageByte-Zero/spec-superflow\n/plugin install spec-superflow@spec-superflow\n/plugin update spec-superflow@spec-superflow\n```\n\nMarketplace 安装自动加载 hooks，每次新会话自动注入上下文。\n\n### Cursor（Skills 目录 / GitHub 导入）\n\n```bash\n# 方式一：通过 ssf CLI\nnpx spec-superflow@latest install-cursor\n\n# 方式二：直接运行脚本\ncurl -fsSL https://raw.githubusercontent.com/MageByte-Zero/spec-superflow/main/scripts/install-cursor.mjs | node -\n```\n\n\u003e Cursor 原生发现 `.cursor/skills/`、`.agents/skills/`、`~/.cursor/skills/` 等目录，也可以在 Customize → Rules → Remote Rule (Github) 导入。脚本会自动部署 skills、scripts、docs 等运行时依赖。\n\n### OpenAI Codex CLI / App\n\nCodex 的主流方式是 Plugin Directory / marketplace。本仓库已提供 `.codex-plugin/plugin.json` 和 `.agents/plugins/marketplace.json`。\n\n```bash\n# 在 Codex CLI 中打开插件目录\ncodex\n/plugins\n\n# 或添加社区 marketplace 后安装\ncodex plugin marketplace add hashgraph-online/awesome-codex-plugins\ncodex plugin add spec-superflow@spec-superflow\n```\n\nCodex App 打开 **Plugins** 面板，安装或启用 `spec-superflow`。如果通过 CLI 安装，重启 App 后在 Plugins 面板启用。\n\n### GitHub Copilot CLI\n\n```bash\ncopilot plugin marketplace add MageByte-Zero/spec-superflow\ncopilot plugin install spec-superflow@spec-superflow\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/MageByte-Zero/spec-superflow\ngemini extensions update spec-superflow   # 升级\n```\n\n### OpenCode / WorkBuddy / Trae\n\n| 平台 | 安装方式 | 状态 |\n|------|---------|------|\n| **OpenCode** | `.opencode/plugins/spec-superflow.js` 或 `.agents/skills -\u003e skills/` | 已提供入口 |\n| **WorkBuddy** | `npx spec-superflow@latest install-workbuddy` | 已提供安装器 |\n| **Trae IDE / TRAE Work** | `.trae/skills/`、`~/.trae/skills/` 或上传 zip/.skill | 手动/导入 |\n\n\u003e 完整安装说明见 [INSTALL.md](INSTALL.md)。\n\n### CLI 工具链\n\n```bash\nnpm install -g spec-superflow    # 全局安装\nnpx spec-superflow list          # 或通过 npx 使用\n```\n\n| 命令 | 功能 |\n|------|------|\n| `ssf list` | 列出所有 changes 及状态 |\n| `ssf validate \u003cdir\u003e` | 验证工件完整性 |\n| `ssf doctor` | 健康检查（版本、hooks、skills、文档一致性） |\n| `ssf version \u003csemver\u003e` | 一键同步版本号到所有 manifest |\n| `ssf state \u003csub\u003e \u003cdir\u003e` | 管理 `.spec-superflow.yaml` 状态文件 |\n| `ssf inject \u003cdir\u003e` | 生成多平台 phase-guard 产物 |\n| `ssf audit \u003cdir\u003e` | 生成决策点审计报告 |\n| `ssf install-cursor` | 部署到 Cursor `.cursor/` 目录 |\n| `ssf install-workbuddy` | 部署到 WorkBuddy marketplace 并启用技能 |\n\n### 版本\n\n- 当前版本：`v0.8.9`\n- 自包含插件，不需要运行时安装 OpenSpec 或 Superpowers\n- 上游来源：[Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) 和 [obra/superpowers](https://github.com/obra/superpowers)\n- 版本历史见 [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## 为什么需要它\n\n用 AI 写代码时，最常碰到两个失控点：\n\n- **还没想清楚要做什么，AI 就开始写代码。** 你说了句\"帮我加个权限控制\"，它就开始改几十个文件。改到一半才发现 —— 到底要 RBAC 还是 ABAC？\n\n- **规划文档写得明明白白，但执行阶段还是会跑偏。** proposal 写了、design 画了，但实现过程中没人盯着测试、没人卡 review，等到合并才发现行为不对。\n\n**spec-superflow 在这两个失控点之间建起一道硬墙：** 需求澄清 → 工件沉淀（Schema 引擎验证格式）→ 执行契约桥接 → TDD + SDD + Review Gate 三重纪律强制执行 → 验证收口 → delta spec 同步防止规范腐烂。\n\n| 设计原则 | 说明 |\n|---|---|\n| Spec First | 没有稳定的规划工件，不允许进入实现 |\n| Guarded Handoff | `execution-contract.md` 是规划到实现的唯一交接层 |\n| Strong Guardrails | 实现中违反契约的行为被明确拦截并回退 |\n| Schema Validated | 规划期工件经过 Schema 引擎验证 |\n| Execute Disciplined | TDD 铁律 + SDD 子代理驱动 + Review Gate |\n| Self-Contained | 不需要安装 OpenSpec 或 Superpowers，一个插件全包 |\n\n### 适用场景\n\n**✅ 推荐：** 大型功能开发、多人协作项目、长期维护项目、需要 TDD + Review Gate 的棕地项目。\n\n**❌ 不推荐：** 一次性脚本/工具、纯咨询/问答。\n\n\u003e **v0.6.0 起自动模式检测**：hotfix（≤2 文件，自动跳过规划）和 tweak（≤4 文件，纯配置/文档，直接编辑）让小型变更也能高效使用。\n\n---\n\n## 核心 Skills\n\n| # | Skill | 阶段 | 职责 |\n|---|---|---|---|\n| 1 | `workflow-start` | 入口 | 内容级状态检测、8 状态路由、阻止非法跳转 |\n| 2 | `need-explorer` | 探索 | 一次一问 + 方案对比 + 推荐 |\n| 3 | `spec-writer` | 规格 | 产出 proposal/specs/design/tasks，Schema 引擎实时验证 |\n| 4 | `contract-builder` | 桥接 | 解析引擎自动提取 4 工件 → 压缩为 execution-contract.md |\n| 5 | `build-executor` | 执行 | TDD 铁律 + SDD 子代理驱动 + Review Gate |\n| 6 | `bug-investigator` | 调试 | 4 阶段根因分析，3+ 修复失败 → 质疑架构 |\n| 7 | `code-reviewer` | 审查 | 结构化审查，三级问题分级 |\n| 8 | `release-archivist` | 收口 | 验证前完成铁律 + 归档 + 风险总结 |\n| 9 | `spec-merger` | 同步 | Delta Spec → 主规范智能合并 |\n\n---\n\n## 工作流\n\n```text\n你说\"帮我加一个权限控制\"\n       │\n       ▼\n   workflow-start     ← 唯一入口。内容级状态检测、路由到正确 skill\n       │\n       ▼\n   exploring          need-explorer：\"你要 RBAC 还是 ABAC？多大粒度？\"\n       ▼\n   specifying         spec-writer 产出 4 份工件 + Schema 引擎验证\n       ▼\n   bridging           contract-builder 自动提取 → execution-contract.md\n       │\n  ◇ 用户批准 ◇         ← 唯一一次人工介入\n       │\n       ▼\n   executing          build-executor: TDD → SDD → Review Gate\n       │\n       ├──[bug]──→ debugging  → bug-investigator\n       ▼\n   closing            release-archivist 验证 + 归档\n       ▼\n   syncing            spec-merger（delta spec → 主规范）\n```\n\n**关键约束：** 没有 `execution-contract.md` 或未被批准 → 不允许实现；需求变更 → 强制回退；遇到 bug → 强制走 debugging，不允许\"随便试试\"。\n\n### 快速路径（hotfix / tweak）\n\n- **hotfix** — ≤2 文件、无新模块时，跳过完整 spec-writer，走最小契约 → inline 执行\n- **tweak** — ≤4 文件、纯配置/文档修改时，跳过规划+桥接，直接编辑\n\n---\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003espec-superflow 和 OpenSpec / Superpowers 什么关系？\u003c/strong\u003e\u003c/summary\u003e\n\n源码级融合，不是简单并列。吸收了两者的引擎（Schema/验证/解析 + TDD/SDD/调试/审查），独创了 contract-builder 桥接层和 8 状态路由。自包含，不需要安装上游运行时。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e能和我已有的 OpenSpec 或 Superpowers 共存吗？\u003c/strong\u003e\u003c/summary\u003e\n\n建议不要在同一会话混用。已有 OpenSpec 工件目录的项目可以直接用 spec-superflow 接管 —— `contract-builder` 能读取现有文件生成 execution contract。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eexecution contract 怎么知道该更新了？\u003c/strong\u003e\u003c/summary\u003e\n\n内容级检测（不是文件时间戳）：proposal 范围变了、specs 已批准需求改了、design 架构约束变了、tasks 批次变了 → 视为过时，回退到 `contract-builder`。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSDD (Subagent-Driven Development) 怎么工作的？\u003c/strong\u003e\u003c/summary\u003e\n\n每任务循环：派实施子代理 → 生成 review diff → 派审查子代理 → 双向判断（spec 合规 + 代码质量）→ 不合格 → 修复 → 重新审查。进度台账防止会话压缩后丢失进度。\n\n\u003c/details\u003e\n\n---\n\n**Star 一下，下次需要的时候能找到。**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagebyte-zero%2Fspec-superflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagebyte-zero%2Fspec-superflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagebyte-zero%2Fspec-superflow/lists"}