spec-first-superpowers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec-First + Superpowers Orchestrator v4

规范先行 + 超级能力编排器 v4

Stop the AI from jumping straight to code. Every feature, bugfix, and refactor goes through a specification phase first — because unexamined code is expensive code.

阻止AI直接生成代码。所有功能开发、漏洞修复、重构工作都必须先经过规范设计阶段——因为未经论证的代码会产生极高的成本。

Commands

命令

Command	Effect
`/super-spec`	Full workflow (auto mode + auto complexity)
`/super-spec force-spec-kit`	Force Spec-Kit mode
`/super-spec force-openspec`	Force OpenSpec mode
`/super-spec reset`	Reset mode selection

命令	作用
`/super-spec`	完整工作流（自动模式 + 自动复杂度判定）
`/super-spec force-spec-kit`	强制使用Spec-Kit模式
`/super-spec force-openspec`	强制使用OpenSpec模式
`/super-spec reset`	重置模式选择

How It Works

工作原理

Step 1: Pick a Mode

步骤1：选择模式

Check for existing signals, then fall back to heuristics:

Signal	Mode
`.spec-mode` file exists	Use whatever it says
`.specify/` directory	Spec-Kit
`openspec/` directory	OpenSpec
Brand new project, < 30 files	Spec-Kit
Everything else	OpenSpec (default)

Save the choice to

.spec-mode

so future sessions remember it.

For detailed mode workflows, read:

Spec-Kit: references/spec-kit-workflow.md
OpenSpec: references/openspec-workflow.md

先检查现有信号，无匹配则按启发式规则判定：

信号	模式
存在 `.spec-mode` 文件	采用文件中指定的模式
存在 `.specify/` 目录	Spec-Kit
存在 `openspec/` 目录	OpenSpec
全新项目，文件数 < 30	Spec-Kit
其他所有情况	OpenSpec（默认）

将选择结果保存到

.spec-mode

文件中，后续会话可直接复用。

如需了解各模式的详细工作流，请阅读：

Spec-Kit: references/spec-kit-workflow.md
OpenSpec: references/openspec-workflow.md

Step 2: Triage Complexity

步骤2：复杂度分级

The AI suggests a level; the user confirms or overrides.

Level	When	What happens
Quick	Single-file bugfix, typo, config	Simplified spec ( `/opsx:propose` or `/opsx:ff` ) → TDD → archive
Standard	Single feature, clear scope	All phases (Phase 3 only if UI)
Thorough	Multi-module, architecture decisions	All phases + Agent Teams evaluation

AI会建议复杂度等级，用户可确认或修改：

等级	适用场景	执行流程
快速	单文件漏洞修复、打字错误、配置修改	简化版规范（ `/opsx:propose` 或 `/opsx:ff` ）→ TDD → 归档
标准	单个功能、需求范围清晰	全流程执行（仅涉及UI时执行阶段3）
全面	多模块改动、涉及架构决策	全流程 + Agent团队评估

Step 3: Execute the Pipeline

步骤3：执行流水线

Phase 0 — Session Recovery (automatic) If

task_plan.md

