shipyard-cp

日本語版 | English

shipyard-cp は、複数の AI provider / worker を有限ネストで上流オーケストレーションする control plane です。
LiteLLM を推論ゲートウェイとして使い、Codex / Claude Code / Google Antigravity / GLM-5 系ワーカーを、共通の task / run / gate / audit モデル上で制御します。

このプロダクトの本体は backend / worker / CLI です。
frontend は補助UIとして、task と run の閲覧、状態確認、補助操作を行います。

3分で分かる最短操作例

まずは backend を起動して、CLI から task を流し、状態を見るだけで全体像が掴めます。

pnpm install
pnpm run dev
curl http://localhost:3100/healthz

その後は Claude Code / Codex から次の入口を使う想定です。

1. task を流す: run コマンド
2. 状態を確認する: status コマンド
3. フロー全体を追う: pipeline コマンド

迷ったら、正本ハブの CLI Usage から始めてください。 コマンドの役割だけ先に見たい場合は .claude/commands 入口 を参照してください。 GLM5 を主線にする場合は GLM5 Quickstart を合わせて確認してください。 実運用向けの詳細手順は GLM5 Operation Instructions を参照してください。 セキュリティ計画と受け入れ条件は Security Docs を参照してください。

CLI フロー図

flowchart LR
    A["run / task 作成"] --> B["plan"]
    B --> C["dev"]
    C --> D["acceptance"]
    D --> E["integrate"]
    E --> F["publish"]
    B --> S["status で進捗確認"]
    C --> S
    D --> S
    E --> S
    F --> S
    S --> U["必要時だけ Web UI で補助確認"]

Loading

Latest Release: v0.2.0

OpenCode serve/session reuse統合完了。詳細は Release Notes 参照。

主な追加機能:

• Session reuse with same-stage policy
• Agent-aware session profiles (planning/build/verification)
• Warm pool for idle session optimization
• Event stream tracking and orphan recovery

何を解決するアプリか

AI コーディングエージェントを実務で使い始めると、すぐに次の問題が出ます。

• どの task が今どこまで進んでいるか分からない
• plan / dev / acceptance の区切りが曖昧で、結果だけ返ってきて途中経過が追えない
• Codex、Claude Code、他の worker で入出力や癖が違い、運用がばらつく
• agent に agent を呼ばせるような構成で、委譲の深さや責務境界が曖昧になりやすい
• 失敗時に再実行、保留、accept 判定、publish 判断を人が場当たりで処理してしまう
• GitHub や tracker とつながっていても、状態と成果物の紐付けが散らばる

shipyard-cp は、この「AI worker を実務フローに載せた時の運用の散らかり」を整理するための control plane です。

具体的には、次をまとめて面倒を見ます。

• 複数 provider / worker を単一の上流 orchestrator から扱う
• 無限委譲ではなく有限ネストを前提にして、task の深さと責務を制御する
• task を plan -> dev -> acceptance -> integrate -> publish の明示的な段階に分ける
• worker ごとの差を吸収して、共通の WorkerJob / WorkerResult 契約で扱う
• retry / lease / heartbeat / capability gate を control plane 側に寄せる
• task、run、timeline、audit を残して「何が起きたか」を後から追えるようにする
• agent-taskstate-js、memx-resolver-js、tracker-bridge-js を通じて、状態・文書・tracker の参照先をつなぐ

要するに、単に「AI にコードを書かせる」ためのツールではなく、複数の worker を有限ネストで束ねながら、実務フローに載せるための上流 control plane です。

運用方針

• 主導線: CLI / Claude Code / Codex
• 補助導線: Web UI
• 内部契約: API / OpenAPI / schema

人が日常的に触る入口は API 直打ちではなく CLI-first です。
API は UI 接続、内部契約、自動化、検証用として維持しています。

最初の入口

まずはここから見れば十分です。

1. CLI Usage
2. GLM5 Quickstart
3. GLM5 Operation Instructions
4. Security Docs
5. run コマンド
6. status コマンド
7. 必要なら pipeline コマンド
8. 実装や運用の現在値は RUNBOOK

クイックスタート

pnpm install
pnpm run dev

疎通確認:

curl http://localhost:3100/healthz

補助UI を使う場合:

• UI: http://localhost:8080
• API: http://localhost:3100

CLI での使い方

