diff --git a/docs/quickstart.ja.md b/docs/quickstart.ja.md new file mode 100644 index 0000000..610ffd9 --- /dev/null +++ b/docs/quickstart.ja.md @@ -0,0 +1,616 @@ +# Quickstart — チームで Roboppi ワークフローを運用する + +このガイドでは、チームプロジェクトに Roboppi ワークフローを導入し、AI エージェントによる設計・実装・レビューの自動化パイプラインを回す方法を説明します。 + +実例として `examples/appthrust-dashboard/workflow.yaml`（AppThrust Dashboard プロジェクト向けの本番ワークフロー）を使います。 + +[English](quickstart.md) | 日本語 + +--- + +## 目次 + +1. [前提条件](#1-前提条件) +2. [Roboppi のインストール](#2-roboppi-のインストール) +3. [ワークフローの全体像](#3-ワークフローの全体像) +4. [プロジェクトにワークフローを組み込む](#4-プロジェクトにワークフローを組み込む) +5. [request.md を書く](#5-requestmd-を書く) +6. [ワークフローを実行する](#6-ワークフローを実行する) +7. [ステップの詳細解説](#7-ステップの詳細解説) +8. [成果物とディレクトリ構造](#8-成果物とディレクトリ構造) +9. [ブランチ安全性](#9-ブランチ安全性) +10. [チーム運用のベストプラクティス](#10-チーム運用のベストプラクティス) +11. [トラブルシューティング](#11-トラブルシューティング) +12. [次のステップ](#12-次のステップ) + +--- + +## 1. 前提条件 + +### 必須 + +| ツール | 用途 | インストール | +|--------|------|------------| +| [Bun](https://bun.sh/) v1.0+ | ランタイム / パッケージマネージャ | `curl -fsSL https://bun.sh/install \| bash` | +| [Git](https://git-scm.com/) | ブランチ管理・diff 生成 | OS のパッケージマネージャ | + +### ワーカー CLI（ワークフローが使用するもの） + +| ツール | ワークフローでの役割 | インストール | +|--------|-------------------|------------| +| [OpenCode](https://opencode.ai/) | 設計 (design)・TODO 作成 | `bun install -g opencode` | +| [Claude Code](https://claude.ai/code) | 実装 (implement) | `npm install -g @anthropic-ai/claude-code` | + +ワークフローの `worker:` フィールドに応じて必要なツールが変わります。`CUSTOM` ステップはシェルスクリプトを直接実行するため、追加のインストールは不要です。 + +### オプション + +| ツール | 用途 | +|--------|------| +| `gh` (GitHub CLI) | PR 作成ステップを追加する場合 | +| `codex` (Codex CLI) | ワーカーとして Codex CLI を使う場合 | + +--- + +## 2. Roboppi のインストール + +### プリビルドバイナリ（推奨） + +```bash +curl -fsSL https://raw.githubusercontent.com/reoring/roboppi/main/install.sh | bash +roboppi --help +``` + +### ソースからビルド + +```bash +git clone https://github.com/reoring/roboppi.git +cd roboppi +bun install +make build +./roboppi --help +``` + +開発中は `bun run src/workflow/run.ts` で直接実行することもできます（ビルド不要）。 + +--- + +## 3. ワークフローの全体像 + +AppThrust Dashboard ワークフロー (`examples/appthrust-dashboard/workflow.yaml`) は、以下のパイプラインを自動実行します。 + +``` +bootstrap ─→ branch ─→ deps ─→ design ─→ todo ─→ implement ─→ validate + │ │ │ │ │ │ │ + │ 環境検証 │ ブランチ │ 依存 │ 設計書 │ TODO │ 実装+検証 │ lint/ + │ + 初期化 │ 作成/ │ install│ 作成 │ 作成 │ + review │ format/ + │ │ 復帰 │ │ (AI) │ (AI) │ inputs │ build + └───────────┴─────────┴────────┴────────┴───────┴───────────┴──────── +``` + +### 各ステップの役割 + +| ステップ | ワーカー | 説明 | +|----------|---------|------| +| `bootstrap` | CUSTOM | git リポジトリの検証、`roboppi/request.md` の存在確認、前回のアーティファクトをクリア | +| `branch` | CUSTOM | 作業ブランチを作成または復帰（`roboppi/branch.txt` で永続化） | +| `deps` | CUSTOM | `bun install` で依存パッケージをインストール | +| `design` | OPENCODE (GPT-5.2) | `request.md` を読み、設計書 `roboppi/design.md` を生成 | +| `todo` | OPENCODE (GPT-5.2) | 設計書をもとに実装チェックリスト `roboppi/todo.md` を生成（completion_check 付き） | +| `implement` | CLAUDE_CODE (Opus 4.6) | TODO を実装し、lint/format/build を通し、レビュー用 diff を生成 | +| `validate` | CUSTOM | 最終的な `bun run lint` / `bun run format:check` / `bun run build` | + +### ワーカーの使い分け + +このワークフローでは **設計・計画は OpenCode (GPT-5.2)**、**実装は Claude Code (Opus 4.6)** と意図的に分けています。 + +- **OpenCode** — 読み取り専用のステップに向いている。コードを書かずに設計や TODO を整理する +- **Claude Code** — 実装力が高い。コード編集 + コマンド実行 + テスト修正を一貫して行う +- **CUSTOM** — シェルスクリプトで確実に動く操作（ブランチ切替、lint、build など） + +--- + +## 4. プロジェクトにワークフローを組み込む + +### ディレクトリ構成 + +対象プロジェクトのリポジトリに、以下の構造を作ります。 + +``` +your-project/ +├── roboppi/ +│ ├── request.md # 実装リクエスト（チームメンバーが書く） +│ ├── workflow.yaml # ワークフロー定義（コピーまたはシンボリックリンク） +│ ├── base-branch.txt # ベースブランチ名（自動生成） +│ ├── branch.txt # 作業ブランチ名（自動生成） +│ └── context/ # ステップ間のアーティファクト（自動生成） +├── .gitignore +└── ...（既存のソースコード） +``` + +### セットアップ手順 + +```bash +cd /path/to/your-project + +# 1. roboppi ディレクトリを作成 +mkdir -p roboppi + +# 2. ワークフローをコピー（またはシンボリックリンク） +cp /path/to/roboppi/examples/appthrust-dashboard/workflow.yaml roboppi/workflow.yaml + +# 3. .gitignore に追加（ワークフローの中間成果物を追跡しない） +cat >> .gitignore << 'EOF' + +# Roboppi workflow artifacts +roboppi/design.md +roboppi/todo.md +roboppi/fix.md +roboppi/review.* +roboppi/validate.ok +roboppi/bootstrap.ok +roboppi/context/ +EOF +``` + +`roboppi/request.md` と `roboppi/workflow.yaml` はリポジトリにコミットしておくことを推奨します。これにより、チーム全員が同じワークフローとリクエストを共有できます。 + +--- + +## 5. request.md を書く + +`roboppi/request.md` はワークフロー全体の入力です。AI エージェントはこのファイルを読んで設計・実装を行います。 + +### 良い request.md のテンプレート + +```markdown +# 機能名（短く、明確に） + +## ゴール +何を達成したいかを 1-3 文で。 + +## 要件 +- 具体的な要件を箇条書き +- UI があるなら見た目やインタラクションの説明 +- データの流れ（API / ローカルモック / 既存コードとの連携） + +## 非スコープ（今回やらないこと） +- 明示的に除外するもの + +## 受け入れ基準 +- [ ] チェックリスト形式で +- [ ] `bun test` がパスする +- [ ] `bun run lint` がパスする +- [ ] `bun run build` がパスする + +## 参考資料 +- 関連するドキュメントやファイルパスがあればここに +``` + +### ポイント + +- **200 バイト以上** ないと bootstrap ステップで弾かれます（空っぽの request を防ぐため） +- 受け入れ基準はチェックリスト（`- [ ]`）で書くと、design/todo ステップがそのまま引用してくれます +- ファイルパスや API の形式など、具体的であるほどエージェントの出力品質が上がります + +--- + +## 6. ワークフローを実行する + +### 基本的な実行方法 + +```bash +# AGENTCORE_ROOT を Roboppi のクローン先に設定 +export AGENTCORE_ROOT="$HOME/roboppi" + +# ワークフローを実行 +bun run --cwd "$AGENTCORE_ROOT" src/workflow/run.ts \ + /path/to/your-project/roboppi/workflow.yaml \ + --workspace /path/to/your-project \ + --base-branch main \ + --supervised --verbose +``` + +### 引数の説明 + +| 引数 | 説明 | +|------|------| +| `--cwd "$AGENTCORE_ROOT"` | Roboppi のソースルートから実行（`bun run` はここで `src/workflow/run.ts` を解決） | +| 第 1 引数 | ワークフロー YAML のパス | +| `--workspace` | 対象プロジェクトのルートディレクトリ | +| `--base-branch` | ベースブランチ（デフォルト: 現在のブランチ） | +| `--supervised` | Supervisor -> Core -> Worker の 3 層モードで実行（デフォルト） | +| `--verbose` | 各ステップの出力を表示 | + +### ビルド済みバイナリを使う場合 + +```bash +roboppi workflow /path/to/your-project/roboppi/workflow.yaml \ + --workspace /path/to/your-project \ + --base-branch main \ + --verbose +``` + +### 便利なエイリアス + +チームで頻繁に使う場合は、プロジェクトの `Makefile` や `package.json` にスクリプトを追加しておくと便利です。 + +```makefile +# Makefile +AGENTCORE_ROOT ?= $(HOME)/roboppi + +roboppi: + bun run --cwd "$(AGENTCORE_ROOT)" src/workflow/run.ts \ + roboppi/workflow.yaml \ + --workspace "$(PWD)" \ + --base-branch main \ + --supervised --verbose +``` + +```bash +make roboppi +``` + +--- + +## 7. ステップの詳細解説 + +### bootstrap — 環境検証 + +```yaml +bootstrap: + worker: CUSTOM + instructions: | + set -euo pipefail + # git リポジトリかチェック + # roboppi/request.md の存在と最小サイズを検証 + # 前回の中間成果物をクリア + # 必要なコマンド（bun, opencode, claude）の存在を確認 +``` + +**失敗する場合:** +- `roboppi/request.md` がない → 先に書く +- `roboppi/request.md` が 200 バイト未満 → 内容を充実させる +- `bun` / `opencode` / `claude` が PATH にない → インストールする + +### branch — ブランチ管理 + +ブランチの状態を 3 つのケースで扱います。 + +| ケース | 動作 | +|--------|------| +| `roboppi/branch.txt` にブランチ名がある + ローカルに存在 | そのブランチに checkout | +| `roboppi/branch.txt` にブランチ名がある + リモートのみ | track して checkout | +| ブランチ名がない（初回実行） | `roboppi/features-YYYYMMDD-HHMMSS` を作成 | + +`roboppi/branch.txt` をコミットしておけば、チームメンバー間で同じブランチを共有できます。 + +### design — AI による設計書生成 + +OpenCode (GPT-5.2) が `roboppi/request.md` と既存ドキュメントを読み、`roboppi/design.md` を生成します。 + +生成される設計書の内容: +- MVP スコープ宣言 +- ルートマップ +- UI コンポーネント一覧 +- データ取得戦略 +- 認証の考慮事項 +- エッジケースとリスク +- 検証計画 +- 受け入れ基準チェックリスト + +**`on_failure: retry` + `max_retries: 1`** — 失敗時に 1 回リトライ。 + +### todo — completion_check 付きループ + +OpenCode が設計書から TODO チェックリストを生成します。 + +```yaml +completion_check: + worker: CUSTOM + instructions: | + # 10 項目以上あるか？ + # lint/format/build コマンドが含まれているか？ + # ファイルパスのヒントがあるか？ +``` + +**`max_iterations: 3`** — チェックに通らなければ最大 3 回やり直し。3 回で通らなければ abort。 + +これにより「TODO が薄すぎる」「検証ステップが抜けている」状態を機械的に防ぎます。 + +### implement — 実装の本体 + +Claude Code (Opus 4.6) が TODO リストに沿って実装します。 + +このステップの特徴: +- `roboppi/fix.md` がある場合はそこに書かれた修正のみ適用（レビューループ用） +- `bun run lint` / `bun run format:check` / `bun run build` を必ず通す +- 終了時にレビュー入力ファイル群を生成: + - `roboppi/review.base_ref` — diff の基準コミット + - `roboppi/review.diff` — ベースからの全 diff + - `roboppi/review.status` — `git status --porcelain` + - `roboppi/review.untracked` — 未追跡ファイル一覧 + - `roboppi/review.untracked.diff` — 未追跡ファイルの diff（サイズ制限付き） + +### validate — 最終チェック + +シェルスクリプトで `bun run lint` / `bun run format:check` / `bun run build` を実行し、すべて通れば `roboppi/validate.ok` を出力します。 + +--- + +## 8. 成果物とディレクトリ構造 + +ワークフロー実行後のディレクトリ: + +``` +your-project/ +├── roboppi/ +│ ├── request.md # 入力（チームが書いた） +│ ├── workflow.yaml # ワークフロー定義 +│ ├── base-branch.txt # ベースブランチ名 +│ ├── branch.txt # 作業ブランチ名 +│ ├── bootstrap.ok # bootstrap 成功マーカー +│ ├── design.md # AI が生成した設計書 +│ ├── todo.md # AI が生成した TODO（チェック済み項目あり） +│ ├── validate.ok # validate 成功マーカー +│ ├── review.base_ref # レビュー用: ベース参照 +│ ├── review.diff # レビュー用: 全 diff +│ ├── review.status # レビュー用: git status +│ ├── review.untracked # レビュー用: 未追跡ファイル一覧 +│ ├── review.untracked.diff # レビュー用: 未追跡ファイル diff +│ └── context/ # ステップ間コンテキスト +│ ├── _workflow.json +│ ├── design/ +│ │ └── _meta.json +│ ├── todo/ +│ │ └── _meta.json +│ └── validate/ +│ └── _meta.json +└── （実装された変更） +``` + +### チームでの活用 + +- `roboppi/design.md` — PR のレビュー前に設計意図を確認できる +- `roboppi/todo.md` — 実装の進捗を確認できる（チェック済みの `[x]` と未完了の `[ ]`） +- `roboppi/review.diff` — 手動レビューの入力として使える +- `roboppi/context/` — 各ステップの実行メタデータ（所要時間、リトライ回数など） + +--- + +## 9. ブランチ安全性 + +このワークフローは `create_branch: true` と `branch_transition_step: "branch"` を設定しています。 + +### Roboppi が保証すること + +1. **ベースブランチの確定的な解決** — 起動時にベースコミット SHA を記録し、以降のステップで一貫した基準を使う +2. **Branch Lock** — ステップ実行前にワークツリーとブランチが期待通りか検証。途中で別のブランチに切り替わっていたら fail-fast +3. **保護ブランチガード** — `main`, `master`, `release/*` への直接編集をデフォルトで禁止 + +### 安全な実行パターン + +```bash +# main ブランチ上で実行 → branch ステップが作業ブランチを切る → 以降はそのブランチで作業 +roboppi workflow roboppi/workflow.yaml \ + --workspace . \ + --base-branch main \ + --verbose +``` + +### 中断からの再開 + +ワークフローが途中で失敗しても、`roboppi/branch.txt` に作業ブランチ名が残っているので、再実行時に同じブランチが復帰されます。 + +```bash +# 再実行 — branch ステップが既存のブランチを checkout する +roboppi workflow roboppi/workflow.yaml \ + --workspace . \ + --base-branch main \ + --verbose +``` + +詳細: [docs/guides/branch.md](./guides/branch.md) / [docs/guides/branch.ja.md](./guides/branch.ja.md) + +--- + +## 10. チーム運用のベストプラクティス + +### ワークフロー管理 + +| やること | 理由 | +|----------|------| +| `roboppi/workflow.yaml` をリポジトリにコミット | チーム全員が同じワークフローを使える | +| `roboppi/request.md` を PR と一緒にコミット | 何を依頼したかが記録に残る | +| `roboppi/design.md` / `roboppi/todo.md` は `.gitignore` に入れる | 毎回再生成されるため | +| `roboppi/branch.txt` はケースバイケース | 共有したいならコミット、個人作業なら `.gitignore` | + +### request.md の書き方チーム規約 + +``` +1. 1 つの request.md に 1 つの機能（スコープを絞る） +2. 受け入れ基準を必ずチェックリストで書く +3. 既存コードへの影響範囲を明記する +4. 非スコープを明示する（エージェントの暴走を防ぐ） +``` + +### ワークフローのカスタマイズ + +プロジェクトの要件に合わせてワークフローを調整できます。 + +**タイムアウトの調整:** + +```yaml +timeout: "240m" # ワークフロー全体 +# 各ステップの timeout も個別に設定可能 +``` + +**ステップの追加・削除:** + +例えば、レビューループを追加する場合: + +```yaml + implement: + # ... + completion_check: + worker: OPENCODE + model: "openai/gpt-5.2" + decision_file: "roboppi/review.verdict" + instructions: | + # レビュー指示... + capabilities: [READ, EDIT, RUN_COMMANDS] + timeout: "15m" + max_iterations: 5 + on_iterations_exhausted: abort +``` + +**convergence（収束制御）の追加:** + +implement ステップでレビューループが空回りするのを防ぐ: + +```yaml + implement: + # ... + convergence: + enabled: true + stall_threshold: 2 # 同じ問題が 2 回繰り返されたらエスカレーション + max_stage: 3 # 最大 3 段階 + fail_on_max_stage: true # 最終段階で fail-fast +``` + +### CI/CD との統合 + +GitHub Actions で Roboppi ワークフローを実行する例: + +```yaml +# .github/workflows/roboppi.yml +name: Roboppi Workflow +on: + push: + paths: + - 'roboppi/request.md' + +jobs: + run-workflow: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Install Roboppi + run: | + curl -fsSL https://raw.githubusercontent.com/reoring/roboppi/main/install.sh | bash + + - name: Run workflow + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + run: | + roboppi workflow roboppi/workflow.yaml \ + --workspace . \ + --base-branch main \ + --verbose +``` + +### 複数のリクエストを並行して扱う + +チームメンバーがそれぞれ異なる機能を実装する場合: + +```bash +# メンバー A: 認証機能 +git checkout -b feat/auth +vim roboppi/request.md # 認証機能のリクエストを書く +roboppi workflow roboppi/workflow.yaml --workspace . --base-branch main --verbose + +# メンバー B: ダッシュボード機能 +git checkout -b feat/dashboard +vim roboppi/request.md # ダッシュボードのリクエストを書く +roboppi workflow roboppi/workflow.yaml --workspace . --base-branch main --verbose +``` + +各メンバーが別ブランチで作業することで、ワークフローの成果物が衝突しません。 + +--- + +## 11. トラブルシューティング + +### bootstrap が失敗する + +| エラーメッセージ | 原因 | 対処 | +|-----------------|------|------| +| `roboppi/request.md not found` | request.md がない | `roboppi/request.md` を作成する | +| `roboppi/request.md is too small` | 内容が 200 バイト未満 | リクエストを充実させる | +| `bun not found in PATH` | Bun がインストールされていない | Bun をインストールする | +| `opencode not found in PATH` | OpenCode がインストールされていない | `bun install -g opencode` | +| `claude not found in PATH` | Claude Code がインストールされていない | `npm install -g @anthropic-ai/claude-code` | + +### todo ステップが max_iterations に達する + +`completion_check` が以下を検証しています: + +- `roboppi/todo.md` に `- [ ]` が 10 項目以上あるか +- `bun run lint` / `bun run format:check` / `bun run build` のいずれかが含まれているか +- ファイルパス（`.ts`, `.tsx`, `.md` など）が含まれているか + +3 回のイテレーションで通らない場合は、`request.md` の内容がエージェントにとって曖昧すぎる可能性があります。より具体的な要件を書いてください。 + +### implement ステップが失敗する + +1. **lint/format/build エラー** — implement ステップは自力で修正を試みますが、修正しきれない場合があります。ログを確認して手動で対処するか、`roboppi/fix.md` に修正指示を書いて再実行してください。 + +2. **タイムアウト** — `timeout: "120m"` を超えた場合。タスクが大きすぎる可能性があります。`request.md` のスコープを絞ってください。 + +### ブランチ関連のエラー + +| エラー | 原因 | 対処 | +|--------|------|------| +| Branch Lock drift detected | ステップ間でブランチが変わった | 手動でブランチを戻す | +| Protected branch guard | main/master に直接編集しようとした | `--base-branch` を指定して作業ブランチを切る | + +### デバッグ用の環境変数 + +```bash +# IPC トレースを有効化 +ROBOPPI_IPC_TRACE=1 roboppi workflow ... + +# 詳細ログ +ROBOPPI_VERBOSE=1 roboppi workflow ... --verbose + +# IPC リクエストタイムアウトを延長 +ROBOPPI_IPC_REQUEST_TIMEOUT=5m roboppi workflow ... +``` + +--- + +## 12. 次のステップ + +### ドキュメント + +- [docs/guide/workflow.md](./guide/workflow.md) — ワークフロー YAML の完全なスキーマリファレンス +- [docs/guide/daemon.md](./guide/daemon.md) — デーモンモード（イベント駆動の自動実行） +- [docs/guide/architecture.md](./guide/architecture.md) — 内部アーキテクチャの詳細 +- [docs/guides/branch.md](./guides/branch.md) — ブランチ安全性の詳細 +- [docs/guides/agents.md](./guides/agents.md) — エージェントカタログ（再利用可能なプロファイル） +- [docs/design.md](./design.md) — コア設計ドキュメント + +### 発展的な使い方 + +- **レビューループの追加** — implement ステップに `completion_check` を追加して、AI レビュー → 修正のループを回す（`examples/agent-pr-loop.yaml` を参考） +- **デーモンモード** — `roboppi/request.md` の変更を検知して自動実行（`examples/daemon/agent-pr-loop.yaml` を参考） +- **エージェントカタログ** — ワーカーの設定を再利用（`docs/guides/agents.md` を参考） +- **PR 自動作成** — implement 後に `create_pr` ステップを追加（`examples/agent-pr-loop.yaml` を参考） + +### カスタムワークフローの作成 + +このワークフローをベースに、チームの開発フローに合わせたワークフローを作成できます。 + +```bash +# 例: テスト付きのフルループ +cp examples/appthrust-dashboard/workflow.yaml my-team/workflow.yaml +# 必要に応じてステップを追加・編集 +``` + +ワークフローの YAML スキーマについては [docs/guide/workflow.md](./guide/workflow.md) を参照してください。 diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..35ab6af --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,616 @@ +# Quickstart — Running Roboppi Workflows as a Team + +This guide explains how to introduce Roboppi workflows into a team project and run an automated pipeline for AI-driven design, implementation, and validation. + +We use `examples/appthrust-dashboard/workflow.yaml` (a production workflow for the AppThrust Dashboard project) as a running example. + +English | [日本語](quickstart.ja.md) + +--- + +## Contents + +1. [Prerequisites](#1-prerequisites) +2. [Installing Roboppi](#2-installing-roboppi) +3. [Workflow Overview](#3-workflow-overview) +4. [Integrating a Workflow into Your Project](#4-integrating-a-workflow-into-your-project) +5. [Writing request.md](#5-writing-requestmd) +6. [Running the Workflow](#6-running-the-workflow) +7. [Step-by-Step Walkthrough](#7-step-by-step-walkthrough) +8. [Artifacts and Directory Layout](#8-artifacts-and-directory-layout) +9. [Branch Safety](#9-branch-safety) +10. [Team Best Practices](#10-team-best-practices) +11. [Troubleshooting](#11-troubleshooting) +12. [Next Steps](#12-next-steps) + +--- + +## 1. Prerequisites + +### Required + +| Tool | Purpose | Install | +|------|---------|---------| +| [Bun](https://bun.sh/) v1.0+ | Runtime / package manager | `curl -fsSL https://bun.sh/install \| bash` | +| [Git](https://git-scm.com/) | Branch management, diff generation | OS package manager | + +### Worker CLIs (used by the workflow) + +| Tool | Role in the Workflow | Install | +|------|---------------------|---------| +| [OpenCode](https://opencode.ai/) | Design (`design`) and TODO generation (`todo`) | `bun install -g opencode` | +| [Claude Code](https://claude.ai/code) | Implementation (`implement`) | `npm install -g @anthropic-ai/claude-code` | + +Which tools you need depends on the `worker:` field of each step. `CUSTOM` steps run shell scripts directly and require no extra installation. + +### Optional + +| Tool | Purpose | +|------|---------| +| `gh` (GitHub CLI) | If you add a PR-creation step | +| `codex` (Codex CLI) | If you use Codex CLI as a worker | + +--- + +## 2. Installing Roboppi + +### Prebuilt binary (recommended) + +```bash +curl -fsSL https://raw.githubusercontent.com/reoring/roboppi/main/install.sh | bash +roboppi --help +``` + +### Build from source + +```bash +git clone https://github.com/reoring/roboppi.git +cd roboppi +bun install +make build +./roboppi --help +``` + +During development you can also run directly with `bun run src/workflow/run.ts` (no build step needed). + +--- + +## 3. Workflow Overview + +The AppThrust Dashboard workflow (`examples/appthrust-dashboard/workflow.yaml`) automates the following pipeline: + +``` +bootstrap ─→ branch ─→ deps ─→ design ─→ todo ─→ implement ─→ validate + │ │ │ │ │ │ │ + │ Validate │ Create/ │ bun │ Create │ Create │ Implement │ lint/ + │ env & │ reuse │install │ design │ TODO │ + generate │ format/ + │ init │ branch │ │ doc(AI) │ (AI) │ review │ build + │ │ │ │ │ │ inputs │ + └────────────┴─────────┴────────┴─────────┴────────┴────────────┴──────── +``` + +### Step roles + +| Step | Worker | Description | +|------|--------|-------------| +| `bootstrap` | CUSTOM | Validate the git repo, check `roboppi/request.md` exists, clear previous artifacts | +| `branch` | CUSTOM | Create or restore a work branch (persisted in `roboppi/branch.txt`) | +| `deps` | CUSTOM | `bun install` to install dependencies | +| `design` | OPENCODE (GPT-5.2) | Read `request.md` and generate a design doc at `roboppi/design.md` | +| `todo` | OPENCODE (GPT-5.2) | Convert the design into an implementation checklist at `roboppi/todo.md` (with completion_check) | +| `implement` | CLAUDE_CODE (Opus 4.6) | Implement the TODO list, pass lint/format/build, generate review diff files | +| `validate` | CUSTOM | Final `bun run lint` / `bun run format:check` / `bun run build` | + +### Why different workers? + +This workflow intentionally splits **design/planning with OpenCode (GPT-5.2)** and **implementation with Claude Code (Opus 4.6)**: + +- **OpenCode** — Best for read-only steps. Produces design docs and TODOs without editing code. +- **Claude Code** — Strong implementation capabilities. Handles code editing, command execution, and test fixing end-to-end. +- **CUSTOM** — Shell scripts for deterministic operations (branch switching, lint, build). + +--- + +## 4. Integrating a Workflow into Your Project + +### Directory layout + +Create the following structure in your project repository: + +``` +your-project/ +├── roboppi/ +│ ├── request.md # Implementation request (written by a team member) +│ ├── workflow.yaml # Workflow definition (copy or symlink) +│ ├── base-branch.txt # Base branch name (auto-generated) +│ ├── branch.txt # Work branch name (auto-generated) +│ └── context/ # Inter-step artifacts (auto-generated) +├── .gitignore +└── ... (existing source code) +``` + +### Setup steps + +```bash +cd /path/to/your-project + +# 1. Create the roboppi directory +mkdir -p roboppi + +# 2. Copy the workflow (or create a symlink) +cp /path/to/roboppi/examples/appthrust-dashboard/workflow.yaml roboppi/workflow.yaml + +# 3. Add generated artifacts to .gitignore +cat >> .gitignore << 'EOF' + +# Roboppi workflow artifacts +roboppi/design.md +roboppi/todo.md +roboppi/fix.md +roboppi/review.* +roboppi/validate.ok +roboppi/bootstrap.ok +roboppi/context/ +EOF +``` + +We recommend committing `roboppi/request.md` and `roboppi/workflow.yaml` so the entire team shares the same workflow and request. + +--- + +## 5. Writing request.md + +`roboppi/request.md` is the input for the entire workflow. AI agents read this file to drive their design and implementation. + +### Template + +```markdown +# Feature Name (short and clear) + +## Goal +What you want to achieve, in 1-3 sentences. + +## Requirements +- Specific requirements as bullet points +- If there is a UI, describe appearance and interactions +- Data flow (API / local mock / integration with existing code) + +## Out of scope +- Explicitly list what is NOT included + +## Acceptance criteria +- [ ] Checklist format +- [ ] `bun test` passes +- [ ] `bun run lint` passes +- [ ] `bun run build` passes + +## References +- Related docs, file paths, or external links +``` + +### Tips + +- Must be **at least 200 bytes**; the bootstrap step rejects empty or tiny requests. +- Writing acceptance criteria as checklists (`- [ ]`) helps the design/todo steps reference them directly. +- The more concrete the file paths, API shapes, and expected behavior, the higher quality the agent output. + +--- + +## 6. Running the Workflow + +### Basic usage + +```bash +# Set AGENTCORE_ROOT to where you cloned Roboppi +export AGENTCORE_ROOT="$HOME/roboppi" + +# Run the workflow +bun run --cwd "$AGENTCORE_ROOT" src/workflow/run.ts \ + /path/to/your-project/roboppi/workflow.yaml \ + --workspace /path/to/your-project \ + --base-branch main \ + --supervised --verbose +``` + +### Arguments + +| Argument | Description | +|----------|-------------| +| `--cwd "$AGENTCORE_ROOT"` | Run from the Roboppi source root (`bun run` resolves `src/workflow/run.ts` here) | +| 1st positional | Path to the workflow YAML | +| `--workspace` | Root directory of the target project | +| `--base-branch` | Base branch (default: current branch) | +| `--supervised` | Run in 3-layer mode: Supervisor -> Core -> Worker (default) | +| `--verbose` | Show output from each step | + +### Using the prebuilt binary + +```bash +roboppi workflow /path/to/your-project/roboppi/workflow.yaml \ + --workspace /path/to/your-project \ + --base-branch main \ + --verbose +``` + +### Convenient aliases + +For frequent use, add a script to your project's `Makefile` or `package.json`: + +```makefile +# Makefile +AGENTCORE_ROOT ?= $(HOME)/roboppi + +roboppi: + bun run --cwd "$(AGENTCORE_ROOT)" src/workflow/run.ts \ + roboppi/workflow.yaml \ + --workspace "$(PWD)" \ + --base-branch main \ + --supervised --verbose +``` + +```bash +make roboppi +``` + +--- + +## 7. Step-by-Step Walkthrough + +### bootstrap — Environment validation + +```yaml +bootstrap: + worker: CUSTOM + instructions: | + set -euo pipefail + # Check this is a git repo + # Validate roboppi/request.md exists and has minimum size + # Clear previous intermediate artifacts + # Verify required commands (bun, opencode, claude) are in PATH +``` + +**Common failures:** +- `roboppi/request.md not found` → Create the file first +- `roboppi/request.md is too small` → Add more content (need 200+ bytes) +- `bun/opencode/claude not found in PATH` → Install the missing tool + +### branch — Branch management + +Handles three cases: + +| Case | Behavior | +|------|----------| +| `roboppi/branch.txt` has a name + branch exists locally | Checkout that branch | +| `roboppi/branch.txt` has a name + branch exists only on remote | Track and checkout | +| No branch name (first run) | Create `roboppi/features-YYYYMMDD-HHMMSS` | + +Committing `roboppi/branch.txt` lets team members share the same working branch. + +### design — AI-generated design doc + +OpenCode (GPT-5.2) reads `roboppi/request.md` and existing project docs, then generates `roboppi/design.md` containing: + +- MVP scope declaration +- Route map +- UI components list +- Data fetching strategy +- Auth considerations +- Edge cases and risks +- Verification plan +- Acceptance criteria checklist + +**`on_failure: retry` + `max_retries: 1`** — Retries once on failure. + +### todo — Loop with completion_check + +OpenCode generates a TODO checklist from the design doc. A `completion_check` validates quality: + +```yaml +completion_check: + worker: CUSTOM + instructions: | + # At least 10 checklist items? + # Contains lint/format/build commands? + # Contains file path hints? +``` + +**`max_iterations: 3`** — Up to 3 attempts. Aborts if the check never passes. + +This mechanically prevents "too-thin TODOs" or "missing validation steps". + +### implement — The core implementation step + +Claude Code (Opus 4.6) implements the TODO list. + +Key behaviors: +- If `roboppi/fix.md` exists, applies only those targeted fixes (for review loops) +- Must pass `bun run lint` / `bun run format:check` / `bun run build` +- Generates review input files at the end: + - `roboppi/review.base_ref` — Base commit for diffs + - `roboppi/review.diff` — Full diff from base + - `roboppi/review.status` — `git status --porcelain` + - `roboppi/review.untracked` — Untracked file list + - `roboppi/review.untracked.diff` — Untracked file diffs (size-bounded) + +### validate — Final checks + +Runs `bun run lint` / `bun run format:check` / `bun run build` as a shell script. Writes `roboppi/validate.ok` on success. + +--- + +## 8. Artifacts and Directory Layout + +After a successful workflow run: + +``` +your-project/ +├── roboppi/ +│ ├── request.md # Input (written by team) +│ ├── workflow.yaml # Workflow definition +│ ├── base-branch.txt # Base branch name +│ ├── branch.txt # Work branch name +│ ├── bootstrap.ok # Bootstrap success marker +│ ├── design.md # AI-generated design doc +│ ├── todo.md # AI-generated TODO (with checked items) +│ ├── validate.ok # Validate success marker +│ ├── review.base_ref # Review input: base ref +│ ├── review.diff # Review input: full diff +│ ├── review.status # Review input: git status +│ ├── review.untracked # Review input: untracked files +│ ├── review.untracked.diff # Review input: untracked file diffs +│ └── context/ # Inter-step context +│ ├── _workflow.json +│ ├── design/ +│ │ └── _meta.json +│ ├── todo/ +│ │ └── _meta.json +│ └── validate/ +│ └── _meta.json +└── (implemented changes) +``` + +### How teams use these artifacts + +- `roboppi/design.md` — Review design intent before looking at a PR +- `roboppi/todo.md` — Track progress (checked `[x]` vs unchecked `[ ]` items) +- `roboppi/review.diff` — Use as input for manual code review +- `roboppi/context/` — Step execution metadata (duration, retry count, etc.) + +--- + +## 9. Branch Safety + +This workflow sets `create_branch: true` and `branch_transition_step: "branch"`. + +### What Roboppi guarantees + +1. **Deterministic base branch resolution** — Records the base commit SHA at startup and uses a consistent reference across all steps. +2. **Branch Lock** — Before each step, verifies the worktree and branch match expectations. Fails fast if the branch drifted. +3. **Protected branch guard** — Blocks direct edits to `main`, `master`, and `release/*` by default. + +### Safe execution pattern + +```bash +# Start on main → the branch step creates a work branch → all subsequent steps run on it +roboppi workflow roboppi/workflow.yaml \ + --workspace . \ + --base-branch main \ + --verbose +``` + +### Resuming after a failure + +If the workflow fails mid-run, `roboppi/branch.txt` retains the work branch name. Re-running restores the same branch: + +```bash +# Re-run — the branch step checks out the existing branch +roboppi workflow roboppi/workflow.yaml \ + --workspace . \ + --base-branch main \ + --verbose +``` + +Details: [docs/guides/branch.md](./guides/branch.md) + +--- + +## 10. Team Best Practices + +### File management + +| Practice | Rationale | +|----------|-----------| +| Commit `roboppi/workflow.yaml` to the repo | Everyone uses the same workflow | +| Commit `roboppi/request.md` alongside PRs | Records what was requested | +| Add `roboppi/design.md` / `roboppi/todo.md` to `.gitignore` | Regenerated on every run | +| `roboppi/branch.txt` — case by case | Commit if you want to share the branch; `.gitignore` for personal work | + +### Team conventions for request.md + +``` +1. One request.md per feature (keep scope narrow) +2. Always include acceptance criteria as checklists +3. Specify the impact on existing code +4. Explicitly list out-of-scope items (prevents agent drift) +``` + +### Customizing the workflow + +Adjust the workflow to match your project's needs: + +**Adjusting timeouts:** + +```yaml +timeout: "240m" # Workflow-level +# Each step also has its own timeout +``` + +**Adding a review loop:** + +Add a `completion_check` to the implement step for AI review -> fix iteration: + +```yaml + implement: + # ... + completion_check: + worker: OPENCODE + model: "openai/gpt-5.2" + decision_file: "roboppi/review.verdict" + instructions: | + # Review instructions... + capabilities: [READ, EDIT, RUN_COMMANDS] + timeout: "15m" + max_iterations: 5 + on_iterations_exhausted: abort +``` + +**Adding convergence control:** + +Prevent non-terminating review loops: + +```yaml + implement: + # ... + convergence: + enabled: true + stall_threshold: 2 # Escalate after the same issue repeats 2 times + max_stage: 3 # 3 stages max + fail_on_max_stage: true # Fail-fast at final stage +``` + +### CI/CD integration + +Example GitHub Actions workflow: + +```yaml +# .github/workflows/roboppi.yml +name: Roboppi Workflow +on: + push: + paths: + - 'roboppi/request.md' + +jobs: + run-workflow: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Install Roboppi + run: | + curl -fsSL https://raw.githubusercontent.com/reoring/roboppi/main/install.sh | bash + + - name: Run workflow + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + run: | + roboppi workflow roboppi/workflow.yaml \ + --workspace . \ + --base-branch main \ + --verbose +``` + +### Parallel work by team members + +When team members work on different features concurrently: + +```bash +# Member A: auth feature +git checkout -b feat/auth +vim roboppi/request.md # Write the auth request +roboppi workflow roboppi/workflow.yaml --workspace . --base-branch main --verbose + +# Member B: dashboard feature +git checkout -b feat/dashboard +vim roboppi/request.md # Write the dashboard request +roboppi workflow roboppi/workflow.yaml --workspace . --base-branch main --verbose +``` + +Each member works on a separate branch, so workflow artifacts never conflict. + +--- + +## 11. Troubleshooting + +### bootstrap fails + +| Error | Cause | Fix | +|-------|-------|-----| +| `roboppi/request.md not found` | File does not exist | Create `roboppi/request.md` | +| `roboppi/request.md is too small` | Content under 200 bytes | Add more detail to the request | +| `bun not found in PATH` | Bun not installed | Install Bun | +| `opencode not found in PATH` | OpenCode not installed | `bun install -g opencode` | +| `claude not found in PATH` | Claude Code not installed | `npm install -g @anthropic-ai/claude-code` | + +### todo step hits max_iterations + +The `completion_check` validates: + +- At least 10 checklist items (`- [ ]`) in `roboppi/todo.md` +- At least one of `bun run lint` / `bun run format:check` / `bun run build` mentioned +- At least one file path (`.ts`, `.tsx`, `.md`, etc.) included + +If it fails after 3 iterations, your `request.md` may be too vague for the agent. Add more specific requirements. + +### implement step fails + +1. **lint/format/build errors** — The implement step tries to self-repair, but may not always succeed. Check the logs and either fix manually or write specific instructions in `roboppi/fix.md` and re-run. + +2. **Timeout** — The default is `timeout: "120m"`. If exceeded, the task may be too large. Narrow the scope in `request.md`. + +### Branch-related errors + +| Error | Cause | Fix | +|-------|-------|-----| +| Branch Lock drift detected | Branch changed between steps | Manually checkout the expected branch | +| Protected branch guard | Attempting direct edits on main/master | Use `--base-branch` so a work branch is created | + +### Debugging environment variables + +```bash +# Enable IPC trace +ROBOPPI_IPC_TRACE=1 roboppi workflow ... + +# Verbose logging +ROBOPPI_VERBOSE=1 roboppi workflow ... --verbose + +# Extend IPC request timeout +ROBOPPI_IPC_REQUEST_TIMEOUT=5m roboppi workflow ... +``` + +--- + +## 12. Next Steps + +### Documentation + +- [docs/guide/workflow.md](./guide/workflow.md) — Full workflow YAML schema reference +- [docs/guide/daemon.md](./guide/daemon.md) — Daemon mode (event-driven execution) +- [docs/guide/architecture.md](./guide/architecture.md) — Internal architecture details +- [docs/guides/branch.md](./guides/branch.md) — Branch safety details +- [docs/guides/agents.md](./guides/agents.md) — Agent catalogs (reusable profiles) +- [docs/design.md](./design.md) — Core design document + +### Advanced usage + +- **Review loop** — Add a `completion_check` to the implement step for AI review -> fix iteration (see `examples/agent-pr-loop.yaml`) +- **Daemon mode** — Auto-trigger on `roboppi/request.md` changes (see `examples/daemon/agent-pr-loop.yaml`) +- **Agent catalogs** — Reuse worker settings across steps (see `docs/guides/agents.md`) +- **Auto PR creation** — Add a `create_pr` step after implement (see `examples/agent-pr-loop.yaml`) + +### Creating a custom workflow + +Use this workflow as a starting point and adapt it to your team's development flow: + +```bash +# Example: copy and customize +cp examples/appthrust-dashboard/workflow.yaml my-team/workflow.yaml +# Add/edit steps as needed +``` + +See [docs/guide/workflow.md](./guide/workflow.md) for the full YAML schema. diff --git a/examples/README.ja.md b/examples/README.ja.md index 2898f56..f3a46ed 100644 --- a/examples/README.ja.md +++ b/examples/README.ja.md @@ -41,6 +41,7 @@ timeout 10s ./roboppi daemon examples/daemon/simple-cron.yaml --verbose - `examples/failure-recovery.yaml`: 失敗時の挙動（retry/continue など） - `examples/todo-loop.yaml`: 反復ループの最小パターン - `examples/agent-pr-loop.yaml`: 大きめのエージェントループ（デモは `examples/agent-pr-loop-demo/`） +- `examples/appthrust-dashboard/workflow.yaml`: チームプロジェクト向けの本番ワークフロー（design -> todo -> implement -> validate） ## daemon の例 diff --git a/examples/README.md b/examples/README.md index fd146af..6962c2b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -41,6 +41,7 @@ timeout 10s ./roboppi daemon examples/daemon/simple-cron.yaml --verbose - `examples/failure-recovery.yaml`: failure handling / retry patterns - `examples/todo-loop.yaml`: simple iterative loop pattern - `examples/agent-pr-loop.yaml`: larger multi-step agent loop (see demo under `examples/agent-pr-loop-demo/`) +- `examples/appthrust-dashboard/workflow.yaml`: production workflow for a team project (design -> todo -> implement -> validate) ## Daemon examples diff --git a/examples/appthrust-dashboard/workflow.yaml b/examples/appthrust-dashboard/workflow.yaml new file mode 100644 index 0000000..bf786d9 --- /dev/null +++ b/examples/appthrust-dashboard/workflow.yaml @@ -0,0 +1,362 @@ +# appthrust/dashboard - Roboppi workflow +# +# Run example: +# +# export AGENTCORE_ROOT="$HOME/roboppi" +# +# bun run --cwd "$AGENTCORE_ROOT" src/workflow/run.ts \ +# "$PWD/roboppi/workflow.yaml" \ +# --workspace "$PWD" \ +# --base-branch main \ +# --supervised --verbose +# +# Note: +# - In bash/zsh, `AGENTCORE_ROOT=... bun ... "$AGENTCORE_ROOT"` will expand to the *previous* value. +# Set it with `export` first (as above), or use the literal path for `--cwd`. + +name: appthrust-dashboard-roboppi +version: "1" +description: "Implement roboppi/request.md as a scoped change for AppThrust Dashboard" +timeout: "240m" +concurrency: 1 + +# Keep Roboppi artifacts under PROJECT_ROOT/roboppi/ +context_dir: "./roboppi/context" + +# Branch safety (see ~/roboppi/docs/guides/branch.ja.md) +create_branch: true +branch_transition_step: "branch" + +steps: + bootstrap: + description: "Validate tools and initialize Roboppi artifacts" + worker: CUSTOM + instructions: | + set -euo pipefail + + if ! git rev-parse --git-dir > /dev/null 2>&1; then + echo "Error: workspace must be a git repository" >&2 + exit 1 + fi + + mkdir -p roboppi + + # Fail fast if request is missing/empty. + if [ ! -f roboppi/request.md ]; then + echo "Error: roboppi/request.md not found" >&2 + exit 1 + fi + REQ_BYTES=$(wc -c < roboppi/request.md | tr -d ' ') + if [ "${REQ_BYTES}" -lt 200 ]; then + echo "Error: roboppi/request.md is too small. Please fill it in first." >&2 + exit 1 + fi + + # Clear derived artifacts from prior runs (keep request + branch/base settings). + rm -f \ + roboppi/design.md \ + roboppi/todo.md \ + roboppi/fix.md \ + roboppi/review.md \ + roboppi/review.verdict \ + roboppi/review.base_ref \ + roboppi/review.diff \ + roboppi/review.status \ + roboppi/review.untracked \ + roboppi/review.untracked.diff \ + roboppi/validate.ok + + # Tools required by this workflow. + command -v bun > /dev/null 2>&1 || { echo "Error: bun not found in PATH" >&2; exit 1; } + command -v opencode > /dev/null 2>&1 || { echo "Error: opencode not found in PATH" >&2; exit 1; } + command -v claude > /dev/null 2>&1 || { echo "Error: claude not found in PATH" >&2; exit 1; } + + # Persist base branch name for review input generation. + if [ -n "${BASE_BRANCH:-}" ]; then + echo "${BASE_BRANCH}" > roboppi/base-branch.txt + elif [ ! -f roboppi/base-branch.txt ]; then + echo "$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo main)" > roboppi/base-branch.txt + fi + + echo "OK" > roboppi/bootstrap.ok + capabilities: [READ, EDIT, RUN_COMMANDS] + timeout: "3m" + + branch: + description: "Create or reuse a working branch" + worker: CUSTOM + depends_on: [bootstrap] + instructions: | + set -euo pipefail + + mkdir -p roboppi + BASE_BRANCH=$(cat roboppi/base-branch.txt 2>/dev/null || echo "${BASE_BRANCH:-main}") + BRANCH_FILE=roboppi/branch.txt + + if [ -f "${BRANCH_FILE}" ] && [ -n "$(tr -d ' ' < "${BRANCH_FILE}")" ]; then + BRANCH=$(cat "${BRANCH_FILE}") + else + BRANCH="roboppi/features-$(date +%Y%m%d-%H%M%S)" + echo "${BRANCH}" > "${BRANCH_FILE}" + fi + + # Prefer the deterministic base commit resolved by Roboppi at startup. + BASE_REF="" + if [ -n "${AGENTCORE_EFFECTIVE_BASE_SHA:-}" ] \ + && git cat-file -e "${AGENTCORE_EFFECTIVE_BASE_SHA}^{commit}" 2>/dev/null; then + BASE_REF="${AGENTCORE_EFFECTIVE_BASE_SHA}" + else + git fetch origin "${BASE_BRANCH}" > /dev/null 2>&1 || true + git fetch origin "${BRANCH}" > /dev/null 2>&1 || true + if git show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then + BASE_REF="${BASE_BRANCH}" + elif git show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then + BASE_REF="origin/${BASE_BRANCH}" + else + BASE_REF="HEAD" + fi + fi + + if git show-ref --verify --quiet "refs/heads/${BRANCH}"; then + git checkout "${BRANCH}" + ACTION="reuse-local" + elif git show-ref --verify --quiet "refs/remotes/origin/${BRANCH}"; then + git checkout -b "${BRANCH}" --track "origin/${BRANCH}" + ACTION="track-remote" + else + git checkout -b "${BRANCH}" "${BASE_REF}" + ACTION="create-from-base" + fi + + echo "BRANCH=${BRANCH} BASE_REF=${BASE_REF} ACTION=${ACTION}" + capabilities: [READ, RUN_COMMANDS] + timeout: "2m" + + deps: + description: "Install dependencies (idempotent)" + worker: CUSTOM + depends_on: [branch] + instructions: | + set -euo pipefail + bun install + capabilities: [READ, EDIT, RUN_COMMANDS] + timeout: "15m" + + design: + description: "Produce an implementation plan (no code changes)" + worker: OPENCODE + model: "openai/gpt-5.2" + depends_on: [deps] + instructions: | + You are OpenCode. + + Task: Produce an implementation plan ONLY (no code changes in this step). + + Read: + - roboppi/request.md + - README.md + - docs/design/README.md + - docs/design/auth.md + - docs/design/auth-keycloak-authjs.md + - docs/design/auth-signin-keycloak-integration.md + + Write/update: + - roboppi/design.md + + Requirements for roboppi/design.md: + - MVP scope declaration (what you WILL / WILL NOT implement now) + - Route map (TanStack Router file routes -> URL paths) + - UI components to build/reuse (by file path) + - Data fetching / local mock strategy (if backend not in scope) + - Auth/session considerations (if request touches auth) + - Edge cases + risks + - Verification plan (commands + key manual flows) + - Acceptance criteria checklist (copy from request, refine if needed) + capabilities: [READ, EDIT] + timeout: "30m" + on_failure: retry + max_retries: 1 + outputs: + - name: design + path: "roboppi/design.md" + type: review + + todo: + description: "Turn the plan into a concrete TODO checklist" + worker: OPENCODE + model: "openai/gpt-5.2" + depends_on: [design] + instructions: | + You are OpenCode. + + Task: Convert the plan into an implementation TODO checklist. + + Read: + - roboppi/request.md + - roboppi/design.md + - README.md + - docs/design/auth.md + + Write/update: + - roboppi/todo.md + + TODO requirements: + - Use Markdown checklist items: "- [ ] ..." + - Group by milestones (small batches) + - Include file paths whenever possible + - Include required repo checks: bun run lint / bun run format:check / bun run build + - Include at least 2 manual validation flows + + If roboppi/todo.md already exists, improve it to satisfy the requirements. + capabilities: [READ, EDIT] + timeout: "30m" + on_failure: retry + max_retries: 1 + + completion_check: + worker: CUSTOM + instructions: | + set -euo pipefail + TODO=roboppi/todo.md + test -s "${TODO}" || { echo "CHECK: missing todo"; exit 1; } + + COUNT=$(grep -c '^- \[ \] ' "${TODO}" || true) + if [ "${COUNT}" -lt 10 ]; then + echo "CHECK: too few tasks: ${COUNT}" + exit 1 + fi + + if ! grep -Eqi '(bun run lint|bun run format:check|bun run build)' "${TODO}"; then + echo "CHECK: missing required validation commands" + exit 1 + fi + + if ! grep -Eq '([A-Za-z0-9_./-]+\.(ts|tsx|js|jsx|md|yml|yaml|json))' "${TODO}"; then + echo "CHECK: no file-path hints found" + exit 1 + fi + + echo "CHECK: todo looks complete" + capabilities: [READ, RUN_COMMANDS] + timeout: "45s" + + max_iterations: 3 + on_iterations_exhausted: abort + outputs: + - name: todo + path: "roboppi/todo.md" + type: code + + implement: + description: "Implement the change set (scoped MVP)" + worker: CLAUDE_CODE + model: "claude-opus-4-6" + depends_on: [todo] + instructions: | + You are Claude Code. + + Read: + - roboppi/request.md + - roboppi/design.md + - roboppi/todo.md + - roboppi/fix.md (if present) + - README.md + - docs/design/auth.md + + Task: + - If roboppi/fix.md exists and is non-empty, apply ONLY those fixes (minimal, targeted). + - Otherwise, implement the TODO checklist. + - Update roboppi/todo.md checkboxes as you complete items. + - Do not add secrets. Do not commit .env files. + + Mandatory verification (fix failures): + - bun run lint + - bun run format:check (run bun run format if needed) + - bun run build + + Mandatory: generate deterministic review inputs for a checker (overwrite each run): + - roboppi/review.base_ref + - roboppi/review.diff + - roboppi/review.status + - roboppi/review.untracked + - roboppi/review.untracked.diff + + Use this exact script at the end of the run: + + ```bash + set -euo pipefail + mkdir -p roboppi + + # Prefer deterministic base SHA if available. + if [ -n "${AGENTCORE_EFFECTIVE_BASE_SHA:-}" ] \ + && git cat-file -e "${AGENTCORE_EFFECTIVE_BASE_SHA}^{commit}" 2>/dev/null; then + BASE_REF="${AGENTCORE_EFFECTIVE_BASE_SHA}" + else + BASE_BRANCH=$(cat roboppi/base-branch.txt 2>/dev/null || echo main) + git fetch origin "${BASE_BRANCH}" >/dev/null 2>&1 || true + if git show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then + BASE_REF="${BASE_BRANCH}" + elif git show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then + BASE_REF="origin/${BASE_BRANCH}" + else + BASE_REF="HEAD" + fi + fi + echo "${BASE_REF}" > roboppi/review.base_ref + git diff --no-color "${BASE_REF}" > roboppi/review.diff || true + git status --porcelain=v1 > roboppi/review.status || true + git ls-files --others --exclude-standard > roboppi/review.untracked || true + + # bounded untracked diffs + MAX_FILES=200 + MAX_FILE_BYTES=200000 + MAX_TOTAL_BYTES=2000000 + out=roboppi/review.untracked.diff + : > "${out}" + count=0 + total=0 + while IFS= read -r f; do + [ -n "${f}" ] || continue + [ -f "${f}" ] || continue + count=$((count + 1)) + if [ "${count}" -gt "${MAX_FILES}" ]; then + printf 'NOTE: untracked diff truncated after %s files\n' "${MAX_FILES}" >> "${out}" + break + fi + bytes=$(wc -c < "${f}" | tr -d ' ') + if [ "${bytes}" -gt "${MAX_FILE_BYTES}" ]; then + printf 'NOTE: skipped large untracked file (%s bytes): %s\n' "${bytes}" "${f}" >> "${out}" + continue + fi + if [ $((total + bytes)) -gt "${MAX_TOTAL_BYTES}" ]; then + printf 'NOTE: untracked diff truncated at ~%s bytes\n' "${MAX_TOTAL_BYTES}" >> "${out}" + break + fi + total=$((total + bytes)) + git diff --no-color --no-index -- /dev/null "${f}" >> "${out}" || true + printf '\n' >> "${out}" + done < roboppi/review.untracked + ``` + + At the end, briefly report what you implemented and how to verify. + capabilities: [READ, EDIT, RUN_TESTS, RUN_COMMANDS] + timeout: "120m" + on_failure: retry + max_retries: 1 + + validate: + description: "Run repo checks (lint/format/build)" + worker: CUSTOM + depends_on: [implement] + instructions: | + set -euo pipefail + bun run lint + bun run format:check + bun run build + echo "OK" > roboppi/validate.ok + capabilities: [READ, EDIT, RUN_COMMANDS] + timeout: "30m" + outputs: + - name: validate + path: "roboppi/validate.ok" + type: text