Agent Config Sync

The wiki is the single source of truth for all agent configuration. Executable skills live under skills/; rules, hooks, MCP servers, and CLI settings live under config/. Bootstrap symlinks them into Cursor, Claude Code, Codex, and the universal AgentSkills location.

Operator Contract

Agent config is durable infrastructure. When behavior changes, update the canonical wiki file first, then let bootstrap project it into agent homes. Do not hand-edit generated symlink targets under $HOME as the source of truth.

The invariant: one canonical instruction library, many harness-specific pointers. If a new agent runtime needs the same behavior, map it to the wiki source rather than copying the prose. For skills specifically, skills/.runtime/all is the repo projection, ~/.agents/skills is the universal home bridge, and bespoke harness skill dirs should symlink or point to ~/.agents/skills. Source: Cross-Agent Harness Portability Only npm run skill-registry writes skills/.runtime/all; it stops when another tool has written a real directory there, and skills/README.md gives the path for adding an upstream skill. Source: wiki overhaul memo Phase 4, 2026-11-02

Architecture

kevin-wiki/
├── skills/
│   ├── engineering/      # coding, review, design, cloud, test skills
│   ├── productivity/     # agent ops, workflow, automation, workspace skills
│   ├── personal/         # Kevin voice, career, content, social skills
│   ├── misc/             # media, pets, diagrams, specialized utilities
│   ├── in-progress/      # draft skills excluded from runtime projection
│   ├── deprecated/       # retired skills excluded from runtime projection
│   ├── .system/          # hidden system skills
│   └── .runtime/all/     # generated flat symlink index consumed by agents
└── config/
    ├── cursor/
    │   ├── rules/        # Personal Cursor rules (*.mdc)
    │   ├── hooks/        # Hook scripts (brin-check.sh)
    │   ├── hooks.json    # Hook config
    │   ├── mcp.json      # Personal MCP servers
    │   └── cli-config.json
    └── dedalus/          # Dedalus rules/hooks/reference docs, not skill bodies

The symlink map below is descriptive. scripts/lib/agent-config-links.ts is the executable source of truth used by bootstrap and doctor checks. Source: scripts/lib/agent-config-links.ts; scripts/apply-agent-config.ts

Config Sync Protocol is the shorter operator checklist. This page owns the architecture, source taxonomy, symlink map, and harness rationale; the protocol owns the run order.

Symlink Map

Canonical list: scripts/lib/agent-config-links.ts (used by bootstrap and doctor --only config-sync).

Cross-agent global presets (not just Cursor)

The wiki is the opinionated harness for every agent, not just Cursor. The two global presets above point Claude Code and Codex at the kevin-wiki brain (identity files → operations hub → AGENTS.md) and enforce brain-first lookup + no-one-off-work everywhere. Source of truth is config/{claude,codex}/; bootstrap symlinks them into $HOME, backing up any existing real file first. This fixes the legacy bug where both global files pointed at the stale ~/Documents/GitHub/my-wiki clone. Activate on a machine with npm run bootstrap.

The Codex preset now includes an explicit Codex sync contract: read the wiki spine, route tool/skill choices through capability-routing-map, SKILL-RESOLVER, and active-stack, treat harness-specific files such as tool-hierarchy.mdc as compact projections, treat skills/.runtime/all as Codex's projected skill library, and close config/wiki edits with bootstrap, skill taxonomy, config-sync doctor, index, qmd, and log checks. private page

