plan-page

計画ページ

ユーザーが読むのは返信ではなくページです。ブロックの Plan pages ルールには、いつ公開するか、返信に何を含めるかが記されています。対象とは、作業によって変更される1つのものを指し、それぞれにページが1つあります。そのファイル <plans>/topics/<slug>.md には現在の状態が記録されます。それを継続する各計画は、差分のみを含むイテレーションです。node .agents/pstack/plan-page.mjs <plan> は、両方のファイルからページを生成して <plans>/artifacts/ に保存します。これはコミット済みの計画ファイルと対象ファイルから再生成されるローカルコピーであり、正式な記録はそれらのファイルです。node .agents/pstack/plan-page.mjs --index は、すべての対象のページと、それらへのリンクを含むインデックスをそこに生成します。公開された claude.ai ページは、ユーザーが1回の引き渡しについてコメントする場所であり、正式な記録ではありません。sync-pstack は、このレンダラーと status.mjs を、管理対象のすべてのプロジェクトに配置します。

計画ファイルまたは対象ファイルを書く前に、references/shape.md を読んでください。すべてのファイル形式、ページの順序、レンダラーが拒否する条件が記載されています。

モード	使用目的
Render	ブロックの Plan pages ルールに記載された各停止時にページを公開します
Refresh	計画が未完了の間に、Render の手順5、7、8を使って指定した計画のページを再生成します。計画を指定しない場合は、セッションで作業中の対象のオープンな計画を使い、該当する計画がない場合は確認します
Check	ページを引き渡す前に、計画と対象を監査します
Repair	形式が正しくないページを修正します
PR	PR の計画のページとして PR の説明文を作成または更新するか、他の人の PR に自分のコミットについてコメントします
Change	ページの形式、レンダラー、またはプレイブックのページセクションを変更します

Render

