recoup-platform-build-os

Recoup — 音楽ワークスペースを構築する

重要なのはフォルダーではありません。自身を管理し、改善するシステムを構築することです。 システムは自らの状態を常に最新に保ち（古くならず）、時間とともに自身の仕事をより良くしていきます。知識を蓄積し、繰り返し行う作業を新しいスキルへと昇華させ、自らの仕組みを改善します。以下の各フェーズでは、これを目標として意識してください。構造はその目標を実現するためにのみ存在します。

具体的には、キックオフ時の入力を、生きたオペレーティングシステムへと変換します。フォルダーとファイルの構造、自己管理する CLAUDE.md（AGENTS.md にも同期）、plugin/ ディレクトリ（スキルを内包する、インプレースでインストール可能なプラグイン）、読み取り専用の doctor を基盤とする常に最新の janitor、複合学習ループ、自己改善ループを構築します。プラグインの名前はデフォルトで {DOMAIN_SLUG}-os とし、Claude、Cursor、Codex 用のマニフェスト／アダプターを含めます。

このビルダー用スキルは、これを実行するエージェント向けです。各フェーズを順番に進めてください。途中で止めず、動作する OS を完成させてから報告してください。各フェーズに進む際に、該当するリファレンスを読んでください。

Recoup の専門化 — 実際の音楽ワークフローを選択する

対象ドメインは、レーベル、作家、出版社、管理者、録音物の権利者、遺産管理団体、権限を付与されたアドバイザーなどを含む音楽ビジネスです。Phase 0 で中核となるレコードを特定してください。作曲やロイヤリティ業務に合わせるために、アーティストアカウントを決して作り出さないでください。

• 実際の業務に基づいて中核の構成を選択します。 アーティスト／リリース業務では artists/ とアーティストごとのリリースを使用します。出版業務では compositions/ と parties/ を使用します。監査、ロイヤリティの照合、買収では、範囲／証拠／段階のレコードとともに cases/ を使用します。実際の業務に裏付けられたフォルダーのみを使用してください。ロスターが空でも問題ありません。
• リポジトリごとに、権限を付与されたワークスペースを 1 つ使用します。 非公開の契約書、明細書、識別子、領収書は、選択した非公開ワークスペースに保管してください。公開プラグインのサンプルには合成データを使用します。保存後の読み戻しがサポートされていない限り、ローカルのケースをホストされたカタログとして扱わないでください。
• 該当する場合は、既存のアーティスト規約を維持します。 確認済みのアーティストを artists/{artist-slug}/RECOUP.md に反映し、artistName、artistSlug、実際の artistId を記載します。リリースレコードは、各アーティストのリリースフォルダーに保存します。ID を決して作り出さないでください。作曲のみのケースでは、ローカルのケース ID を使用し、ISRC／ISWC が不明な値はそのまま保持できます。
• 利用可能なアクセス手段を使用します。 認証済みの MCP 接続から、アカウントのスコープをすでに取得できる場合があります。REST では、提供された環境認証情報を使用できます。ハーネス固有の環境ファイルは必須ではありません。ホストされた操作で必要な場合に限り、アカウントを接続してください。MCP の OAuth 認証情報をファイルにコピーしないでください。ファイルの確認／取り込みにはログインは不要です。
• オブジェクトごとに operations/sync.md を作成します。 ホストされた構造化レコードを正として扱えるのは、検出された API が実際にサポートするフィールドに限られます。非公開ワークスペースには、証拠、未解決の候補、計画、ソースのバージョンを保持します。すべてのローカルレコードがデータベースに存在すると主張せず、サポートされていないフィールドを記録してください。実際のロスターがある場合は、サポートされているロスター読み取りと、依頼された場合の API 優先のアーティスト作成を使用します。アーティストが 0 人であっても、関係のない人や出版社を登録してよいことにはなりません。
• 用途を絞った Recoup スキルを再利用します。 カタログのインポート、整理、契約内容の説明、監査、照合、登録、解決、取引のレビューでは、それぞれの段階の境界を維持します。ソングクレジットとリリースメタデータは引き続き確認項目です。ローカルの連携処理は、明示的に依頼された段階を調整します。レビューを外部への連絡に変えてはいけません。
• シークレットをバージョン管理対象の素材に含めないでください。 REST アクセスが必要な場合は、変数名を記載した .env.example と、実際の認証情報を除外する .gitignore を用意します。プロバイダーへの加入、音楽業務の委任、ソフトウェアの権限は、それぞれ別の事実です。
• 選択した構成に合わせてメンテナンスを設定します。 doctor／dashboard のテンプレートには、実際のエンティティフォルダーとワークフローを設定します。アーティスト、評価額、定期タスクがないことを理由に、出版や会計のワークスペースがヘルスチェックに失敗してはなりません。

