| name | recoup-roster-add-artist |
| description | Onboard a brand-new artist to your roster and enrich them — the 8-call chain (create → Spotify match → research → catalog → socials → knowledge base) that sets up the artist and their workspace folder. Use for "create/add/onboard an artist", "set up [artist]", "we just signed [artist]", or "new signing". To see your roster use recoup-roster-list-artists; to work inside an existing artist's files use recoup-roster-manage-artist. |
Recoup — Add Artist
Bring a new artist into the box: create the account, enrich it, and scaffold their
workspace. Driven by a checklist so the long chain is resumable.
The 8-call onboarding chain (drive from the RECOUP.md checklist)
Long chains run from prose drop steps, so drive from the RECOUP.md checklist:
scaffold it first (frontmatter holds captured values; body holds the unchecked
steps), tick + persist after each step — the file IS the workflow state, resumable
from the first unchecked box. Don't run under an agent+ account (data gets
orphaned). The 8 calls:
POST /api/artists {name, organization_id} → capture account_id.GET /api/spotify/search → best match → id, external_urls.spotify, images[0].PATCH /api/artists/{id} with image + profileUrls:{SPOTIFY} (UPPERCASE keys).- Structured research (retry transient misses):
/research/lookup?spotifyId= →
songstats_artist_id, then /research/profile|career|playlists + /research/web.
- Spotify catalog (
topTracks, albums, album) → write releases/{slug}/RELEASE.md
per album + releases/top-tracks.md.
- Web search for socials (ig/tiktok/twitter/youtube).
PATCH /api/artists/{id} with discovered profileUrls (only platforms found).- Synthesize a
## Knowledge base section into RECOUP.md.
Run in order; don't continue past a 4xx/5xx without recovery. Uses
recoup-platform-api-access for the call shapes.
Guardrails
- The file is the state — tick + persist each step or a fresh turn redoes/skips work.
- No placeholder data in artist files — real content or leave the section out.
- Never invent a roster/artist — confirm via recoup-platform-api-access first; an
empty filesystem is not an empty roster.
