spec-stack

spec-stack — 编写 → 冻结 → 运行，经过验证

spec-stack 组合了三种技能，分别负责规格驱动交付的不同层面，并避免它们争抢同一项工作：

层面	技能	负责内容
规格（是什么）	spec-kit	通过 /speckit.constitution → specify → plan → tasks 生成供人阅读的 SDD 文档；可在 30 多种 Agent 之间共享
循环（直到完成）	ooo	通过苏格拉底式访谈将歧义降至 ≤ 0.2，生成不可变种子、测量偏移，并持久运行“验证后再完成”的循环（ralph）
工具（用什么）	cli-anything	为真实软件提供原生支持 Agent 的 CLI — CLI-Hub 注册表、--json 输出、工件级验证

这套栈只有一条规则：spec-kit 负责编写，ooo 负责冻结并循环，cli-anything 负责动手。 每一层都会向下一层交付具体工件 — spec.md/plan.md 为种子访谈提供输入，种子指定循环可使用的工具框架，而工具框架的 --json 输出则是 evaluate 步骤接受的证据。

何时使用此技能

• 用户需要从书面规格到经过验证的工件的完整流程，而不只是使用这三种工具中的一种
• 用户询问 spec-kit 和 ooo 应如何协同工作（谁负责规格，谁负责完成），或如何避免重复编写规格
• 实现必须在经过验证的循环中驱动真实软件（图像/视频/办公/3D/GIS/游戏工具），而不是一次性生成代码
• 用户提到“spec-stack”、“write freeze run”，或在一个工作流中同时提到 spec-kit、ooo、cli-anything 中的两种或更多

何时不使用此技能

• 只需为一个或多个 Agent 编写 SDD 文档 → 使用 spec-kit
• 只需一个持续验证直到完成的循环，且没有文档工件 → 使用 ooo
• 只需安装或生成 CLI 工具框架 → 使用 cli-anything
• 决定接下来需要哪个规划工件（简报、PRD、架构）→ 使用 bmad
• 对现有计划或差异进行人工审查/批准 → 使用 plannotator

前置条件

要求	备注
Python 3.11+	specify-cli 需要 3.11+；CLI-Hub 需要 3.10+
uv（推荐）或 pipx/pip	用于通过 scripts/install.sh 安装这三种工具
一种受支持的 AI Agent	Claude Code、Codex、Gemini、Cursor、opencode、…
目标软件（模式 A）	工具框架会调用真实后端 — 也要安装上游应用

说明

步骤 0 — 选择组合模式

模式	适用情况	层面
A — 全栈	涉及真实软件、需要共享文档和经过验证的循环的中型及以上工作	spec-kit → ooo → cli-anything
B — 仅循环	单次会话中“持续进行直到验证通过”，且没有文档交付物	ooo（涉及软件时加上 cli-anything）
C — 仅文档	多 Agent/团队需要 .specify/ 工件；完成情况由其他机制强制保障	spec-kit

如果用户没有指定模式，则在涉及外部软件或验收证据时默认使用 A；仅代码且需要持久运行时使用 B；需要交接文档时使用 C。

步骤 1 — 安装这套工具栈

bash scripts/install.sh                      # specify-cli + cli-anything-hub
SPEC_STACK_OOO=1 bash scripts/install.sh     # also pip-install ouroboros-ai

在 Claude Code 上，优先使用 ooo 插件而不是 pip： claude plugin marketplace add Q00/ouroboros。使用 specify --version、cli-hub list 和 ouroboros --help（或 ouroboros_* MCP 工具）进行验证。

步骤 2 — 编写规格（spec-kit）

specify init . --integration claude

然后在 Agent 中依次运行：/speckit.constitution → /speckit.specify → /speckit.clarify（仅当仍有未解决问题时）。在 /speckit.implement 之前停止 — 在模式 A 中，实现属于循环层。 将成功标准写成可由机器检查的陈述 （“输出 PNG 为 1024×1024，通过像素检查验证”），而不是凭感觉描述 （“图像看起来不错”）— 步骤 3 和步骤 5 都依赖这一点。

步骤 3 — 冻结契约（ooo）

将 spec.md/plan.md 输入 ooo 访谈（侧重棕地项目）， 将歧义度控制在 ≤ 0.2，然后生成不可变种子：

ouroboros interview --context .specify/   # or MCP: ouroboros_interview
ouroboros seed generate                   # or MCP: ouroboros_generate_seed

让整个技术栈顺利运作的两条种子规则：

1. 成功标准应以机器可检查的形式映照规范的验收标准—— evaluate 步骤会要求提供证据。
2. 约束要指明工具：例如，“图像操作通过 cli-anything-gimp harness 执行；GUI 自动化不在契约范围内。”这 会让工具偏移变成可衡量的规范偏移。

从此以后，种子就是执行 SSOT；spec.md 仍是文档 SSOT。方向是单向的：spec-kit → seed。如果需求变更， 先更新规范，再重新冻结。

