artist-workspace

アーティストのワークスペース

すべてのアーティストには、コンテキスト、楽曲、参考資料を保存するディレクトリであるワークスペースがあります。ルートにある RECOUP.md ファイルが、ワークスペースを Recoupable プラットフォームに接続します。

アーティストのディレクトリは、サンドボックス内の artists/{artist-slug}/ にあります。サンドボックスはすでに単一の Recoupable 組織にスコープ設定されています（そのリポジトリ自体が組織です）。そのため、アーティストのディレクトリは最上位にあり、orgs/ ディレクトリはありません。

サンドボックス内の項目を一覧表示する

アカウントから「自分のアーティストは誰ですか」、「アーティストを一覧表示して」、「どの組織に所属していますか」など、サンドボックス内の項目について尋ねられた場合は、ファイルシステムを確認してください。ファイルシステムが、このサンドボックスに関する正式な情報源です。 この目的で Recoupable API を呼び出さないでください。API が返すのは「このアカウントがすべての範囲でアクセスできるアーティスト」であり、サンドボックスが開かれた目的に対応する範囲とは異なり、通常はその範囲よりも広くなります。

# All artist workspaces in this sandbox
ls -d artists/*/ 2>/dev/null

# Every artist's identity file — read the frontmatter for name/slug/id
find artists -type f -name RECOUP.md 2>/dev/null

各 RECOUP.md にはフロントマター（artistName、artistSlug、artistId）があります。head または任意の YAML パーサーで読み取り、正式な識別情報を取得してください。

artists/ が存在しない場合、サンドボックスはまだセットアップされていません。データを作り出すのではなく、アカウントに setup-sandbox スキルを案内してください。

新しいアーティストを作成する

ユーザーが新しいアーティストの作成（オンボーディング、追加、セットアップなど）を依頼した場合は、チェックリストファイルを使って作業を進めてください。手順を記憶だけに頼って実行しないでください。セットアップは API 呼び出しを 8 回順番に行うもので、エージェントのループはターンの間に状態を失います。チェックリストがあれば、作業を確実に再開でき、実際に完了した手順を証明できます。

ステップ 0：API を呼び出す前にワークスペースを準備する

スラッグを決め、ディレクトリを作成し、最初の RECOUP.md テンプレートを書き込みます。フロントマターには一連の手順で取得する値を、本文には未完了の手順を記載します。

ARTIST_SLUG=$(echo "$ARTIST_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\+/-/g; s/^-//; s/-$//')
ARTIST_DIR="artists/$ARTIST_SLUG"
mkdir -p "$ARTIST_DIR"

cat > "$ARTIST_DIR/RECOUP.md" <<EOF
---
artistName: $ARTIST_NAME
artistSlug: $ARTIST_SLUG
artistId:
spotifyArtistId:
spotifyProfileUrl:
imageUrl:
cmArtistId:
---

# $ARTIST_NAME

## Setup checklist

- [ ] 1. Create the artist (\`POST /api/artists\`) — capture \`account_id\` → \`artistId\`
- [ ] 2. Find canonical Spotify match (\`GET /api/spotify/search\`) — capture \`id\`, \`external_urls.spotify\`, \`images[0].url\`
- [ ] 3. PATCH artist with image + Spotify profile URL
- [ ] 4. Structured research — \`/research/lookup\` (capture \`cmArtistId\`) → \`/research/profile\` + \`/research/career\` + \`/research/playlists\` + \`/research/web\`. Save responses under \`## Research\` in this file.
- [ ] 5. Pull Spotify catalog → write \`releases/{album-slug}/RELEASE.md\` per album + \`releases/top-tracks.md\` (see Releases section)
- [ ] 6. Web search for additional socials (instagram / tiktok / twitter / youtube)
- [ ] 7. PATCH artist with discovered socials
- [ ] 8. Synthesize knowledge base — append it as \`## Knowledge base\` in this file

## Notes
EOF

ファイルがディスク上に作成されるまで、ステップ 1 に進まないでください。

ステップ 1～8 の curl を使った詳細な手順は、create-artist スキルと、ドキュメントサイト https://developers.recoupable.com/skills/create-artist にあります。ワークスペースの準備時にそのスキルを読み込み、8 ステップの手順に従ってください。

各ステップの完了後：チェックを付けて保存する

各ステップの完了後に、RECOUP.md に 2 つの書き込みを行います。

1. チェックボックスにチェックを付ける（- [ ] → - [x]）。実行したステップにチェックを付けます。
2. 取得した値をフロントマターに書き込む（artistId:、spotifyArtistId:、spotifyProfileUrl:、imageUrl:、cmArtistId:）。後続のステップでは、フロントマターに保存されたこれらの値を読み取ります。すでに保存されている値を再導出しないでください。より大きなペイロード（調査結果、ソーシャル URL）はフロントマターではなく、本文の専用の見出しが付いたサブセクションに記載します。

このファイルがワークフローの状態です。値がディスク上に存在しなければ、次のターンではその値を把握できません。

途中までのセットアップを再開する

$ARTIST_DIR/RECOUP.md がすでに存在する場合、完了済みのステップを再実行しないでください。ファイルを読み、最初の未チェック項目を見つけて、フロントマターに保存された値を使ってそこから再開します。

# Show the next unchecked step
grep -n '^- \[ \]' "$ARTIST_DIR/RECOUP.md" | head -1

すべての項目にチェックが付いている場合、アーティストのセットアップは完了しています。それ以外のことをする前に、ユーザーに確認してください。

チェックリストを使う理由

文章を頼りに長い決定的な手順を実行すると、ステップが抜け落ちがちです。エージェントはドキュメントを一度読み、いくつかの呼び出しを行ったあと、残りを忘れてしまいます。状態をファイルで管理するチェックリストなら、この問題を回避できます。進捗はディスク上で確認でき、各ステップには書き戻しの副作用があり、新しいターンではすでに完了した作業を再導出せずにファイルから再開できます。

アーティストのワークスペースに入る

アーティストのディレクトリで作業を始めるときは、次の手順を実行します。

1. RECOUP.md を読み、アーティストのワークスペースにいることを確認し、アーティストの名前、スラッグ、ID を確認します。
2. 何があるかを確認します。ディレクトリで ls を実行し、すでに存在するファイルやフォルダーを確認します。
3. context/artist.md がある場合は読みます。これはアーティストに関する信頼できる唯一の情報源です。行う作業はすべて、その内容と一貫している必要があります。
4. このアーティストに関する最近の git 履歴を確認します。リポジトリのルートから git log --oneline -10 -- artists/{artist-slug}/ を実行すると、このアーティストのファイルに関係するコミットだけが表示されます。すでにアーティストのディレクトリ内にいる場合は、代わりに git log --oneline -10 -- . を実行します。自分の変更を加える前に、コミットメッセージを読んで最近の変更を把握します。

---

アーティストのディレクトリで作業する

ファイルの配置場所

情報がそろったアーティストのワークスペースは、次のようになります。ここにあるものはあらかじめ作成されているわけではありません。それぞれのファイルやディレクトリは、実際のコンテンツができたときに追加されます。

{artist-slug}/
├── RECOUP.md                    # identity — connects workspace to the platform
├── context/
│   ├── artist.md                # who they are, how they present, creative constraints
│   ├── audience.md              # who listens and what resonates
│   └── images/
│       └── face-guide.png       # face reference for visual content generation
├── releases/
│   ├── top-tracks.md            # cross-release Spotify top tracks (snapshot)
│   └── {release-slug}/          # one folder per album / EP / single
│       └── RELEASE.md           # tracklist + Spotify metadata + cover art URL
└── songs/
    └── {song-slug}/
        ├── {song-slug}.mp3
        └── {song-slug}.wav

ファイルやディレクトリがまだ存在しない場合は、コンテンツが届いたときに作成します。すでに存在する場合は、まず内容を読んでから更新し、上書きしないでください。ディレクトリ構造は、ひな形からではなく、作業を通じて形作られていきます。

静的コンテキストと動的コンテキスト

アーティストのコンテキストは、次の 2 つの層で考えてください。

静的コンテキストは、アーティストがどんな人かを示すものです。数か月、リリースサイクル、キャリアの段階を通じて、ゆっくりと変化します。artist.md と audience.md は静的コンテキストです。20 歳のベッドルームポップのピアニストは、来年もベッドルームポップのピアニストであるかもしれませんが、時間とともに新たなサウンドを取り入れたり、審美性を変えたり、異なるオーディエンスに届いたりすることもあります。静的コンテキストは、気軽にではなく、慎重に更新してください。artist.md を変更することは、すべてのツールとエージェントが参照する信頼できる唯一の情報源を変更することです。

動的コンテキストは、今起きていることを示すものです。リリース資料、キャンペーンのリサーチ、戦略資料などは、特定の時点に結びついています。内容が追記され、古くなり、次のサイクルで置き換えられます。期間が限られた情報として扱ってください。リリースサイクルが終わったときや、リサーチが古くなったときは、作業ディレクトリを散らかしたままにせず、アーカイブしてください。

この違いが重要なのは、ワークスペースを読むエージェントが、その情報がアーティストに関する長く有効な事実なのか、それとも 3 か月前のスナップショットなのかを知る必要があるためです。静的コンテキストは信頼できるものにしてください。動的コンテキストは最新の状態にしてください。最新でない場合は、邪魔にならない場所に移動してください。

アーティストのコンテキスト（context/artist.md）

ワークスペースで最も重要なファイルです。アイデンティティ、ブランド、声、審美性、創作上の制約を定義します。他のツールやエージェントは、ブランドイメージを保つためにこれを読みます。これは静的コンテキストです。キャンペーンごとの変化ではなく、アーティストが本当に進化したときに更新してください。

実際の情報があるときに作成します。プレースホルダーだらけの完全なテンプレートより、実データを含む未完成のプロフィールのほうが適切です。知らない情報を捏造しないでください。推測するのではなく、該当するセクションを省略してください。

初めて作成するときは、セクションごとの構成について references/artist-template.md を読んでください。記入済みの例は references/artist-example.md を参照してください。

オーディエンスのコンテキスト（context/audience.md）

ファンがどんな人たちなのか、何に共感するのか、どのような話し方をするのかを示します。これは静的コンテキストです。オーディエンスは、リリースごとではなく、アーティストの成長に合わせて徐々に変化します。

実際のオーディエンスデータがあるときに作成してください。初めて作成するときは、references/audience-template.md を読んでください。

曲

曲はソース素材です。曲は songs/{song-slug}/ に永続的に保存します。mp3 のファイル名には曲名を使用してください。ファイル名が、後続のツールで曲のタイトルとして使われます。

songs/adhd/adhd.mp3           ✓  title becomes "adhd"
songs/adhd/audio.mp3          ✗  title becomes "audio"

リリース

リリースは releases/{release-slug}/ に保存します。各リリースはフォルダーで、ルートに RELEASE.md があります。これは、リリースのあらゆるライフサイクル段階（告知、リリース週、継続対応）を通じてリリースとともに引き継がれる、リリース管理のマスタードキュメントです。その他のリリース単位の成果物（調査資料、コピー、アセット、派生レポート）はすべて同じフォルダーに保存します。

スラッグの規則 — プロジェクトタイトルを lowercase-kebab-case にし、フォーマットのサフィックスを付けます。

• アルバム → releases/{title-slug}/（サフィックスなし。アルバムがデフォルトです）
• EP → releases/{title-slug}-ep/
• シングル → releases/{title-slug}-single/
• コンピレーション → releases/{title-slug}-compilation/

releases/after-hours/RELEASE.md          # album
releases/adhd-ep/RELEASE.md              # EP
releases/blinding-lights-single/RELEASE.md

RELEASE.md は、プロジェクトの概要、識別子とメタデータ、ナラティブ、オーディエンス、DSP 戦略、マーケティング、ソーシャル、PR、ビジュアル、フィジカル商品／マーチャンダイズ／ツアー、チーム、予算、KPI 追跡、リンク集を網羅する18 のセクションに加え、未完了成果物の表とドキュメント履歴を含みます。完全な標準テンプレート、共有タグの規則（[INTERNAL] ／ [SHAREABLE] ／ [OPS]）、ステータスマーカー（✅ ／ ❌ ／ ⚠️ TBD ／ N/A）については、references/release-template.md を参照してください。

曲はスラッグで参照します。複製したり移動したりすることはありません。

Spotify カタログデータの保存先

アーティスト作成チェーンのステップ 5（Spotify カタログ）では、このフォルダーにデータを入力します。

• GET /api/spotify/artist/albums が返すすべてのアルバム → references/release-template.md をもとに releases/{release-slug}/RELEASE.md を作成します。ステップ 5 では、Spotify から取得できる項目（セクション 1：アーティスト名、プロジェクトタイトル、リリース日、フォーマット。セクション 2.1：Spotify URI。セクション 2.2：各トラックのタイトル、再生時間、explicit の有無。セクション 2.3：ローカルの songs/ への相互参照。セクション 18：カバーアートの URL）を入力し、それ以外はすべて ⚠️ TBD のままにします。ISRC、UPC、作詞・作曲者／プロデューサー、レーベル、ディストリビューター、マーケティング／PR／予算に関するすべてのセクションは、Spotify の公開レスポンスには含まれないため、ユーザーから情報が提供されるまで TBD のままです。完全なマッピングについては、references/release-template.md を参照してください。

• GET /api/spotify/artist/topTracks → releases/top-tracks.md（リリース横断のスナップショットです。これらはそれ自体がリリースではありませんが、Spotify カタログデータであり、リリースの隣に保存しておくことでカタログを一か所にまとめられるため、ここに保存します）。インライン構造：

  ---
  title: Top Tracks
  source: spotify
  snapshotDate: {YYYY-MM-DD}
  ---
  
  # Top Tracks
  
  | # | Track | Album | Duration |
  |---|-------|-------|----------|
  | 1 | {name} | {album-slug or external} | {mm:ss} |
  

その他のファイルの整理

関連するファイルをまとめてください。競合分析、ブランドガイド、戦略ドキュメントはいずれも調査資料です。3 つのディレクトリに分散させず、同じディレクトリにまとめます。新しいディレクトリを作成する前に、そのファイルを既存のディレクトリに保存できないか確認してください。

動的なコンテキストが古くなった場合（リリースサイクルが終了した、戦略ドキュメントが時代遅れになったなど）は、削除したり、アクティブなファイルと同じ場所に残したりせず、アーカイブに移動してください。アーカイブは必要になったときに作成し、事前には作成しないでください。

データは一か所に保存します。曲は songs/ に保存し、リリースフォルダーにコピーしません。コンテキストは context/ に保存し、調査ドキュメントに重複して記載しません。別の場所にあるデータを参照する必要がある場合は、コピーせず、パスで参照してください。

命名規則

• ディレクトリとスラッグ： lowercase-kebab-case
• 曲ファイル： songs/{song-slug}/{song-slug}.mp3

変更の追跡

進捗ログには git の履歴を使用します。アーティストディレクトリへの変更はすべて、何を変更したか、その理由が分かるメッセージを付けてコミットします。

アーティストディレクトリのコミットメッセージの例：

artist: update aesthetic — shifting from bedroom to lo-fi studio (user direction)
songs: add 5 tracks from ADHD EP with lyrics and clips
research: competitive analysis for Q2 release planning
release: update ADHD EP — distributor confirmed as SpaceHeater
context: refine audience — adding Gen Alpha psychographics from fan survey
archive: move pre-release strategy docs from ADHD EP cycle

形式は {what}: {why} です。「what」には対象領域を記載します。「why」には、何かが変更されたという事実だけでなく、その理由を次のエージェントに伝える意図を記載します。静的なコンテキストを変更する場合は特に重要です。将来のエージェントが、その更新が意図的な進化なのか、誤りなのかを理解する必要があるためです。

アーティストごとに別の進捗ファイルを管理しないでください。真実の情報源は git のログです。何が起きたかを把握する必要がある場合は、コミットを確認してください。

この構成を採用する理由

以前のアーティスト用ワークスペースには、あらかじめ10個以上のディレクトリが作成され、すべてのフォルダーにREADMEファイルが置かれ、プレースホルダーテンプレート、スコープ付きメモリーシステム、アーティストごとの設定ファイルも用意されていました。そのほとんどはすぐに古くなっていました。エージェントには、実際のデータと足場となるファイルを見分けられなかったからです。作成時にその場にいなかったエージェントにとって、{placeholder}トークンだらけのファイルは本物のデータのように見えます。その結果、出力の品質が損なわれます。

現在の構成は、意図的に最小限にしています。実際のコンテンツを入れる段階になるまで、何も作成されません。スキルでは、作業の進行に合わせてエージェントがワークスペースを自然に構築できるよう、各ファイルの置き場所を教えます。