1. 計画を書く前に対象を選びます。作業によって内容が変わる対象を継続します。再び取り上げる新しい対象がある場合に限り、新しい対象を始めます。レビュー判定のような一度限りの計画には対象がなく、独立したページを使います。レビュー判定、または計画がまだない「次の作業」の回答では、後で継続する反復作業の計画か、一度限りの計画のいずれかを、今ここで作成します。単一の修正など、ブロックの Plans and trails ルールに従って計画を残さない作業では、計画を作成せず、返信で引き継ぎます。読み取り専用の依頼にも対象があります。その計画はリポジトリ外のコピーからレンダリングし、対象の Page: URL に公開します。二つ目のページは作成しません。
2. Status: の下に Topic: <slug> を記載するか、プロジェクトが pageTopic.field で指定するフロントマターのリストの先頭項目を使って対象を指定します。つまり、変更を管理するスコープを最初に記載します。リストで指定された対象にまだファイルがない計画は、誰かがそのファイルを作成するまで独立したページを使います。レンダラーは、対象のファイルが存在するまで、対象のファイルがない Topic: 行を拒否します。
3. Status: の下に Playbook: <name> を記載して、poteto-mode が選んだプレイブックを指定します。これにより、レールに表示されます。.agents/playbooks/ にあるプロジェクトのプレイブックが計画を書く場合は、そのプレイブックを指定します。そのページセクションが先頭になり、必須セクションが適用されます。それ以外の場合は、feature や bug-fix など、pstack のプレイブックを指定します。レンダラーは、いずれでもない名前を拒否します。
4. references/shape.md に従い、先頭の計画の ## Brief を最初に書き、次に ## Teach を書きます。これらは対象の所有者が最初に読む部分です。pstack:teach を読み込み、Teach の作成方法に従います。実行時の how と why の調査で見つかった内容を再利用し、同じ調査を繰り返さないでください。Brief の後には、How it works、Demo、Needs you、Picked for you、計画の変更点、計画完了後の Verification、Open work の順でページが表示され、計画ファイルには手順と履歴が残ります。PR の本文も同じ順序にします。
5. 最初に公開する前と、修正のたびに、Check の確認用リストに目を通し、その後 node .agents/pstack/plan-page.mjs <plan> を実行します。チェック可能なすべての形式上の問題について、修正方法を示して拒否します。計画または対象のファイルを修正し、HTML は決して修正しないでください。
6. 対象の所有者が試せる作業を行う場合は、引き継ぐ前に、references/shape.md に従って計画の ## Demo を書きます。その際、検証で記録したフレームを再利用します。作業を締めくくる際は、レンダリング前に計画の ## Close を書きます。完了した内容、証拠とその限界、ブロックの Todo リストと完了ルールで求められる件数、差し戻しと逸脱（これらを先に記載）、担当者と停止条件を含む未完了作業を記載します。ページに表示されるのは Brief であり、Close ではありません。そのため、Close の内容が対象の所有者に伝わるよう、Changes と Risks を書き直します。
7. ページが対象に属する場合は、node .agents/pstack/plan-page.mjs --index を実行し、続けて計画をもう一度レンダリングします。--index はすべての対象のページとインデックスをローカルでレンダリングし、各ページの先頭には最新の未完了の反復作業を表示します。二度目のレンダリングで、今回の作業に対応する計画のページに戻します。インデックスは公開しません。
8. ユーザーがコメントできるよう、対象の Page: URL、または一度限りの計画自体の URL に公開します。Claude Code では、Plan pages ルールのとおり、page-stop.mjs を介して公開します。そこで指定されるファイルをすべて最後まで読み、出力された内容を送信してください。レンダラーが出力するページ全体を公開してはいけません。チェックアウトでは、その行が origin/<branch> からチェックアウトを分岐した後に変更されている場合、チェックアウト側の Page: 行に公開します。変更されていない場合は、origin/<branch> 側の行に公開します。この行はレンダリング結果に表示されます。対象を初めて公開するとそのページが作成されます。その後、ヘルパーはリードに対し、対象ファイルのタイトルの下、または一度限りの計画の Status: 行の下に Page: <url> と記載するよう伝えます。ページが削除された、または別のアカウントに属しているなどの理由でリンクを開けなくなった場合は、別のワークツリーからレンダリングされた行に公開します。それがない場合は、ヘルパーを --new 付きで実行して新しいページを作成し、その行を置き換えます。所有者が意図的に削除した可能性もあるため、返信からリンクする計画にも Defaults 行を追加します。そこには古いリンクと新しいリンクを記載し、新しいページを残すとともに、そのページを破棄する際に使う語句を指定します。ページを読むときは、公開されたページではなく、plans ディレクトリ内のレンダリング済みファイル、または計画ファイルと対象ファイルを開きます。返信に含める内容と、Codex のセッションで代わりに行う内容は、ブロックの Plan pages ルールに記載されています。対象ページを初めて公開する際は、一度だけピン留めを提案します。所有者がチャットでページの場所を尋ねた場合は、リンクを伝え、あらためてピン留めを提案します。

チェック

node .agents/pstack/plan-page.mjs <plan> --check を実行します。すべての拒否チェックを実行し、何も書き込みません。その後、プランと対象を読み、レンダラーでは判断できない点を確認します。