日常運用は docs/cli-usage.md を正本にします。

よく使う入口:

• 単発 task を流す: run.md
• 状態を確認する: status.md
• フルフローを追う: pipeline.md
• コマンドの違いを先に掴む: commands README

補足:

• .claude/commands/ は product runtime の一部ではなく、Claude Code 用の運用補助コマンド集です
• API 直打ちはデバッグや検証時に限定するのを推奨します

運用 Skills

Codex / Claude Code 向けの運用 Skills は skills に置いています。

• shipyard-cp-cli-quickstart
• shipyard-cp-cli-pipeline

Skills は product の API 契約ではなく、repo を扱う人向けの運用ガイドです。

アーキテクチャ概要

shipyard-cp
├─ src/                  backend / control plane 本体
├─ web/                  補助UI
├─ packages/             内蔵 npm packages
│  ├─ agent-taskstate-js
│  ├─ memx-resolver-js
│  ├─ tracker-bridge-js
│  └─ shared-redis-utils
├─ infra/                Docker / compose / kubernetes / TLS
├─ docs/                 要件・運用・仕様・CLIハブ
└─ skills/               Codex / Claude Code 向け運用 Skills

主要な責務:

• src/: state machine、dispatch、result orchestration、acceptance / integrate / publish、monitoring
• src/domain/worker/: WorkerAdapter契約、session reuse、event stream正規化、orphan recovery
• src/infrastructure/: server manager、session executor、fallback制御
• web/: task / run の閲覧、補助操作、接続確認
• packages/: 状態・resolver・tracker の埋め込み依存
• infra/: compose、Dockerfile、Kubernetes TLS 資材

Worker Execution Architecture (内部実装)

Codex / Claude Code workerは内部でOpenCode serve/session reuseを使用。詳細は OpenCode Specification 参照。

概要:

• Session reuse: 同一条件でsession再利用（same-stageのみ）
• Warm pool: idle session事前validation
• Event stream: transcript/tool_use/permission_request追跡
• Orphan recovery: timeout/crash時自動cleanup

外部API契約は維持。public worker typeはcodex/claude_code/google_antigravity/glm_5のまま。

Web UI の位置づけ

Web UI は「主役」ではなく「補助UI」です。

• task / run の閲覧
• 状態確認
• 補助的な dispatch / acceptance 完了などの操作

CLI や worker フローが本命で、frontend はそれを邪魔しない軽い導線として扱います。
詳細は web/README.md と web/FRONTEND_RUNBOOK.md を参照してください。

最小環境変数

ローカル起動の最低限:

• .env または環境変数
• REDIS_URL（Redis を使う場合）

外部連携で必要になりやすいもの:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GOOGLE_API_KEY
• GITHUB_TOKEN
• GLM_API_KEY

ライブテストや publish 系では、必要なキーだけ個別に追加してください。

インフラ資材

• compose: infra/docker-compose.yml
• production compose: infra/docker/docker-compose.yml
• backend Dockerfile: infra/docker/api.Dockerfile
• k8s / TLS: infra/kubernetes/tls

ドキュメント

主要ドキュメント:

• CLI Usage: CLI-first 運用の正本ハブ
• REQUIREMENTS: 要件定義
• RUNBOOK: 実装・運用の現在値
• OpenCode Specification: Worker内部実装仕様
• State Machine: 状態遷移仕様
• API Contract: API 契約
• OpenAPI: OpenAPI 3.1
• Schemas: JSON Schema 一覧
• BIRDSEYE: 文書間ナビゲーション

テストと品質

日常的に使うコマンド:

pnpm test           # テスト実行
pnpm run test:coverage  # カバレッジ付きテスト
pnpm run build      # ビルド
cd web && npm test  # frontend テスト
cd web && npm run build  # frontend ビルド

テスト構成:

• テストファイル: 89ファイル
• テストケース: 約2,100件
• テストコード: 約55,000行
• カバレッジ: 約83% (src/ 配下)

ライブテストは外部 API トークンが必要です。 token 類は .env や環境変数で管理し、repo に直接入れない運用を前提としています。

API について

API は残っていますが、位置づけは internal contract です。

• UI 接続
• 自動化
• worker / result 反映
• デバッグ / 検証

通常運用では docs/cli-usage.md の CLI 導線を優先してください。