日本語版 | 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 の閲覧、状態確認、補助操作を行います。
まずは backend を起動して、CLI から task を流し、状態を見るだけで全体像が掴めます。
pnpm install
pnpm run dev
curl http://localhost:3100/healthzその後は Claude Code / Codex から次の入口を使う想定です。
- task を流す: run コマンド
- 状態を確認する: status コマンド
- フロー全体を追う: pipeline コマンド
迷ったら、正本ハブの CLI Usage から始めてください。
コマンドの役割だけ先に見たい場合は .claude/commands 入口 を参照してください。
GLM5 を主線にする場合は GLM5 Quickstart を合わせて確認してください。
実運用向けの詳細手順は GLM5 Operation Instructions を参照してください。
セキュリティ計画と受け入れ条件は Security Docs を参照してください。
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 で補助確認"]
MIT版OpenCodeの session / tool / event 設計をShipyardのControl Plane側へ移植し、WorkerRuntimeSession として共通runtime contractを追加しました。詳細は OpenCode-Compatible Worker Runtime release note を参照してください。
主な追加機能:
- Durable input admission と session event replay
- Scoped tool registry と stale tool registration拒否
- Tool output bounding と retained artifact参照
- OpenCode event streamのruntime-neutral正規化
- QEG
standardprofileでの証跡付きGo
主な追加機能:
- 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 です。
- 主導線: Claude Code / Codex コマンド経由の API 操作
- 補助導線: Web UI
- 内部契約: API / OpenAPI / schema
人が日常的に触る入口は .claude/commands/ に定義した操作手順です。これらは実 CLI バイナリではなく、Claude Code / Codex から API 操作を行うための補助コマンドです。
API は UI 接続、内部契約、自動化、検証用として維持しています。
まずはここから見れば十分です。
- CLI Usage
- GLM5 Quickstart
- GLM5 Operation Instructions
- Security Docs
- run コマンド
- status コマンド
- 必要なら pipeline コマンド
- 実装や運用の現在値は RUNBOOK
pnpm install
pnpm run dev疎通確認:
curl http://localhost:3100/healthz補助UI を使う場合:
- UI:
http://localhost:8080 - API:
http://localhost:3100
日常運用は docs/cli-usage.md を正本にします。
よく使う入口:
- 単発 task を流す: run.md
- 状態を確認する: status.md
- フルフローを追う: pipeline.md
- コマンドの違いを先に掴む: commands README
補足:
.claude/commands/は product runtime や実 CLI バイナリではなく、Claude Code / Codex 用の運用補助コマンド集です- API 直打ちはデバッグや検証時に限定するのを推奨します
Codex / Claude Code 向けの運用 Skills は skills に置いています。
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、monitoringsrc/domain/worker/: WorkerAdapter契約、session reuse、event stream正規化、orphan recoverysrc/domain/worker-runtime/: OpenCode-compatible session / tool registry / event replay / output bounding の共通runtime contractsrc/infrastructure/: server manager、session executor、fallback制御web/: task / run の閲覧、補助操作、接続確認packages/: 状態・resolver・tracker の埋め込み依存infra/: compose、Dockerfile、Kubernetes TLS 資材
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 は「主役」ではなく「補助UI」です。
- task / run の閲覧
- 状態確認
- 補助的な dispatch / acceptance 完了などの操作
CLI や worker フローが本命で、frontend はそれを邪魔しない軽い導線として扱います。
詳細は web/README.md と web/FRONTEND_RUNBOOK.md を参照してください。
ローカル起動の最低限:
.envまたは環境変数REDIS_URL（Redis を使う場合）
外部連携で必要になりやすいもの:
OPENAI_API_KEYANTHROPIC_API_KEYGOOGLE_API_KEYGITHUB_TOKENGLM_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: Claude Code / Codex コマンド経由運用の正本ハブ
- REQUIREMENTS: 要件定義
- RUNBOOK: 実装・運用の現在値
- Release Notes: 大きな変更の互換性・検証・証跡まとめ
- OpenCode Specification: Worker内部実装仕様
- OpenCode-Compatible Worker Runtime Release Note: OpenCode MIT由来runtime contract移植のリリースノート
- Worker Runtime / Session Control Requirements: Open Synaptic Code / OpenCode MIT由来のsession / tool registry / restore point / event replay制御要件
- OpenCode MIT Porting Notes: MIT版OpenCodeからShipyardへ移植したsession / tool / event契約の採用記録
- Instruction Precision Requirements: worker指示伝達の要件
- Instruction Precision Specification: Envelope伝達・優先順位・失敗時挙動
- Instruction Precision Design: 共通rendererと実行経路の設計
- State Machine: 状態遷移仕様
- API Contract: API 契約
- OpenAPI: OpenAPI 3.1
- Schemas: JSON Schema 一覧
- Instruction Precision Task Seed: worker 指示精度改善の実装記録
- Instruction Precision Acceptance: worker 指示精度改善の検収記録
- Deployment Guide: 現行のデプロイ手順とヘルスチェック
- BIRDSEYE: 文書間ナビゲーション
docs/frontend-* は検収時点の履歴資料です。現在の挙動を判断するときは、
実装本体と上記の正本文書を優先してください。
日常的に使うコマンド:
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 は残っていますが、位置づけは internal contract です。
- UI 接続
- 自動化
- worker / result 反映
- デバッグ / 検証
通常運用では docs/cli-usage.md の CLI 導線を優先してください。