exists from a previous session, read all planning files, run the 5-Question Reboot Test (Where am I? / Where am I going? / What's the goal? / What did I learn? / What did I do?), then resume from the last checkpoint.

Phase 1 — Specification Write the spec using the selected mode. Quick tasks use

/opsx:propose

; standard/thorough use the full flow with

/opsx:explore

/speckit.specify

. The user must explicitly confirm the spec before moving on. Gate G1: User confirmed + spec aligns with constitution + spec review loop passed + scope check done.

Phase 2 — Persistent Planning Generate

task_plan.md

(numbered checklist with file structure mapping + test points),

findings.md

, and

progress.md

using

planning-with-files

writing-plans

. Gate G2: Every task has file paths + acceptance criteria + test strategy + plan review loop passed.

Phase 3 — UI/UX Design (conditional) Triggered only when UI keywords are detected. Invoke

ui-ux-pro-max --design-system --persist

to generate and persist the design system (v2.0: 67 styles, 161 palettes, 57 fonts, 13 tech stacks). Gate G3: Pre-delivery checklist passed + user confirmed design.

Phase 4 — Implementation Execute via one of two strategies (AI recommends, user picks):

Subagent-Driven: Fresh subagent per task + two-stage review (spec conformance → code quality) + model selection per task role + implementer status handling (DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED)
Executing-Plans: Batch execution + checkpoint reviews

TDD throughout. Errors escalate through the 3-Strike protocol →

systematic-debugging

. Gate G4: All tests pass + review passed + verification evidence written to

progress.md

/opsx:verify

passed (if available).

Phase 5 — Archive

finishing-a-development-branch

→ update all checkboxes → archive spec artifacts → final

progress.md

entry.

阶段0 — 会话恢复（自动执行）如果上一次会话遗留了

task_plan.md

文件，读取所有规划文件，运行5问重启测试（我当前进度到哪？/我要完成什么？/目标是什么？/我已经获得了哪些信息？/我已经做了什么？），然后从最后一个检查点恢复执行。

阶段1 — 规范设计 使用选定的模式编写规范。快速任务使用

/opsx:propose

；标准/全面任务使用完整流程，执行

/opsx:explore

或

/speckit.specify

。进入下一阶段前必须获得用户对规范的明确确认。 Gate G1: 用户已确认 + 规范符合章程 + 规范评审循环通过 + 范围校验完成。

阶段2 — 持久化规划 使用

planning-with-files

writing-plans

生成

task_plan.md

（带文件结构映射和测试点的编号检查清单）、

findings.md

和

progress.md

。 Gate G2: 所有任务都包含文件路径 + 验收标准 + 测试策略 + 方案评审循环通过。

阶段3 — UI/UX设计（条件触发）仅当检测到UI相关关键词时触发。调用

ui-ux-pro-max --design-system --persist

生成并持久化设计系统（v2.0版本：67种样式、161套配色、57种字体、13种技术栈）。 Gate G3: 交付前检查清单通过 + 用户已确认设计方案。

阶段4 — 开发实现 通过两种策略之一执行（AI推荐，用户选择）：

子Agent驱动：每个任务分配全新的子Agent + 两阶段评审（规范符合性 → 代码质量） + 按任务角色选择模型 + 处理实现者状态（DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED）
方案执行：批量执行 + 检查点评审

全流程执行TDD。错误按3次警告规则升级处理 → 调用

systematic-debugging

。 Gate G4: 所有测试通过 + 评审通过 + 验证结果已写入

progress.md

/opsx:verify

通过（如可用）。

阶段5 — 归档 执行

finishing-a-development-branch

→ 更新所有检查框 → 归档规范产物 → 写入

progress.md

最终条目。

Quality Gates

质量门

Each gate is a hard stop — nothing moves forward until all checks pass. If a gate fails, fix the issue and re-evaluate. Full gate criteria: references/quality-gates.md

每个质量门都是硬性卡点——所有检查通过前不得进入下一阶段。如果质量门不通过，修复问题后重新评估。完整的质量门标准：references/quality-gates.md

Anti-Rush Protection

防抢跑保护

If the user asks to skip the spec phase, politely decline and redirect to

/super-spec

. The whole point of this skill is preventing premature implementation.

如果用户要求跳过规范阶段，礼貌拒绝并引导使用

/super-spec

。本技能的核心目标就是避免过早实现功能。

Reference Files

参考文件

Read these as needed — they contain detailed procedures that would bloat this file:

File	When to read
references/quality-gates.md	Evaluating any gate (G0-G4)
references/synergy-patterns.md	Understanding cross-tool integration
references/integration-guide.md	Setup, troubleshooting, dependency list
references/spec-kit-workflow.md	Running the Spec-Kit flow
references/openspec-workflow.md	Running the OpenSpec flow
assets/constitutions/openspec-constitution.md	OpenSpec constitution template
assets/constitutions/spec-kit-constitution.md	Spec-Kit constitution template

按需读取以下文件——它们包含了会导致本文档过于臃肿的详细流程：

文件	读取场景
references/quality-gates.md	评估任意质量门（G0-G4）时
references/synergy-patterns.md	了解跨工具集成逻辑时
references/integration-guide.md	安装配置、故障排查、查看依赖列表时
references/spec-kit-workflow.md	运行Spec-Kit流程时
references/openspec-workflow.md	运行OpenSpec流程时
assets/constitutions/openspec-constitution.md	OpenSpec章程模板
assets/constitutions/spec-kit-constitution.md	Spec-Kit章程模板