re0-readme

同梱スクリプトでリポジトリのREADME、AGENTS.md、マニフェストを監査し、指摘された各行を、読む人に必要なファイルに移動、書き換え、またはそのまま残します。また、リポジトリの内容と一致しない各マニフェストを修正します。

目標

README.mdは、リポジトリを使うかどうか、また使い方を判断する人向けのファイルです。AGENTS.mdは、リポジトリ内で作業するエージェント向けのファイルで、構成、コマンド、ゲート、規約を記載します。各行は、それを必要とする読み手向けのファイルに置きます。両方の読み手に必要な事実は、それぞれの読み手に適した形で記載します（READMEには人が開くアドレス、AGENTS.mdにはエージェントが維持する設定）。どちらのファイルも、もう一方の手順を繰り返さず、コピーする代わりにリンクします。ホストやレジストリがどちらかのファイルを開く前に表示するマニフェスト（package.json、.claude-plugin/と.codex-plugin/のプラグインファイル、マーケットプレイスファイル、各スキルのagents/openai.yaml）には、リポジトリで使う名前を統一し、リポジトリ内の該当するアドレスを指定し、提供するスキルフォルダーだけを過不足なく列挙します。そのため、名前を変更してREADMEだけを更新し、マニフェストを更新しないと、それを掲載するすべてのホストで古い名前が表示され続けます。

対象となるのは、READMEまたはAGENTS.mdを書こうとしているとき、書いた直後、またはレビュー中の場合、あるいは、どちらかのファイルに、もう一方のファイルの読み手向けと思われる行がある場合です。入力はリポジトリのルート（依頼の対象リポジトリ。指定がなければ作業ディレクトリのリポジトリ）です。任意で、実行の種類、追加のローカル状態フォルダー名、書き換えが可能か、報告のみとするかも指定できます。

実行のたびに、ベースライン監査、その種類とソース、各指摘事項のルールID、ファイル、行、重大度、および理由付きの維持リストを報告します。レビューのみの実行では、移動案を報告して停止し、編集、実行後の監査、ホスト監査は行いません。すでに問題がない場合は、ベースラインを報告して変更せずに停止します。書き換えを行う場合は、編集したファイル、実行後の監査、およびホスト監査または未解決の失敗を報告します。

ベースライン監査に問題がない場合も、マニフェストの修正を含め、各指摘事項と予定している変更をすべてレビューします。対応が必要な項目がない場合に限り、変更せずに停止します。編集がゼロ件でも、実行は成功です。

ワークフロー

1. 編集する前に監査を実行し、その出力をベースラインとして保存します。このスキルのフォルダーから実行します。

   node scripts/audit.mjs [<repo-root>] [--kind app|cli|library|skills] [--loop-dir <name>]... [--host <owner/repo>] [--strict] [--json] [--rules]
   

   各検出結果について、ルール ID、ファイル、行、重大度を報告し、ファイル、行、ルール ID の順に並べます。--json は結果を 1 つの JSON オブジェクトとして出力し、--rules はルール ID ごとに種類別の重大度をすべて出力します。終了コード：0 は fail 検出なし、1 は fail 検出あり、--strict の場合に何らかの検出結果がある、または AGENTS.md がない場合です。2 は使用方法の誤り、または読み取れない入力（不明な種類、ディレクトリではないルート、解析できない package.json）です。終了コード 2 は実行の失敗であり、監査の不合格ではありません。コマンドまたは入力を修正して、再実行してください。CLAUDE.md のみがある場合は、エージェントガイドとして読み込み、AGENTS.md がないことを fail として報告します。書き換えによって、ガイドまたは CLAUDE.md へのリンクとして AGENTS.md を作成し、その後監査を再実行できます。レビューでは、書き込みを行わずに修正案を提示します。

2. 種類を確認します。 --kind が指定されていない場合、種類はリポジトリ内のファイルから検出されます。リポジトリが実際に提供するものと比較し、検出が誤っている場合は --kind を渡してください。リポジトリ自身の .gitignore が除外するドットフォルダーはローカル状態として扱われます。--loop-dir を使うたびに名前を 1 つ追加できるため、.gitignore に記載されていないローカル状態フォルダーがある場合は指定してください。種類によって重大度が決まります。CLI ではコマンドが製品の表面であり、スキルカタログではエージェントの用語が主題であり、アプリでは画像が製品の一部です。

