@@ -38,7 +38,7 @@ The `setup` skill uses `AskUserQuestion` at 5 decision points. On non-Claude pla
1.**Tool-not-found error** — LLM tries to call `AskUserQuestion` as a function; platform returns an error. Setup halts.
2.**Silent skip** — LLM reads `AskUserQuestion` as prose, ignores the decision gate, auto-configures. User never consulted. This is worse — produces a `compound-engineering.local.md` the user never approved.
`plugins/compound-engineering/skills/setup/SKILL.md` has 5 `AskUserQuestion` blocks:
`plugins/compound-engineering/skills/ce-setup/SKILL.md` has 5 `AskUserQuestion` blocks:
| Line | Decision Point |
|------|----------------|
@@ -70,7 +70,7 @@ If not, present each question as a numbered list and wait for a reply before pro
**Why 4 lines, not 16:** LLMs know what a numbered list is — no example blockquote needed. The branching condition is tool availability, not platform identity — no platform name list needed (YAGNI: new platforms will be added and lists go stale). State the "never skip" rule once here; don't repeat it in `codex-agents.ts`.
**Why this works:** The skill body IS read by the LLM on all platforms when `/setup` is invoked. The agent follows prose instructions regardless of tool availability. This is the same pattern `brainstorming/SKILL.md` uses — it avoids `AskUserQuestion` entirely and uses inline numbered lists — the gold standard cross-platform approach.
**Why this works:** The skill body IS read by the LLM on all platforms when `/ce-setup` is invoked. The agent follows prose instructions regardless of tool availability. This is the same pattern `brainstorming/SKILL.md` uses — it avoids `AskUserQuestion` entirely and uses inline numbered lists — the gold standard cross-platform approach.
### 2. Apply the same preamble to `create-new-skill.md`
@@ -118,7 +118,7 @@ Add to the "Skill Compliance Checklist" in `plugins/compound-engineering/CLAUDE.
## Files
-`plugins/compound-engineering/skills/setup/SKILL.md` — Add 4-line preamble after line 8
-`plugins/compound-engineering/skills/ce-setup/SKILL.md` — Add 4-line preamble after line 8
-`plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md` — Add same preamble at top
# Consolidate Todo Storage Under `.context/compound-engineering/todos/`
## Overview
Move the file-based todo system's canonical storage path from `todos/` to `.context/compound-engineering/todos/`, consolidating all compound-engineering workflow artifacts under one namespace. Use a "drain naturally" migration strategy: new todos write to the new path, reads check both paths, legacy files resolve through normal usage.
## Problem Statement / Motivation
The compound-engineering plugin standardized on `.context/compound-engineering/<workflow>/` for workflow artifacts. Multiple skills already use this pattern (`ce-review-beta`, `resolve-todo-parallel`, `feature-video`, `deepen-plan-beta`). The todo system is the last major workflow artifact stored at a different top-level path (`todos/`). Consolidation improves discoverability and organization. PR #345 is adding the `.gitignore` check for `.context/`. (see origin: `docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md`)
## Proposed Solution
Update 7 skills to use `.context/compound-engineering/todos/` as the canonical write path while reading from both locations during the legacy drain period. Consolidate inline todo path references in consumer skills to delegate to the `file-todos` skill as the single authority.
## Technical Considerations
### Multi-Session Lifecycle vs. Per-Run Scratch
Todos are gitignored and transient -- they don't survive clones or branch switches. But unlike per-run scratch directories (e.g., `ce-review-beta/<run-id>/`), a todo's lifecycle spans multiple sessions (pending -> triage -> ready -> work -> complete). The `file-todos` skill should note that `.context/compound-engineering/todos/` should not be cleaned up as part of any skill's post-run scratch cleanup. In practice the risk is low since each skill only cleans up its own namespaced subdirectory, but the note prevents misunderstanding.
### ID Sequencing Across Two Directories
During the drain period, issue ID generation must scan BOTH `todos/` and `.context/compound-engineering/todos/` to avoid collisions. Two todos with the same numeric ID would break the dependency system (`dependencies: ["005"]` becomes ambiguous). The `file-todos` skill's "next ID" logic must take the global max across both paths.
### Directory Creation
The new path is 3 levels deep (`.context/compound-engineering/todos/`). Unlike the old single-level `todos/`, this needs an explicit `mkdir -p` before first write. Add this to the "Creating a New Todo" workflow in `file-todos`.
### Git Tracking
Both `todos/` and `.context/` are gitignored. The `git add todos/` command in `ce-review` (line 448) is dead code -- todos in a gitignored directory were never committed through this path. Remove it.
## Acceptance Criteria
- [ ] New todos created by any skill land in `.context/compound-engineering/todos/`
- [ ] Existing todos in `todos/` are still found and resolvable by `triage` and `resolve-todo-parallel`
- [ ] Issue ID generation scans both directories to prevent collisions
- [ ] Consumer skills (`ce-review`, `ce-review-beta`, `test-browser`, `test-xcode`) delegate to `file-todos` rather than encoding paths inline
- [ ]`ce-review-beta` report-only prohibition uses path-agnostic language
- [ ] Stale template paths in `ce-review` (`.claude/skills/...`) fixed to use correct relative path
- Add `mkdir -p .context/compound-engineering/todos/` as first step
- Update `ls todos/` for next-ID to scan both directories: `ls .context/compound-engineering/todos/ todos/ 2>/dev/null | grep -o '^[0-9]\+' | sort -n | tail -1`
- Update template copy target to `.context/compound-engineering/todos/`
5.**Reading/Listing commands** (line 106+): Update `ls` and `grep` commands to scan both paths. Pattern: `ls .context/compound-engineering/todos/*-pending-*.md todos/*-pending-*.md 2>/dev/null`
6.**Dependency checking** (lines 131-142): Update `[ -f ]` checks and `grep -l` to scan both directories
7.**Quick Reference Commands** (lines 197-232): Update all commands to use new canonical path for writes, dual-path for reads
8.**Key Distinctions** (lines 237-253): Update "Markdown files in `todos/` directory" to new path
9.**Add a Legacy Support note** near the top: "During the transition period, always check both `.context/compound-engineering/todos/` (canonical) and `todos/` (legacy) when reading. Write only to the canonical path. Unlike per-run scratch directories, `.context/compound-engineering/todos/` has a multi-session lifecycle -- do not clean it up as part of post-run scratch cleanup."
1.**Line 244** (`<critical_requirement>`): Replace `todos/ directory` with `the todo directory defined by the file-todos skill`
2.**Lines 275, 323, 343**: Fix stale template path `.claude/skills/file-todos/assets/todo-template.md` to correct relative reference (or delegate to "load the `file-todos` skill for the template location")
3.**Line 435** (`ls todos/*-pending-*.md`): Update to reference file-todos conventions
4.**Line 448** (`git add todos/`): Remove this dead code (both paths are gitignored)
1.**Line 35**: Change `todos/` items to reference file-todos skill conventions
2.**Line 41** (report-only prohibition): Change `do not create todos/` to `do not create todo files` (path-agnostic -- closes loophole where agent could write to new path thinking old prohibition doesn't apply)
3.**Line 479**: Update `todos/` reference to delegate to file-todos skill
1.**Line 13**: Change `Get all unresolved TODOs from the /todos/*.md directory` to scan both `.context/compound-engineering/todos/*.md` and `todos/*.md`
## Dependencies & Risks
- **Dependency on PR #345**: That PR adds the `.gitignore` check for `.context/`. This change works regardless (`.context/` is already gitignored at repo root), but #345 adds the validation that consuming projects have it gitignored too.
- **Risk: Agent literal-copying**: Agents often copy shell commands verbatim from skill files. If dual-path commands are unclear, agents may only check one path. Mitigation: Use explicit dual-path examples in the most critical commands (list, create, ID generation) and add a prominent note about legacy path.
- **Risk: Other branches with in-flight todo work**: The drain strategy avoids this -- no files are moved, no paths break immediately.
## Sources & References
### Origin
- **Origin document:** [docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md](docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md) -- Key decisions: drain naturally (no active migration), delegate to file-todos as authority (R5), update all 7 affected skills.
### Internal References
-`plugins/compound-engineering/skills/file-todos/SKILL.md` -- canonical todo system definition
-`plugins/compound-engineering/skills/file-todos/assets/todo-template.md` -- todo file template
-`AGENTS.md:27` -- `.context/compound-engineering/` scratch space convention
-`.gitignore` -- confirms both `todos/` and `.context/` are already ignored
# 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](/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 `<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](/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 approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
```text
user_state_dir/
config.yaml # optional global defaults / compatibility state if needed
projects/
<project-slug>/
todos/
ce-review/<run-id>/
deepen-plan/<run-id>/
feature-video/<run-id>/
...
<repo>/repo_state_dir/
config.yaml # optional tracked repo-level CE config (reserved / future)
config.local.yaml # optional machine-local CE config; gitignore this file, not the whole directory
Resolution flow:
1. Resolve repo_state_dir as `<repo>/.compound-engineering`
2. Resolve user_state_dir from the documented fallback chain
3. Derive the per-project path under user_state_dir/projects/<project-slug>/
4. Read config layers only when they exist and the skill needs persisted CE values
5. If compatibility or migration state is stale, route the user to /ce-setup
- readable prefix: sanitized basename of `${git_common_dir%/.git}`
- stable suffix: short hash of the full absolute `git_common_dir`
- format: `<sanitized-repo-name>-<short-hash>`
Action model:
- no repo-local CE file yet -> warn only when relevant, `/ce-doctor` explains current state, `/ce-setup` initializes or refreshes if needed
- legacy `compound-engineering.local.md` present -> warn in core entry skills, `/ce-doctor` explains that it is obsolete, `/ce-setup` deletes it after explanation
- new config below required contract -> warn in core entry skills, `/ce-doctor` explains rerun requirement, `/ce-setup` refreshes
- current config -> proceed with no migration warning
- canonical storage can be derived but CE state is incomplete -> proceed using canonical paths and warn when relevant
- canonical storage cannot be derived safely -> do not write to legacy or guessed fallback paths; degrade locally, report what could not be persisted, and direct the user to `/ce-setup`
```
## Implementation Units
- [ ]**Unit 1: Codify the state contract and authoring rules**
**Goal:** Establish `user_state_dir` / `repo_state_dir` terminology and the standard config/storage contract section as a single prompt-authoring contract before touching individual skills.
- Update the repo and plugin instruction surfaces so skill authors have one stable vocabulary and one two-tier authoring contract to copy:
- compact header required in every skill
- full config-resolution preamble required only in independently invocable config/storage consumers
- Clarify that `repo_state_dir` is for repo-local CE config, `user_state_dir` is for user-level CE state, and the per-project path derives from the latter.
- Define the compact header contents explicitly: state vocabulary, whether the skill resolves config itself or expects caller-passed values, and the rule to warn or route to `/ce-setup` when required config/storage cannot be resolved safely.
- Define the full preamble trigger explicitly: use it only in independently invocable skills that diagnose migration/config state or that read/write durable CE-owned state.
- Define the full preamble contents explicitly:
- prefer caller-passed resolved values
- resolve `repo_state_dir`, `user_state_dir`, and the per-project path deterministically
- read config layers only when needed and when present
- warn and route to `/ce-setup` when migration or rerun is needed
- do not write to legacy or guessed fallback paths when canonical storage cannot be derived
- degrade locally and report what could not be persisted instead of blocking the main task by default
- Keep the guidance capability-first and cross-platform, following current plugin AGENTS conventions.
- New skill author can determine where config is read from and where durable project state lives without inferring hidden terminology.
- A skill author can tell from the contract whether a skill needs only the compact header or the full config-resolution preamble.
- A spawned helper/delegate skill can rely on caller-passed resolved values rather than re-reading the config layers.
- The documented config section still makes sense in Claude Code, Codex, Gemini, and copied-skill targets.
**Verification:**
- Both AGENTS files describe the same contract without conflicting path terminology.
- The plan no longer leaves “header vs full preamble” as an implementation-time choice.
- README no longer implies that CE runtime state belongs in repo-local `.context/compound-engineering/...`.
- [ ]**Unit 2: Move `/ce-setup` and `/ce-doctor` to the new config and migration contract**
**Goal:** Make `/ce-setup` own obsolete-file cleanup plus any surviving compatibility migration work, make `/ce-doctor` diagnose compatibility, storage state, and gitignore safety in addition to dependencies, and give core entry skills one consistent migration-warning contract.
- Replace the current “dependency-only setup” language with a flow that also removes obsolete `compound-engineering.local.md` files after explaining why they are no longer used, and writes machine-local config only if the surviving CE contract truly requires persisted state.
- Extend the doctor script and wrapper skill to report resolved config layers when present, the derived per-project storage path, whether a legacy file still needs cleanup, and repo-local gitignore safety for `.compound-engineering/config.local.yaml` when that file exists or is expected.
- Make `/ce-setup` the remediation path for gitignore safety as well as diagnostics: if `.compound-engineering/config.local.yaml` should exist and is not ignored, `/ce-setup` should explain why the file is machine-local and offer to add the `.gitignore` entry.
- Add a short shared warning contract to the core entry skills so they all route users toward `/ce-setup` from the same states, while full-preamble skills degrade locally rather than blocking or writing to stale paths when canonical CE storage cannot be resolved.
- Keep dependency detection registry-driven and MCP-aware, but update the output model so dependency gaps and config/storage gaps share one diagnostic report.
- Legacy `compound-engineering.local.md` exists; `/ce-doctor` reports obsolete-file cleanup needed and `/ce-setup` becomes the next action.
- Legacy file and new repo-local CE files both exist; `/ce-doctor` reports that the legacy file is obsolete and `/ce-setup` deletes it without attempting a semantic merge.
- New config exists but compatibility metadata is stale; `/ce-doctor` asks for rerun without relying on raw plugin semver.
-`.compound-engineering/config.local.yaml` is required but not gitignored; `/ce-doctor` reports the issue and `/ce-setup` offers to add the `.gitignore` entry.
-`ce:brainstorm` and `ce:plan` warn and continue because they can still read or write durable docs safely without project-state writes.
-`ce:work` and `ce:review` share the same warning vocabulary, derive canonical paths when possible, and otherwise report degraded persistence instead of writing to legacy paths.
- Dependency checks still distinguish CLI-present, MCP-present, and missing states.
**Verification:**
-`/ce-setup` prompt no longer implies a legacy markdown config target.
-`/ce-doctor` output contract covers config/storage state in addition to dependency health.
-`/ce-doctor` checks `.compound-engineering/config.local.yaml` gitignore safety rather than the old repo-local storage paths.
-`/ce-setup` can remediate `.compound-engineering/config.local.yaml` gitignore safety instead of only surfacing the problem.
- Core entry skills no longer invent their own migration wording or remediation instructions.
- Canonical per-project storage is derivable without `/ce-setup` having to pre-write that path into config.
- New contract tests pin the migration/reporting language so future edits do not regress it.
- [ ]**Unit 3: Move the todo system to per-project durable storage with legacy reads**
**Goal:** Re-home the durable todo lifecycle under `<user_state_dir>/projects/<project-slug>/todos/` while preserving the existing legacy-drain behavior from `todos/` and `.context/compound-engineering/todos/`.
- Update `todo-create` to treat the per-project path under `user_state_dir` as canonical, but keep both legacy directories in the read/ID-generation story until the drain period ends.
- Keep the status lifecycle unchanged: `pending` and `ready` remain load-bearing, only the storage location changes.
- Update all todo-producing skills to defer to `todo-create` conventions instead of hardcoding canonical paths inline.
**Goal:** Repoint per-run artifact instructions from repo-local `.context/compound-engineering/...` to `<user_state_dir>/projects/<project-slug>/<workflow>/...` without attempting historical migration.
-`ce:review` contract tests still enforce artifact-writing rules, but against the new path vocabulary.
-`feature-video` and `deepen-plan` examples no longer require repo-local `.context/compound-engineering/...`.
- Report-only guidance still forbids externalized writes regardless of exact path wording.
**Verification:**
- The highest-signal per-run artifact skills no longer treat `.context/compound-engineering/...` as their runtime contract.
- Storage contract tests pin the new path expectations for future edits.
- [ ]**Unit 5: Remove the old contract from converter and compatibility surfaces**
**Goal:** Update converter instructions, fixtures, and contract tests so installed targets no longer assert `compound-engineering.local.md`, `todos/`, or `.context/compound-engineering/...` as the stable CE contract.
- Replace literal assertions about legacy config/todo paths with assertions about the new state vocabulary or about skill text that remains platform-agnostic after conversion.
- Update PI/Codex helper text so converted skill guidance does not teach stale todo/config locations.
- Update active solution docs that still present the old runtime contract as current guidance, while leaving clearly historical plan/requirements docs intact unless they need a brief superseded note.
- Keep path rewriting logic minimal; if the new wording is sufficiently target-agnostic, prefer updating fixtures/tests over adding new target-specific rewriting behavior.
- Existing converter tests in [tests/converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/converter.test.ts)
**Test scenarios:**
- Converted command/skill bodies no longer assert `compound-engineering.local.md` as the canonical config target.
- PI conversion no longer describes todo workflows as `todos/ + /skill:todo-create`.
- Copilot/Codex tests still prove target-specific rewriting where that target genuinely owns a path transformation.
**Verification:**
-`bun test` passes for converter and skill-contract suites.
- Active docs that describe current CE runtime behavior no longer teach `compound-engineering.local.md` or repo-local durable storage as the live contract.
- No test fixture still encodes the old CE runtime contract as expected behavior.
## System-Wide Impact
- **Interaction graph:** `/ce-setup` becomes the only migration writer; `/ce-doctor` and core workflow skills become migration-state readers; todo/review/media/planning skills become consumers of the derived per-project storage path.
- **Error propagation:** Incorrect compatibility metadata or repo-identity resolution can cause stale-path fallbacks, false “rerun setup” warnings, or storage fragmentation across worktrees.
- **State lifecycle risks:** Todo ID collisions, stale obsolete-file cleanup behavior, and accidental commits of `.compound-engineering/config.local.yaml` are the main durable-state hazards.
- **User-experience risks:** If warning wording drifts between entry skills, users will receive contradictory guidance about whether they can proceed or must rerun `/ce-setup`.
- **API surface parity:** Converter outputs and copied skills must continue to make sense across Claude Code, Codex, Copilot, PI, and other pass-through targets without assuming one platform’s shell/tool naming.
- **Integration coverage:** Unit tests alone will not prove prompt-contract correctness; contract tests plus the converter suite need to cover the text surfaces that now encode the runtime model.
## Risks & Dependencies
- Legacy `compound-engineering.local.md` cleanup is intentionally destructive; the setup messaging has to be explicit so users understand the file is obsolete and no longer carries supported CE state.
- The path derivation contract depends on stable project slug resolution across worktrees; if that is underspecified, users can end up with split project state.
- The entry-skill warning contract spans multiple high-traffic workflows; if the copy is not kept deliberately short, this refactor could add prompt bloat to the plugin's most-used surfaces.
- Root and plugin AGENTS changes are part of the runtime contract now; if they drift from skill bodies, future skills will regress into mixed terminology and shell-heavy config loading.
- The converter/test cleanup depends on the final wording chosen for the new state vocabulary. Churn here is likely if execution changes the vocabulary again.
## Documentation / Operational Notes
- Update [plugins/compound-engineering/README.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/README.md) when setup/ce-doctor/storage behavior changes.
- Run `bun test` because the converter and contract-test surfaces are directly affected.
- Run `bun run release:validate` because skill descriptions and plugin docs are being updated.
- Do not hand-edit release-owned versions or changelogs.
- Related code: [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)
- Related code: [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)
- Related tests: [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Trevin Chow