--- title: "Redesign Config and Worktree-Safe Storage for Compound Engineering" description: "Replace the legacy repo-local config and storage assumptions with a two-scope state model:" type: skill canonical_url: https://claudary.paisolsolutions.com/skills/2026-03-25-002-refactor-config-storage-redesign-plan source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T10:59:00.361Z license: CC-BY-4.0 attribution: "Redesign Config and Worktree-Safe Storage for Compound Engineering — Claudary (https://claudary.paisolsolutions.com/skills/2026-03-25-002-refactor-config-storage-redesign-plan)" --- # Redesign Config and Worktree-Safe Storage for Compound Engineering Replace the legacy repo-local config and storage assumptions with a two-scope state model: ## Overview --- title: "refactor: Redesign config and worktree-safe storage for compound-engineering" type: refactor status: active date: 2026-03-25 deepened: 2026-03-25 origin: docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md --- # Redesign Config and Worktree-Safe Storage for Compound Engineering ## Overview Replace the legacy repo-local config and storage assumptions with a two-scope state model: - `user_state_dir` for user-level CE state and per-project durable storage - `repo_state_dir` for repo-local CE config The work preserves the new `/ce-doctor` + `/ce-setup` dependency flow already added on this branch, but repoints it at the new state contract and migrates durable plugin state out of `.context/compound-engineering/...` and `todos/`. ## Problem Frame The current plugin still treats repo-local `.context/compound-engineering/...` and legacy `compound-engineering.local.md` as stable runtime contracts. That breaks across git worktrees, leaves setup migration undefined, and leaks old assumptions into docs, tests, and converter fixtures. Main has also removed setup-managed reviewer selection, so this refactor must not recreate that model in a new config file. (see origin: `docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md`) ## Requirements Trace - R1-R10. Introduce YAML config under `repo_state_dir`, keep compatibility metadata minimal, and make `/ce-setup` the sole migration owner for legacy config. - R11-R16. Codify the standard config/storage contract section in `AGENTS.md`, keep it cross-agent and low-friction, and centralize migration warnings in core entry skills plus `/ce-doctor`. - R17-R23. Resolve durable CE state under `user_state_dir/projects//`, preserve legacy todo reads, and move future durable writes there. - R24-R31. Expand `/ce-doctor` and `/ce-setup` around the new config/storage contract while preserving the registry-driven dependency flow and fresh scans. - R32-R33. Remove the old config/storage contract from skills, tests, and converter surfaces without introducing provider-specific paths. ## Scope Boundaries - Do not reintroduce review-agent selection or review-context storage into plugin-managed config. - Do not actively migrate historical per-run scratch directories out of repo-local `.context/compound-engineering/...`. - Do not add garbage collection or pruning for orphaned per-project directories. - Do not keep `compound-engineering.local.md` as a long-term dual-write format; treat it as legacy migration input only. - Do not expand this work into project dependency management such as `bundle install`, app setup, or team-authored config workflows beyond laying the repo-local config structure. ## Context & Research ### Relevant Code and Patterns - [plugins/compound-engineering/skills/ce-setup/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-setup/SKILL.md) now focuses on dependency setup only; review-agent configuration is already gone on main. - [plugins/compound-engineering/skills/ce-doctor/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/SKILL.md) and [plugins/compound-engineering/skills/ce-doctor/scripts/check-health](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/scripts/check-health) already provide the shared diagnostic surface and script-first dependency checks. - [plugins/compound-engineering/skills/ce-brainstorm/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md), [plugins/compound-engineering/skills/ce-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-plan/SKILL.md), and [plugins/compound-engineering/skills/ce-work/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-work/SKILL.md) are the concrete core entry skills that currently lack any shared migration-warning contract. - [plugins/compound-engineering/skills/todo-create/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-create/SKILL.md), [plugins/compound-engineering/skills/todo-triage/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-triage/SKILL.md), and [plugins/compound-engineering/skills/todo-resolve/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-resolve/SKILL.md) encode the current todo path contract and legacy-drain semantics. - [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md), [plugins/compound-engineering/skills/feature-video/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/feature-video/SKILL.md), and [plugins/compound-engineering/skills/deepen-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/deepen-plan/SKILL.md) are the highest-signal per-run artifact consumers still hardcoding `.context/compound-engineering/...`. - Converter/test surfaces still encode the old contract in [tests/converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/converter.test.ts), [tests/codex-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/codex-converter.test.ts), [tests/copilot-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/copilot-converter.test.ts), [tests/pi-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/pi-converter.test.ts), [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts), [src/utils/codex-agents.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/utils/codex-agents.ts), and [src/converters/claude-to-pi.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/converters/claude-to-pi.ts). - [docs/solutions/skill-design/beta-skills-framework.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/skill-design/beta-skills-framework.md) is an active solution doc that still references the old config contract, so the doc sweep cannot be limited to tests and plugin README alone. - Repo-level instruction surfaces live in [AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/AGENTS.md) and [plugins/compound-engineering/AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/AGENTS.md). ### Institutional Learnings - [docs/solutions/skill-design/compound-refresh-skill-improvements.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/skill-design/compound-refresh-skill-improvements.md): keep skill instructions platform-agnostic, avoid hardcoded tool names, and prefer dedicated file tools over shell exploration to reduce prompts. - [docs/solutions/workflow/todo-status-lifecycle.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/workflow/todo-status-lifecycle.md): todo status is load-bearing; any path migration must preserve the pending/ready/complete pipeline rather than flattening it. - [docs/solutions/codex-skill-prompt-entrypoints.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/codex-skill-prompt-entrypoints.md): copied `SKILL.md` content is often passed through mostly as-is, so skill wording must remain meaningful without target-specific rewriting assumptions. ### External References - None. The repo already contains sufficient current patterns for this planning pass. ## Key Technical Decisions - **Keep the state vocabulary to two named directories.** Use `user_state_dir` and `repo_state_dir`, and treat the per-project storage path as the derived subpath `/projects//` rather than naming a third root. - **Standardize on header plus selective preamble.** Every skill carries one compact config/storage header so the vocabulary and fallback behavior stay consistent. Only independently invocable skills that diagnose config state or read/write durable CE state carry the full config-resolution preamble. Parent skills pass resolved values to spawned agents unless the child is itself independently invocable. - **Do not revive legacy review config.** `compound-engineering.local.md` is obsolete cleanup input only. Any surviving YAML config should store only real persisted CE state such as minimal compatibility metadata, not values that the runtime can derive deterministically. - **Keep migration state user-action oriented.** The runtime only needs to distinguish four practical states: no new config yet, legacy/conflicting config that needs migration, stale compatibility contract that requires rerunning `/ce-setup`, and current config. Do not split “migration version” and “setup version” unless execution discovers a real user-visible difference in remediation. - **Make `/ce-setup` the only writer of migration state.** `/ce-doctor` diagnoses and entry skills warn, but only `/ce-setup` reconciles legacy and new config. - **Treat path derivation as runtime contract, not persisted config.** Independently invocable config/storage consumers should derive `user_state_dir`, `repo_state_dir`, and the per-project path directly from the standard preamble. `/ce-setup` should not pre-write the derived per-project path just to make later skills work. - **Treat project identity as a shared-storage guarantee.** The per-project path must resolve from shared repo identity, not current checkout identity. Use `git rev-parse --path-format=absolute --git-common-dir` as the primary identity source so linked worktrees map to the same CE project. Derive the directory slug as `-`, where the repo name comes from the basename of `${git_common_dir%/.git}` and the hash comes from the full absolute `git_common_dir`. If git identity cannot be resolved, execution may use a deterministic absolute-path fallback, but the worktree-safe path must be the default contract. - **Degrade instead of blocking on missing CE state.** Core entry skills should emit a short migration warning and point to `/ce-setup`, but missing CE config or storage should not block the main workflow by default. Full-preamble skills should derive canonical paths when possible and otherwise degrade locally: do not write to legacy or guessed fallback paths, report what could not be persisted, and continue when the main task is still safe to complete. - **Preserve todo migration semantics, not per-run artifact history.** Todos retain dual-read compatibility during the drain period; per-run artifact directories only change future writes. - **Keep one active planning chain.** Current operational surfaces should adopt the new contract directly, and earlier setup/todo requirements and plan docs should be folded into this plan rather than left as competing active guidance. - **Use contract tests for prompt surfaces that now matter operationally.** Existing converter and review contract tests already validate prompt text; add setup/ce-doctor or storage-focused contract coverage rather than relying only on manual inspection. ## Open Questions ### Resolved During Planning - **Should this plan assume review-agent config still exists?** No. Main has already removed setup-managed reviewer selection, so this refactor must not recreate it. - **Should the storage vocabulary keep a named project root variable?** No. Use `user_state_dir` and `repo_state_dir`; refer to `/projects//` directly. - **How is the per-project slug derived?** Use the shared git identity from `git rev-parse --path-format=absolute --git-common-dir`, then derive a human-friendly directory-safe slug as `-`. This is intentionally stable across linked worktrees of the same repo and intentionally different across separate clones. - **Which skills should carry migration warnings?** The concrete warning surfaces are [plugins/compound-engineering/skills/ce-setup/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-setup/SKILL.md), [plugins/compound-engineering/skills/ce-doctor/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/SKILL.md), [plugins/compound-engineering/skills/ce-brainstorm/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md), [plugins/compound-engineering/skills/ce-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-plan/SKILL.md), [plugins/compound-engineering/skills/ce-work/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-work/SKILL.md), and [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md). Non-core skills should inherit the contract only when they are independently invocable and actually need config or durable storage. - **Should every old reference be rewritten?** No. Active docs and tests should adopt the new contract. Historical requirements/plans should be preserved for traceability and only annotated when they could plausibly be mistaken for current runtime guidance. - **Is external research needed?** No. The repo already contains the relevant prompt, converter, and lifecycle patterns. ### Deferred to Implementation - **Compatibility metadata shape:** The plan assumes a minimal compatibility contract, but execution should finalize whether that is a single revision key or a small structured object once the surrounding prompt text is updated. - **Shared reference artifact vs. AGENTS-only wording:** The plan assumes `AGENTS.md` is the primary source of truth for the config/storage contract section. Execution can decide whether a separate reference file materially reduces duplication. ## High-Level Technical Design > *This illustrates the intended approac --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/2026-03-25-002-refactor-config-storage-redesign-plan) · https://claudary.paisolsolutions.com