agentleFS
philipyazphilipyaz/cos/.claude/skills/cos-setup/SKILL.md

cos-setup

Skill4 starsChanged 4 months agoMITView on GitHub

The single first-run entry point that stands up the WHOLE Cos system, sequencing the four component setup skills in dependency order — setup-vault → guard-setup → mcp-bridge-setup → backup-recovery — then finishes with the automation step, installing the operator skill bundles into Cowork and creating the scheduled tasks the generated catalog lists. Use when setting up the chief of staff system, doing a first-run setup, onboarding a new machine, or asking for the full setup; also when you're unsure which component skill to run first and want the guided end-to-end runbook. Covers the three multi-device paths at Step 0.0 — a fresh hub, joining as a spoke (routes to spoke-setup), or promoting this machine to hub in a hub swap (routes to hub-handover).

  • Reads credentials
  • Installs packages
  • Sends data out

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every shell step below begins with the loader line source "$(git rev-parse --show-toplevel)/config/load-config.sh", which exports …

    line 18
  2. Distinctive:

    neither: place (no id AND never opened in Obsidian):

    line 246
  3. Distinctive:

    No license / can't gate? Use the heuristic-only preset (zero-dependency, no download, no token) — honest but degraded.

    line 265
  4. Very specific:

    Run from the repo root with the board dev app up (cd board && npm run dev, port $BOARD_PORT).

    line 483
  5. Very specific:

    Start each shell with source "$(git rev-parse --show-toplevel)/config/load-config.sh":

    line 484
  6. Distinctive:

    If all five pass, the Cos system is fully stood up: vault populated, guard classifying, all bridges live for Cowork + Claude Code, and the …

    line 510
  7. Distinctive:

    After setup, most of it runs itself — make sure the user knows how to live with it and how to check health:

    line 566
  8. Very specific:

    One-shot health check anytime: run mcp/ensure-bridges.sh directly — it is re-runnable and never stops anything, so it's the canonical "is …

    line 577

≈ “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

Cos — full first-run setup (orchestrator)

This is the root runbook that brings the whole system up on a fresh machine. It does not re-implement the component skills — it sequences them in the one order that works, because each step produces what the next one needs: the vault must exist before the MCP can point at it and before backup has something to protect; the guard model must be configured before the guard bridge can report a real classifier; all the bridges + sidecars must be wired before backup can snapshot live, populated stores. Run the four sub-skills in order, stop at each CHECKPOINT, and only advance when it passes. End with the § End-to-end verification, then finish with Step 5 — operator automation, which is what makes the system run itself.

Every shell step below begins with the loader line source "$(git rev-parse --show-toplevel)/config/load-config.sh", which exports $REPO_ROOT (git-derived), $BREW_PREFIX, $LAUNCH_AGENTS_DIR, $COWORK_CONFIG, $VAULT_DIR, $BOARD_URL, and the bridge/sidecar ports + URLs — use those instead of hardcoding paths, ports, or your username. The only value still derived inline is $U=$(id -u), which launchctl needs at runtime.

Prerequisites checklist (gather these BEFORE step 1)

  • node + npm (Homebrew) — bridges, vault Agent SDK, backup. node -v.
  • supergateway — npm install -g supergateway. The stdio→HTTP bridge for Claude Code.
  • uv (Homebrew: brew install uv) — runs the two Python sidecars (search :8008, guard :8009); self-provisions each venv on first launch.
  • hf CLI (pip install -U huggingface_hub / brew install huggingface-cli) + a Llama license — only if you want the real gated guard model (step 2). The heuristic-only fallback needs none of this.
  • ANTHROPIC_API_KEY (sk-ant-…) in config/secrets.env — the vault bridge embeds the Agent SDK and makes outbound Anthropic calls; it is the only bridge that needs a key, and the key goes in this one gitignored file (the launch wrapper loads it), never in the plist.
  • A PRIVATE GitHub backup repo + a recovery passphrase — step 4. Encrypted, off-site.

The whole system runs on these ports — keep them free (lsof -nP -iTCP:<port> -sTCP:LISTEN): 3000 board app · 8001 board · 8003 calendar · 8004 guard · 8005 vault (core bridges) · 8002 openwhispr · 8006 whatsapp · 8007 nutrition · 8011 fitness · 8012 body (optional add-on bridges) · 8008 search · 8009 guard · 8010 whatsapp-go (sidecars). The 8002 (openwhispr), 8006/8010 (WhatsApp), 8007 (Nutrition & Chef), 8011 (Fitness), and 8012 (Body) ports are only needed if you run those optional add-ons (Steps 3.4–3.8).


The sequence

Step 0.0 — first Cos machine, joining as a spoke, or taking over the hub role? (multi-device)

Only want to VIEW the board from another device? You need NOTHING on that device — no spoke, no runbook. Run the production board on the hub (cd board && npm run build && npm run start, or install the boardapp LaunchAgent — not next dev, whose on-demand compilation + lazy chunks are unreliable through a reverse proxy: the page loads but opening a case can silently fail) and expose it on the tailnet with tailscale serve --bg 3000 (needs Tailscale HTTPS/MagicDNS). The board is loopback-bound, so tailscale serve is the ONLY door in — and the URL is portless (HTTPS 443): any tailnet device opens https://<hub>.<tailnet>.ts.net in a browser and gets the full read/write UI (the browser writes through the same HTTP API). A spoke (below) is only for running Claude/Cowork agents on the second machine — never needed just to view.

