Spec Stack

spec-stack — Write → Freeze → Run, Verified

spec-stack composes three skills that own different layers of spec-driven delivery and keeps them from fighting over the same job:

The stack's one rule: spec-kit writes, ooo freezes and loops, cli-anything is the hands. Each layer hands a concrete artifact to the next — spec.md/plan.md feed the seed interview, the seed names the harnesses the loop may use, and harness --json output is the evidence the evaluate step accepts.

When to use this skill

• The user wants the **full path from a written spec to a verified

artifact**, not just one of the three tools

• The user asks how spec-kit and ooo should work together (which owns

the spec, which owns completion) or how to avoid duplicating the spec

• The implementation must drive real software (image/video/office/3D/

GIS/game tooling) inside a verified loop instead of one-shot codegen

• The user says "spec-stack", "write freeze run", or names two or more of

spec-kit, ooo, cli-anything in one workflow

When not to use this skill

• Only authoring SDD documents for one or more agents → use spec-kit
• Only a verify-until-done loop with no document artifacts → use ooo
• Only installing or generating a CLI harness → use cli-anything
• Deciding which planning artifact comes next (brief, PRD,

architecture) → use bmad

• Human review/approval of an existing plan or diff → use plannotator

Prerequisites

Instructions

Step 0 — Choose the composition pattern

If the user has not stated a pattern, default to A when external software or acceptance evidence is involved, B for code-only persistence, C for documentation handoffs.

Step 1 — Install the stack

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

On Claude Code, prefer the ooo plugin instead of pip: claude plugin marketplace add Q00/ouroboros. Verify with specify --version, cli-hub list, and ouroboros --help (or the ouroboros_* MCP tools).

Step 2 — Write the spec (spec-kit)

specify init . --integration claude

Then inside the agent: /speckit.constitution → /speckit.specify → /speckit.clarify (only if open questions remain). Stop before /speckit.implement — implementation belongs to the loop layer in pattern A. Write success criteria as machine-checkable statements ("output PNG is 1024×1024, verified by pixel inspection"), not vibes ("image looks right") — Step 3 and Step 5 depend on this.

Step 3 — Freeze the contract (ooo)

Feed spec.md/plan.md into the ooo interview (brownfield weighting), drive ambiguity ≤ 0.2, then generate the immutable seed:

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

Two seed rules that make the stack work:

1. Success criteria mirror the spec's acceptance criteria in machine-checkable form — the evaluate step will demand evidence. 2. Constraints name the tools: e.g. "image operations go through the cli-anything-gimp harness; GUI automation is out of contract." This turns tool drift into measurable spec drift.

The seed is the execution SSOT from here on; spec.md stays the document SSOT. Direction is one-way: spec-kit → seed. If requirements change, update the spec first, then re-freeze.

Step 4 — Arm the tools (cli-anything)

Before writing integration code, search the registry:

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

Only when the registry has no match, generate: /cli-anything <path-or-repo> (7-phase pipeline), then /cli-anything:refine as needed. Generation is the fallback, never the default.

Step 5 — Run the loop

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

In the evaluate step, verify artifacts, not exit codes: use the harness --json output, magic bytes, document structure, or pixel/audio checks as evidence — the same discipline cli-anything's own test suite uses. On failure the loop continues; on repeated failure use ooo's unstuck step instead of blind retries. Pattern A users who want the spec-kit task list can run /speckit.implement per task inside the loop — the seed still gates completion.

Step 6 — Plugin-style installation alongside 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

Installing spec-stack does not auto-install the three layer skills; install whichever you lack the same way (--skill spec-kit, --skill ooo, --skill cli-anything).

Output format

When the user asks spec-stack for help, return a compact brief:

# 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

Examples

Example 1 — Pattern A end to end (image pipeline against real software)

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

Example 2 — Routing a vague combined request

User: "spec-kit이랑 ooo 같이 쓰고 싶은데 어디서부터?" → Return the Routing Brief with Pattern: full-stack, Stack state: nothing-installed, Recommended next move: install-stack, and route-outs left intact. Do not start /speckit.implement — in pattern A completion belongs to the ooo loop.

Example 3 — Near-miss that should route out

User: "GIMP용 CLI 하니스만 만들어줘" → single-layer work; hand off to cli-anything (registry search first), no seed or spec ceremony.

Best practices

1. One SSOT per concern — spec.md is the document SSOT, seed.yaml the execution SSOT, flowing one way. Running both pipelines fully in parallel creates two competing specs. 2. Registry before generation — cli-hub search costs seconds; a 7-phase harness build costs a session. 3. Machine-checkable acceptance criteria — write them in /speckit.specify, mirror them in the seed, demand them in evaluate. 4. Name tools in seed constraints — uncontracted tool choice is invisible drift. 5. No ralph without a seed — a persistent loop without verification criteria runs "until tired", not "until done". Seed first, loop second. 6. Hand the plan to `plannotator` before implement on level 2+ work; the approval gate sits between Step 3 and Step 5.

References

• Layer skills: `../spec-kit/SKILL.md`,

`../ooo/SKILL.md`, `../cli-anything/SKILL.md`

• Upstream: <https://github.com/github/spec-kit>,

<https://github.com/Q00/ouroboros>, <https://github.com/HKUDS/CLI-Anything>

• Installer script: `scripts/install.sh`
• Command crosswalk + handoff map: `references/commands.md`
• Adjacent skills: ../bmad/SKILL.md, ../plannotator/SKILL.md
• License: MIT (this wrapper); upstream licenses apply to each tool

spec-stack command crosswalk

Three tools, one delivery path. Layer skills own the detail: `../../spec-kit/references/commands.md`, ../../ooo/SKILL.md, ../../cli-anything/references/commands.md.

The handoff map

Stage 1 — Spec (spec-kit)

In pattern A, stop before /speckit.implement — the loop layer gates completion.

Stage 2 — Contract (ooo)

Seed authoring rules: success criteria mirror spec.md acceptance criteria in machine-checkable form; constraints name the permitted harnesses (e.g. cli-anything-gimp, no GUI automation).

Stage 3 — Tools (cli-anything)

Pattern quick reference

Anti-patterns

• Two SSOTs: running /speckit.implement to completion and an ooo

loop against a separately-evolved seed. Flow is one-way: spec → seed.

• Generate-first: building a harness before cli-hub search.
• Seedless ralph: a persistence loop with no frozen verification

criteria.

• Exit-code verification: evaluate should inspect artifacts

(--json output, file structure, pixels), not just process status.