• ページに表示される各文が、pstack:bro の語り口になっています。まず、unslop など、プランの文章を整えるパスを実行します。次に最後のパスとして pstack:bro を読み込み、概要、Teach、各未解決の質問、各 Defaults 行、各 before and after ペアの直前にある各文を、すべてこれを通して言い換えます。後続のパスで元に戻らないようにするためです。より平易な表現を採用し、他のセクションにすでに記載されている内容は、担当者に不要なら削除します。このパスでは主張の表現を変えても範囲は変えません。そのため、試したケースなど、主張を限定するすべての数値と修飾語を維持します。パスの後、言い換えた各主張を、置き換え前の文およびその内容を記録したログ行と照合します。ある bro パスでは「試したタスクで改善がなかった」が「何も追加しなかった」に変わり、試行回数も 2 回から 3 回になりました。
• 各 before フェンスは、プラン作成前のコミットにある実際の呼び出し箇所であり、after フェンスはチェックアウト内の同じ呼び出し、またはプランが未実装なら実装予定の呼び出しです。各フェンスにはコメントでパスを記載し、ペアの直前には 1 文を置きます。
• プランが未完了の間、対象ファイルにはプラン適用前の状態が示されています。これはプランが新規作成した対象にも当てはまります。
• プランが変更する対象の各セクションには、対象の行に対応付けた Delta テーブルを付けます。そうでない場合、そのセクションは変更なしとページに記載します。
• Main changes には、コードの動作を変える非公開の変更だけを記載します。
• 前回のレンダリング以降に完了した各ボックスは、承認済みの Proof: 節と、証明が実行された場所および正確なバイト列が一致しています。共有ソースへの変更は、そのプロジェクトがプッシュ済みのコミットから同期した後に限り、プロジェクトで有効とみなします。
• 前回のコミット以降に変更されたプランの行にある all、each、every などの全称表現は、いずれもその集合を列挙したログ行またはチェックと一致しています。
• この実行で見つかり、実行ディレクトリ内にしか存在しない、確定済みのビルド入力（リクエストの形式、ストアのパス、環境変数名、ドキュメントの URL など）は、必要とするステップより前に、プランまたは対象ファイルへコピーされています。ただし、シークレット値や実際のペイロードは含めません。
• プロジェクトのドキュメントチェックでは、プランまたは対象ファイル内のバッククォートで囲まれた .md 名をすべてドキュメントリンクとして読み取り、無視対象の実行ディレクトリ内にあるものを拒否することがあります。その場合は、ブロックの Plans and trails ルールに従い、その参照先を decision-log 行の proof: ラベルに移します。文章で置き換えてはいけません。
• Status: は短い 1 行にします。状態を表す語の後に、プランが何を待っているかを記載します。未解決項目は専用のセクションに記載し、それぞれに担当者、追跡場所、停止条件を付けます。
• 複数の対象が担当者の回答を待っている場合、概要、質問、返信で提示する回答の各語に対象名を付けます（例：「go model」）。これにより、単独の「go」が誤ったページに適用されるのを防ぎます。

修正

1. 各ファイルを書き換える前に実行ディレクトリへコピーし、修正を検出すべきだった拒否チェックのためのフィクスチャとして、そのコピーを保持します。
2. チェックを実行し、検出事項をそれぞれ発生源で修正します。すべてのステップが完了し、証明も済んでいるのに対象にプランの差分が示されている場合、それは完了済みの fold ですが、Status: がまだ更新されていません。元に戻すのではなく、更新します。早すぎる fold の場合は、プランの before フェンスと git show <base>:<path> を使い、対象ファイルを未完了のプランが開く前の状態に戻し、差分をプランに移します。
3. 修正について、decision-log に 1 行記録します。
4. プランのバイト列に紐付けられた台帳レコードは、編集すると古くなります。プロジェクトのレコードルールに従って再紐付けします。
5. レンダリングし、同じ URL に再公開します。

PR

PR の本文は、プランのページを GitHub Markdown としてレンダリングしたものです。そのため、レビュー担当者は担当者と同じ概要、rail、models、How it works、Demo、picks、API の各ペアを読みます。

