recoup-platform-build-os

Recoup — Build Label OS

The point is not the folders — it's to scaffold a system that both manages itself and improves itself. It keeps its own state current (never-stale) and gets better at its own job over time: compounding knowledge, promoting repeated work into new skills, and improving its own machinery. Hold that as the goal of every phase below; the structure only exists to serve it.

Concretely, turn a kickoff input into a living operating system: a folder + file structure, a self-managing CLAUDE.md (mirrored to AGENTS.md), a plugin/ directory (an in-place installable plugin with skills inside), a never-stale janitor backed by a read-only doctor, a compound-learning loop, and a self-improvement loop. The plugin is named {DOMAIN_SLUG}-os by default and includes manifests/adapters for Claude, Cursor, and Codex.

This builder skill is for the agent running it. Follow the phases in order. Don't stop halfway — drive to a working OS, then report. Read the references as you reach each phase.

Recoup specialization — this is a music-company OS [read before Phase 0]

This skill is workspace-os (by Sidney Swift) locked to one domain — a music company / independent label — and wired into Recoup. The phases below are unchanged; apply them with these Recoup rules layered on top.

• The domain is fixed — don't re-infer it. Core unit: the artist (and their releases). Entities folder: top-level artists/. The release lifecycle (demo -> A&R -> signed -> production -> release -> promo -> catalog) is tracked per release under artists/{slug}/releases/ (stage in RELEASE.md) — there is no separate top-level pipeline/; unsigned candidates live in prospects/. Spend Phase 0's effort understanding this specific label (roster, genres, deal posture, content motion, team), not which archetype it is.
• The repo is one org/label. This runs inside a single org's git repo, so artists live at top-level artists/{artist-slug}/ — no orgs/ nesting (the repo already is the org).
• Seed Recoup's conventions exactly — other recoup skills depend on them:
  • artists/{artist-slug}/RECOUP.md — identity file, frontmatter artistName / artistSlug / artistId (artistId = the Recoup account_id). Same shape recoup-roster-list-artists, recoup-roster-add-artist read/write.
  • releases/{release-slug}/RELEASE.md and releases/top-tracks.md per artist.
  • slugify = lowercase-kebab; never append IDs to folder names.
• Secrets stay out of the shared repo. Always seed .env.example (documenting RECOUP_API_KEY or RECOUP_ACCESS_TOKEN, RECOUP_ORG_ID, optional RECOUP_API_URL) and a .gitignore that ignores .env. Real credentials live outside the repo (env vars / ~/.claude/recoup.env); never commit them — the repo is shared across the label's team.
• The Recoup API is the system of record; the repo is the brain. Get the real roster from the live account — never invent one:
  1. Connect the machine first by chaining recoup-platform-connect-account (mints/loads the credential: RECOUP_API_KEY or RECOUP_ACCESS_TOKEN, optional RECOUP_ORG_ID).
  2. If the roster is empty (0 artists), hand off to recoup-roster-onboard to bootstrap it (it fans recoup-roster-add-artist out across parallel subagents); otherwise materialize the existing roster into artists/ yourself: GET /api/organizations (or use RECOUP_ORG_ID) -> GET /api/artists?org_id=… -> mkdir -p artists/{slugify(name)} and write RECOUP.md per artist (artistName/artistSlug/artistId from account_id); skip existing. Use recoup-roster-list-artists to inventory first and recoup-platform-api-access for the call shapes.
  3. Write operations/sync.md with the contract: DB owns structured entities (roster, socials, metrics, releases-as-records, billing); the repo owns the unstructured brain (knowledge, research, plans, drafts). Entity creation is API-first — onboard a new artist with recoup-roster-add-artist (the 8-call create -> enrich chain), then its folder appears; never create an artist by mkdir alone. Use recoup-platform-api-access for raw REST / connector calls. Empty orgs+artists usually means a throwaway key, not a blank label — surface it, don't fabricate a roster.
