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 folder and
  present it for install.

Phase 6 — Wire the never-stale schedule

• Try to create a scheduled task that runs the janitor skill (default weekly) so the workspace
  self-reconciles even when the user isn't looking.
• If no scheduling tool is available, or the user declines: this is not a failure. Record the
  intended cadence in operations/routines.md, AND drop a ready-to-use schedule from
  assets/janitor-schedule.tmpl (GitHub Actions / cron / launchd / agent-runner task) so enabling it
  later is a single copy, not a research project. The OS is still complete — the janitor also runs on
  demand — but until the schedule is armed, the doctor keeps a standing low "schedule armed" finding,
  because "self-reconciles when no one is looking" is only true once it actually runs unattended.
• Don't block or leave the build "unfinished" over scheduling; treat it as the one optional step.

Phase 7 — Report

Run {domain}-doctor and report its score as the build's verification surface — "done" is a clean
(or explained) doctor run, not a feeling. Summarize: the structure created, the skills authored, the
plugin produced, the schedule set, and the health score. List what was inferred vs. confirmed so the
user can correct any assumptions.

Guardrails

• Don't invent domain facts the user must own — mark inferred items "draft — confirm".
• Leave nothing stale: if you touched the project, update the dashboard, boards, and any affected
  README in the same turn.
• Prefer improving a template/skill over a one-off instance.