簡潔な構成については references/blueprint.md を参照してください。レーベル固有のリリース運用も引き続き利用できますが、すべての出版社やカタログアドバイザーに適用してはいけません。

運用上の信念（構築するすべての OS に適用）

以下の信念が目指すのは、システムが自らを管理する（最新の状態を保つ）と同時に、自らを改善する（知識、機能、独自の仕組みを蓄積する）ことです。

1. **蓄積するものと流れていくものを分けます。**蓄積するもの＝使うたびに改善される再利用可能な資産（テンプレート、ナレッジベース、スキル、証跡）。流れていくもの＝各段階を進む個々の案件（商談、チケット、リリース、実験）。流れていく各案件のフィードバックが、必ず蓄積する資産に還元されるように仕組みを整えます。
2. **古い状態を放置しません。**状態を管理するのはエージェントの役割です。新しい入力が届いたとき、またはユーザーが OS を操作したときは、更新が必要なすべてのファイルやフォルダーを同じターン内で更新します。安全網として、クリーンアップ用スキルとスケジュールタスクを用意します。
3. **学びを蓄積します。**セッションのたびにシステムを賢くします。意思決定、繰り返し尋ねられる回答、パターンをナレッジベースに記録します。同じ問題を二度解決しないようにします。
4. **実証済みの反復可能な作業をスキル化します。**作業を終えたら、今後も繰り返すか、継続して保守するかを確認します。該当する場合は、実証済みのプロセスを段階的に整備し、検証したうえで plugin/skills/ に配置します。一度限りの作業は work/（日付付き）に置き、トップレベルのフォルダーとして独立させません。
5. **自己説明的にします。**各フォルダーで、その目的を説明します。CLAUDE.md には、新しい項目の配置先とシステムを最新の状態に保つ方法を記載します。
6. 自信より証拠を重視します。「完了」「一貫性がある」「到達可能」といった判断は、エージェントの感覚ではなく、確認可能な基準に基づいて行います。たとえば、{domain}-doctor の実行、スキルの検証、到達可能なトリガーなどです。また、OS は内容を増やすだけでなく、時間とともに自らを改善します（{domain}-reflect）。

フェーズ 0 — プロジェクトを深く理解する（必ず最初に実施）

references/domain-inference.md を読みます。

• 立ち上げ時の入力（ファイル、トランスクリプト、プロンプト）をすべて取り込みます。ファイルがある場合は、最後まで読みます。
• ドメインの類型と中核となる作業単位を特定します（例：コンサルティング → 商談／クライアント、製品 → 機能／リリース、レコードレーベル → アーティスト／リリース、研究 → 問い／実験）。
• 入力が豊富な場合は、資料から構造を導き出します。入力が乏しい（プロンプトのみ）場合は、最善の判断を用います。ドメインを推測し、プロジェクトに必要となるエンティティ、段階、資産、定例業務、指標を予測して、指示を待たずに準備します。ただし、その準備は追加のトップレベルディレクトリではなく、簡素なルート内のスタブやサブフォルダーとして表現します（フェーズ 1 を参照）。
• 簡潔な理解ブリーフを作成します。内容は、ドメイン、中核単位、ライフサイクルの段階、主要なエンティティ、蓄積する資産、定例タスク（スキル候補）、指標、想定される外部ツールです。
• 重要な点に曖昧さがある場合に限り、ブリーフをユーザーに確認します。それ以外の場合は、そのまま進めます。

フェーズ 1 — 分類体系を設計する

references/blueprint.mdを読みます。

