recoup-artist-workspace

What this skill does

# Artist Workspace

Every artist has a workspace — a directory that holds context, songs, and reference material. The `RECOUP.md` file at the root connects it to the Recoupable platform.

Artist directories live inside the sandbox at `artists/{artist-slug}/`. The sandbox is already scoped to a single Recoupable organization (its repo *is* the org), so artists live at the top level — there is no `orgs/` directory.

## Listing what's in the sandbox

When the account asks *"what artists do I have"*, *"list my artists"*, *"which orgs am I in"*, or any other inventory question, **walk the filesystem when this is a real sandbox** — a populated `artists/` tree is authoritative for the sandbox, and the API would answer the broader "what can this account access across everything" question instead.

**The filesystem is only authoritative when it exists.** If `artists/` is missing or empty — e.g. you're an API-key install rather than an open-agents sandbox — the filesystem can't answer the question. Do **not** report an empty roster; fall back to the API via the `recoup-api` skill's **Roster discovery** (`GET /organizations` → `GET /artists?org_id=…`), which lists the artists the credential can actually see.

```bash
# 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
```

Each `RECOUP.md` has frontmatter (`artistName`, `artistSlug`, `artistId`) — read it with `head` or any YAML parser to get the canonical identity.

If `artists/` does not exist: in an open-agents sandbox, it hasn't been set up yet — point the account at the `recoup-setup-sandbox` skill. Outside a sandbox (API-key install), use the `recoup-api` skill's Roster discovery to list artists from the API. Either way, **never invent data to fill the gap.**

## Creating a new artist

When the user asks to create a new artist (or onboard, add, or set one up), drive the work from a **checklist file** — don't try to run the chain from memory. The setup is 8 sequential API calls and the agent loop loses state between turns; the checklist is what lets you resume cleanly and prove which steps actually ran.

### Step 0: Scaffold the workspace BEFORE any API call

Pick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures, body holds the unchecked steps:

```bash
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
```

Don't proceed to step 1 until the file exists on disk.

The full curl-by-curl playbook for steps 1–8 lives in the [`recoup-create-artist`](https://github.com/recoupable/skills/tree/main/plugins/recoup-essentials/skills/recoup-create-artist) skill and on the docs site at `https://developers.recoupable.com/skills/create-artist`. Load that skill once at scaffold time and follow its 8-step chain.

### After every step: tick + persist

Two writes back to `RECOUP.md` after each step completes:

1. **Tick the checkbox** (`- [ ]` → `- [x]`) for the step that just ran.
2. **Write the captured value** into frontmatter (`artistId:`, `spotifyArtistId:`, `spotifyProfileUrl:`, `imageUrl:`, `cmArtistId:`). Later steps read these values from the frontmatter — never re-derive what's already saved. Larger payloads (research responses, social URLs) belong under their own headed subsection in the body, not in frontmatter.

The file IS the workflow state. If a value isn't on disk, the next turn doesn't know it.

### Resuming a partial setup

If `$ARTIST_DIR/RECOUP.md` already exists, do not re-run completed steps. Read the file, find the first unchecked item, and resume from there using the captured frontmatter values:

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

If every item is checked, the artist is fully set up — confirm with the user before doing anything else.

### Why the checklist

Long deterministic chains executed from prose tend to drop steps: the agent reads the doc once, runs a few calls, and forgets the rest. A file-as-state checklist sidesteps that — progress is visible on disk, every step has a write-back side effect, and a fresh turn can resume from the file rather than re-deriving what's already been done.

## Entering an Artist Workspace

When starting work in an artist directory:

1. Read `RECOUP.md` to confirm you're in an artist workspace and get the artist's name, slug, and ID.
2. Check what exists — `ls` the directory to see which files and folders are already there.
3. Read `context/artist.md` if it exists — this is the source of truth for who the artist is. Everything you do should be consistent with it.
4. Check recent git history for this artist — from the repo root, `git log --oneline -10 -- artists/{artist-slug}/` shows only commits that touched this artist's files. If you're already inside the artist directory, use `git log --oneline -10 -- .` instead. Read the commit messages to understand recent changes before making your own.

---

## Working in an Artist Directory

### What Goes Where

A populated artist workspace looks like this. Nothing here is pre-created — each file and directory gets added when there's real content for it.

```
{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
```

If a file or directory doesn't exist yet, create it when the content arrives. If it already exists, update it — don't overwrite without reading what's there first. The directory structure emerges from the work, not from scaffolding.

### Static vs Dynamic Context

Think of artist context in two layers:

**Static context** is who the artist IS. It evolves slowly — across months, release cycles, career phases. `artist.md` and `audience.md` are static. A 20-year-old bedroom-pop pianist might still be a bedroom-pop pianist next year, but over time she may grow into new sonics, shift her aesthetic, or reach a different audience. Update static context deliberately, not casually. When you change `artist.md`, you're changing the source of truth that every tool and agent relies on.

**Dynamic context** is what's happening NOW. Release documents, campaign research, strategy