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/<project-slug>/, 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 now focuses on dependency setup only; review-agent configuration is already gone on main.
• plugins/compound-engineering/skills/ce-doctor/SKILL.md and 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, plugins/compound-engineering/skills/ce-plan/SKILL.md, and 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, plugins/compound-engineering/skills/todo-triage/SKILL.md, and 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, plugins/compound-engineering/skills/feature-video/SKILL.md, and 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, tests/codex-converter.test.ts, tests/copilot-converter.test.ts, tests/pi-converter.test.ts, tests/review-skill-contract.test.ts, src/utils/codex-agents.ts, and src/converters/claude-to-pi.ts.
• 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 and plugins/compound-engineering/AGENTS.md.

Institutional Learnings

• 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: 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: 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 <user_state_dir>/projects/<project-slug>/ 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 <sanitized-repo-name>-<short-hash>, 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 <user_state_dir>/projects/<project-slug>/ 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 <sanitized-repo-name>-<short-hash>. 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, plugins/compound-engineering/skills/ce-doctor/SKILL.md, plugins/compound-engineering/skills/ce-brainstorm/SKILL.md, plugins/compound-engineering/skills/ce-plan/SKILL.md, plugins/compound-engineering/skills/ce-work/SKILL.md, and 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