recoup-roster-add-artist

Recoup — アーティストを追加

既存の正式なプロフィールがある場合はそれを再利用し、正しいアーティストを指定されたワークスペースに追加します。recoup-platform-api-access を通じてすでに選択されている認証済みアカウントと組織を使用します。実際に変更を加える前に、対象のアーティストとロースターへの追加操作を確認してください。名前やローカルフォルダーだけでは本人確認になりません。不明な認証情報や使い捨ての agent+ 認証情報は使用しないでください。

8 ステップのオンボーディングチェーン（RECOUP.md のチェックリストを起点に進めます）

既存の RECOUP.md チェックリストを起点にワークフローを進めます。確認済みの値と未完了のステップを、認証情報を含めずにそこへ保存します。チェックポイントには保留中の作業を記載できますが、API の結果を得る前にアーティストが作成または紐付け済みと記載してはいけません。

1. 作成前に ID を確認します。 提供された Spotify アーティスト URL／ID を検証するか、GET /api/spotify/search を使用してアーティストとカタログを確認します。正確な 22 文字の大文字・小文字を区別する spotify_artist_id、検証済み URL、および存在する場合は画像を記録します。一致候補が曖昧な場合は、選択されるまで停止します。一致するアーティストが見つからなくても、名前だけで作成してよいことにはなりません。適切な場合に限り、以下の意図的な手動手順を使用します。再開時は新しい一致候補を検索せず、保存済みの検証済み ID を保持します。
2. 指定された組織で解決／紐付けを行います。 最初の書き込みの前に、認証済みアカウント ID、指定された organization_id、spotify モード、検証済み Spotify ID、および保留中の状態を保存します。正確な ID とワークスペースを指定して POST /api/artists {name, spotify_artist_id, organization_id} を送信します。200 は既存の正規アーティストが再利用されたことを意味し、201 はアーティストが作成されたことを意味します。実際の HTTP ステータス、処理結果、返されたアーティストのアカウント ID を直ちに保存します。artist.id と artist.account_id は同じアーティストアカウントを識別するものであり、account_info の行を指すものではありません。両方が存在して値が一致しない場合は、照合のために停止します。この操作で Spotify との関連付けを確立します。名前で作成してから Spotify をパッチで追加してはいけません。
3. 返されたアーティスト ID を使って続行します。 中断した実行を再開する前に、現在の対象範囲のロスターを照合します。該当するアーティストがすでに表示されている場合は、その ID を使って情報の補完を続けます。任意のアートワーク／プロフィールの変更には、ID の確認後にのみ PATCH /api/artists/{id} を使用します。これらは正規のオンボーディングとは別の操作です。
4. GET /api/research/lookup?spotifyId={verifiedSpotifyId} → 空ではない文字列の id をフロントマターの researchArtistId として記録します。これは不透明なリサーチ ID であり、アーティストアカウント UUID や Spotify ID とは別のものです。以前に保存した ID はコピーせず、再解決します。ID を取得できた場合は、GET /api/research/profile|career|playlists?id={researchArtistId} を読み取ります。プロフィールの網羅性は部分的な場合があります。career は活動フィードで、playlists は placements を返します。ID のない検索が成功した場合、これらの読み取りは省略し、その不一致を記録します。経歴やプレス情報について、JSON の query を指定して POST /api/research/web を実行します。返された証拠と網羅性の不足を ## Research の下に保存します。データが空でも、ウォームアップジョブの実行や、事実を捏造する理由にはなりません。
5. Spotify カタログ（topTracks、albums、album）→ アルバムごとに releases/{slug}/RELEASE.md と releases/top-tracks.md を作成します。
6. Web 検索でソーシャルアカウント（ig／tiktok／twitter／youtube）を調べます。
7. 見つかったプラットフォームのみを含む profileUrls を指定して PATCH /api/artists/{id} を実行します。
8. RECOUP.md に ## Knowledge base セクションをまとめて追加します。

各レスポンスを使用する前に HTTP ステータスを確認します。402 では停止し、billingUrl を提示します。429 は Retry-After で後続の試行が許可されるまで延期します。認証、ID の不一致、永続化の失敗が発生した場合、名前だけで作成する手順に切り替えてはいけません。ネットワーク障害または 5xx が発生した場合、変更操作を自動的に再試行してはいけません。すでにコミットされている可能性があります。チェックポイントを保持し、まず照合します。読み取り専用の情報補完リクエストは、ネットワーク障害／5xx の場合、リクエストごとに 90 秒のタイムアウトを設定して最大 3 回まで再試行できます。失敗したステップのチェックは外したままにします。呼び出し形式の確認には recoup-platform-api-access を使用します。接続済みの MCP 呼び出しでも、同じ ID とワークスペースを維持する必要があります。

