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

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. Source: User request, 2026-06-27; config/codex/AGENTS.md

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 ~/Documents/GitHub/kevin-wiki
cd ~/Documents/GitHub/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 ~/Documents/GitHub/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 ~/Documents/GitHub/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.

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-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. Source: User request, 2026-07-01
• 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. Source: User request, 2026-06-28
• 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. Source: User request, 2026-06-28; scripts/compact-skill-families.ts
• 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. Source: User request, 2026-06-27; config/codex/AGENTS.md
• 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. Source: User request, 2026-06-27; scripts/sync-skills.sh
• 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. Source: User request, 2026-06-24; scripts/sync-skills.sh
• 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. Source: User request, 2026-06-18; scripts/lib/agent-config-links.ts