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).

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.
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.
Compound learning. Every session makes the system smarter — capture decisions, recurring answers, and patterns into the knowledge base. Never solve the same thing twice.
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.
Self-describing. Every folder explains its own purpose;
```
CLAUDE.md
```
encodes where new things go and how to keep the system current.
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.

recoup-platform-build-os

NPX Install

Tags

SKILL.md Content

Recoup — Build Label OS

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

Operating beliefs (apply to every OS you build)

Phase 0 — Understand the project deeply (always first)

Phase 1 — Design the taxonomy

Phase 2 — Scaffold structure + the brain

Phase 3 — Seed compounding assets

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

Phase 5 — Package the plugin

Phase 6 — Wire the never-stale schedule

Phase 7 — Report

Guardrails

recoup-platform-build-os

NPX Install

Tags

SKILL.md Content

Recoup — Build Label OS

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

Operating beliefs (apply to every OS you build)

Phase 0 — Understand the project deeply (always first)

Phase 1 — Design the taxonomy

Phase 2 — Scaffold structure + the brain

Phase 3 — Seed compounding assets

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

Phase 5 — Package the plugin

Phase 6 — Wire the never-stale schedule

Phase 7 — Report

Guardrails

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