**Phase:** 1 (Independent Draft) **Agent:** listener (RESPAWN)
---
### A1. Anthropic Skills (the marketplace) **Substrate:** Plugin marketplaces — a `marketplace.json` manifest hosted in a GitHub/GitLab repo that lists plugins (each containing skills) and where to fetch them. Users run `/plugin marketplace add <repo>` then `/plugin install <name>`. As of Dec 2025 the Agent Skills spec is an open standard adopted by OpenAI's Codex CLI and ChatGPT — same `SKILL.md` + frontmatter format. **Push or pull:** Pull-only. The CLI fetches when the user runs `/plugin install` or `/plugin update`. There is no hosted broadcast API — Anthropic's own `anthropics/skills` repo is just a public Git repo. **Conflict handling:** None native — last-installed wins. Skills are filesystem objects under `~/.claude/skills/` (or plugin directories); collisions resolve at the filename level by clobber. **The trick we're missing:** Anthropic ships the *spec* and a Git-fetcher; they explicitly leave distribution-as-a-service to the operator. That confirms our approach (GitHub + LaunchAgent receiver) is on-paradigm — we're not fighting the platform, we're filling the gap Anthropic intentionally left. The marketplace.json manifest is also the right shape for our private fan-out: one JSON file per machine declaring which skills + which versions, fetched by a receiver. Source: https://code.claude.com/docs/en/plugin-marketplaces , https://github.com/anthropics/skills
### A2. Cursor / .cursorrules + .mdc team templates **Substrate:** `.cursor/rules/*.mdc` files committed to the project repo. Cursor 2.2 deprecated the legacy `.cursorrules` flat file in favor of per-rule MDC folders. Team/Enterprise plans add a *dashboard-pushed* layer: admins author rules in the Cursor web UI and they propagate to every team member's IDE, with a "required" flag the admin can toggle. **Push or pull:** Hybrid. Project rules = pull (git clone/pull). Team rules = push from Cursor's hosted dashboard down to the IDE on next sync. Global `~/.cursor/rules/` is per-developer and explicitly warned as drift-prone. **Conflict handling:** Layered precedence — Team Rules > Project Rules > Global Rules. The IDE merges; same-name collisions take the higher-tier one. No three-way merge, just precedence ordering. **The trick we're missing:** The two-layer split (Team-pushed vs Project-committed vs Personal-global) is exactly the *scope* answer for §B3. Cursor enforces it at the loader, not the sync layer — meaning the sync layer can be dumb if the loader knows which directory wins. Also: Cursor explicitly tells teams "global rules drift silently — don't put architecture there." That's the warning we should mirror about `~/.claude/skills/private/`. Source: https://cursor.com/docs/rules , https://dev.to/olivia_craft/cursor-rules-for-teams-how-to-share-ai-rules-across-your-entire-codebase-4l0g
### A3. chezmoi (the dotfile manager) **Substrate:** Source state in a Git repo (`~/.local/share/chezmoi/`), target state on the live filesystem (`~/`). A single binary translates source→target via templates, encrypted secrets, OS-conditional logic. No daemon — chezmoi is a CLI invoked on demand or by the user's own cron/launchd. **Push or pull:** Pull-only by design. `chezmoi update` = `git pull` + `chezmoi apply`. Push happens via plain `git push` from the source repo. Combined `chezmoi update --apply` is the daily-driver command; many users wire it to a shell hook or a launchd job. **Conflict handling:** Genuine three-way merge. `chezmoi merge` invokes vimdiff/configurable merge tool when the live file diverges from the last-applied source. Critically, `chezmoi diff` and `chezmoi update -a=false` give a *preview-before-apply* gate — the user can review the pull before it touches their config. **The trick we're missing:** **Preview-before-apply is the load-bearing UX** chezmoi proves works. The current setup-skills.sh just clobbers — that's why agents and humans fight. A LaunchAgent receiver should write to a staging dir, diff against live, and only swap on clean apply (or surface a conflict to a review UI). chezmoi also encrypts per-machine secrets via age/gpg — relevant for B5 (per-machine override). And chezmoi's "no daemon, just a smart CLI invoked by the OS scheduler" is exactly the LaunchAgent shape, validating the receiver design. Source: https://www.chezmoi.io/ , https://www.chezmoi.io/why-use-chezmoi/
### A4. VS Code Settings Sync **Substrate:** Microsoft-hosted backend keyed to a GitHub or Microsoft account. Settings, keybindings, extensions, snippets, UI state are stored as discrete resources. Local backups kept 30 days; remote keeps last 20 versions per resource (this is the audit/rollback story). **Push or pull:** **Polling, not push.** The IDE polls the backend on an interval (and on relevant local-change events) and pushes only changed items after the first full sync. There is no server-initiated push channel — latency is bounded by the poll interval, typically tens of seconds to minutes in practice. Users complain about "Settings Sync extension startup too slow" precisely because the poll runs at startup and blocks UX. **Conflict handling:** Per-resource last-write-wins with a manual "Show Conflicts" UI when divergence is detected. Users can revert to any of the last 20 remote versions per resource — a built-in rollback ladder. **The trick we're missing:** Two things. (1) **Per-resource versioning with N-deep history** is the right model for B4 (rollback). Don't version the whole skills tree as one git ref — version each skill independently so "revert listener to last week" doesn't drag the rest backward. (2) Polling is fine for a 50-machine fleet but the latency tax is real; for our 4-operator/72-skill case, GitHub Actions webhook → LaunchAgent (push-from-Git) is strictly better than poll. VS Code chose poll because they can't put a daemon on every user's machine; we can. Source: https://code.visualstudio.com/docs/configure/settings-sync
---
### B1. Audit trail per machine **Need:** When Charlie says "the listener skill broke for me Tuesday at 2pm," operator must reconstruct *which exact bytes* of `listener/SKILL.md` were on his Mac at that timestamp. Without this, every intern bug report becomes an unresolvable he-said-she-said. **Consequence of ignoring:** Trust collapse — Charlie/Bear stop reporting bugs because "Ewing can't tell what version I had anyway." Drift becomes invisible. **Where it lives:** Receiver-side ledger on each machine: `~/.claude/skills/.sync_log.jsonl` — one line per apply (timestamp, commit SHA, files changed, agent attribution). Mirrored to a Supabase `skill_sync_events` table the next time the machine has network. Not git-only because git history is global; we need the per-machine "what landed when on *this* box."
### B2. Programmatic skill writes (agent attribution) **Need:** swarm-upgrade and other agents write to `~/.claude/skills/*/SKILL.md`. The current UserPromptSubmit auto-pull never fires for these writes — they bypass the human-typed-prompt surface. Each programmatic edit must (a) reach the central repo and (b) carry an attribution tag (which agent, which run). **Consequence of ignoring:** Agent-authored improvements stay on whichever machine ran the agent, never propagate. Worse: a buggy autonomous edit overwrites the canonical version silently. **Where it lives:** A filesystem watcher (fswatch / FSEvents on Mac) on `~/.claude/skills/` that debounces, runs `git commit` with author `agent:<name>@run-<id>`, and pushes. Distinct from human-edit path. Goes in the same LaunchAgent as the receiver.
### B3. Skill scopes — personal vs team **Need:** Cursor's three-layer model maps cleanly: **team** (all 4 operators get it, in main repo), **personal** (Ewing only — `private/` subtree), **machine** (this box only — `local/`). A skill in `private/listener-experimental/` must NEVER ship to Charlie's MacBook even though Charlie's receiver is pulling from the same repo. **Consequence of ignoring:** Half-baked private experiments leak to interns; intern-only skills (like dial-ready) confuse Ewing's main thread; deal-specific skills end up on machines that shouldn't see those clients. **Where it lives:** A per-machine `manifest.json` (chezmoi-style) declaring which subtrees this machine subscribes to. Receiver only applies files matching the manifest. Substrate stays one repo; selection is at apply-time.
### B4. Roll-forward / roll-back **Need:** "Last week's listener was better — revert just that one skill, keep the rest current." Per-skill rollback, not whole-tree. **Consequence of ignoring:** A regression in one skill freezes upgrades to all 71 others while Ewing investigates. Or operator copy-pastes an old version, creating a fork that never reconciles. **Where it lives:** Borrow VS Code's per-resource-versioning. Each skill is its own logical unit with its own history pointer in the manifest. `chapter skill revert listener --to=2026-04-30` rewrites just that skill's tree from a tagged commit; receiver picks up on next pull. Git provides the history; the manifest provides per-skill version pinning.
### B5. Per-machine overrides **Need:** Mac mini is headless — listener should not pop UI dialogs there. Charlie's MacBook should not run scheduled crons that require Ewing's Doppler tokens. Same skill, different runtime config per machine. **Consequence of ignoring:** Either (a) ship the lowest-common-denominator skill (worst on every machine), or (b) fork per machine and lose sync. **Where it lives:** chezmoi's template approach. A skill ships with a base SKILL.md plus optional `overrides/{hostname}.yaml` that the loader merges at read time. Manifest declares hostname; receiver applies overrides during apply. No fork, no drift.
### B6. Trust signal (most load-bearing) **Need:** Operator must glance at one thing and know "yes, my skills are current and the sync system is alive." Not a dashboard tour — a single observable: a status-bar dot, a menu-bar icon, a `chapter status` CLI line. Green = caught up within last 60s, yellow = stale, red = receiver dead. **Consequence of ignoring:** Without it, every doubt becomes "let me manually pull and restart Claude" — which is the exact friction we're solving. The system can be perfect but if the operator doesn't *know* it's working, they bypass it and we're back to manual setup-skills.sh. **Where it lives:** macOS menu-bar item driven by the LaunchAgent receiver, color from the heartbeat file (`~/.claude/skills/.heartbeat` — `mtime` last successful apply). Heartbeat is the single source of truth — every audit-trail entry, manifest decision, rollback event also touches it. This is the *one* thing every operator sees, so it earns its load-bearing status.
---
### S1. What I was asked Phase 1 Independent Draft for mission `skills-sync-architecture`. As listener, produce: (§A) 4 community-precedent breakdowns of how comparable systems sync configuration across machines — substrate, push/pull, conflict handling, the trick we're missing. (§B) 6 unstated requirements I infer Ewing has but did not say aloud — audit, attribution, scope, rollback, override, trust signal. Hard ceiling 1500 words. RESPAWN — prior listener timed out at 43min; discipline rule is write-stub-first then refine.
### S2. What I did 1. Read first 60 lines of listener SKILL.md to confirm phase contract and intent-extraction discipline. 2. Wrote stub markdown to disk before any research (survival-of-partial rule). 3. Loaded WebSearch via ToolSearch (single round-trip). 4. Ran 4 parallel/sequential web searches: Anthropic skills marketplace, Cursor team rules, chezmoi sync, VS Code Settings Sync. Capped at 4 (under 6 budget). 5. Filled §A then §B section by section, Edit-saving each so partial output survives. 6. Compiled this S1–S6 journal and rendered HTML.
### S3. What I found Three load-bearing insights for the architect to weigh: - **Anthropic explicitly left distribution to operators.** Plugin marketplace is a Git-fetcher with a manifest schema — it *is* the substrate they want us to use. Our GitHub + LaunchAgent design is on-paradigm, not a hack around it. - **chezmoi's preview-before-apply is the missing UX.** The current setup-skills.sh clobbers; that's why agent-edits and human-edits collide silently. Receiver should stage + diff + apply, not git-pull-and-overwrite. - **The trust signal is the load-bearing piece, not the sync itself.** VS Code Settings Sync technically works fine, but the user complaint is always "is it actually syncing?" Without a glanceable green dot, operators bypass the system and we're back where we started. Whatever the architect picks for substrate, B6 is the part that earns adoption.
Cursor's Team-vs-Project-vs-Personal three-layer model directly answers B3, and VS Code's per-resource versioning answers B4. Both can be implemented on top of a single Git repo — substrate stays simple, layering happens at the loader.
### S4. Currency log
[
{"to": "architect", "type": "request", "ask": "Does the proposed substrate support per-skill version pinning (B4)? VS Code keeps last 20 per resource — will we?"},
{"to": "architect", "type": "request", "ask": "Confirm the LaunchAgent receiver has access to a heartbeat file the menu-bar item can poll (B6)."},
{"to": "architect", "type": "request", "ask": "Where does the per-machine manifest.json live and who edits it — Ewing only, or per-operator self-service?"},
{"to": "writer", "type": "offer", "give": "Phrase 'preview-before-apply gate' for B4/B6 user-facing copy — chezmoi proves this UX works."},
{"to": "writer", "type": "offer", "give": "Trust-signal framing: green/yellow/red dot mapped to heartbeat freshness — single observable, copy-able verbatim."},
{"to": "writer", "type": "offer", "give": "Cursor's 'global rules drift silently' warning is the right voice for documenting why ~/.claude/skills/private/ is intern-invisible."}
]### S5. Debrief candidate Stub-first-then-refine discipline worked. Two-phase write (write headers to disk, then Edit each section) made the 43-min-timeout failure mode impossible — at any interruption point I had a ship-able partial. The 6-search budget was correct; 4 was enough. RESPAWN-discipline beat first-pass freedom.
### S6. Verdict PASS. Draft delivered under hard ceiling, with concrete substrate trick (preview-before-apply), concrete UX trick (single-observable trust signal), and concrete scope model (Cursor 3-layer mapped to private/team/local). Architect now has the precedents needed to commit on substrate; writer has copy hooks; storyteller has a coherent through-line (Anthropic-left-the-gap → we-fill-it-with-borrowed-patterns → operator-trusts-it-because-of-B6).
Generated from 019__listener.md — do not edit this HTML directly.