3. 各検出結果を文脈の中で読みます。 一致は手掛かりであり、結論ではありません。トラブルシューティング用の変数は README に記載してよく、コントリビューター向けのテストコマンドは注記として残してもかまいません。各検出結果について、移動、書き換え、維持のいずれかを判断し、維持する場合はその理由を keep リストに記載します。keep リストはファイルではなくレポートに含めます。1 つの読み手につき 1 つの形式に分ける範囲を超えて、ある事実が両方のファイル、または 3 つ目のドキュメントにも記載されている場合は、Skill ツールを「ssotize」（paperthin:ssotize）で呼び出します。

4. レビュー依頼の場合は、ここで止めます。 レビュー、監査、確認の依頼では、ベースライン、各検出結果に対する移動案、keep リストを報告し、何も編集しません。ファイルの作成、修正、書き換えが依頼された場合にのみ続行します。

5. README をその読み手に合わせて書き換えます。 リポジトリの所有者または関連リポジトリが定める、読み手が読む言語を使います。コードが書かれている言語には合わせません。まず製品が何であるかを 1 文で述べ、次に測定に基づいて現在できることを説明し、続けて目に見える結果または使用例、最短で動作するセットアップ、対応環境、重要な依存関係、詳細ドキュメントへのリンクを示します。製品が本来の目的よりもできることが少ない場合は、その測定結果とともに冒頭付近で明示し、設計上の目的は目標としてのみ記載します。設計を現状として説明すると、ファイルの存在意義を誤って伝えることになります。リストの表では、グループ分けの列をセクションに置き換え、状態はアイコンと語句で示し、凡例は一度だけ記載します。運用上の詳細は、利用やコントリビューションに役立つものに限ります。README 内のスタック、ベンダー、ツールを表す名詞が仕組みを意味する場合は、Skill ツールを「detool」（paperthin:detool）で呼び出します。

6. ビジュアル製品では、長い説明より先に実際の製品画像を掲載します。 フォント、画像、データの読み込みが完了してから各画像を撮影し、公開前にフレームを確認します。製品がスマートフォンやその他のデバイスで動作するようになったら、その画面をデスクトップ画面と並べて表示し、コミット済みのサンプルデータを使ってリポジトリ内のスクリプトで撮影します。画像のサイズとフォルダーはリポジトリの慣例に従います。

7. AGENTS.md をその読み手であるエージェントに合わせて書き換えます。 リポジトリの契約で別の言語が指定されていない限り、英語で記述します。韓国語の読み手向けに README が書かれていても、AGENTS.md を韓国語にするわけではありません。まず、どの種類の事実をどのドキュメントが管理するかを示し、次にリポジトリの構成、実行コマンド、各ゲートが何を保護するかを添えたゲート一覧、根拠を示した失敗時のルール、ドキュメントの慣例、コミットの慣例を記載します。所有者一覧の後で Skill ツールを「re0-order」（paperthin:re0-order）で呼び出し、セクションと一覧を明示した 1 つの順序に並べます。チェックで強制されるルールには、エージェントが実行できるよう、そのチェックを併記します。測定済みの事例は根拠を示す 1 文にまとめ、人向けの説明は README に移します。契約と根拠へのリンクは翻訳せず、元の言語のままにします。どちらかのファイルが、情報を支える密度を超えて肥大化している場合は、Skill ツールを「debloat」（paperthin:debloat）で呼び出します。

8. 監査で指定されたマニフェストを揃えます。 それぞれにリポジトリ名を付け（npm 名は小文字形式）、各アドレスはリポジトリ自体のオリジンを指すようにし、プラグインが提供するすべてのスキルフォルダーを列挙し、それ以外は記載しません。各スキルには、デフォルトのプロンプトで $<skill> を指定する agents/openai.yaml を用意します。リポジトリが生成するマニフェストは、生成元で修正します。