1. PR のプランを選びます。1 つのプランで差分全体をカバーできる場合は、それを使います。PR に複数のプランが含まれる場合、またはどのプランでもカバーされない変更がある場合は、PR プランを作成します。これは、そのプランが含む各プランを相対パスで Status: の下の Plans: 行に記載した、一度限りのプランです。変更内容に合わせてタイトルを付けます。タイトルは PR タイトルと同じにします。レンダラーはタイトルに PR 番号が含まれていると拒否します。PR 番号は、その PR の中では何も伝えないためです。Render の手順 3〜6 に従って作成し、Brief、Teach、Demo、Public API のペアと Defaults で差分全体をカバーします。どのプランでもカバーされない変更は、それぞれ該当するセクションに記載します。PR で使うプランがどれであっても、PR 時点でレビュー担当者向けに Changes と Risks を書き直します。実行途中に書いた brief は担当者向けだからです。レンダラーは brief に PR 番号が含まれていると拒否します。Demo には、レビュー担当者が確認できる変更ごとに 1 つの手順を記載し、その変更の変更前と変更後のクリップをフレームとして示し、クリップに制限がある場合は手順に記載します。## Verification には、実行した各項目と証明できる範囲を 3 つ以内の箇条書きで記載します。## Open work には、PR で扱わない事項を記載します。PR に表示するすべてのセクションから、ローカルの実行フォルダーパスを削除します。これらのパスは GitHub では開けないためです。pstack:bro を最後にして、Check を実行します。
2. 最後にプッシュした後、リポジトリのルートから node .agents/pstack/plan-page.mjs <plan> --pr を実行し、リンクがプッシュしたコミットを指すようにします。このコマンドはページのレンダリングで行われるすべての拒否チェックを実行し、状態にかかわらず brief のないプランを拒否して、<plans>/artifacts/<name>.pr.md を出力します。パスを表示した後、本文にまだアップロードされていないローカルの Demo または Teach フレームごとに、--attach <file> の行を 1 つ表示します。
3. land.mjs を使って取り込むプロジェクトでは、land.mjs がこの本文をレンダリングして新しい PR も自ら開きます。また、ガードによって、エージェントが trunk ブランチに対して gh pr create を実行することは禁止されます。それ以外の場合、新しい PR は gh pr create --body-file <file> と、表示された --attach 行を使って開きます。PR を更新するには、gh pr view <number> --json body --jq .body > <run directory>/body.md を使って本文を保存し、--into <run directory>/body.md を指定してレンダリングしたうえで、表示された --attach 行を付けて gh pr edit <number> --body-file <file> を実行します。gh は添付された各フレームをアップロードし、その参照を書き換えます。レンダリングでは、plan-page マーカーの間にあるテキストだけを置き換え、リリースブロックや手動で添付した動画など、本文の残りは保持します。また、本文ですでにアップロードされている各フレームを再利用します。プランまたはその差分が変わるプッシュのたびに再レンダリングし、本文がプッシュした差分と一致するようにします。

他の人が開いた PR では、その説明文に手を加えないでください。自分のコミットが相手のコミットに追加する内容だけを、コメント 1 つで説明します。

1. これらのコミットの計画を書きます。Brief と Teach は、どのページでもそうであるように所有者に語りかけますが、コメントでは所有者への言及を省きます。Public API とプレイブックの設計セクションの各フェンスより前にある内容は、それぞれ作者があなたより前に行った最後のコミット時点のコードです。Demo には、あなたのコミットによって画面上で変わることだけを手順として記載します。ユーザーに見える変更がない場合、計画に Demo はありません。## On top of the PR セクションを追加し、作者のバージョンから維持、変更、削除した内容を列挙します。あなたのコミットによる変更を列挙する場所はコメントにほかにないため、このセクションがないコメントはレンダラーで拒否されます。計画の Verification では、あなたのコミットの検証がどこまでであるかを明記します。たとえば、使い捨ての検証用コードでしか確認していないケースなどです。コメントには Risks が表示されないためです。
2. プッシュ後、PR のプッシュ済み HEAD をチェックアウトした状態で、gh pr view <number> --json body --jq .body > <run directory>/description.md を実行して説明文を保存します。続けて node .agents/pstack/plan-page.mjs <plan> --comment <author's last commit> --against <run directory>/description.md を実行します。これにより <plans>/artifacts/<name>.comment.md が書き出され、そのコミットからあなたの HEAD までの DiffsHub の比較ビューへのリンクが追加されます。コメントには、そのリンク、On top of the PR、Demo、Public API、プレイブックの設計セクション、Verification が含まれます。作者がすでに知っていること、または所有者だけが読む内容、つまり brief、How it works、実行時のモデルとステージ、未解決の質問、Defaults、未完了の作業、計画へのリンクは含まれません。また、説明文にすでに表示されている各 Demo クリップと、すべてのクリップがそれに該当する手順も含まれません。
3. gh pr comment <number> --body-file <file> と出力された --attach 行を使ってコメントを投稿します。その後プッシュしたら、該当するコメントの本文を run ディレクトリに保存し、--into にそのファイルを指定してレンダリングしたうえで、まだ自分の最後のコメントである間に gh pr comment <number> --edit-last --body-file <file> で更新します。そのコメントの下に誰かが返信した場合は、新しいコメントを投稿します。

変更

