spec-stack

spec-stack — 作成 → 凍結 → 実行、検証済み

spec-stack は、仕様駆動型のデリバリーにおいて異なるレイヤーを担う3つのスキルを組み合わせ、同じ作業を奪い合わないようにします。

レイヤー	スキル	担当
仕様（何を）	spec-kit	/speckit.constitution → specify → plan → tasks で作成する、人が読めるSDD成果物。30以上のエージェント間で共有できます
ループ（完了するまで）	ooo	曖昧さを0.2以下にするソクラテス式インタビュー、不変のシード、ドリフトの測定、完了前に検証する永続的なループ（ralph）
ツール（何を使って）	cli-anything	実際のソフトウェア向けのエージェントネイティブCLI — CLI-Hubレジストリ、--json 出力、成果物レベルの検証

このスタックのルールは1つです。spec-kitが作成し、oooが凍結してループを回し、cli-anythingが手を動かします。 各レイヤーは、具体的な成果物を次のレイヤーに渡します。spec.md／plan.md はシードインタビューに使われ、シードにはループで使用できるハーネスが記され、ハーネスの --json 出力はevaluateステップが受け入れる証拠になります。

このスキルを使う場面

• 3つのツールのいずれか1つだけでなく、記述された仕様から検証済みの成果物までの一連の流れをユーザーが求めている
• spec-kitとoooをどのように連携させるか（仕様をどちらが担当し、完了をどちらが担保するか）、または仕様の重複をどう避けるかをユーザーが尋ねている
• 検証済みループの中で、単発のコード生成ではなく、実際のソフトウェア（画像／動画／オフィス／3D／GIS／ゲームツール）を操作して実装する必要がある
• ユーザーが「spec-stack」「write freeze run」と言う、または1つのワークフローで spec-kit、ooo、cli-anything のうち2つ以上を挙げている

このスキルを使わない場面

• 1つ以上のエージェント向けのSDDドキュメント作成のみ → spec-kit を使います
• ドキュメント成果物を伴わない完了までの検証ループのみ → ooo を使います
• CLIハーネスのインストールまたは生成のみ → cli-anything を使います
• 次に作成する計画成果物（ブリーフ、PRD、アーキテクチャ）の選定 → bmad を使います
• 既存の計画または差分の人によるレビュー／承認 → plannotator を使います

前提条件

要件	備考
Python 3.11+	specify-cli には3.11+が必要です。CLI-Hubには3.10+が必要です
uv（推奨）または pipx／pip	3つすべてのツールで scripts/install.sh が使用します
サポート対象のAIエージェントを1つ	Claude Code、Codex、Gemini、Cursor、opencode、…
対象ソフトウェア（パターンA）	ハーネスは実際のバックエンドを呼び出すため、上流のアプリもインストールしてください

手順

ステップ0 — 組み合わせパターンを選ぶ

パターン	場面	レイヤー
A — フルスタック	実際のソフトウェアに関わり、共有ドキュメントと検証ループの両方が必要な、中規模以上の作業	spec-kit → ooo → cli-anything
B — ループのみ	ドキュメント成果物を作らず、1回のセッションで「検証が済むまで続ける」場合	ooo（ソフトウェアが関わる場合は cli-anything も）
C — ドキュメントのみ	複数エージェント／チームで .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では、pipではなくoooプラグインを推奨します： claude plugin marketplace add Q00/ouroboros。specify --version、cli-hub list、ouroboros --help（または ouroboros_* MCPツール）で確認してください。

ステップ2 — 仕様を作成する（spec-kit）

specify init . --integration claude

続いて、エージェント内で /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

スタックを機能させるためのシードのルールは 2 つです。

1. 成功基準は仕様の受け入れ基準を反映するよう、機械的に検証できる形式で記述します。評価ステップでは証拠が求められます。
2. 制約にはツールを明記します。たとえば、「画像操作には cli-anything-gimp ハーネスを使用する。GUI の自動化は契約の対象外」とします。これにより、ツールの逸脱を測定可能な仕様の逸脱として扱えます。

ここから先、シードが実行に関する唯一の信頼できる情報源（SSOT）となり、 spec.md は文書に関する SSOT のままです。 方向は一方通行です。spec-kit → シード。 要件が変わったら、まず仕様を更新してから、シードを再度固定します。

ステップ 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

評価ステップでは、終了コードではなく成果物を検証します。ハーネスの --json 出力、マジックバイト、ドキュメント構造、またはピクセル／音声の チェックを証拠として使用します。これは cli-anything 自体のテストスイートと 同じ検証方法です。失敗してもループは続行します。失敗が繰り返される場合は、 やみくもに再試行するのではなく、ooo の行き詰まり解消ステップを使用します。 Pattern A のユーザーが spec-kit のタスクリストを使いたい場合は、ループ内で タスクごとに /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 をインストールしても、3 つのレイヤースキルは自動でインストールされません。 不足しているスキルを、同じ方法でインストールしてください（--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を一緒に使いたいけど、どこから始めればいい？」 → Pattern: full-stack、 Stack state: nothing-installed、Recommended next move: install-stack を含む Routing Brief を返し、振り分け先の情報はそのままにします。 /speckit.implement は開始しません。pattern A では、完了の判断は ooo ループが担います。

例 3 — 振り分けるべき、あと一歩のリクエスト

ユーザー：「GIMP用のCLIハーネスだけ作って」 → 単一レイヤーの作業です。cli-anything に引き継ぎます（最初にレジストリを検索）。 シードや仕様に関する手順は不要です。

ベストプラクティス

1. 懸念事項ごとに SSOT を 1 つにする — spec.md は文書に関する SSOT、seed.yaml は実行に関する SSOT とし、一方通行で進めます。両方のパイプラインを並行してすべて実行すると、2 つの仕様が競合します。
2. 生成する前にレジストリを検索する — cli-hub search は数秒で済みますが、7 フェーズのハーネス構築にはセッション全体がかかります。
3. 機械的に検証できる受け入れ基準 — /speckit.specify で記述し、シードにも反映して、評価時にその基準を求めます。
4. シードの制約にツールを明記する — 契約に記載されていないツールの選択は、見えない逸脱になります。
5. シードなしで ralph を実行しない — 検証基準のない永続的なループは、「完了するまで」ではなく「疲れるまで」続きます。まずシードを作り、その後にループを実行します。
6. レベル 2 以上の作業では、実装前に計画を plannotator に渡します。承認ゲートはステップ 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（このラッパー）。各ツールには上流のライセンスが適用されます。