• ループが維持する小さなコアから始めます。流動的なストア（ステージング用のパイプラインフォルダー＋clients/／artists/／features/のようなエンティティ用フォルダー）、蓄積するストアknowledge/とlibrary/、work/（プロジェクトごとの、繰り返し発生しない成果物）、artifacts/（ダッシュボードのような、確定済みの定期的な成果物）、plugin/（インプレースのプラグイン）、operations/（ルーチン、同期、ヘルスチェック、改善）です。
• ドメインに今すぐ実際の素材がある場合に限り、任意のトップレベルフォルダーを追加します。reference/（正典／ソース）、proof/（成果）、content/（実際のコンテンツ活動）、business/（法務／財務／指標）です。迷った場合は追加しません。後から追加するのはmkdirを1回実行するだけです。
• すべてのトップレベルフォルダー名は、小文字1語にします（operating-systemではなくoperations、knowledge-baseではなくknowledge）。ドメインで使われる言葉に変更してもかまいませんが、1語にします。（plugin/skills/内のスキルフォルダーはケバブケースのままです。これは別の規則です。）
• 反射的に構成全体を再現せず、一度きりの作業をトップレベルフォルダーに昇格させないでください。アドホックなタスクはwork/に置き、繰り返し発生する、または保守が必要な作業だけをplugin/のスキルにします。準備しすぎてしまう場合は、空のトップレベルディレクトリを並べるのではなく、サブフォルダーやスタブに振り分けます。

フェーズ 2 — 構造と頭脳を整える

• 分類体系で必要とされるフォルダーだけを作成します（ルートは最小限に保ちます）。用途が自明でないフォルダーには、その中に何を置くかを記した短いREADME.mdスタブを用意します。
• assets/dashboard.html.tmplからartifacts/dashboard.htmlを作成します（mdではなくHTML）。operations/health.md（空の状態で作成し、{domain}-doctorが内容を記入）と、operations/improvements.md（{domain}-reflectの記録用の見出し）を用意します。
• assets/CLAUDE.md.tmplをもとに、ドメインに合わせてカスタマイズした自己管理型のCLAUDE.mdを作成します（分類の判断ツリー、自動管理ループ、常に最新に保つための契約、繰り返し発生する作業をスキルにするルール）。契約に含めるべき内容については、references/self-management.mdを読みます。
• AGENTS.mdをCLAUDE.mdへのシンボリックリンクとして作成し（ln -s CLAUDE.md AGENTS.md）、どちらのファイルを探すエージェントランナーからも同じ頭脳が参照されるようにします。シンボリックリンクに対応していない場合は、"See CLAUDE.md"と記したAGENTS.mdを作成します。ただし、シンボリックリンクを優先してください。

フェーズ 3 — 蓄積するアセットを用意する

• library/（テンプレート、スクリプト、チェックリストなど、繰り返し使うひな形や道具）と、knowledge/（読み返す、確定済みの回答。FAQ、インサイト、決定事項、SOPなど）を充実させます。目安として、何かを作るために使うものはlibrary/、何かを決めるために参照するものはknowledge/に置きます。
• これらの素材を入力から抽出します。入力が少ない場合は、そのドメインに適した基本テンプレートを用意し、「draft — confirm」と記します。

フェーズ 4 — スキルを作成する（配置済みの plugin/）

references/skill-authoring.md と references/skillifying-work.md（昇格ワークフロー）を読みます。

• ユーザーが明示的に名前を指定していない限り、ドメインからプラグイン名を {DOMAIN_SLUG}-os（ケバブケース）として導出します。すべてのマニフェストで同じ名前を使います。
• plugin/ を配置済みの実際のプラグインとして足場を組みます。assets/claude-plugin.json.tmpl から plugin/.claude-plugin/plugin.json を、assets/codex-plugin.json.tmpl から plugin/.codex-plugin/plugin.json を作成し、plugin/skills/ ディレクトリを用意します。Codex のマニフェストには "skills": "./skills/" を含める必要があります。references/packaging.md を参照してください。
• .agents/skills を ../plugin/skills へのシンボリックリンクとして作成し、Cursor と Codex が同じプロジェクトスキルを検出できるようにします。シンボリックリンクがサポートされていない場合は、plugin/skills/ をそこにコピーし、互換性ミラーであることを記してください。
• brief 内の反復タスクごとに、plugin/skills/{name}/SKILL.md を作成します（フロントマターには name と実際のトリガーフレーズを含む説明を記載し、その後にワークスペースのパスを参照する命令形の手順を記載します）。
• テンプレートから生成したメンテナンススキル（OS のフィードバック器官）は必ず含めます。
  • doctor（assets/doctor-SKILL.md.tmpl） — 読み取り専用の検証インターフェースです（健全性スコアと、operations/health.md に記載する対応事項リスト）。janitor とビルドレポートはこれを前提とします。また、その確定的な高速パスとして assets/doctor.py.tmpl から operations/doctor.py も生成し、PIPELINE／ENTITY／スラッグを埋め込みます。これにより、機械的なチェックを後回しにして再発明するのではなく、ビルドに含めて出荷できます。
  • janitor（assets/janitor-SKILL.md.tmpl） — doctor を実行してから、安全に対処できる項目を照合し、修正します。
  • compound-learn スキル（assets/compound-learn-SKILL.md.tmpl） — 各作業セッションの後に、決定事項／回答／パターンを knowledge/ に記録します。
  • reflect スキル（assets/reflect-SKILL.md.tmpl） — OS 自体（スキル、ルーティング、チェック、テンプレート）を改善し、その内容を operations/improvements.md に記録します。予算は 50／50 です。
  • skillify スキル（assets/skillify-SKILL.md.tmpl） — 実績のある反復可能な作業を、ステージング済みで検証済みのスキルに昇格します。