步骤 4 — 准备好工具（cli-anything）

编写集成代码之前，先搜索注册表：

cli-hub search <keyword>     # 40+ harnesses exist — seconds, not a session
cli-hub install <name>       # install the harness + the upstream app

只有在注册表中找不到匹配项时，才生成：/cli-anything <path-or-repo> （7 阶段流水线），然后按需运行 /cli-anything:refine。生成是 后备方案，不是默认选择。

步骤 5 — 运行循环

ouroboros run        # or MCP: ouroboros_execute_seed; ralph for persistence
ouroboros evaluate   # or MCP: ouroboros_evaluate

在 evaluate 步骤中，验证产物，而不是退出代码：使用 harness 的 --json 输出、魔数、文档结构或像素／音频检查作为证据——这与 cli-anything 自身测试套件 采用的严谨方法一致。如果失败，循环会继续；如果反复失败，则使用 ooo 的 unstuck 步骤，而不是盲目重试。想使用 spec-kit 任务清单的 Pattern A 用户， 可以在循环中按任务运行 /speckit.implement——完成与否仍由种子把关。

步骤 6 — 以插件方式与 jeo-skills 一同安装

# Project install (writes into .agents/skills/spec-stack/)
npx skills add https://github.com/akillness/jeo-skills --skill spec-stack

# Global install for every detected agent
npx skills add -g https://github.com/akillness/jeo-skills --skill spec-stack

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill spec-stack -a claude-code -a codex -y

安装 spec-stack 不会自动安装三个层级的技能； 按需用相同方式安装缺少的技能（--skill spec-kit、--skill ooo、 --skill cli-anything）。

输出格式

用户请求 spec-stack 提供帮助时，返回一份简明说明：

# spec-stack Routing Brief

## Scope
- Pattern: full-stack | loop-only | docs-only
- Target software: <name> | none | undecided
- Stack state: nothing-installed | spec-written | seed-frozen | tools-armed | loop-running

## Recommended next move
- install-stack | specify-init | write-spec | freeze-seed | hub-search | run-loop | evaluate

## Why
- 2-3 bullets grounded in the user's packet

## Route-outs
- `spec-kit` / `ooo` / `cli-anything` for single-layer work
- `bmad` for choosing the next planning artifact
- `plannotator` for human plan approval before implement

示例

示例 1 — Pattern A 端到端（针对真实软件的图像流水线）

bash scripts/install.sh                      # specify-cli + cli-anything-hub
specify init . --integration claude          # spec layer
# in the agent: /speckit.constitution → /speckit.specify → /speckit.clarify
ouroboros interview --context .specify/      # loop layer: drive ambiguity ≤ 0.2
ouroboros seed generate                      #   freeze; criteria mirror spec.md
cli-hub search image && cli-hub install gimp # tool layer: registry first
ouroboros run                                # implement against the seed
ouroboros evaluate                           # verify --json artifacts, loop on fail

示例 2 — 为含糊的组合请求确定路由

用户：“我想同时用 spec-kit 和 ooo，该从哪里开始？” → 返回 Routing Brief，其中包含 Pattern: full-stack、 Stack state: nothing-installed、Recommended next move: install-stack， 并保留路由转接信息。不要启动 /speckit.implement—— 在 Pattern A 中，是否完成由 ooo 循环决定。

示例 3 — 应转接出去的擦边请求

用户：“只帮我制作 GIMP 用的 CLI harness” → 单层工作；转交给 cli-anything（先搜索注册表），无需种子或规范流程。

最佳实践

1. 每项关注点对应一个 SSOT——spec.md 是文档 SSOT，seed.yaml 是 执行 SSOT，数据单向流动。让两条流水线完整并行运行会产生两份相互竞争的规范。
2. 先查注册表，再生成——cli-hub search 只需几秒；构建一个 7 阶段 harness 则要花掉一个工作会话。
3. 验收标准应可由机器检查——在 /speckit.specify 中编写，在种子中映照，并在 evaluate 中要求验证。
4. 在种子约束中指明工具——未纳入契约的工具选择会造成不可见的偏移。
5. 没有种子就不要用 ralph——没有验证标准的持久循环只会“直到厌倦”，而不是“直到完成”。先准备种子，再运行循环。
6. 在 implement 之前将计划交给 plannotator，适用于 2 级及以上工作； 审批关卡位于步骤 3 和步骤 5 之间。

参考资料

• 层级技能：../spec-kit/SKILL.md、 ../ooo/SKILL.md、 ../cli-anything/SKILL.md
• 上游项目：https://github.com/github/spec-kit、 https://github.com/Q00/ouroboros、 https://github.com/HKUDS/CLI-Anything
• 安装脚本：scripts/install.sh
• 命令对照表及交接图：references/commands.md
• 相关技能：../bmad/SKILL.md、../plannotator/SKILL.md
• 许可证：MIT（此封装）；各工具适用其上游许可证