Full cross-agent matrix (Cursor / Claude Code / Codex / OpenClaw / Hermes — skill dirs, identity-file mapping, what's bootstrap-wired vs remote/manual, and how to add a new agent): wiki/meta/cross-agent-harness.md.

Repo-scoped Cursor config (wiki workspace only)

These live under .cursor/ in the wiki repo and are not symlinked to $HOME. They apply when the workspace root is kevin-wiki:

Global rules in config/cursor/rules/ + repo rules in .cursor/rules/ together match wiki/meta/agent-operations-hub.md § always-on rules. Source: compiled from repo layout, 2026-06-03

What Is NOT Synced

These are Cursor-managed or machine-specific and stay local:

• ~/.cursor/skills-cursor/ -- Cursor auto-manages these
• ~/.cursor/plugins/ -- auto-fetched marketplace plugin caches
• ~/.cursor/extensions/ -- VS Code/Cursor extensions
• ~/.cursor/projects/ -- per-project state
• ~/.cursor/ide_state.json, argv.json -- internal state

Bootstrap (new machine)

git clone --recursive git@github.com:<user>/kevin-wiki.git ~/repos/Kevin-Wiki
cd ~/repos/Kevin-Wiki
npm run bootstrap

Implementation: scripts/apply-agent-config.ts (symlinks, submodules, git hooks, self-verify). scripts/bootstrap-agent-config.sh is a thin wrapper.

The script backs up any existing real files/directories at symlink targets, creates symlinks, initializes submodules, wires submodule skill roots, installs git hooks, validates the skill taxonomy, and verifies the canonical symlink map before exiting. As of 2026-06-18, that map has 11 global links. On failure it exits non-zero.

The skill taxonomy check is part of portability: every skills/{engineering,productivity,personal,misc,in-progress,deprecated}/<slug>/SKILL.md must appear in wiki/meta/skill-registry.json, every registry row must point at a family synthesis page under wiki/concepts/*-skills.md, and every promoted skill must appear in the generated runtime index at skills/.runtime/all. This guarantees a fresh clone can reconstruct the executable skill library while the wiki stays compact enough to read.

Daily Workflow

Because ~/.cursor/skills/ points at the generated runtime index, edit source skills in the category folders, then run npm run skill-registry to refresh the flat projection. New skills installed via npx skills install should be promoted into the appropriate category. Run git status in the wiki to see changes, then commit.

cd ~/repos/Kevin-Wiki
bash scripts/sync-skills.sh --check
npm run skill-registry
git add skills/ wiki/meta/skill-registry.json wiki/meta/skill-registry.md wiki/concepts/*-skills.md wiki/skills/README.md
git commit -m "chore(skills): add new-skill"
git push

On another machine: git pull --recurse-submodules to get the latest config.

Dedalus Repo Config (reference copies)

config/dedalus/ contains READ-ONLY reference copies of the dedalus-monorepo's rules, hooks, subagents, and Cursor rules. Dedalus executable skill bodies are folded into the category taxonomy with origin: dedalus and source_slug: .... The canonical source for repo-scoped rules is still the Dedalus repo itself; these copies exist so the wiki has a complete picture of all agent configuration in one place.

Resolver index: Every Dedalus rule file, Cursor .mdc, and Dedalus-origin skill is listed in wiki/SKILL-RESOLVER.md § Dedalus monorepo. wiki/meta/capability-routing-map.md owns generic route order; config/cursor/rules/tool-hierarchy.mdc only summarizes paths for Cursor when the workspace is Dedalus.

To refresh after dedalus repo changes:

cp ~/Documents/GitHub/dedalus-monorepo/.cursor/rules/*.mdc ~/repos/Kevin-Wiki/config/dedalus/cursor-rules/

Verification

Run after config changes:

npx tsx scripts/doctor.ts --only config-sync
npm run bootstrap
bash scripts/sync-skills.sh --check

Use the doctor to catch broken links. Use bootstrap to repair them. The config-sync doctor also resolves every path named in a harness-loaded file and in the wiki files the global presets name, and fails on a missing one (scripts/lib/boot-paths.ts). It fails when a preset's Mac rules block differs from private page; npm run boot-rules rewrites it.

If a config change touches generated runtime links, skill registry pages, agent-doc packs, or qmd discoverability, use Generated Surface Contract for the extra closeout commands.

---

Timeline

• 2026-11-02 | The runtime generator became the only writer of skills/.runtime/all, and the skills CLI lock moved to ~/repos/_retired/skills-cli-lock-20261102/. Source: wiki overhaul memo Phase 4, 2026-11-02
• 2026-10-30 | Added the boot-path and boot-rules checks to the config-sync doctor. It had scored 100 with a dead wiki path in every preset. Source: wiki overhaul Phase 1, 2026-10-30
• 2026-07-01 | Clarified the architecture/checklist split with Config Sync Protocol and linked generated-surface closeout for runtime links, skill registry output, packs, and qmd. private page
• 2026-06-28 | Replaced runtime-named skill source folders with category folders plus a generated flat runtime index at skills/.runtime/all; folded Claude, Dedalus, Cursor plugin, Codex plugin, and skills.sh imports into the same source taxonomy with origin metadata. private page
• 2026-06-28 | Added parent-router compaction for noisy skill families. Child skills now live under references/skills/<old-slug>/SKILL.md inside the owning parent router, so the shared runtime stays compact while preserving upstream/plugin prompt depth. private page
• 2026-06-27 | Tightened the Codex global preset with an explicit sync contract: startup wiki spine, tool/skill routing surfaces, personal skill library ownership, no-one-off codification, quality spine, and config/wiki verification commands. private page
• 2026-06-27 | Skill portability now validates executable skills against the generated skill registry and family pages instead of requiring one wiki article per skill. private page
• 2026-06-24 | Bootstrap ran the old bidirectional skill taxonomy check so fresh-clone setup validated both executable skills and wiki catalog pages. Superseded by the 2026-06-27 registry model. private page
• 2026-06-18 | Added operator contract, corrected bootstrap verification from the older seven-link wording to the current 11-link symlink map, and added explicit verification commands. private page