recoup-platform-build-os

Recoup — Build Music Workspace

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 — select the actual music workflow

The domain is a music business, including labels, writers, publishers, administrators, recording owners, estates and authorized advisers. Identify its core records in Phase 0; never manufacture an artist account to fit composition or royalty work.

• Choose a spine from actual work. Artist/release operations use artists/ and

per-artist releases. Publishing uses compositions/ and parties/. Audit, royalty reconciliation and acquisitions use cases/ with scope/evidence/stage records. Use only the folders backed by real work; an empty roster is legitimate.

• One authorized workspace per repository. Keep private agreements, statements,

identifiers and receipts in the selected private workspace. Public plugin examples remain synthetic. A local case is not a hosted catalog until a supported save reads back.

• Preserve the existing artist convention where applicable. Mirror verified artists

into artists/{artist-slug}/RECOUP.md with artistName, artistSlug and the actual artistId. Release records live under each artist's releases. Never invent IDs. A composition-only case can use local case IDs and retain missing ISRC/ISWC values.

• Use available access. An authenticated MCP connection can already provide account

scope. REST can use supplied environment credentials; no harness-specific env file is mandatory. Connect an account only when the requested hosted operation needs it. Never copy MCP OAuth credentials into files. File review/intake works without login.

• Write `operations/sync.md` per object. Hosted structured records are authoritative

only for fields the discovered API actually supports. The private workspace preserves evidence, unresolved candidates, plans and source versions. Record unsupported fields instead of asserting every local record is in the database. For an actual roster use supported roster reads and API-first artist creation when requested; zero artists is not permission to onboard unrelated people or publishers.

• Reuse focused Recoup skills. Catalog import, organization, contract explanation,

audit, reconciliation, registration, resolution and deal review retain their stage boundaries. Song credits and release metadata remain checks. Local glue coordinates explicitly requested stages; it never turns a review into external correspondence.

• Keep secrets outside versioned material. If REST access is needed, seed an

.env.example documenting names and a .gitignore excluding actual credentials. Provider membership, a music mandate and software permissions are separate facts.

• Configure maintenance to the selected spine. Fill the doctor/dashboard templates

with the actual entity folder and workflow. A publishing or accounting workspace must not fail health checks because it has no artists, valuation or recurring task.

Read references/blueprint.md for the lean structures. Label-specific release mechanics remain available; do not impose them on every publisher or catalog adviser.

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.

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

1. Compound learning. Every session makes the system smarter — capture decisions, recurring

answers, and patterns into the knowledge base. Never solve the same thing twice.

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

1. Self-describing. Every folder explains its own purpose; CLAUDE.md encodes where new things

go and how to keep the system current.

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