Globals derived from workspace by script (with grill on drift)
Globals derived from workspace
Rule
chirag127/workspace files are canonical for agent configuration. Global config files (~/.claude.json, ~/.opencode/config.json, ~/.kilocode/, ~/.gemini/, etc.) are derived caches written by scripts/sync-globals.mjs.
You never edit a global file directly. The script reads workspace ? writes global ? diffs ? fires grill-me if drift is detected.
What "canonical" maps to
| Concern | Workspace source | Global target (derived) |
|---|---|---|
| MCP servers | .mcp.json |
~/.claude.json mcpServers; ~/.opencode/config.json mcp; etc. |
| Claude Code settings | .agents/claude/settings.json |
~/.claude/settings.json (per-machine .local.json layered on top) |
| OpenCode settings | .agents/opencode/opencode.{json,jsonc} |
~/.config/opencode/opencode.{json,jsonc} |
| Kilo Code settings | .agents/kilocode/kilo.jsonc |
~/.config/kilo/kilo.jsonc |
| Agent rules | AGENTS.md + knowledge/rules/ |
~/.claude/CLAUDE.md (pointer) |
| Skills | repos/own/infra/agent-skills/ |
~/.claude/skills/ (junction) |
When the script runs
Automatic — Scheduled Task Oriz-SyncAgentConfigs at logon + daily 09:00, via scripts/sync-agent-configs.ps1. Manual force: pwsh scripts/sync-agent-configs.ps1. See agent-configs-workspace-canonical-2026-07-03.
Reverses 2026-06-29 "manual only" guidance — that predated the sync-agent-configs script. Writes are idempotent, byte-for-byte, and preserve ~/.claude/settings.local.json (per-machine secrets, gitignored, never touched).
How grill-me fires
Script detects diff ? prints diff ? calls grill-me (via claude CLI invocation, or interactive PS prompt fallback) with the question:
"Workspace has X but global doesn't (or vice versa). Migrate / keep both / delete from workspace?"
The answer is committed back to the script's allow/deny registry so the same diff doesn't re-prompt on the next session.
Why this rule, not "workspace-only"
Tried workspace-only (rule deleted in this commit). Real failure modes:
- Per-agent schema drift — OpenCode's
mcpshape ? Claude Code's; sync script must transform per agent. Workspace-only meant manually maintaining N adapters. - Per-machine variation — auth tokens, absolute binary paths (
codebase-memory.exe), model env vars vary per laptop. Forcing them into workspace = either commits secrets or commits a per-machine config file that doesn't work elsewhere. - Repo cleanliness — workspace root should hold minimum essential files. Stuffing every agent's global content into workspace would bloat the root.
Workspace-canonical + derived-globals keeps both: clean workspace root + reproducible globals via script.
Anti-patterns
- ? Editing
~/.claude.jsonor~/.opencode/config.jsondirectly. Script will overwrite next run. - ? Letting globals drift "just for this machine" without committing the variation to workspace as a per-machine profile.
- ? Running the script via cron — must run when CC session starts so changes you push from one machine reflect on this one.
First-run / new-laptop bootstrap
cd C:\D\oriz
node scripts/sync-globals.mjs --bootstrap
--bootstrap skips the grill-me on every new item (you just cloned; everything is new) and just writes globals from workspace. After bootstrap, the next session-start run uses normal grill-on-drift.
Cross-refs
mcp-config-single-source-of-truth— the MCP-side of this ruleagent-fleet-parity— what derived-globals enables (4-agent uniform config)mcp-workspace-not-global— narrower MCP-scope rule (still applies; same direction)