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
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- backup-recoverySkill
- body-mcp-setupSkill
- cos-setupSkill
- cos-upgradeSkill
- debug-cowork-mcp-issuesSkill
- fitness-mcp-setupSkill
- guard-setupSkill
- hub-handoverSkill
- mcp-bridge-setupSkill
- nutrition-mcp-setupSkill
- openwhispr-mcp-setupSkill
- setup-vaultSkill
- spoke-setupSkill
- voice-operationsSkill
- whatsapp-mcp-setupSkill
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
- Distinctive: line 16
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 …
- Very specific: line 21
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 …
- Very specific: line 25
add an /api/<x>/* route prefix that nothing in ADDON_REGISTRY claims → register it.
- Very specific: line 52
Writes close: every mutation calls assertAddonEnabled(db, id) inside mutate() → NotFoundError → 404 when disabled (atomic with the write, …
- Very specific: line 54
Reads stay open: every GET is ungated. Disabling freezes an add-on.
- Very specific: line 69
Add your owned array(s) as optional fields on DBShape (e.g.
- Very specific: line 82
Add one entry to board/lib/addons.ts (copy NUTRITION_ADDON).
- Very specific: line 86
Do not: add bespoke helpers; the four existing ones (listAddons, getAddon, isAddonEnabled, assertAddonEnabled) are the entire gate.
- Very specific: line 95
POST / PATCH / DELETE = gated: Do the read-modify-write inside mutate() and call assertAddonEnabled(db, "<id>") as the first line inside …
- Very specific: line 118
Create mcp/<name>-server/server.mjs using packages/mcp-kit (err, text, str, start, baseUrl, makeBoardApi) — copy …
- Very specific: line 133
Add the port to config/load-config.sh ONLY: a default : "${<NAME>_BRIDGE_PORT:=80NN}", the derived : …
- Very specific: line 164
Write the feature page under docs/features/<x>.md and add it to the nav: in mkdocs.yml (under features:, next to Nutrition & Chef).
- Very specific: line 177
Add all of them to tests/run.sh.
- Distinctive: line 181
When your add-on reads another add-on's data (e.g.
- Very specific: line 185
Reads stay open: Read the other add-on's array directly (db.foodLogs) and default with ??
- Very specific: line 254
Missing install path + smuggled pm2: No service descriptor / no <X>_BRIDGE_PORT, and a new
≈ “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.
Files
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.tsor a newboard/data/<x>.json→ the data belongs oncases.jsonviaDBShape, written through the existingmutate(). - 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 inADDON_REGISTRYclaims → register it. - mint a second persistence chokepoint, a second SSE channel, a second backup path → there
is exactly one of each, and riding
cases.jsongives 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 incases.json(board state, not config).isAddonEnabled(db, id)istrueonly when it is exactlytrue; absent === off. - Writes close: every mutation calls
assertAddonEnabled(db, id)insidemutate()→NotFoundError→ 404 when disabled (atomic with the write, closes the TOCTOU). - Reads stay open: every
GETis 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 (oneversionbump reaches every tab), free encrypted backup (the whole file is snapshotted), and free attribution (humanfrom the UI,agentfrom 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[], mirroringfoodLogs?). BumpSCHEMA_VERSION; the change is purely additive so old boards read unchanged. - A non-array singleton (a profile/goal object) is a bare field —
athleteProfile?mirrorsnutritionGoal?— and is deliberately NOT indataArrays(that list is arrays only). - Carry the new fields through
migration+validate+ensureFileand add typedgetX/setXstore helpers with stickycreatedAt(mirrorgetNutritionGoal/setNutritionGoal). - Define all vocabulary as
VALID_*arrays intypes.tsand 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 callassertAddonEnabled(db, "<id>")as the first line inside the lock (gate + id-mint + write are one critical section). Map thrown store errors withstoreErrorToResponse. - 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
fetchto your own/api/*. If two routes share logic, extract a function intoboard/lib/<x>.tsand call it in-process. - Zero
console.loginboard/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 inboard/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.shONLY: a default: "${<NAME>_BRIDGE_PORT:=80NN}", the derived: "${<NAME>_BRIDGE_URL:=http://localhost:$<NAME>_BRIDGE_PORT}", and both names on theexportline. Then mirror it intoconfig/cos.env.examplefor 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). Copymcp/nutrition-server/nutrition.service.jsonbeat for beat. Theaddon:"<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-caseanymore. - If your write tools need a machine-local secret (e.g. the vault's
ANTHROPIC_API_KEY; no add-on ships one today), addsecrets:["<TOKEN>"]+secretWrapper:"${REPO_ROOT}/mcp/<name>-server/launch.sh"to the descriptor and ship alaunch.sh(copymcp/vault-server/launch.sh) that sourcesconfig/secrets.envthenexec "$@"— 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 bygen-launchd.mjs; that is the only mechanism.
7. Skills — one setup skill + one operator skill
/<x>-mcp-setup(copynutrition-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— copytests/api-nutrition-gate.mjsexactly: snapshotcases.json, prove disabled → GET 200 but POST/PATCH/DELETE 404, enable bumpsdb.version, enabled → POST 201, unknown id → 404, non-booleanenabled→ 400; restore infinally.- 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. Reserverequired: truefor a future dependent that is genuinely useless alone.
Copy CHECKLIST — tick every box before the PR
- Owned array(s) on
DBShape(types.ts);SCHEMA_VERSIONbumped; migration + validate + ensureFile carry them. - Any singleton is a bare field with sticky-
createdAtgetX/setXhelpers; not indataArrays. - All vocabulary as
VALID_*arrays intypes.ts, imported by both route + UI; English only. - ONE
AddonManifestinADDON_REGISTRY; no new gate helpers. - GETs ungated; every write calls
assertAddonEnabledinsidemutate(). - Routes reuse
isISODate/resolveActor/storeErrorToResponse; no re-inline. - No loopback
fetchto own/api/*; shared logic inboard/lib/<x>.ts, in-process. - Zero
console.loginboard/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-kitfetch wrapper;{ actor: "agent" }on writes;npm installat root +package-lock.jsoncommitted. - ONE co-located descriptor
mcp/<name>-server/<name>.service.json(schemaVersion:1,addon:"<id>",portVar);<X>_BRIDGE_PORT(+ derived_URL) added toconfig/load-config.shand documented inconfig/cos.env.example; no committed plist template, noensure-bridges.shedit, no pm2;.mcp.jsonregenerated viagen-mcp-json.mjs(never hand-edited). /<x>-mcp-setup+ operator skill.docs/features/<x>.mdinmkdocs.yml;mkdocs build --strictclean.api-<x>-gate.mjs+ CRUD + unit tests, all inrun.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 whatcases.jsongives free and losing SSE + backup + attribution. → Fold ontoDBShape; retire the standalone store. (Repoint every@/lib/health-storeimport to@/lib/fitness.) - Unregistered feature. Pages + routes shipped with no
ADDON_REGISTRYentry, 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 insidemutate()). → Gate inside the lock. - Hardcoded nav. Links jammed into the core sidebar list, on for everyone. →
navItemsonly. - Split-brain taxonomy. The producer stored type
"hrv"but consumers queried"heart_rate_variability"; summarise/trends readdata.duration_min/data.avg_ms/data.bpm/data.countwhile the producer wrotedata.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 usedata.value, dayts) 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 toboard/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/sdkand 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-sideGET /api/fitness/training-plan|weekly-review|pre-workout-briefgenerate routes did.) → Delegate generation to the agent; expose a CRUD seam (POST /api/fitness/coaching+ thesave_*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.logof biometric data in API routes. → Zeroconsole.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
todaymisclassified 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_PORTinload-config.sh; install via the generators (the probe picks it up automatically fromaddon:); pm2 is dropped from this PR. - Missing docs / tests. No
docs/features/<x>.md, no gate test. → Both are required, wired intomkdocs.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 intypes.ts.
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
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.