リクエスト例と、意図的に選択する手動手順

scripts/onboarding_examples.sh はこのスキルに同梱されています。例の実行には Bash、jq と、設定済みの RECOUP_API_KEY または RECOUP_ACCESS_TOKEN が必要です。ホストの OAuth トークンを抽出することはありません。利用可能な場合は、接続済みのツールを優先してください。ソースを読み込むだけで関数が定義され、リクエストは送信されません。このスキルのディレクトリから実行します。

source scripts/onboarding_examples.sh
# These values must come from the verified identity and selected workspace.
onboard_spotify_artist "$ARTIST_NAME" "$SPOTIFY_ARTIST_ID" "$ORGANIZATION_ID"

1 リクエストの例では、検証済みの ID、組織、返されたアーティスト ID、create_http_status、outcome が出力されます。これらの実際の値を RECOUP.md に保存してください。エンリッチメントや自動再試行、フォールバックは行いません。認証情報はプロセス引数やファイルではなく、標準入力経由のヘッダーで curl に渡されます。

手動／名前のみのオンボーディングは別の手順です。 検証済みの Spotify ID がなく、ユーザーが意図的に手動でアーティストを登録する場合は、まずモードを manual として記録し、未解決の ID を記録します。送信するのは {name, organization_id} のみです。これによって共有 ID が確立されたり、名前の一致で別のアーティストがリンクされたり、プロフェッショナル名簿のレコードが作成されたりすることはありません。明示的な REST の例は次のとおりです。

onboard_manual_artist "$ARTIST_NAME" "$ORGANIZATION_ID" confirmed-manual

確認引数に記録されるのは選択した例であり、認証や所有権の証明ではありません。正規のリクエストに失敗した後に、これを使用してはいけません。手動リクエストの結果が不確かな場合は、名簿と返された ID を確認してください。名前検索で結果が空でも、作成を繰り返してはいけません。

アーティストを重複させずに再開する

新たに変更を加える前に、保存済みのアカウント、組織、モード、Spotify ID、判明している場合は返されたアーティスト ID、作成ステータス／結果を読み込みます。認証済みアカウントまたは選択中の組織が変わっている場合は、実行を移動せずに停止し、意図したスコープを再確立してください。GET /api/artists?org_id={savedOrganizationId} を読み込み、表示名ではなく、検証済みの Spotify 関連付けと保存済みのアーティストアカウント ID を正確に照合します。保存されたプロフィール URL ではスキームが省略されている場合があります。照合では API のロケール URL と Spotify URI 形式も受け入れますが、大文字と小文字を区別する ID はそのまま保持します。照合を強制するためにアーティスト ID を小文字に変換してはいけません。読み取り専用の例は次のとおりです。

reconcile_spotify_artist "$SPOTIFY_ARTIST_ID" "$ORGANIZATION_ID" "${SAVED_ARTIST_ACCOUNT_ID:-}"

GET を 1 回実行し、POST は行いません。一意の完全一致が見つかると、そのアーティスト ID と reconciliation: matched が返されます。元の create_http_status と、作成／再利用の結果を保持してください。後から名簿を読み込んでも、失われた作成レスポンスを復元することはできません。未完了のエンリッチメントは、その ID を使って再開します。保存済み ID の不一致、複数の一致、アクセス拒否、または名簿レスポンスが不完全な場合は、レビューのために停止します。終了コード 2 は、名簿の読み込み自体は成功したものの、完全一致がなかったことを示すものであり、先の書き込みが行われなかった証明ではありません。さらに許可された正規のリクエストを行う前に、同じ保存済み Spotify ID と組織を使って、アクセス権とスコープを確認してください。新しい ID を選んだり、エラーを解消するために手動作成へフォールバックしたりしてはいけません。

ガードレール

• このファイルが状態を保持します — 各ステップにチェックを入れて保存してください。そうしないと、新しいターンで作業がやり直されたり、スキップされたりします。
• アーティストファイルに プレースホルダーデータを入れないでください — 実際の内容を記入するか、そのセクションを省略してください。
• 名簿やアーティストを捏造しないでください — まず recoup-platform-api-access で確認してください。ファイルシステムが空でも、名簿が空とは限りません。