• Reuse the platform; don't reinvent it. In Phase 4, do not author plugin/skills/ that duplicate Recoup capabilities — wire to the installed recoup-* skills: roster (recoup-roster-*), research (recoup-research-*), content (recoup-content-*), release (recoup-release-*), song (recoup-song-*), catalog (recoup-catalog-*). The OS's own plugin/skills/ should be label-specific glue (this label's routines/orchestration) plus the standard maintenance organs (doctor/janitor/learn/reflect/skillify/intake). Default the plugin name to {label-slug}-os.
• Still scaffold everything else a music company needs. Beyond the core (artists/, knowledge/, library/, work/, artifacts/, plugin/, operations/), add optional folders only with real material: content/ (the flywheel), deals/ (catalog acquisitions), contacts/ (industry network), proof/ (press/milestones), business/ (splits/royalties/contracts), prospects/ (A&R funnel), reference/ (label bible). Mark inferred items "draft — confirm". See references/blueprint.md for the full tree.
• Filling the generic templates (doctor/dashboard/janitor). When you generate them from assets/, the entity is artists/ and there is no pipeline folder — leave {PIPELINE} empty, or set it to prospects/ only if the label does A&R. The doctor reads release status from each artists/{slug}/releases/ (stage in RELEASE.md), not a top-level funnel.

Operating beliefs (apply to every OS you build)

Every belief below serves one goal: a system that manages itself (stays current) and improves itself (compounds its knowledge, its capabilities, and its own machinery).

1. Separate what compounds from what flows. Compounding = reusable assets that improve every time (templates, knowledge base, skills, proof). Flowing = instances moving through stages (deals, tickets, releases, experiments). Wire feedback so every flowing instance deposits back into a compounding asset.
2. Never stale. It is the agent's job to manage state. Any time new input arrives OR the user works in the OS, every file/folder that should change gets touched in the same turn. A janitor skill + scheduled task is the safety net.
3. Compound learning. Every session makes the system smarter — capture decisions, recurring answers, and patterns into the knowledge base. Never solve the same thing twice.
4. Skillify proven repeatable work. After finishing work, ask whether it will be done again or maintained. If yes, promote the proven process into a staged, verified skill before it lands in plugin/skills/. One-off work stays in work/ (dated) — it never becomes its own top-level folder.
5. Self-describing. Every folder explains its own purpose; CLAUDE.md encodes where new things go and how to keep the system current.
6. Evidence over confidence. "Done", "consistent", and "reachable" are decided by a checkable surface — a {domain}-doctor run, a skill's verification, a reachable trigger — not the agent's feeling. And the OS improves itself over time ({domain}-reflect), not just its contents.

Phase 0 — Understand the project deeply (always first)

Read references/domain-inference.md.

• Ingest ALL kickoff input (files, transcripts, prompt). If files exist, read them fully.
• Determine the domain archetype and the core unit of work (e.g. consulting -> deals/clients, product -> features/releases, record label -> artists/releases, research -> questions/experiments).
• If input is rich, derive structure from the material. If input is sparse (just a prompt), use best judgment: infer the domain, predict the entities, stages, assets, routines, and metrics the project will need, and anticipate them rather than waiting — but express that preparation as stubs and subfolders inside a lean root (see Phase 1), not as extra top-level directories.
• Produce a short Understanding Brief: domain, core unit, lifecycle stages, key entities, compounding assets, recurring tasks (skill candidates), metrics, and likely external tools.
• Confirm the brief with the user only if something material is ambiguous; otherwise proceed.

Phase 1 — Design the taxonomy

Read references/blueprint.md.

• Start from the small core the loops maintain: the flowing stores (a staged pipeline folder + an entity folder like clients/ / artists/ / features/), the compounding stores knowledge/ and library/, work/ (non-recurring output, by project), artifacts/ (finalized recurring outputs like the dashboard), plugin/ (the in-place plugin), and operations/ (routines, sync, health, improvements).
• Add an optional top-level folder only when the domain has real material for it now — reference/ (canon/source), proof/ (outcomes), content/ (a real content motion), business/ (legal/finance/metrics). When unsure, leave it out; adding later is one mkdir.
• Keep every top-level folder name to one lowercase word (operations, not operating-system; knowledge, not knowledge-base). Rename to the domain's language but keep it a single word. (Skill folders inside plugin/skills/ stay kebab-case — a different convention.)
• Don't reproduce the whole anatomy by reflex, and don't promote one-off work to a top-level folder — ad-hoc tasks live in work/; only work that repeats or needs upkeep becomes a skill in plugin/. Push over-preparation into subfolders and stubs, not a row of empty top-level dirs.

Phase 2 — Scaffold structure + the brain

• Create only the folders the taxonomy calls for (lean root). Give every non-obvious folder a short README.md stub stating what belongs there.
• Write artifacts/dashboard.html from assets/dashboard.html.tmpl (HTML, not md). Seed operations/health.md (empty — the {domain}-doctor fills it) and operations/improvements.md (a header for the {domain}-reflect ledger).
• Write the self-managing CLAUDE.md from assets/CLAUDE.md.tmpl, customized to the domain (filing decision tree, the auto-manage loop, never-stale contract, repetition-to-skill rule). Read references/self-management.md for what the contract must contain.
• Create AGENTS.md as a symlink to CLAUDE.md (ln -s CLAUDE.md AGENTS.md) so agent runners that look for either file get the same brain. If symlinks aren't supported, write an AGENTS.md that says "See CLAUDE.md" — but prefer the symlink.

Phase 3 — Seed compounding assets

• Populate library/ (blank instruments you reuse — templates, scripts, checklists) and knowledge/ (settled answers you read back — faqs, insights, decisions, sops). Rule of thumb: if you'd use it to make something it's library/; if you'd consult it to decide something it's knowledge/.
• Extract this material from the input. With sparse input, seed sensible starter templates for the domain and mark them "draft — confirm".

Phase 4 — Author skills (the in-place plugin/)

Read references/skill-authoring.md and references/skillifying-work.md (promotion workflow).

• Derive the plugin name from the domain as {DOMAIN_SLUG}-os (kebab-case) unless the user explicitly gave a name. Use that same name in every manifest.
• Scaffold plugin/ as a real plugin in place: plugin/.claude-plugin/plugin.json from assets/claude-plugin.json.tmpl, plugin/.codex-plugin/plugin.json from assets/codex-plugin.json.tmpl, and a plugin/skills/ directory. The Codex manifest must include "skills": "./skills/"; see references/packaging.md.
• Create .agents/skills as a symlink to ../plugin/skills so Cursor and Codex can discover the same project skills. If symlinks aren't supported, copy plugin/skills/ there and note that it is a compatibility mirror.
• For each recurring task in the brief, author plugin/skills/{name}/SKILL.md (frontmatter name + description with real trigger phrases, then imperative steps referencing the workspace paths).
• Always include the maintenance skills (the OS's feedback organs), generated from the templates:
  • a doctor (assets/doctor-SKILL.md.tmpl) — the read-only verification surface (health score + punch list to operations/health.md); the janitor and the build report are gated on it. Also generate operations/doctor.py from assets/doctor.py.tmpl (fill the PIPELINE/ENTITY/slug) as its deterministic fast path — so the mechanical checks ship with the build instead of being reinvented later.
  • a janitor (assets/janitor-SKILL.md.tmpl) — run the doctor, then reconcile and fix what's safe.
  • a compound-learn skill (assets/compound-learn-SKILL.md.tmpl) — capture decisions/answers/patterns into knowledge/ after each work session.
  • a reflect skill (assets/reflect-SKILL.md.tmpl) — improve the OS itself (skills, routing, checks, templates) into operations/improvements.md; the 50/50 budget.
  • a skillify skill (assets/skillify-SKILL.md.tmpl) — promote proven repeatable work into staged, verified skills.
• Also include an orchestrator skill (the auto-manage loop as one trigger) named {domain}-intake.
• Routing stays lean: rely on each skill's description for routing while the pack is small; add a plugin/skills/RESOLVER.md (trigger -> skill table) only once skills grow enough that descriptions overlap or the doctor's reachability check flags ambiguity.
• Author a skill only for work that repeats or needs upkeep — one-off builds belong in work/, not a throwaway skill. For skills created from completed work, follow the skillify loop: prove provenance, extract the repeatable process, stage in work/, verify with the strongest domain-appropriate check, ask before moving into plugin/skills/, then repackage.

Phase 5 — Package the plugin

Read references/packaging.md.

• Run {domain}-doctor first — packaging is gated on a clean (or explained) report.
• The workspace plugin/ directory is already the installable plugin — no copying. Validate it: every plugin/skills/*/ has a SKILL.md; both plugin manifests are valid JSON and share the {DOMAIN_SLUG}-os name; the Codex manifest points at ./skills/; no angle brackets in any description; no stray non-skill folders in plugin/skills/; .agents/skills points to or mirrors plugin/skills/. Fix before packaging.
• zip the contents of plugin/ to /tmp first, then copy the .plugin to the outputs

...