Otherwise, decide the role of this machine — there are three setup paths:

  • First Cos machine (a fresh HUB) — this machine runs the state machine (board on :3000, its own cases.json, sidecars, backups, the Cowork routines) and there is no existing hub to inherit from. Continue with Step 0 below. COS_DEVICE_ROLE stays hub (the default). This is the path the rest of this runbook documents.
  • Joining an existing Cos (a SPOKE) — this machine is a stateless CLIENT of an existing hub: its board-facing MCP wrappers point at the hub's BOARD_URL, and it has no local store of its own. A spoke exists for one reason — to run Claude Code + Cowork agents against the hub through LOCAL stdio MCP tools. It is required because Cowork only accepts local stdio MCP servers; it can't consume the hub's remote HTTP MCP over the tailnet (a hard, validated fact), so a thin local shim forwarding tool calls to the hub's /api/* is the only way. If you just want to view the board here, stop — use a browser (top of this step); a browser can't give a local agent tools. Then SKIP Step 0 entirely (there is no local store to seed — the board-seed copy that follows is the documented seed-over-live-data footgun, and a spoke must never run it), skip the vault/guard-model steps and Step 4 (backup is hub-only), and run the spoke-setup skill instead — it flips COS_DEVICE_ROLE=spoke, points BOARD_URL at the hub, and wires only the board-facing wrappers. You get the hub's join string (cos-join://…) from the hub's board Devices panel ("Add a device") or node scripts/join-blob.mjs on the hub.
  • Joining but PROMOTING this machine to HUB (a hub swap) — an existing hub is stepping down and THIS machine becomes the new hub (the old one demotes to a spoke, or retires). This is neither a fresh first-run nor a plain spoke join, so do NOT run this runbook straight through — the data-safety is in the order of the swap. Run the hub-handover skill, which sequences the freeze → final-backup → cutover → demote ceremony and reuses this runbook's component steps with two deliberate substitutions:

    • Step 0's seed becomes a RESTORE. The new hub is hydrated from the old hub's newest encrypted snapshot (node "$REPO_ROOT/backup/restore.mjs" --device <old-hub-id> --apply, with no board running), never from the fixture — seeding would create a divergent empty store that the cutover re-restore only has to overwrite. (restore.mjs --list on this machine names <old-hub-id>.)
    • Step 4's backup PRODUCER role is DEFERRED to cutover. You still do Steps 0.5–3 (cos.env, vault, guard model, bridges) and provision the same recovery key as the old hub, but you do NOT install this machine's backup LaunchAgent until the handover cutover, where backup.mjs --claim takes the HUB.json lease. Two producers racing that lease is exactly what the ceremony exists to prevent — old hub off, new hub on, in that order.

    Prereqs (hub-handover enforces them): both machines on the same Tailscale tailnet, the same recovery key on both, and this machine's checkout at SCHEMA_VERSION ≥ the store's schema (the migration's safe direction — otherwise the board fails closed with SchemaAheadError after restore).

The rest of this runbook is the fresh HUB / first-machine path.

Step 0 — seed runtime stores (fresh public clone only)

  • What it does — a fresh clone of the public repo ships WITHOUT real runtime data (board/data/cases.json, config/settings.json, guard/data/*.json are gitignored). Seed the board + config once from the shipped synthetic counterparts so everything boots:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"; cd "$REPO_ROOT"
    cp tests/fixtures/board-seed.json board/data/cases.json   # board store — OR skip: the board
                                                              # auto-creates an EMPTY store if absent
    cp config/settings.example.json   config/settings.json    # then HAND-EDIT "principalEmail" to yours
    config/settings.json holds board/app prefs; you must set principalEmail by hand (the copy ships a placeholder — nothing auto-fills it). The next step (0.5) adds config/cos.env to the config/ picture: the machine-local paths/ports for the skills.
  • Skip on the private dev machine where the real stores already exist.
  • CHECKPOINT — config/settings.json exists with your principalEmail (and board/data/cases.json exists, or you accept an empty board that the app creates on first run).

Step 0.5 — generate config/cos.env (machine paths / ports for the skills)

  • What it does — writes config/cos.env, the machine-local public config every skill reads through the loader: the absolute Homebrew prefix, the node/uv/supergateway binary paths, the LaunchAgents + Cowork config locations, the OpenWhispr store paths, the backup repo, and all the ports (board :3000, bridges :8001–8005, sidecars :8008/:8009). It writes only these public values — no secrets. The config split is deliberate, four files under config/:
    • cos.env — machine paths + ports for the skills/setup (this step). Public, gitignored.
    • secrets.env — the ANTHROPIC_API_KEY (step 3). The loader does not source it; the vault bridge's own launch wrapper (launch.sh) does.
    • settings.json — board/app prefs incl. principalEmail (step 0).
    • auto-sync.json — the ingest router's auto-sync switch.
  • Idempotent — never overwrites an existing cos.env (delete the file to regenerate, e.g. if you changed machines and BREW_PREFIX moved). VAULT_NAME is left blank here — step 1 (setup-vault) fills it once your vault exists.
  • Why before the vault — from here on every shell step in this skill and the component skills begins with the loader line source "$(git rev-parse --show-toplevel)/config/load-config.sh", which sources this file and exports $REPO_ROOT, $BREW_PREFIX, $LAUNCH_AGENTS_DIR, $COWORK_CONFIG, $OPENWHISPR_DB, $VAULT_DIR, $BOARD_URL, the bridge/sidecar ports + URLs, etc. ($REPO_ROOT is git-derived, never stored in the file.) Generate it first so every step downstream resolves to your machine's real values.
  • Run (the heredoc body must stay flush-left — <<EOF preserves leading whitespace, so do not indent these lines or cos.env would gain stray spaces):
# --- Step 0.5 · Generate config/cos.env (machine paths / ports for skills) ---
# Idempotent: never overwrites an existing cos.env (delete the file to regenerate).
source "$(git rev-parse --show-toplevel)/config/load-config.sh"   # sets $REPO_ROOT, $BREW_PREFIX, $HOME defaults
cd "$REPO_ROOT"
if [ -f config/cos.env ]; then
  echo "config/cos.env exists — leaving it untouched (delete it to regenerate). Current values:"
  grep -E '^[A-Z]' config/cos.env
  [ -d "$BREW_PREFIX" ] || echo "WARNING: BREW_PREFIX '$BREW_PREFIX' not found — changed machines? delete config/cos.env and re-run."
else
  tmp="$(mktemp)"
  # Locate Claude Cowork Desktop's config file PER OS, and VERIFY its directory exists (= Cowork is
  # installed there). Don't just assume the macOS path: on Windows it lives under %APPDATA%. If the
  # dir is missing, keep the best-guess default but WARN — you MUST point COWORK_CONFIG at the real
  # file before mcp-bridge-setup's Cowork step writes to it (gen-cowork-config.mjs will refuse a
  # nonexistent dir). When in doubt, find it: `ls -d ~/Library/Application\ Support/Claude` (macOS) /
  # `ls "$APPDATA/Claude"` (Windows Git Bash).
  case "$(uname -s)" in
    Darwin)              COWORK_CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json" ;;
    MINGW* | MSYS* | CYGWIN*) COWORK_CONFIG="${APPDATA:-$HOME/AppData/Roaming}/Claude/claude_desktop_config.json" ;;
    *)                   COWORK_CONFIG="$HOME/.config/Claude/claude_desktop_config.json" ;;
  esac
  [ -d "$(dirname "$COWORK_CONFIG")" ] || echo "WARNING: Cowork config dir '$(dirname "$COWORK_CONFIG")' not found — is Claude Cowork Desktop installed? If it lives elsewhere, set COWORK_CONFIG in config/cos.env to the real path before running mcp-bridge-setup."
  cat > "$tmp" <<EOF
# Cos — machine-local PUBLIC config (paths/ports for SKILLS + SETUP).
# Generated by cos-setup. Safe to edit. NO SECRETS (those live in config/secrets.env).
# Skills read this via: source "\$(git rev-parse --show-toplevel)/config/load-config.sh"
# ALWAYS QUOTE values (paths contain spaces). REPO_ROOT is git-derived, never stored here.
BREW_PREFIX="$BREW_PREFIX"
NODE_BIN="$BREW_PREFIX/bin/node"
UV_BIN="$BREW_PREFIX/bin/uv"
SUPERGATEWAY_BIN="$BREW_PREFIX/bin/supergateway"
LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
COWORK_CONFIG="$COWORK_CONFIG"
# OpenWhispr voice add-on (optional; wired by openwhispr-mcp-setup) — paths to the desktop app's store.
OPENWHISPR_DB="$HOME/Library/Application Support/open-whispr/transcriptions.db"
OPENWHISPR_AUDIO_DIR="$HOME/Library/Application Support/open-whispr/audio"
BACKUP_REPO="$HOME/.cos-backups"
VAULT_NAME=""
BOARD_PORT="3000"
BOARD_BRIDGE_PORT="8001"
OPENWHISPR_BRIDGE_PORT="8002"
CALENDAR_BRIDGE_PORT="8003"
GUARD_BRIDGE_PORT="8004"
VAULT_BRIDGE_PORT="8005"
SEARCH_SIDECAR_PORT="8008"
GUARD_SIDECAR_PORT="8009"
# WhatsApp MCP add-on (optional; wired by whatsapp-mcp-setup). WHATSAPP_GO_PORT is the Go
# whatsmeow bridge sidecar (8010; whatsmeow's default 8080 is usually taken).
WHATSAPP_MCP_DIR="$HOME/Code/whatsapp-mcp"
WHATSAPP_MCP_BRIDGE_PORT="8006"
WHATSAPP_GO_PORT="8010"
# Nutrition & Chef add-on (optional; built-in in-repo mcp/nutrition-server, wired by
# nutrition-mcp-setup). NUTRITION_BRIDGE_PORT is the supergateway HTTP bridge for Claude Code;
# the add-on is gated per-board via Settings.addons, so naming the port only documents it.
NUTRITION_BRIDGE_PORT="8007"
# Fitness + Body add-ons (optional; in-repo mcp/fitness-server + mcp/body-server, wired by
# fitness-mcp-setup / body-mcp-setup — Steps 3.7 / 3.8). Same "documents the port" role as above.
FITNESS_BRIDGE_PORT="8011"
BODY_BRIDGE_PORT="8012"
EOF
  mv "$tmp" config/cos.env
  echo "Wrote config/cos.env — review it, then continue. setup-vault (Step 1) fills VAULT_NAME."
fi
  • CHECKPOINT — config/cos.env exists, lists your real BREW_PREFIX, and sourcing the loader exports the vars:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    echo "$REPO_ROOT $BREW_PREFIX $LAUNCH_AGENTS_DIR"   # all three populated for your machine

Step 1 — setup-vault (FIRST: create the knowledge target)

  • What it does — creates a private vault instance from the committed template $REPO_ROOT/vault/example-vault/ (cp -R vault/example-vault vault/<name>), records the slug as VAULT_NAME in config/cos.env (the loader derives $VAULT_DIR from it, and the vault plist's COS_VAULT_DIR regenerates from that via scripts/gen-launchd.mjs when step 3 installs it), registers it with Obsidian and records its unique vault ID in config/settings.json (so the board's obsidian:// deep-links open THIS in-repo vault, not a same-named copy elsewhere — STEP 3.5 of setup-vault), folds it into the backup SCOPE (auto-derived from VAULT_NAME in backup/config.mjs — no hand-edit), and confirms it is gitignored (the real vault holds PII and is NOT git-backed — its durability comes from step 4's encrypted off-site backup; only example-vault is tracked).
  • Why FIRST — the MCP needs a target to scope COS_VAULT_DIR to, and backup needs something to protect. Nothing downstream works without the vault directory existing.
  • Prereq — the committed template $REPO_ROOT/vault/example-vault/ is present (it ships with the repo). Confirm: ls "$REPO_ROOT/vault/example-vault/".
  • Run — invoke /setup-vault (or follow its steps): cp -R vault/example-vault vault/<name>, record VAULT_NAME="<name>" in config/cos.env (backup SCOPE then auto-derives from it; the vault plist's COS_VAULT_DIR regenerates from $VAULT_DIR when step 3 installs the bridge).
  • CHECKPOINT — all three must hold before step 2 (VAULT_DIR resolves to $REPO_ROOT/vault/$VAULT_NAME once setup-vault has set VAULT_NAME in cos.env):
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    ls "$VAULT_DIR" >/dev/null && echo "vault dir OK"
    git -C "$REPO_ROOT" check-ignore "vault/$VAULT_NAME" && echo "gitignored OK"   # prints the path = ignored
    grep -q "vault/$VAULT_NAME" "$REPO_ROOT/backup/config.mjs" && echo "in backup SCOPE OK"
    Plus, for board deep-links to open the right vault: config/settings.json may carry a 16-char obsidianVaultId (setup-vault STEP 3.5). A blank id is non-fatal and now self-heals — the board reads the id through from Obsidian's own registry (vault-config.ts realpath-matches obsidian.json) the moment the vault has been Open-folder-as-vault'd, so the ↗ deep-link and the /vault "Registered with Obsidian" check light up on the next Refresh without re-running anything; the in-app vault preview works regardless. So only flag the case where the vault is in neither place (no id AND never opened in Obsidian):
    grep -o '"obsidianVaultId": *"[0-9a-f]\{16\}"' "$REPO_ROOT/config/settings.json" && echo "obsidianVaultId OK" \
      || echo "note: no obsidianVaultId in settings.json — fine IF you've opened vault/$VAULT_NAME in Obsidian (the board self-detects it); otherwise do File → Open Vault → Open folder as vault to enable the ↗ deep-link"

Step 2 — guard-setup (the prompt-injection classifier model)

  • What it does — configures the guard classifier model the sidecar (guard/sidecar.py, :8009) runs: picks a preset (default the gated Meta Llama-Prompt-Guard-2-86M), accepts the Llama license + authenticates with hf, prefetches the model, sets COS_GUARD_MODEL/COS_GUARD_THRESHOLD/COS_GUARD_CLASSIFIER in config/cos.env, installs the guardsvc launchd plist (generated from guard/guardsvc.service.json by scripts/gen-launchd.mjs — see mcp/CLAUDE.md), and verifies the sidecar reports the real model, not the heuristic-fallback. (The guard MCP bridge on :8004 is wired in step 3 — this step is just the model + :8009 sidecar.)
  • Why now (before the bridges) — wiring the guard bridge is pointless until the sidecar behind it reports a real classifier; do the model first so step 3's :8004 check is meaningful. Guard is OFF by default and the board's /security toggle stays gated until the model's deps are ready.
  • Prereq — uv, the hf CLI, and an accepted Llama license for the gated default. No license / can't gate? Use the heuristic-only preset (zero-dependency, no download, no token) — honest but degraded; you can upgrade to the model later.
  • Run — invoke /guard-setup (or follow its steps: hf auth login → hf download meta-llama/Llama-Prompt-Guard-2-86M → uv sync --directory "$REPO_ROOT/guard" --extra model → set COS_GUARD_MODEL/COS_GUARD_THRESHOLD in config/cos.env → node "$REPO_ROOT/scripts/gen-launchd.mjs" --install guardsvc).
  • CHECKPOINT — the sidecar is up and reports the real model (not the heuristic):
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    curl -s "$GUARD_SIDECAR_URL/healthz"
    # {"ok":true,"classifier":"model:meta-llama/Llama-Prompt-Guard-2-86M",...}
    classifier must read model:… (or, deliberately, heuristic-fallback if you chose the heuristic-only preset). A silent heuristic-fallback when you wanted the model = not done — see guard-setup → Troubleshooting (force COS_GUARD_CLASSIFIER=promptguard to surface the cause).

Step 3 — mcp-bridge-setup (wire the CORE servers + sidecars)

  • What it does — wires the four core stdio MCP servers (board, calendar, guard, vault) into both clients: Cowork spawns them directly as stdio command entries in claude_desktop_config.json; Claude Code reaches them over HTTP via $REPO_ROOT/.mcp.json, each a supergateway + launchd bridge on 8001/8003/8004/8005. Also loads the two uv sidecars — search :8008 and guard :8009 — and mcp/ensure-bridges.sh (chained into board's dev/start) so the app brings the bridges up. (The optional openwhispr voice server on :8002 is wired by Step 3.4's add-on skill, not here.)
  • The vault bridge is special — :8005, launchd label com.chiefofstaff.mcp-vault. Unlike the other four it embeds the Agent SDK and makes outbound Anthropic calls, so it needs an ANTHROPIC_API_KEY. The key is NOT in the plist: the plist's ProgramArguments runs the launch wrapper mcp/vault-server/launch.sh, which sources the gitignored config/secrets.env (copied from config/secrets.env.example) and exports the key before exec'ing supergateway — so the secret lives in one machine-local file, never in the installed plist or a committed file. COS_VAULT_DIR (= $VAULT_DIR, i.e. $REPO_ROOT/vault/$VAULT_NAME) IS set in the installed plist (EnvironmentVariables) and the Cowork config; the plist is generated from mcp/vault-server/vault.service.json by scripts/gen-launchd.mjs (it resolves $REPO_ROOT / $VAULT_DIR from config/load-config.sh — see mcp/CLAUDE.md; the API key has no placeholder, it stays in config/secrets.env). Restart it after editing the key (rotating the key needs only this restart, no plist regen):
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"; U=$(id -u)
    launchctl bootout   gui/$U/com.chiefofstaff.mcp-vault 2>/dev/null || true
    launchctl bootstrap gui/$U "$LAUNCH_AGENTS_DIR/com.chiefofstaff.mcp-vault.plist"
    launchctl kickstart -k gui/$U/com.chiefofstaff.mcp-vault
  • Prereq — node + supergateway; the vault from step 1 (the bridge's COS_VAULT_DIR target); the guard model from step 2 (so :8004 reports the real classifier); an ANTHROPIC_API_KEY in config/secrets.env (cp config/secrets.env.example config/secrets.env, then edit in the sk-ant-… key) for the vault bridge.
  • Run — invoke /mcp-bridge-setup (or follow its steps: node "$REPO_ROOT/scripts/gen-launchd.mjs" --install renders + loads the core plists — board/calendar/guard/vault bridges on 8001/8003/8004/8005 plus the search + guardsvc sidecars; node "$REPO_ROOT/scripts/gen-mcp-json.mjs" regenerates the Claude Code .mcp.json; node "$REPO_ROOT/scripts/gen-cowork-config.mjs" board calendar guard vault merges the Cowork stdio entries; mcp/ensure-bridges.sh).
  • CHECKPOINT — all four core bridges answer an MCP initialize, and the vault one is scoped:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"; U=$(id -u)
    launchctl list | grep chiefofstaff      # PIDs present, exit 0
    for p in "$BOARD_BRIDGE_PORT" "$CALENDAR_BRIDGE_PORT" "$GUARD_BRIDGE_PORT" "$VAULT_BRIDGE_PORT"; do
      curl -s -X POST "http://127.0.0.1:$p/mcp" \
        -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
        -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \
        | grep -o '"name":"[a-z]*"' | head -1
    done
    # expect: board / calendar / guard / vault
    The vault server's ready line ($REPO_ROOT/mcp/logs/vault.out.log) must echo your COS_VAULT_DIR (= $VAULT_DIR). serverInfo.name=="vault" confirms the vault bridge ($VAULT_BRIDGE_PORT).

Step 3.4 — openwhispr-mcp-setup (OPTIONAL: the voice-notes add-on)

  • What it does — wires the openwhispr voice server (a Node stdio MCP fronted by a supergateway + launchd bridge on :8002, plus a direct Cowork stdio entry) so /voice-operations and /second-brain-ingest can read your OpenWhispr transcripts and route them onto the board / vault. Entirely optional: skip it if you don't use the OpenWhispr desktop app.
  • Why HERE (after the core bridges) — it reuses the same supergateway/launchd/ensure-bridges.sh machinery Step 3 set up, and routing voice notes depends on the board + vault MCPs already being live (Steps 1–3). Its only external state is the app's own store, so its position relative to Step 4 doesn't matter.
  • Prereq — node + supergateway (from Step 3) and the OpenWhispr desktop app installed with at least one recorded note (so $OPENWHISPR_DB exists). No app yet? Skip this step, or wire it against the bundled fixtures for a dry run (see the skill).
  • Run — invoke /openwhispr-mcp-setup (confirm the store → install the :8002 bridge plist → register both clients → wire ensure-bridges.sh → verify list_transcripts reports Source: sqlite).
  • CHECKPOINT — the openwhispr MCP answers and reads the real store:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    curl -s -X POST "$OPENWHISPR_BRIDGE_URL/mcp" \
      -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \
      | grep -o '"name":"openwhispr"' && echo "openwhispr MCP OK"

Step 3.5 — whatsapp-mcp-setup (OPTIONAL: the WhatsApp add-on)

  • What it does — stands up the external whatsapp-mcp repo (the Go whatsmeow bridge as a launchd SIDECAR on :8010, the Python stdio MCP as a supergateway BRIDGE on :8006), does the one-time QR pairing against your phone, and registers whatsapp in .mcp.json + the Cowork config — so the /whatsapp-triage skill can reconcile WhatsApp onto the board exactly like /mail-to-board does Gmail. Entirely optional: skip it if you don't want WhatsApp on the board.
  • Why HERE (after the bridges) — it reuses the same supergateway/launchd/ensure-bridges.sh machinery Step 3 set up, and /whatsapp-triage depends on the board + guard MCPs already being live (Steps 2–3). Its external store/ is not covered by Step 4's backup (that protects the Cos repo's own stores), so its position relative to Step 4 doesn't matter.
  • Prereq — go (builds the bridge), uv, supergateway, the whatsapp-mcp checkout at $WHATSAPP_MCP_DIR, and a phone running WhatsApp for the QR pairing.
  • Run — invoke /whatsapp-mcp-setup (clone/build → QR pair → install both LaunchAgents → register both clients → wire ensure-bridges.sh → verify list_chats).
  • CHECKPOINT — the whatsapp MCP answers and returns chat data:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    curl -s -X POST "$WHATSAPP_MCP_BRIDGE_URL/mcp" \
      -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \
      | grep -o '"name":"whatsapp"' && echo "whatsapp MCP OK"

Step 3.6 — nutrition-mcp-setup (OPTIONAL: the Nutrition & Chef add-on)

  • What it does — wires the built-in nutrition add-on MCP (a thin in-repo Node fetch wrapper over the board's /api/nutrition/* routes, fronted by a supergateway + launchd bridge on :8007, plus a direct Cowork stdio entry), then ENABLES the add-on (Settings.addons.nutrition.enabled) so its food-log / pantry / meal-plan writes land and the three /nutrition/* nav pages appear — so the /nutrition-chef operator skill can log meals, track the pantry, and plan a week. Entirely optional and the SIMPLEST add-on (no sidecar, no external repo, no secret); skip it if you don't want nutrition on the board. Enabling nutrition also hard auto-enables the foundational body add-on (dependsOn in board/lib/addons.ts; the cascade in /api/addons/[id]) — Step 3.8 wires the body MCP that just came on.
  • Why HERE (after the core bridges) — it reuses the same supergateway/launchd/ensure-bridges.sh machinery Step 3 set up, and it is a pure wrapper over the board API (Steps 1–3 must be live). Its data rides cases.json, so it is covered by Step 4's backup automatically — but its position relative to Step 4 doesn't matter.
  • Prereq — node + supergateway (from Step 3) and the board reachable on CRM_BASE_URL. There is nothing external to install, clone, build, pair, or authenticate.
  • Run — invoke /nutrition-mcp-setup (confirm NUTRITION_BRIDGE_PORT=8007 → install the :8007 bridge plist → register both clients → ENABLE the add-on → verify a log_food write round-trips).
  • CHECKPOINT — the nutrition MCP answers and the add-on is enabled:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    curl -s -X POST "$NUTRITION_BRIDGE_URL/mcp" \
      -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \
      | grep -o '"name":"nutrition"' && echo "nutrition MCP OK"
    curl -s "$BOARD_URL/api/addons" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const a=JSON.parse(s).addons.find(x=>x.id==="nutrition");process.exit(a&&a.enabled===true?0:1)})' && echo "add-on enabled"

Step 3.7 — fitness-mcp-setup (OPTIONAL: the Fitness add-on)

  • What it does — wires the built-in fitness add-on MCP (a thin in-repo Node fetch wrapper over the board's /api/fitness/* routes, fronted by a supergateway + launchd bridge on :8011 / $FITNESS_BRIDGE_PORT, plus a direct Cowork stdio entry), then ENABLES the add-on (Settings.addons.fitness.enabled) so its writes land and the /fitness + /fitness/* nav pages appear — so the 7-skill fitness operator family (/fitness-coach, /fitness-training-plan, …) can drive it. Enabling fitness also hard auto-enables the foundational body add-on (dependsOn in board/lib/addons.ts) — Step 3.8 wires the body MCP that just came on. Entirely optional; skip it if you don't want fitness on the board.
  • Why HERE (after the core bridges) — it reuses the same supergateway/launchd/ensure-bridges.sh machinery Step 3 set up, and it is a pure wrapper over the board API (Steps 1–3 must be live). Its data rides cases.json, so it is covered by Step 4's backup automatically.
  • Prereq — node + supergateway (from Step 3) and the board reachable on CRM_BASE_URL. The loader seeds FITNESS_BRIDGE_PORT=8011 when cos.env lacks it — no cos.env edit needed.
  • Run — invoke /fitness-mcp-setup (confirm the port → verify the stdio server → the .mcp.json entry → install the :8011 bridge → register Cowork → ENABLE the add-on → verify a round-trip — its §1–§7).
  • CHECKPOINT — mirror 3.6's: the fitness MCP answers and the add-on is enabled:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    curl -s -X POST "$FITNESS_BRIDGE_URL/mcp" \
      -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \
      | grep -o '"name":"fitness"' && echo "fitness MCP OK"
    curl -s "$BOARD_URL/api/addons" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const a=JSON.parse(s).addons.find(x=>x.id==="fitness");process.exit(a&&a.enabled===true?0:1)})' && echo "add-on enabled"

Step 3.8 — body-mcp-setup (CONDITIONAL: the foundational Body add-on — REQUIRED after 3.6 or 3.7)

  • What it does — wires the built-in body add-on MCP (a thin in-repo Node fetch wrapper over the board's /api/body/* routes, fronted by a supergateway + launchd bridge on :8012 / $BODY_BRIDGE_PORT, plus a direct Cowork stdio entry). body is the single owner of body identity, the weight + body-composition series, and the free-text objective that Nutrition and Fitness both read.
  • Why this step is REQUIRED if you ran 3.6 or 3.7 — enabling nutrition or fitness already auto-enabled body (the hard-dependency cascade in /api/addons/[id]), so the /body nav and /api/body prefix are live NOW — but until this step runs, that surface has no agent access, and no other skill wires it. This is the exact invisible step cos-ops#35 closes. Skip only if you skipped BOTH 3.6 and 3.7. Running body standalone (weight tracking alone, with neither nutrition nor fitness) is also legitimate — see the skill's §6 to enable it directly.
  • Run — invoke /body-mcp-setup (same §1–§7 flow as 3.6/3.7; its §6 confirms the auto-enable rather than flipping it).
  • CHECKPOINT — the body MCP answers and the add-on is enabled:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"
    curl -s -X POST "$BODY_BRIDGE_URL/mcp" \
      -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \
      | grep -o '"name":"body"' && echo "body MCP OK"
    curl -s "$BOARD_URL/api/addons" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const a=JSON.parse(s).addons.find(x=>x.id==="body");process.exit(a&&a.enabled===true?0:1)})' && echo "add-on enabled"

Step 4 — backup-recovery (LAST: protect the now-populated stores)

  • What it does — stands up daily AES-256-GCM-encrypted, off-site snapshots of the live stores (board board/data/, guard guard/data/, config/, and the vault) to a private GitHub repo, with the recovery key in the macOS Keychain (cos-backup-key) + an offline copy.
  • Why LAST — backup snapshots the populated stores; running it before the vault exists and the bridges are wired would back up an empty/partial system. The backup SCOPE already covers the active vault — it auto-derives from the VAULT_NAME you recorded in step 1.
  • Prereq — a private GitHub backup repo (e.g. gh repo create cos-backups --private) and a recovery passphrase stored in the macOS Keychain as cos-backup-key (plus a password-manager copy — it is unrecoverable). The backup LaunchAgent (com.chiefofstaff.backup, daily 03:30) reads backup/config.mjs at run time, so SCOPE edits need no restart.
  • Run — invoke /backup-recovery (§1 Setup: generate + store the key, create + clone the repo, first backup + verify, install the daily LaunchAgent).
  • CHECKPOINT — the key exists and a backup verifies end-to-end:
    source "$(git rev-parse --show-toplevel)/config/load-config.sh"; cd "$REPO_ROOT"
    security find-generic-password -s cos-backup-key -w >/dev/null 2>&1 && echo "key OK"
    node backup/backup.mjs && node backup/restore.mjs   # backup, then DRY-RUN verify (no writes)
    # → auth tag OK ✓ / sha256 OK ✓ / JSON-verified ✓ ; and "vault/$VAULT_NAME" appears in the manifest

End-to-end verification (the whole system, after all four steps)

Run from the repo root with the board dev app up (cd board && npm run dev, port $BOARD_PORT). Start each shell with source "$(git rev-parse --show-toplevel)/config/load-config.sh":

  1. All four core bridges answer (the step-3 loop) → board / calendar / guard / vault (plus openwhispr on :8002, whatsapp on :8006, nutrition on :8007, fitness on :8011, and/or body on :8012 if you ran the Step 3.4–3.8 add-ons). launchctl list | grep chiefofstaff shows each with exit 0.
  2. Guard sidecar healthy — curl -s "$GUARD_SIDECAR_URL/healthz" → {"ok":true, "classifier":"model:…"} (or the deliberate heuristic-fallback). The search sidecar is best-effort: curl -s "$SEARCH_SIDECAR_URL/healthz" → {"ok":true} (a cold/absent one just degrades the board to keyword search — not a failure).
  3. A test vault ingest + query round-trips — drop a throwaway note into the vault and read it back through the vault MCP ($VAULT_BRIDGE_URL); the inner Agent SDK session is scoped to your COS_VAULT_DIR (= $VAULT_DIR), so it must find what you just wrote and return it. (Equivalently, use /second-brain-ingest then /second-brain-query.) Remove the throwaway note after.
  4. A backup dry-run verifies — node backup/backup.mjs && node backup/restore.mjs → auth tag OK ✓ / sha256 OK ✓ / JSON-verified ✓, with vault/$VAULT_NAME present in the manifest.
  5. The Cowork config is actually wired (don't just assume it — it's the one client whose file is off-repo at $COWORK_CONFIG): the file exists, parses, and lists the core stdio servers.
    node -e 'const fs=require("fs"),p=process.env.COWORK_CONFIG;let c;try{c=JSON.parse(fs.readFileSync(p,"utf8"))}catch(e){console.log("FAIL: Cowork config missing/invalid at "+p+" — set COWORK_CONFIG in cos.env + re-run /mcp-bridge-setup §5");process.exit(1)}const m=c.mcpServers||{},miss=["board","calendar","guard","vault"].filter(n=>!m[n]);console.log(miss.length?"FAIL: missing from Cowork config: "+miss.join(", ")+" — re-run /mcp-bridge-setup §5":"OK: Cowork config lists "+Object.keys(m).join(", "))'
    (Cowork only reads it at launch — the next section is the one-time UI activation; this just proves the file is on disk and correct first.)

If all five pass, the Cos system is fully stood up: vault populated, guard classifying, all bridges live for Cowork + Claude Code, and the live data under encrypted off-site backup. Tell the user so, then hand off with the first-open and Day-to-day notes below.

First open in Claude Cowork — confirm the connectors + allow their tools

The config is wired, but Cowork reads claude_desktop_config.json only at launch and gates tool calls behind a permission prompt. Walk the user through the one-time activation:

  1. Quit + reopen Cowork (⌘Q) so it re-reads the config.
  2. Settings → Connectors — confirm the local MCP servers (board, calendar, guard, vault, plus openwhispr/whatsapp/nutrition/fitness/body if added) are listed and enabled. They run as local stdio command servers (not custom HTTP connectors), so they appear automatically once the config is read — if they don't, it didn't parse: re-check §5 of /mcp-bridge-setup.
  3. Allow their tools — the first time an agent calls a server's tool, Cowork asks for permission; choose "Always allow" per server so routine agent runs aren't interrupted by a prompt every call (or approve per-tool if you prefer — "Always allow" is the smooth default for your own local servers).

(Claude Code uses the HTTP bridges via .mcp.json and skips this — the connector-approval step is Cowork-only.)

Step 5 — operator automation (install the skill bundles, then schedule the sweeps)

  • What it does — installs every operator skill bundle in $REPO_ROOT/board/.claude/skill-bundles/ into Cowork, then creates a Cowork Scheduled Task for each scheduled row of the generated catalog in board/.claude/skills/README.md (built from board/.claude/skills/automation.json) — pasting that row's trigger line at its suggested cadence.
  • Why every bundle, not just the scheduled ones — a called skill (vault-operations) is invoked by other skills mid-run, and in Cowork a delegation to a skill that is not installed is a silent no-op, not an error — the class of bug that left the vault unfed for weeks with nothing in any log to say so (ADR 0015). Installing every bundle costs one extra upload per skill and closes that failure mode structurally.
  • Why LAST — it needs Cowork open with its connectors allowed (the previous section), and it is the step that turns "the board can do this" into "the board actually does this on its own" — the automation Philip asked for is exactly this catalog, instantiated.
  • Run:
    1. Cowork Desktop → Settings → Capabilities → Skills → Upload skill, once per .zip in $REPO_ROOT/board/.claude/skill-bundles/.
    2. Record the upload receipt — node scripts/mark-skill-uploaded.mjs --all (any shell at $REPO_ROOT; the script needs no env — it resolves the repo from its own location). This is what makes the next /cos-upgrade's bundle list exact — every zip whose bytes differ from what THIS machine last uploaded — instead of a git-range guess (scripts/upgrade-check.mjs item 10 reads it).
    3. Cowork Desktop → Scheduled Tasks → new task, one per row of the scheduled table in board/.claude/skills/README.md — paste that row's trigger, and pick a cadence (the table's column is a suggestion; the schedule is yours to set and adjust — see docs/architecture/ triage-skills.md).
  • CHECKPOINT — manual, and honest about it: nothing on this machine can read Cowork's installed state back (ADR 0020's standing consequence), so this is a look, not a curl. In Cowork Desktop → Settings → Capabilities → Skills, every bundle you uploaded is listed; in Scheduled Tasks, every task you chose to create is listed, at the cadence you picked. The receipt is the machine-readable half: node scripts/mark-skill-uploaded.mjs --list shows every bundle up to date (marked …) — your own statement of what you uploaded (it reads nothing back from Cowork), and the input the next upgrade's exact drift list is computed from.

Day-to-day: running Cos in later sessions

After setup, most of it runs itself — make sure the user knows how to live with it and how to check health:

  • The bridges + sidecars are launchd-managed. The core four (board, calendar, guard, vault), the search/guardsvc uv sidecars, and any optional add-ons you wired (openwhispr/whatsapp/nutrition/fitness/body) start at login and crash-restart on their own (KeepAlive). A normal next session needs no action — Cowork and Claude Code reach them through the bridges whether or not the board dev app is running.
  • Starting the board self-heals them. cd board && npm run dev (or npm run start) runs mcp/ensure-bridges.sh first, which bootstraps + kickstarts every service and prints one line each ([mcp] vault bridge up on :$VAULT_BRIDGE_PORT … or WARN: <name> bridge DOWN on :<port> — see mcp/logs/<name>.err.log). Reading that startup block IS the fastest health check.
  • One-shot health check anytime: run mcp/ensure-bridges.sh directly — it is re-runnable and never stops anything, so it's the canonical "is everything up?" probe. Backstops: launchctl list | grep chiefofstaff (each agent + last exit code; 0 = clean) and curl -s "$GUARD_SIDECAR_URL/healthz" / curl -s "$SEARCH_SIDECAR_URL/healthz" for the sidecars.
  • In-app health surfaces: /security (guard model, deps, master toggle), /backups (last snapshot + recovery-key readiness), /vault (vault wiring + Obsidian deep-link).
  • When a client can't see a server: re-run mcp/ensure-bridges.sh; if it's still missing, re-run /mcp-bridge-setup. Per-service logs for any WARN/DOWN live in mcp/logs/<name>.{err,out}.log.
  • Pulling an update later is a different skill: /cos-upgrade. A git pull migrates the store on the next board start and nothing else — the production board, the launchd bridges, the Cowork bundles and scheduled tasks keep running the old version silently. /cos-upgrade backs up, pulls, runs node scripts/upgrade-check.mjs (the diff → the ordered checklist), applies the automatable steps, and hands you the manual residue. Never re-run cos-setup to upgrade.
  • The two standing gestures: Guard ships OFF — flip it ON in /security once its model deps are ready (or deliberately leave it OFF; see /guard-setup). Backups then run nightly at 03:30 on their own once /backup-recovery is set up.

If something fails

Each component skill owns its own troubleshooting — jump straight there: /setup-vault (template/gitignore/SCOPE), /guard-setup (GatedRepoError, silent heuristic fallback, cold sidecar), /mcp-bridge-setup (the node/simdjson + pm2 gotchas, a bridge DOWN, Cowork can't see a server), /backup-recovery (bad magic / auth-tag throw / sha256 mismatch on restore). Re-run only the failing step, re-check its CHECKPOINT, then resume the sequence.

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.