• オーケストレータースキルも含めます。自動管理ループを 1 つのトリガーとして扱い、名前は {domain}-intake とします。
• ルーティングはシンプルに保ちます。 パックが小さいうちは、各スキルの description によるルーティングを利用します。説明が重複するほどスキルが増えた場合、または doctor の到達可能性チェックで曖昧さが検出された場合に限り、plugin/skills/RESOLVER.md（トリガー -> スキルの表）を追加します。
• 反復する作業、または継続的な保守が必要な作業に限り、スキルを作成します。一度限りのビルドは、使い捨てのスキルではなく work/ に置きます。完了済みの作業からスキルを作成する場合は、skillify のループに従います。由来を証明し、再利用可能なプロセスを抽出し、work/ でステージングし、ドメインに最適なチェックで検証し、plugin/skills/ への移動前に確認を求めてから、再パッケージします。

フェーズ 5 — プラグインをパッケージ化する

references/packaging.md を読みます。

• まず {domain}-doctor を実行します。パッケージ化は、問題がない（または問題の説明が記載された）レポートが前提です。
• ワークスペースの plugin/ ディレクトリはすでにインストール可能なプラグインです。コピーは不要です。以下を検証します。plugin/skills/*/ のそれぞれに SKILL.md があること、2 つのプラグインマニフェストが有効な JSON であり、{DOMAIN_SLUG}-os という同じ名前を使っていること、Codex のマニフェストが ./skills/ を指していること、どの説明にも山かっこが含まれていないこと、plugin/skills/ にスキル以外の余分なフォルダーがないこと、.agents/skills が plugin/skills/ を指しているか、そのミラーになっていること。パッケージ化する前に修正します。
• plugin/ の内容をまず /tmp に zip し、その後 .plugin を出力フォルダーにコピーして、インストール用に提示します。

フェーズ 6 — 常に最新状態を保つスケジュールを設定する

• ジャニタースキルを実行するスケジュール済みタスク（デフォルトは週次）の作成を試み、ユーザーが見ていないときもワークスペースが自動的に整合するようにします。
• **スケジュール設定ツールが利用できない場合、またはユーザーが辞退した場合：**これは失敗ではありません。予定している実行頻度を operations/routines.md に記録し、さらに assets/janitor-schedule.tmpl からすぐに使えるスケジュール（GitHub Actions／cron／launchd／エージェントランナーのタスク）を用意します。そうすれば、後から有効にするときに必要なのはコピーだけで、調査は不要です。ジャニターは必要に応じて実行することもできるため、OS は完成しています。ただし、スケジュールが有効になるまでは、「スケジュールが有効」という低レベルの指摘が doctor に継続して表示されます。「誰も見ていないときに自動で整合する」という状態は、実際に無人で実行されて初めて実現するためです。
• スケジュール設定を理由に作業を止めたり、ビルドを「未完成」のままにしたりしないでください。これは唯一の任意ステップとして扱います。

フェーズ 7 — 報告する

{domain}-doctor を実行し、そのスコアをビルドの検証結果として報告します。「完了」とは、問題のない（または説明済みの）doctor の実行を指し、単なる感覚ではありません。作成した構造、作成したスキル、生成したプラグイン、設定したスケジュール、ヘルススコアを要約します。ユーザーが前提を訂正できるよう、推測した事項と確認済みの事項を列挙します。

ガードレール

• ユーザー自身が確定すべきドメイン情報を作り上げないでください。推測した項目には「ドラフト — 要確認」と記してください。
• 古い情報を残さないでください。プロジェクトに変更を加えた場合は、同じターンでダッシュボード、ボード、影響を受ける README を更新します。
• 単発の事例を作るより、テンプレートやスキルの改善を優先します。