レンダラーのソースは、dotai のチェックアウト内の skills/sync-pstack/assets/pstack/plan-page.mjs で、その隣に status.mjs があります。テストは skills/sync-pstack/scripts/sync-pstack.test.mjs 内の plan-page テストです。あるプロジェクトの計画だけが記述するセクションは、そのプロジェクトのプレイブックのフロントマターに置き、レンダラーには決して置きません。

ゲート、コーパスのルール、デリバリーを担う sync-pstack の Lesson モードを実行します。このモードでは、各ステップにレンダラー固有の内容を追加します。

1. Lesson のステップ 2 では、dotai の AGENTS.md に従い、別のセッションが未コミットの編集を保持している場合でも、ワークツリーは使わず、常に main 上の dotai チェックアウトを編集します。
2. Lesson のステップ 3 では、新しい拒否条件や動作ごとに、名前が示す不具合について旧レンダラーで失敗するテストを用意します。テキストを比較する拒否条件には、パネルを追加する前に、各軸で必ず通るケースと拒否されるケースを1つずつ用意します。対象は、大文字と小文字、インデント、リテラル内の空白、句読点だけの行、行の順序、別のイテレーションとの部分的な重複、セクションの欠落です。
3. Lesson のステップ 4 では、管理対象の各プロジェクトについて、旧レンダラー用に計画、対象ファイル、ハブ、.agents/pstack.json、プレイブックを一度スクラッチにコピーします。そのコピーに cp -R を適用し、変更のマイグレーションを適用して新レンダラー用のコピーを作成します。その後、本文に進む前に、2つの計画リストを差分比較します。ライブツリーに拒否ゲートが対象とする状態の実例がない場合は、イテレーションが開いていた過去のコミット時点の対象ファイルと、Repair が保持したスクラッチコピーも再生します。--check より前のレンダラーには、書き込み前に終了するアダプターを用意します。両方のレンダラーですべての計画を実行し、新たに拒否された計画をオーナーとともに列挙してから、両方で各計画をレンダリングし、Updated 行を無視して本文を差分比較します。
4. Lesson のステップ 4 ではさらに、レンダラーが分岐する各モードで、実際の計画を1つずつレンダリングします。対象は、単発計画、開いているイテレーションがある対象、イテレーションがない対象、別のイテレーションが開いている間にレンダリングする実行済み計画です。ライブの対象にあるモードを使えない場合は、Status: を反転させたスクラッチコピーを使います。両方のバージョンを公開し、オーナーが比較できるようにします。dotai のコミット前に、変更自体の計画も、実際の対象ページ上でクローズ状態にしてレンダリングします。
5. レンダラーが解析する新しい見出し、フィールド、ステータス語を計画に記載する前に、管理対象のすべてのプロジェクトの計画での既存の使用数を数えます。すでに使われている語によって、既存ページが意図せず変更されないようにします。

プレイブックのセクション

プロジェクトのプレイブック .agents/playbooks/<name>.md には、その計画が記述するレビューセクションを、extends および when と並べてフロントマターにカンマ区切りのリストとして記載します。

page-lead: What other editors do, Document shape, Layer and owner
page-pairs: Document shape
page-require: What other editors do
page-pr: What other editors do, Document shape

• page-lead セクションは Public API の直後にレンダリングされ、先頭の計画のプレイブックが最初に表示されます。
• page-pairs セクションには、Public API のように before と after のペアを記載します。
• プロジェクトの対象に pageTopic.hub ファイルが存在する場合、page-require セクションは対象ファイル、またはその計画に brief がある場合はページを先導する計画に存在している必要があります。
• page-pr セクションは、レビュー担当者が設計を評価する基準となる page-lead セクションです。PR 本文では Public API の後に、page-lead の順で表示されます。PR には、対象となるいずれかの計画のプレイブックに記載された各セクションが表示されます。また、それを持たない PR 計画には、対象となる各計画のタイトルの下に、その計画が持つ各セクションが表示されます。同じプレイブックの page-lead にないタイトルは拒否されます。

先頭の計画にプレイブックが指定されていない場合は、すべてのプレイブックのセクションと要件が適用されます。各セクションに何を記載するかは、プレイブックまたはプレイブックが指定するスキルで定義します。