agentleFS
philipyazphilipyaz/cos/.claude/skills/add-an-addon/SKILL.md

add-an-addon

Skill4 starsChanged 4 months agoMITView on GitHub

Build a NEW optional vertical (an "add-on") in the Cos repo the framework-native way — one four-layer slice (nav + API + data + MCP) gated by ONE Settings.addons.[id] flag, with all data folded onto cases.json. Use when adding a whole new feature area (a "health" dashboard, a "finance" tracker, a "reading list", etc.), when reviewing/refactoring a feature that was built OUTSIDE the framework (its own *-store.ts, its own data/*.json, hardcoded nav, an unregistered route prefix), or whenever you're about to mint a new persistence store / new top-level nav and need to know whether it should instead be an add-on. The worked example is Nutrition & Chef (board/lib/addons.ts, mcp/nutrition-server, board/app/api/nutrition, tests/api-nutrition-gate.mjs); the cautionary example is the Health & Athlete PR this skill was written from.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 2 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when you are adding a whole feature area (its own pages + routes + agent tools) that should ship disabled by default and not …

    line 16
  2. Very specific:

    create a new board/lib/<x>-store.ts or a new board/data/<x>.json → the data belongs on cases.json via DBShape, written through the existing …

    line 21
  3. Very specific:

    add an /api/<x>/* route prefix that nothing in ADDON_REGISTRY claims → register it.

    line 25
  4. Very specific:

    Writes close: every mutation calls assertAddonEnabled(db, id) inside mutate() → NotFoundError → 404 when disabled (atomic with the write, …

    line 52
  5. Very specific:

    Reads stay open: every GET is ungated. Disabling freezes an add-on.

    line 54
  6. Very specific:

    Add your owned array(s) as optional fields on DBShape (e.g.

    line 69
  7. Very specific:

    Add one entry to board/lib/addons.ts (copy NUTRITION_ADDON).

    line 82
  8. Very specific:

    Do not: add bespoke helpers; the four existing ones (listAddons, getAddon, isAddonEnabled, assertAddonEnabled) are the entire gate.

    line 86
  9. Very specific:

    POST / PATCH / DELETE = gated: Do the read-modify-write inside mutate() and call assertAddonEnabled(db, "<id>") as the first line inside …

    line 95
  10. Very specific:

    Create mcp/<name>-server/server.mjs using packages/mcp-kit (err, text, str, start, baseUrl, makeBoardApi) — copy …

    line 118
  11. Very specific:

    Add the port to config/load-config.sh ONLY: a default : "${<NAME>_BRIDGE_PORT:=80NN}", the derived : …

    line 133
  12. Very specific:

    Write the feature page under docs/features/<x>.md and add it to the nav: in mkdocs.yml (under features:, next to Nutrition & Chef).

    line 164
  13. Very specific:

    Add all of them to tests/run.sh.

    line 177
  14. Distinctive:

    When your add-on reads another add-on's data (e.g.

    line 181
  15. Very specific:

    Reads stay open: Read the other add-on's array directly (db.foodLogs) and default with ??

    line 185
  16. Very specific:

    Missing install path + smuggled pm2: No service descriptor / no <X>_BRIDGE_PORT, and a new

    line 254

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add an add-on (the framework-native way)

An add-on is an optional, self-contained vertical layered over the core board. The framework already exists — your job is to parametrise it with one manifest, not to invent a parallel one. Copy Nutrition & Chef (board/lib/addons.ts, mcp/nutrition-server/, board/app/api/nutrition/, tests/api-nutrition-gate.mjs) beat for beat. Read docs/architecture/addons.md first; it is the spec, this is the recipe.

WHEN this applies — and the tell that you're doing it wrong

Use this skill when you are adding a whole feature area (its own pages + routes + agent tools) that should ship disabled by default and not bloat the core.

The tell — STOP and make it an add-on if you catch yourself about to:

  • create a new board/lib/<x>-store.ts or a new board/data/<x>.json → the data belongs on cases.json via DBShape, written through the existing mutate().
  • hardcode a nav entry into the sidebar's core list → nav comes from the manifest's navItems, revealed only when the flag is on.
  • add an /api/<x>/* route prefix that nothing in ADDON_REGISTRY claims → register it.
  • mint a second persistence chokepoint, a second SSE channel, a second backup path → there is exactly one of each, and riding cases.json gives you all three for free.

Does NOT apply to: a tweak to a core surface (cases/events/reminders/priorities — those are always-on, never gated), or a pure agent-skill with no new data/nav/routes.

The mental model (memorise this)

One four-layer slice, gated by ONE flag. Writes close; reads stay open. A component is a STATE MACHINE — it never calls an LLM; the agent is the intelligence.

An add-on is a deterministic state machine: it persists state and exposes it via an API + an MCP server, and that is the whole contract. It does NOT call an LLM / the Anthropic API. Any generative step (a training plan, a summary, a drafted reply) is produced by the external agent (your operator skill, Claude Cowork) and written back through an MCP write tool / a POST; the add-on only validates, versions, attributes, stores, and serves it. Deterministic server-side compute (stats, projections, aggregations) is fine — only generative LLM inference is delegated. The sole exception in the whole repo is the vault MCP (mcp/vault-server), which embeds the Claude Agent SDK and is itself an agent. If you catch yourself reaching for @anthropic-ai/sdk (or any LLM client) inside an add-on route or MCP server, stop — that generative step belongs in the agent's context, not the component.

  • Four layers: nav + API + data + MCP server — the same machinery the core uses, parametrised by an AddonManifest. Nothing about an add-on is special-cased.
  • ONE flag: Settings.addons.<id>.enabled, persisted in cases.json (board state, not config). isAddonEnabled(db, id) is true only when it is exactly true; absent === off.
  • Writes close: every mutation calls assertAddonEnabled(db, id) inside mutate() → NotFoundError → 404 when disabled (atomic with the write, closes the TOCTOU).
  • Reads stay open: every GET is ungated. Disabling freezes an add-on; it never hides or deletes a byte. Re-enabling resumes exactly where it left off.
  • WHY data rides cases.json: you inherit free SSE live-update (one version bump reaches every tab), free encrypted backup (the whole file is snapshotted), and free attribution (human from the UI, agent from the MCP). A standalone store throws all three away and you'd have to rebuild them badly.

Two clocks, on purpose: the in-board surface (nav + API gate) activates the instant you flip the flag via SSE; the agent surface (the MCP bridge) activates only when someone runs the setup skill on that machine. Flipping the DB flag does not start a daemon — nothing hot-loads.

The 9-step walkthrough (copy nutrition at each step)

1. Data — on DBShape in board/lib/types.ts, plus a singleton if you need one

  • Add your owned array(s) as optional fields on DBShape (e.g. healthEntries?: HealthEntry[], mirroring foodLogs?). Bump SCHEMA_VERSION; the change is purely additive so old boards read unchanged.
  • A non-array singleton (a profile/goal object) is a bare field — athleteProfile? mirrors nutritionGoal? — and is deliberately NOT in dataArrays (that list is arrays only).
  • Carry the new fields through migration + validate + ensureFile and add typed getX/setX store helpers with sticky createdAt (mirror getNutritionGoal/setNutritionGoal).
  • Define all vocabulary as VALID_* arrays in types.ts and import them everywhere — the route validator AND the UI bind to the same arrays. Never redefine an enum inline; never store a label in a non-English language.

2. Manifest — ONE AddonManifest literal in ADDON_REGISTRY

Add one entry to board/lib/addons.ts (copy NUTRITION_ADDON). This single source of truth gives you the /addons catalog row, the toggle, the nav, the gate, and the bridge probe — for free. Fill: id, title, description, icon, navItems[], apiPrefixes[], dataArrays[] (arrays only — omit singletons), the mcp block, and any dependsOn[]. Do not add bespoke helpers; the four existing ones (listAddons, getAddon, isAddonEnabled, assertAddonEnabled) are the entire gate.

3. API — routes that gate writes inside mutate(), leave GETs open, reuse helpers

For each resource under board/app/api/<prefix>/:

  • GET = ungated. readDB(), filter, return { ..., version: db.version }. A disabled add-on's data must still read.
  • POST / PATCH / DELETE = gated. Do the read-modify-write inside mutate() and call assertAddonEnabled(db, "<id>") as the first line inside the lock (gate + id-mint + write are one critical section). Map thrown store errors with storeErrorToResponse.
  • Reuse @/lib/route-helpers — isISODate (validate every date), resolveActor (write attribution), storeErrorToResponse. Never re-inline them.
  • NEVER call a sibling route over loopback HTTP. No fetch to your own /api/*. If two routes share logic, extract a function into board/lib/<x>.ts and call it in-process.
  • Zero console.log in board/app/api — and absolutely no logging of user/biometric data.
  • A route NEVER calls an LLM. The component is a state machine; the agent generates. A "coach/summary" endpoint is a CRUD seam that accepts an already-generated artifact (the agent built it in its own context and POSTs it) — validate the artifact's JSON before the store write (never persist an unvalidated body), version it, attribute it, store it. Deterministic compute (stats, a projection, an aggregator in board/lib/<x>.ts) is fine — only generative inference is off-limits. The vault MCP is the one exception (it embeds the Agent SDK).

4. Nav — from the manifest only

The sidebar reads navItems off the manifest and shows the group only when the add-on is enabled. Do NOT touch the sidebar's core/daily nav array — adding your links there hardcodes them on for everyone and defeats the gate.

5. MCP server — a THIN fetch wrapper, no business logic

Create mcp/<name>-server/server.mjs using packages/mcp-kit (err, text, str, start, baseUrl, makeBoardApi) — copy mcp/nutrition-server/server.mjs. Every tool is a thin fetch over your /api/* routes on CRM_BASE_URL; no business logic and NO LLM calls in the MCP (the intelligence lives in the operator skill / the agent; the vault MCP is the one server that embeds an LLM, and it is the exception, not the template). Every WRITE tool sends { actor: "agent" } + an x-actor: agent header. A disabled add-on 404s writes → surface as a Not found. tool error. Adding a new mcp/<x>-server makes it a root npm workspace member: run npm install at the repo root and commit package-lock.json, or CI's npm ci fails.

6. Install path — ONE descriptor + a port in the loader (manifest-driven, both OSes)

Supervision is manifest-driven (see mcp/CLAUDE.md): you define the service once as a co-located descriptor and the generators render every platform from it. No committed plist template, no ensure-bridges.sh edit, no second port map.

  • Add the port to config/load-config.sh ONLY: a default : "${<NAME>_BRIDGE_PORT:=80NN}", the derived : "${<NAME>_BRIDGE_URL:=http://localhost:$<NAME>_BRIDGE_PORT}", and both names on the export line. Then mirror it into config/cos.env.example for documentation. This is the canonical port on every OS.
  • Drop ONE descriptor mcp/<name>-server/<name>.service.json (schemaVersion:1, kind/runtime:"bridge", addon:"<id>", portVar:"<NAME>_BRIDGE_PORT", stdio:["${NODE_BIN}", "${REPO_ROOT}/mcp/<name>-server/server.mjs"], env:{CRM_BASE_URL:"${BOARD_URL}", COS_DEVICE_ID:"${COS_DEVICE_ID}", COS_DEVICE_ROLE:"${COS_DEVICE_ROLE}"}, clients:["claude-code","cowork"], probe:{type:"httpListen"}, idleExit:true). Copy mcp/nutrition-server/nutrition.service.json beat for beat. The addon:"<id>" field is what makes the probe treat the bridge as OPTIONAL and skip it silently on a board that never installed it — there is no hand-maintained registry line or skip-case anymore.
  • If your write tools need a machine-local secret (e.g. the vault's ANTHROPIC_API_KEY; no add-on ships one today), add secrets:["<TOKEN>"] + secretWrapper:"${REPO_ROOT}/mcp/<name>-server/launch.sh" to the descriptor and ship a launch.sh (copy mcp/vault-server/launch.sh) that sources config/secrets.env then exec "$@" — gen-launchd renders the shared supergateway argv (preload included) after the wrapper, so the secret never lands in the rendered plist or .mcp.json. Most add-ons need no secret (copy nutrition, which has none).
  • Do NOT smuggle in pm2 or any new process manager, and never hand-edit .mcp.json (it is a generated, CI-checked artifact). The bridge is a launchd LaunchAgent rendered by gen-launchd.mjs; that is the only mechanism.

7. Skills — one setup skill + one operator skill

  • /<x>-mcp-setup (copy nutrition-mcp-setup): renders + loads the launchd bridge plist, wires the .mcp.json + Cowork stdio entry, points <X>_BRIDGE_PORT, verifies the bridge.
  • An operator skill (copy /nutrition-chef) that turns plain language into structured writes via your MCP — this is where any estimation/judgement lives, not in the MCP.

8. Docs — docs/features/<x>.md wired into mkdocs.yml

Write the feature page under docs/features/<x>.md and add it to the nav: in mkdocs.yml (under features:, next to Nutrition & Chef). No loose root *.md. Cross-link with relative .md paths; validate with uvx --with mkdocs-material mkdocs build --strict.

9. Tests — gate + CRUD + unit, wired into tests/run.sh

  • tests/api-<x>-gate.mjs — copy tests/api-nutrition-gate.mjs exactly: snapshot cases.json, prove disabled → GET 200 but POST/PATCH/DELETE 404, enable bumps db.version, enabled → POST 201, unknown id → 404, non-boolean enabled → 400; restore in finally.
  • CRUD coverage per resource and unit tests for any pure logic in board/lib/<x>.ts (summarisers, target engines) — assert the canonical field names, not the producer's incidental shape.
  • Add all of them to tests/run.sh.

Cross-add-on dependencies (soft by default)

When your add-on reads another add-on's data (e.g. a coach folding in the food log):

  • Declare a soft edge: dependsOn: [{ id: "<other>", required: false }]. The catalog surfaces "works better with <other>"; runtime posture is unchanged.
  • Reads stay open. Read the other add-on's array directly (db.foodLogs) and default with ?? []. That ?? [] only ever fires when the other add-on was never installed (the field is absent) — a disabled add-on still has readable data.
  • NEVER gate a cross-read on the other add-on's isAddonEnabled. That would hide frozen-but-readable data and violate "reads stay open". Soft deps never auto-enable and never hard-gate. Reserve required: true for a future dependent that is genuinely useless alone.

Copy CHECKLIST — tick every box before the PR

  • Owned array(s) on DBShape (types.ts); SCHEMA_VERSION bumped; migration + validate + ensureFile carry them.
  • Any singleton is a bare field with sticky-createdAt getX/setX helpers; not in dataArrays.
  • All vocabulary as VALID_* arrays in types.ts, imported by both route + UI; English only.
  • ONE AddonManifest in ADDON_REGISTRY; no new gate helpers.
  • GETs ungated; every write calls assertAddonEnabled inside mutate().
  • Routes reuse isISODate / resolveActor / storeErrorToResponse; no re-inline.
  • No loopback fetch to own /api/*; shared logic in board/lib/<x>.ts, in-process.
  • Zero console.log in board/app/api; no PII/biometric logging.
  • No LLM client imported anywhere in the add-on (route OR MCP) — the component is a state machine; the agent generates and POSTs. Any "coach" route is a CRUD seam that validates the artifact JSON before the store write. (Vault is the sole LLM-bearing server.)
  • Nav from manifest only; core sidebar array untouched.
  • MCP = thin mcp-kit fetch wrapper; { actor: "agent" } on writes; npm install at root + package-lock.json committed.
  • ONE co-located descriptor mcp/<name>-server/<name>.service.json (schemaVersion:1, addon:"<id>", portVar); <X>_BRIDGE_PORT (+ derived _URL) added to config/load-config.sh and documented in config/cos.env.example; no committed plist template, no ensure-bridges.sh edit, no pm2; .mcp.json regenerated via gen-mcp-json.mjs (never hand-edited).
  • /<x>-mcp-setup + operator skill.
  • docs/features/<x>.md in mkdocs.yml; mkdocs build --strict clean.
  • api-<x>-gate.mjs + CRUD + unit tests, all in run.sh.

Lessons from the Health & Athlete PR (anti-pattern catalog)

Each of these was a real mistake in the feature this skill reviews. Don't repeat them.

  • Standalone store. board/lib/health-store.ts + a separate data file — re-implementing what cases.json gives free and losing SSE + backup + attribution. → Fold onto DBShape; retire the standalone store. (Repoint every @/lib/health-store import to @/lib/fitness.)
  • Unregistered feature. Pages + routes shipped with no ADDON_REGISTRY entry, so no catalog row, no toggle, no gate. → One manifest gives all of it.
  • Ungated writes. Mutations with no assertAddonEnabled (or the check only at the route edge, not inside mutate()). → Gate inside the lock.
  • Hardcoded nav. Links jammed into the core sidebar list, on for everyone. → navItems only.
  • Split-brain taxonomy. The producer stored type "hrv" but consumers queried "heart_rate_variability"; summarise/trends read data.duration_min / data.avg_ms / data.bpm / data.count while the producer wrote data.value. Producer and consumer disagreed on the type string and the field, so reports silently came back empty. → Canonicalise one taxonomy (the HAE ingest shape; metric entries use data.value, day ts) and make every consumer read it. And: the test that masked it asserted the producer's incidental shape instead of the canonical contract — tests must assert the contract, or they certify the bug.
  • Loopback self-calls. A route fetch-ing its sibling /api/* over HTTP. → Extract to board/lib/<x>.ts, call in-process.
  • Re-inlined helpers + unvalidated artifact JSON. Date checks re-written instead of isISODate; an agent-supplied artifact body written straight to the store without validation. → Reuse route-helpers; validate the artifact shape before any write (raw bodies are never trusted).
  • An LLM call inside a component. A route or MCP server that imports @anthropic-ai/sdk and generates a plan/summary/reply server-side — turning a state machine into a key-bearing, offline-broken, non-deterministically-testable thing. (This is exactly what the fitness add-on's removed board-side GET /api/fitness/training-plan|weekly-review|pre-workout-brief generate routes did.) → Delegate generation to the agent; expose a CRUD seam (POST /api/fitness/coaching + the save_* MCP tools) that accepts the agent's already-generated, validated artifact and persists it. The vault MCP is the only server that may embed an LLM.
  • Debug PII logging. console.log of biometric data in API routes. → Zero console.log.
  • Silent missed-day data drop. The HAE ingest converter kept only today's points and discarded the rest of the re-sent history, so a single missed sync lost those days permanently (and the UTC today misclassified late-evening points). → Don't filter the caller's data to one day; rely on dedup-by-id and compute day boundaries in the user's timezone.
  • Missing install path + smuggled pm2. No service descriptor / no <X>_BRIDGE_PORT, and a new pm2 dependency sneaked in. → ONE co-located descriptor (<name>.service.json) + the <X>_BRIDGE_PORT in load-config.sh; install via the generators (the probe picks it up automatically from addon:); pm2 is dropped from this PR.
  • Missing docs / tests. No docs/features/<x>.md, no gate test. → Both are required, wired into mkdocs.yml / run.sh.
  • French in an English codebase. Stored vocabulary, prompts, enums, and UI labels in French. → ALL stored vocabulary, prompts, enums, and labels in English; bind to the VALID_* arrays in types.ts.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.