| name | ravel-impl |
| description | Ravel の実装単位を worktree 隔離でサブエージェントへ委譲し、独立検証 → ravel-review + 独立レビュー（既定 codex、--review で指定 / skip）の 突き合わせ → 指摘対応 → PR → CI → （明示時のみ）マージまで通す。 単位 ID から仕様・完了条件・依存・フェーズ境界を scripts/docs.sh で解決し、 依存が未マージなら起動しない。複数単位は --multi（並行・単位ごとに PR） または --compress（1 PR に集約）。 トリガー: "/ravel-impl"、「この単位を実装して」「委譲して」（単位 ID を伴う）。 |
ravel-impl
実装単位を、着手からマージ可能な状態まで運ぶ。手を動かすのは
サブエージェント、判断と検証は呼び出し側という分担を守る。
既定は 1 単位 1 PR。複数を並行で回すなら --multi、PR を 1 本に畳むなら
--compress（§2b）。
既定では呼び出し側（あなた）は司令塔に徹する。実装差分を自分で書き始めない。
例外は「指摘対応のうち局所的なもの」（§5）と、--self を明示したとき（§4）。
0. 引数
/ravel-impl <単位 ID | 自由文> [オプション]
| オプション | 意味 |
|---|
--agent <claude|kimi|codex> | 実装するサブエージェント。既定 claude |
--self | 委譲せず自分で実装する。worktree 隔離と §5 以降はそのまま |
--brief | ブリーフを書いてそこで止まる（起動しない） |
--transfer-only | 委譲して起動した時点で返す（検証・レビュー・PR をやらない） |
--no-pr | 指摘対応まで済ませ、PR を作らずブランチを残して返す |
--merge | CI 全緑 + Critical / FAIL 無しならマージし、状態更新と掃除まで行う |
--review-cycle n | 「指摘 → 修正 → 再レビュー」の上限巡回数。既定 2 |
--stack | 未マージ依存のブランチに重ねる（既定は拒否。§2） |
--multi | 複数の単位 ID を受け、依存上ぶつからないものを並行で、単位ごとに PRで回す |
--compress | 複数の単位 ID を受け、1 ブランチ 1 PR にまとめる（§2b） |
--review <agent|skip> | 独立レビューの担当。既定 codex。skip でも自分の検査は省かない（§5） |
--squash | マージを squash にする。既定は merge コミット（§7） |
既定はマージしない。 --merge は無人で回すときに明示する。
--multi と --compress は排他。前者は PR を分けて並行で速く回す、
後者は PR を 1 本に畳む。同時に指定されたら止めて聞く。
1. 単位の解決
bash scripts/docs.sh id <単位 ID>
ここから 4 つを取る。これがブリーフの背骨になる。
- 仕様の正: 計画書の「単位 N」節（
docs/implementation/*-plan.md）
- 完了条件: 同じ節の一覧。言い換えずに写す
- 状態と依存:
backlog.md の行
- フェーズ境界:
roadmap.md の該当フェーズ表
単位 ID が解決できない自由文のときは規模で判定する:
- 複数クレート / 複数パネル / 評価・永続化・コマンド経路に触れる →
起動せず「先に
docs/implementation/ の計画書を」と返す（AGENTS.md の
Design gate）
- 局所修正・単一パネルの機能 → そのまま進める
2. 依存の確認
backlog.md の依存列を見て、✅ 以外の依存が 1 つでもあれば起動しない。
理由（どの単位が未マージか、その PR 番号があれば添えて）を返して終わる。
--stack のときだけ依存ブランチから切って重ねる。依存が先にマージされたら
rebase する。依存先のレビュー修正は全部下流に伝播するので、既定にしない。
2b. --compress（複数単位を 1 PR に畳む）
フェーズ丸ごとを片付けたいときに、PR の本数を減らす。
主目的はレビューを 1 回にまとめることで、CI 待ちの削減は副次的。
まとめすぎるとレビューの密度が落ち、人間が読むのも辛くなる。迷ったら
まとめない側に倒す。
まとめてよい条件
次をすべて満たすときだけ 1 グループにする。
- 同じ計画書の単位であること。
*-plan.md をまたぐ組は作らない。
PR のテーマが 1 つに保たれ、本文の「なぜ今か」が 1 段落で書ける
- 集合の中で依存を並べられること。 依存が鎖でなくてもよい
（
EXPO-4 / EXPO-5 / EXPO-6 のように同じ親にぶら下がる並列も可）。
トポロジカルソートできればよい
- 集合の外に未マージの依存が無いこと。 §2 と同じ判定
満たさない組が混ざっていたら、満たす部分集合を提案して確認を取る。
勝手に落とさない。
しきい値で確認を取る
上限は設けないが、5 単位を超えるか、diff が 1500 行を超える見込みの
ときは、起動前に分割案を出して確認する。
EXPO-2..EXPO-7 の 6 単位（見込み 2400 行）。
2 本に割ることを勧める:
A: EXPO-2, EXPO-3, EXPO-4 （束縛の解決と列挙）
B: EXPO-5, EXPO-6, EXPO-7 （編集 UI と文書）
このまま 1 本にするか、A / B に割るか。
進め方の差分
- worktree は 1 つ。 名前はグループを表すもの（
.worktrees/expo-binding）。
単位 ID を並べた名前にしない
- ブランチも 1 本。 グループ全体を表す具体的なケバブケース
- ブリーフは単位ごとに節を分ける（§4）。「やること」「完了条件」は
単位ごとに独立して書き、実装順を依存順で明示する
- コミットは単位ごとに分ける。 これは畳まない。
git log で単位の
境界が読めることが、まとめた PR をレビュー可能にする唯一の担保。
既定の merge コミットならその境界が main にもそのまま残る
（だから --squash との併用は §7 で止めて聞く）
- レビューは単位ごとに検査する。 diff 全体を 1 度眺めて終わりにしない。
§5 のチェックリストを単位ごとに辿る
- 1 単位に FAIL が出ると PR 全体が止まる。 これは受け入れる。
切り離したくなったら、その単位だけ別ブランチへ移す判断を止めて聞く
3. worktree を切る
git worktree add .worktrees/<単位 ID 小文字> -b <prefix>/<kebab-case> <base>
- 場所はリポジトリ直下の
.worktrees/。.gitignore に /.worktrees/ が
無ければ最初に足す（一度きり）
- ブランチ名は
.agents/rules/ の規約どおり、意味のある prefix +
具体的なケバブケース。単位 ID をブランチ名に入れない
base は main（--stack なら依存ブランチ）- 新しい worktree では
mise trust を一度実行する。しないと mise run が
全部 Config files … are not trusted で落ちる
4. ブリーフを渡す
ブリーフはリポジトリの外（セッションの一時ディレクトリ）に書き、
サブエージェントにはパスを渡して「まず読め」と指示する。
worktree の中にメモを置かせない（git add -A での混入事故を原理的に断つ）。
ブリーフに必ず入れる 7 項目:
- 作業場所: worktree の絶対パスとブランチ名。「主ワークツリーと他の
worktree には触るな」を明記（並行作業がある）
- 最初に読むもの:
AGENTS.md、対象ファイルに paths が一致する
.agents/rules/*.md、計画書の該当単位、関連する docs/dev/ の手順書
- 前提: 直前にマージされた単位が用意した型・関数・規約。倣うべき既存の
形を名指しする（例「
RequiresPlanarP / require_planar と同じ粒度で」）
- やること: 計画書の記述 + 実測した箇所数（
grep -c の結果を書く。
計画書の数字は古いことがある）
- 完了条件: 計画書から逐語で写す
- 制約: push と PR の禁止、
git add -A 禁止、論理単位ごとの英語 1 行
Conventional Commit（タスク ID・issue 番号・エージェント名・セッション URL を
書かない）、mise run check と mise run docs:check を通す、
scripts/lint-patterns.sh を弱めない、本番依存を追加しない（要ると
判断したら実装せず報告）、backlog / roadmap の状態列は触らない（§7）、
フェーズの外へ出ない（触ってはいけない単位を名指しする）
- 最終報告の形: コミット一覧、変更ファイル、検証結果、設計判断、
既存ゴールデンが無改変であることの確認、判断が必要な点、worktree のパス
--brief ならここで止まる。--transfer-only なら起動して返す。
--compress のブリーフ
上の 7 項目のうち 1・2・3・6・7 はグループで 1 回書き、
4（やること）と 5（完了条件）は単位ごとに節を分ける。
## 実装順（依存順。この順で 1 単位ずつ完了させること）
1. EXPO-2 束縛の解決と適用
2. EXPO-3 宣言の機械可読な列挙
3. EXPO-4 素材参照の宣言と差し替え
### 単位 1: EXPO-2 …
やること / 完了条件
### 単位 2: EXPO-3 …
やること / 完了条件
追加で必ず書く制約:
- 単位ごとにコミットを分ける。 1 単位が複数コミットになるのは可。
複数単位を 1 コミットに混ぜるのは不可
- 前の単位の完了条件を満たしてから次へ進む。 まとめて実装して
最後にテストを書かない
- 報告は単位ごとに節を分ける。 どの単位のどのコミットか対応が付く形
--self（委譲しない）
委譲せず自分で実装する。§1〜3 と §5 以降は変わらない — 単位の解決、
依存の確認、worktree 隔離、独立検証、レビュー、PR、状態更新まで同じ手順を
踏む。飛ばすのはブリーフの受け渡しと起動だけ。
worktree を切るのは --self でも同じ。並行して別の作業が走っていても
主ワークツリーが汚れず、失敗しても捨てられる。
ただしレビューの独立性が落ちる（書いた本人が読むことになる）。
--self のときは §5 の codex への独立レビューを省略しない。codex が
使えないなら、少なくとも「この変更が入れた退行か、元からある穴か」を
main と比較して確認する手順を明示的に踏む。
単位が小さい（1 ファイル、機械的、完了条件が 2〜3 個）ときや、委譲の往復が
実装そのものより高くつくときに使う。
エージェント別の起動と進捗の見方
| agent | 起動 | 完了の判断 |
|---|
claude | サブエージェント機構（worktree 隔離が使えるならそれに乗る） | 完了通知 |
kimi / codex | herdr pane run <pane> にブリーフのパスを渡す。実行前に cwd と前面プロセスを確認 | worktree の git log / git status の変化と画面 |
agent_status 単独を根拠にしない。 kimi はツール呼び出しごとに idle に
落ち、pane read が空を返すこともある。どちらも停止の証拠にならない。
5. 独立検証とレビュー（1 サイクル）
報告を鵜呑みにしない。必ず自分で回す。
mise run check と mise run docs:check を自分の手で実行する- main が進んでいれば rebase する（doc の衝突は「両方の内容を残す」で解く）。
rebase の前に、ローカル main の未 push コミットを push しておく。
origin/main が遅れていると、GitHub は PR の merge-base をその古い位置で
計算するので、ローカル main にしか無いコミットが全部 PR の diff に
混ざる。CodeRabbit がそれをレビューして、単位と無関係な指摘が大量に付く
（マージ結果自体は正しいので、事故に気づきにくい）
ravel-review の検査手順を辿る（render 純粋性、focus 所有権、Command 経路、
Global 用法、コア層分離）--review の指定先に独立レビューを投げ、所見を突き合わせる。
既定は codex。指定したエージェントが使えなければ該当箇所を自分で
読む。「レビューしていない」で通さない- 報告に挙がった「判断が必要な点」を §6 で仕分ける
- 指摘は必ずコードで裏取りしてから採否を決める。既存の
main と
比べて「この変更が入れた退行か、元からある穴か」を確認する
--review <agent|skip>
| 値 | 意味 |
|---|
codex（既定） / claude / kimi | そのエージェントへ独立レビューを投げる |
skip | 独立レビューだけを飛ばす |
skip でも次は必ずやる（飛ぶのは 4 だけ）:
- 1 の
mise run check / mise run docs:check
- 3 の
ravel-review の検査手順
- 6 の裏取り
- §7 の CodeRabbit 1 巡
つまり skip は「もう 1 人分の目を省く」であって「レビューしない」ではない。
--self と --review skip の同時指定は拒否する — 書いた本人しか読まない
状態になり、§4 の --self が課している独立性の担保が消える。
--compress のときは、単位ごとにレビューを投げるのではなく、
グループ全体の diff を 1 回投げる。ただし依頼文には単位の境界と
それぞれの完了条件を書き、単位ごとに見るよう指示する。
指摘の直し手:
- 局所的・機械的・ドキュメント → 呼び出し側が直す（往復が無駄）
- 構造的・設計判断を伴う・広範 → 実装したサブエージェントへ差し戻す
（文脈を持っているので速い）
--review-cycle n の上限に達しても指摘が残るとき:
- FAIL / Critical が残る → PR を作らず停止し、ブランチと残課題を報告
- WARN だけ → PR は作る。本文に「未対応の指摘」として列挙し、マージしない
6. 判断の仕分け
サブエージェントが上げた「判断が必要な点」と、レビューで出た設計上の分岐は
影響範囲で分ける。
- 実装の内側に閉じる（命名、エラー型、テストの置き場、到達不能な腕の書き方、
機械的な修正）→ 決めて進む。決めた内容は報告に列挙する
- 外に出る（ユーザーに見える挙動、仕様の追加・変更、スコープ拡大、
永続化フォーマット、公開 API の破壊）→ 止めて聞く。勝手に広げない
7. PR とマージ
-
bash scripts/review-gate.sh --mark <branch> でゲートを記録する
（マーカーが無いと gh pr create がブロックされる）
-
push して PR を作る。本文には次を書く: なぜこの単位を今やるのか
（roadmap の根拠）、何を変えたか、設計判断とその理由、既存挙動が
変わらないことの根拠、検証内容、残した制約
--compress のときは冒頭に単位の一覧と実装順を置き、以降の節を
単位ごとに切る。レビューする人が「どこからどこまでが 1 単位か」を
本文だけで追えるようにする。タイトルはグループ全体を表す
Conventional Commit 1 行にする（単位 ID を並べない）
-
CI と CodeRabbit を待つ。CodeRabbit は 1 巡だけ対応して push し、
再レビューは追わない
待ち方は次で固定。自作のポーリングループを書かない:
# run_in_background で 1 つのコマンドとして投げる
gh pr checks <PR 番号> --watch --interval 20 > /tmp/pr<N>-watch.log 2>&1
gh pr checks <PR 番号> --json name,bucket > /tmp/pr<N>.json 2>&1
--watch と --json は併用できない（cannot use --watch with --json
で即座に usage エラーになり、待たずに「終わった」ように見える）。待つ側と
読む側を 2 コマンドに分け、待ち終わってから bucket を読む。
--watch は全チェック確定まで待つ。背景実行なら完了時に通知が来るので、
前景の 10 分上限に切られない。背景ジョブは cwd が消えると落ちるので、
worktree の中ではなく主ワークツリーから投げる。
sleep N を単体で、または sleep N && gh pr checks … の形で使わない。
前景の sleep はブロックされる。
終了コードだけで「CI 全緑」を判定しない。 0 は pass と skip の
両方で返る（1 = 失敗、8 = 保留）。bucket を見て区別する:
| bucket | 意味 | 扱い |
|---|
pass | 成功 | 可 |
skipping | ジョブが条件で飛んだ（bench は常にこれ） | 可 |
fail / cancel | 失敗・打ち切り | マージしない |
pending | 未確定 | まだ待つ |
さらに ravel では ci.yml の paths-ignore により、docs のみの PR で
check (macos-latest) / check (windows-latest) が一件も現れない
（skipping ですらなく不在。CodeRabbit だけが残る）。よって:
- Rust を触った単位 → 両
check (…) が であることを確認する。
不在なら の誤爆なので調べる
--no-pr なら 1 の手前で止まる。
8. 報告
最後に必ず返す:
- 単位 ID と PR 番号（作った場合）、マージしたか。
--compress なら含めた単位を全部列挙する
- レビューで出た指摘と、その事実確認の結果・対応。
--compress ならどの単位の指摘かを添える
- 独立レビューを誰に投げたか（
--review skip ならその旨と、
代わりに自分で読んだ範囲）
- 止めて聞くべき判断が残っていればそれ（次の一手を提示する）
- 残した制約と、依存が解けて着手可能になった単位
やらないこと
- 実装差分を呼び出し側が書く（§5 の局所修正と
--self を除く）
- 計画書に無い機能の追加。フェーズや単位の境界を越える作業
- サブエージェントの報告を検証せずに PR を出すこと
- 指摘が残ったままのマージ
--compress で計画書をまたいで束ねること、しきい値を超えたのに
確認を取らずに進めること--compress の PR を確認なしに --squash でマージすること（単位の履歴が消える）- 既定を squash と思い込むこと（既定は merge コミット）