9. **監査を再実行し、**両方のファイルとマニフェストを、それぞれの想定読者の視点で読みます。

10. ホスト上の表示内容を監査します。 node scripts/audit.mjs --host <owner/repo> を実行します。説明文が README の冒頭や記載内容と一致しているか、トピック、ホームページの正当性、コミュニティプロフィールの不足、README のサイズ、カスタムのソーシャルプレビューが設定されている場合はそのサイズと適切さを確認します。ホスト監査は報告のみを行います。検出結果への修正案を提示してください。利点と損失を伴う設定は、検出結果ではなく選択肢として表示され、実行が不合格になることはありません。カスタムのソーシャルプレビューがない場合、GitHub のデフォルトカードには最新のスター数、フォーク数、コントリビューター数が表示されるため、レポートでは変更可能であることを所有者に伝え、判断は所有者に委ねます。

11. 書き換えを試読します。 承認前に Skill ツールを「sip」（paperthin:sip）で呼び出します。

12. ゲートを提案し、そこで終わります。 リポジトリにゲート一覧がある場合は、新規クローンでもゲートが実行されるよう、監査スクリプトを提供元のコメント付きでベンダーコピーとして追加することを提案します。1 台のマシンにしか存在しないパスをゲートが参照することは避けてください。最終判断は人間が行います。承認前にゲート一覧や CI に追加することはありません。

ルール

• ホストに Skill ツールがない場合は、名前が指定されたインストール済みの各スキルを直接読み、従ってください。利用できない場合は、その手順が実行できなかったことを報告し、実行したと主張しないでください。
• ルール表はスクリプトが管理します。スクリプト名、そのフラグと終了コードを記載し、ルールを再掲しないでください。--rules を指定するとルールが表示されます。
• 説明によって終了コードが変わることはありません。受け入れられた注記は --strict を指定しなくても合格できますが、残された fail は赤のままです。種別を修正するか、正当な理由があればリポジトリ内のルールのコピーの変更を提案するか、ゲートが未解決であると報告してください。文章による例外で合格したと主張しないでください。
• コンテンツを移動しても、何も失われてはいけません。あるファイルから移動した行は、別のファイル、リンク先のドキュメント、または理由を添えた保持リストのいずれかに残してください。事実を完全に削除するには、人間の承認が必要です。
• レビュー依頼では報告のみ行います。ファイルの作成、修正、書き換えを依頼された場合に限り、書き換えてください。
• 安全に編集してください。置換する前に対象の各行が存在することを確認し、MISS を報告してください。Unicode に対応した方法で編集し、全体への一括置換ではなく、該当箇所ごとに処理してください。
• 契約書、台帳、変更履歴、リリースノートは対象外です。
• 3つの変更には、人間の明示的な承認が必要です。承認されるまでは、実行結果でそれぞれを提案として報告してください。対象となる変更は、監査をリポジトリのゲート一覧または CI に追加すること（ステップ 12）、他に記載箇所のない事実を削除すること、リポジトリにベンダー提供されているスクリプトのコピー内のルールを変更することです。

検証

完了前に、次の項目を確認してください。

1. すべての報告にベースラインと種別の根拠が含まれていること。書き換えの場合は、書き換え後の監査結果とホスト側の結果も含まれていること。レビューまたはすでに合格している実行の場合は、明記された終了時点で停止していること。
2. すべての指摘事項が移動、書き換え、または理由を明記して保持されていること。またはレビューで処理方針が提案されていること。さらに、fail の指摘事項が説明によって合格したと報告されていないこと。
3. 事実が失われていないこと。移動した各行を、新しい記載先で見つけられること。
4. 書き換えの場合、README が製品の説明から始まり、エージェントガイドが各文書の役割の説明から始まっていること。
5. 書き換えの場合、README に、読者が読む言語で、測定に基づく現在の製品の機能が記載されており、ホスト側の説明にも同じ内容が記載されていること。または、その新しい記載行が提案されていること。
6. ゲートの変更が承認を待ってから行われていること。また、承認待ちで未解決の項目がすべて報告されていること。