john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ce-setup): unified setup skill with dependency management and config bootstrapping (#345)

Browse Source 
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Trevin Chow
2026-04-10 17:39:43 -07:00
committed by GitHub
parent 545405380d
commit 354dbb7582
12 changed files with 895 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -6,3 +6,5 @@ todos/
.worktrees
.context/
.claude/worktrees/
.compound-engineering/*.local.yaml

58
docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md
View File

@@ -1,58 +0,0 @@
---
date: 2026-03-24
topic: todo-path-consolidation
---
# Consolidate Todo Storage Under `.context/compound-engineering/todos/`
## Problem Frame
The file-based todo system currently stores todos in a top-level `todos/` directory. The plugin has standardized on `.context/compound-engineering/` as the consolidated namespace for CE workflow artifacts (scratch space, run artifacts, etc.). Todos should live there too for consistent organization. PR #345 is already adding the `.gitignore` check for `.context/`.
## Requirements
- R1. All skills that **create** todos must write to `.context/compound-engineering/todos/` instead of `todos/`.
- R2. All skills that **read** todos must check both `.context/compound-engineering/todos/` and legacy `todos/` to support natural drain of existing items.
- R3. All skills that **modify or delete** todos must operate on files in-place (wherever the file currently lives).
- R4. No active migration logic -- existing `todos/` files are resolved and cleaned up through normal workflow usage.
- R5. Skills that create or manage todos should reference the `file-todos` skill as the authority rather than encoding todo paths/conventions inline. This reduces scattered implementations and makes the path change a single-point update.
## Affected Skills
| Skill | Changes needed |
|-------|---------------|
| `file-todos` | Update canonical path, template copy target, all example commands. Add legacy read path. |
| `resolve-todo-parallel` | Read from both paths, resolve/delete in-place. |
| `triage` | Read from both paths, delete in-place. |
| `ce-review` | Replace inline `todos/` paths with delegation to `file-todos` skill. |
| `ce-review-beta` | Replace inline `todos/` paths with delegation to `file-todos` skill. |
| `test-browser` | Replace inline `todos/` path with delegation to `file-todos` skill. |
| `test-xcode` | Replace inline `todos/` path with delegation to `file-todos` skill. |
## Scope Boundaries
- No active file migration (move/copy) of existing todos.
- No changes to todo file format, naming conventions, or template structure.
- No removal of legacy `todos/` read support in this change -- that can be cleaned up later once confirmed drained.
## Key Decisions
- **Drain naturally over active migration**: Avoids migration logic, dead code, and conflicts with in-flight branches. Old todos resolve through normal usage.
## Success Criteria
- New todos created by any skill land in `.context/compound-engineering/todos/`.
- Existing todos in `todos/` are still found and resolvable.
- No skill references only the old `todos/` path for reads.
- Skills that create todos delegate to `file-todos` rather than encoding paths inline.
## Outstanding Questions
### Deferred to Planning
- [Affects R2][Technical] Determine the cleanest way to express dual-path reads in `file-todos` example commands (glob both paths vs. a helper pattern).
- [Affects R2][Needs research] Decide whether to add a follow-up task to remove legacy `todos/` read support after a grace period.
## Next Steps
-> `/ce:plan` for structured implementation planning

172
docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md Normal file
View File

@@ -0,0 +1,172 @@
---
date: 2026-03-25
topic: config-storage-redesign
---
# Config and Worktree-Safe Storage Redesign
## Problem Frame
The current branch improves `/ce-doctor` and `/ce-setup`, but it still assumes two foundations that do not hold up:
1. Plugin state lives inside the repo under `.context/compound-engineering/` or `todos/`, which breaks across git worktrees and Conductor-managed parallel checkouts.
2. Older plugin flows wrote `compound-engineering.local.md`, and parts of the repo still reference it, but main no longer treats review-agent selection as an active setup concern. Any new repo/user-level config system should not revive that removed model.
This work is broader than dependency setup alone. It needs one coherent model for:
- user-level defaults
- repo-level overrides
- machine-local overrides
- worktree-safe durable storage
- setup and doctor behavior
- skill instructions, docs, and tests that currently hardcode `compound-engineering.local.md` or `.context/compound-engineering/...`
Terminology for this document:
- `user_state_dir` = the user-level Compound Engineering directory, defaulting to `~/.compound-engineering`
- `repo_state_dir` = the repo-local Compound Engineering directory at `<repo>/.compound-engineering`
- per-project storage path = `<user_state_dir>/projects/<project-slug>/`
## Consolidation Notes
This document is the active consolidated requirements doc for the setup, config, and worktree-safe storage work. It replaces the earlier setup-dependency-management and todo-path-consolidation brainstorm docs and incorporates the external worktree-safe storage draft from the parallel `gwangju` workspace.
It changes the direction of two earlier efforts:
- The dependency-management work remains in scope, but `/ce-setup` can no longer write `compound-engineering.local.md`; any surviving YAML config is optional and minimal.
- The todo-path consolidation work is superseded by home-directory storage. The dual-read migration logic still matters for durable todo files, but `.context/compound-engineering/todos/` is no longer the end state.
## Requirements
- R1. Any new plugin config introduced by this work must use plain YAML files under `repo_state_dir`, specifically `config.yaml` and `config.local.yaml`. Config is data, not a markdown document.
- R2. Config must support a three-layer cascade with `local > project > global` precedence and first-found wins per key:
- `<user_state_dir>/config.yaml`
- `<repo_state_dir>/config.yaml`
- `<repo_state_dir>/config.local.yaml`
- R3. The config model must persist only active plugin-level behavior that truly needs durable storage, starting with minimal compatibility metadata if such metadata is still needed after planning. Deterministic path derivation under `user_state_dir` is runtime logic, not config data.
- R4. The new config model must not reintroduce removed review-agent selection or review-context storage behavior. Reviewer selection is now automatic in `/ce:review`, and project-specific guidance belongs in `CLAUDE.md` or `AGENTS.md`, not plugin-managed config files.
- R5. The YAML config shape may reorganize keys (for example, grouping review-related settings under a `review` object), but any such reshape must be applied consistently across all skills, docs, and tests that read or write config.
- R6. The new config format must include only the minimum compatibility metadata needed for the plugin to decide whether `/ce-setup` must be run again.
- R7. Compatibility checks must not rely only on plugin semver. If explicit versioning is needed, prefer a single setup or config contract revision that answers the practical question "is rerunning `/ce-setup` required?" Optional diagnostic metadata may be stored separately, but the requirements should not assume multiple independent version counters unless planning proves they are necessary.
- R8. `/ce-setup` must treat legacy `compound-engineering.local.md` as obsolete. If the surviving CE contract still requires machine-local persisted state, `/ce-setup` may write `repo_state_dir/config.local.yaml`; otherwise it should not invent stored values just to mirror deterministic runtime path derivation. Because the legacy file no longer contains any valid first-class CE settings, `/ce-setup` should explain that it is obsolete and delete it as part of cleanup rather than attempting a semantic migration.
- R9. `/ce-setup` must be the canonical place that executes config cleanup and any remaining compatibility migration. This flow should be safe to re-run, and it should handle at least these cases:
- legacy `compound-engineering.local.md` exists and no repo-local CE files exist yet
- legacy `compound-engineering.local.md` exists alongside `repo_state_dir/config.local.yaml`
- no repo-local CE files exist yet, but deterministic storage derivation still works
- R10. When legacy `compound-engineering.local.md` and new repo-local CE files both exist, the new CE contract is authoritative. `/ce-setup` should explain that the legacy file is obsolete and delete it rather than attempting to merge removed settings back into the new model.
- R11. `AGENTS.md` must define the config/storage contract section as a standard skill authoring criterion: every skill should include the approved compact header even if that specific skill does not currently consume config values, so the contract stays consistent across the plugin.
- R12. The standard config section and its instructions must be coding-agent cross-compatible. They must not assume Claude Code-only or Codex-only tool names, interaction patterns, or permission models.
- R13. The standard config section must be written to optimize for speed and execution reliability:
- prefer a minimal number of reads/tool calls
- avoid unnecessary shell fallbacks once config is established
- reduce permission prompts where the platform makes that possible
- keep wording concise so agents are more likely to execute it correctly
- R14. Independently invocable skills that depend on config or storage must use one standard full preamble that:
- prefers caller-passed resolved values
- deterministically resolves `repo_state_dir`, `user_state_dir`, and the per-project storage path
- reads local, project, and global YAML layers with the same precedence rules when those layers exist
- warns and routes to `/ce-setup` when migration or rerun is needed
- continues with degraded behavior rather than writing to legacy or guessed fallback paths when canonical config or storage cannot be resolved safely
`AGENTS.md` must also define and enforce the delegation rule: when a parent skill spawns an agent that needs configuration or storage values, the parent skill must pass the resolved values into the agent prompt rather than making the spawned agent re-resolve them unless that agent is independently invocable.
- R15. Migration warning behavior must be centralized rather than duplicated across the entire plugin. A small set of core entry skills, including `/ce-setup`, `/ce-doctor`, `/ce:brainstorm`, `/ce:plan`, `/ce:work`, and `/ce:review`, must detect legacy-only or conflicting config states and direct the user to run `/ce-setup` to migrate. Non-core skills should not each implement their own migration flow.
- R16. Core entry skills and `/ce-doctor` must use the compatibility metadata to distinguish the actionable states that matter to the user:
- no new config exists yet
- legacy-only or conflicting config exists and `/ce-setup` must migrate it
- new config exists but is below the required contract and `/ce-setup` must be rerun
- config is current and no rerun is needed
- R17. All durable plugin storage must resolve outside the repo tree under `user_state_dir`, with this fallback chain for determining `user_state_dir`:
- `$COMPOUND_ENGINEERING_HOME`
- `$XDG_DATA_HOME/compound-engineering` when `XDG_DATA_HOME` is set
- `~/.compound-engineering`
- R18. Durable per-project storage must live under `<user_state_dir>/projects/<project-slug>/`, where the slug is deterministic and stable across worktrees of the same repo.
- R19. Project identity must resolve from shared repo identity so all worktrees for the same repo share the same per-project storage path under `user_state_dir`. The primary identity source is `git rev-parse --path-format=absolute --git-common-dir`, and the directory-safe slug should be derived as `<sanitized-repo-name>-<short-hash>`. Non-git contexts must have a deterministic fallback.
- R20. The standard full preamble must be sufficient for independently invocable skills to deterministically resolve the canonical per-project storage path without requiring `/ce-setup` to pre-write that path into config.
- R21. Skills that read or write durable plugin state must use the per-project storage path under `user_state_dir` instead of repo-local `.context/compound-engineering/...` or `todos/` paths.
- R22. Durable todo files must retain legacy read compatibility from repo-local `todos/` and `.context/compound-engineering/todos/` until they drain naturally. New todo writes must go only to `<user_state_dir>/projects/<project-slug>/todos/`.
- R23. Per-run scratch and run-artifact directories do not need active migration from repo-local `.context/compound-engineering/...`; new writes move to `<user_state_dir>/projects/<project-slug>/<workflow>/...`.
- R24. `/ce-doctor` must remain a standalone entry point and expand from dependency/env checks to also report config and storage health:
- resolved config layers
- resolved `user_state_dir`
- resolved `repo_state_dir`
- resolved per-project storage path
- presence of legacy `compound-engineering.local.md`
- whether no repo-local CE file exists yet
- whether setup attention is needed because a legacy file still exists or compatibility metadata is stale
- whether rerunning setup is required because the stored compatibility metadata is below the required contract
- whether `.compound-engineering/config.local.yaml` is safely gitignored
- R25. `/ce-doctor` must continue to use a centralized dependency registry that lists known CLIs, MCP-backed capabilities, related environment variables, install guidance, tiering, and the skills/agents that depend on them.
- R26. `/ce-doctor` remains informational only. It reports dependency, env, config, and storage status, but it does not install tools or mutate user config beyond diagnostics.
- R27. `/ce-setup` must continue to include the dependency and environment flow already designed in this branch, but its output and guidance must target the new storage contract and any surviving YAML config state without inventing persisted path values that skills can derive deterministically.
- R28. If `.compound-engineering/config.local.yaml` is part of the surviving CE contract and is not safely gitignored, `/ce-setup` must explain why that file is machine-local and offer to add an appropriate `.gitignore` entry for it.
- R29. `/ce-setup` must present missing installable dependencies by tier, offer installation one item at a time with user approval, verify each install, and prompt for related environment variables at the appropriate point in the flow.
- R30. For dependencies with both MCP and CLI paths, diagnostics and setup must detect MCP availability first, then CLI availability, and only offer CLI installation if neither satisfies the dependency.
- R31. Dependency and env checks must always scan fresh on each run rather than relying on persisted installation state.
- R32. Skill content, docs, and tests must stop treating `.context/compound-engineering/...` and `compound-engineering.local.md` as the stable contract.
- R33. The config and storage contract must stay tool-agnostic across Claude Code, Codex, Gemini CLI, OpenCode, Copilot, and Conductor worktrees. This work should not introduce new provider-specific config paths.
## Success Criteria
- A user can run `/ce-setup` in the main checkout or any worktree and end up with the same resolved project storage location.
- Independently invocable skills that need CE state can derive the same canonical per-project storage path without requiring `/ce-setup` to pre-write that path.
- Users on the legacy config format get a clear migration path through `/ce-setup` without needing every individual skill to invent its own migration behavior.
- Core skills and `/ce-doctor` can determine whether `/ce-setup` must run again without relying on raw plugin semver comparisons or multiple unnecessary version counters.
- Todos and other durable workflow artifacts remain available across worktrees without symlinks, git hooks, or manual copying.
- Existing users with repo-local todo files do not lose access to unresolved work.
- Legacy `compound-engineering.local.md` files are cleaned up by `/ce-setup` after a brief explanation, without reviving removed review-agent selection behavior.
- `/ce-doctor` can explain both dependency gaps and config/storage misconfiguration in one report.
- `/ce-setup` can bring `.compound-engineering/config.local.yaml` under gitignore safely instead of only warning later.
- The dependency registry remains the single source of truth for `/ce-doctor` and `/ce-setup` rather than splitting dependency metadata across multiple docs or skills.
- Provider conversion tests and plugin docs reflect the new contract instead of the old file/path names.
## Scope Boundaries
- Do not add a full team-managed authoring workflow for tracked project config in `/ce-setup`; reading the project layer is in scope, authoring it is a separate effort.
- Do not auto-migrate per-run scratch or historical run artifacts out of `.context/compound-engineering/...`.
- Do not add storage garbage collection or project-directory pruning in this change.
- Do not preserve markdown-frontmatter config as a long-term supported format after migration; legacy support is for import/migration, not dual-write.
- Do not introduce provider-specific config directories for this feature.
- Do not auto-install dependencies without explicit user approval.
- Do not expand this work into project dependency management such as `bundle install`, `npm install`, or app-specific environment setup.
## Key Decisions
- **Home-directory storage is the durable answer:** repo-local `.context` is fine for scratch in a single checkout, but it is the wrong primitive for shared multi-worktree state.
- **Plain YAML replaces the legacy markdown config format:** if this work introduces plugin-managed config, it should do so with files in `repo_state_dir`, not by extending `compound-engineering.local.md`.
- **Legacy review config is not the target model:** main has already removed setup-managed reviewer selection. The new config system should focus on current setup-owned state such as storage and compatibility metadata, not on recreating reviewer preferences in a new file.
- **Compatibility metadata should stay minimal:** plugin semver alone is too coarse, but the fix is not to add version fields everywhere. Keep only the metadata needed to answer whether `/ce-setup` must run again.
- **Migration should have one owner:** `/ce-setup` should perform migration, `/ce-doctor` should report migration state, and a small set of entry skills should warn. Spreading migration logic across every skill creates drift and inconsistent user experience.
- **Todo migration deserves special handling:** unlike per-run artifacts, todo files have a multi-session lifecycle. Read compatibility is worth keeping during the transition.
- **Standard preamble, not universal prompt bloat:** use one shared config-loading pattern for independently invocable config/storage consumers and have parent skills pass resolved values to delegates. Requiring every skill to load config even when it does nothing with it adds carrying cost without enough value.
- **Standard section belongs in AGENTS.md:** the skill-level config instructions should be codified as a repo authoring rule so future skills inherit the same structure instead of drifting.
- **Cross-agent and low-friction wording matters:** the config section should be written against capability classes, minimal reads, and low-prompt execution patterns so it works well across Claude Code, Codex, Gemini, OpenCode, Copilot, and Conductor.
- **`/ce-doctor` and `/ce-setup` stay coupled but distinct:** doctor diagnoses; setup installs/configures. The new architecture should deepen that relationship, not replace it.
- **The dependency design from this branch carries forward:** registry-driven checks, tiered installs, env var prompting, and MCP-first detection still belong in scope. They just need to target the new config/storage contract.
- **Gitignore safety is part of the feature, not a follow-up:** if `/ce-setup` writes `.compound-engineering/config.local.yaml` into repos, the plugin must also verify that users will not accidentally commit it. The gitignore rule should target that machine-local file, not the entire `.compound-engineering/` directory.
## Dependencies / Assumptions
- The current `/ce-doctor` dependency registry and install flow remain the starting point for the dependency portion of this work.
- Skills and docs that currently reference `.context/compound-engineering/...` or `compound-engineering.local.md` will need an inventory-based update pass.
- Converter and contract tests that assert old config names or old storage paths are part of the affected surface, not incidental cleanup.
- `git worktree` metadata is available in normal git repos; planning still needs to define the exact fallback behavior for non-git contexts and edge cases.
## Outstanding Questions
### Deferred to Planning
- [Affects R3][Technical] Choose the exact YAML shape for any surviving setup-owned config such as compatibility metadata and any future plugin-level keys that still belong in plugin-managed config.
- [Affects R5][Technical] Define the smallest compatibility metadata shape that reliably tells the plugin whether `/ce-setup` must run again, and add extra diagnostic metadata only if it materially improves behavior.
- [Affects R15][Technical] Decide when a plugin change should bump the setup or migration requirement versus when it should be treated as backward-compatible.
- [Affects R17][Technical] Define the precise slugging and fallback algorithm for git repos, linked worktrees, and non-git directories.
- [Affects R21][Technical] Decide how long legacy todo read compatibility remains and where to document eventual removal.
- [Affects R13][Technical] Build the inventory of independently invocable skills that need direct config/storage loading versus parent-passed values.
- [Affects R23][Technical] Define the doctor output format for config/storage warnings and migration guidance.
- [Affects R30][Needs research] Inventory all docs, tests, and conversion fixtures that encode the old config/storage contract.
## Next Steps
-> `/ce:plan` for a phased implementation plan that starts by codifying the new config schema and migration strategy, then updates `/ce-setup` and `/ce-doctor`, then migrates storage consumers and tests.

4
docs/plans/2026-03-01-feat-ce-command-aliases-backwards-compatible-deprecation-plan.md
View File

@@ -75,7 +75,7 @@ The grep reveals `workflows:*` is referenced in **many more places** than just `
**Skills (update to new names):**
- `skills/document-review/SKILL.md` — references `/workflows:brainstorm`, `/workflows:plan`
- `skills/git-worktree/SKILL.md` — references `/workflows:review`, `/workflows:work` extensively
- `skills/setup/SKILL.md` — references `/workflows:review`, `/workflows:work`
- `skills/ce-setup/SKILL.md` — references `/workflows:review`, `/workflows:work`
- `skills/brainstorming/SKILL.md` — references `/workflows:plan` multiple times
- `skills/file-todos/SKILL.md` — references `/workflows:review`
@@ -209,7 +209,7 @@ NOTE: /workflows:<command> is deprecated. Please use /ce:<command> instead. This
**Skills:**
- `skills/document-review/SKILL.md`
- `skills/git-worktree/SKILL.md`
- `skills/setup/SKILL.md`
- `skills/ce-setup/SKILL.md`
- `skills/brainstorming/SKILL.md`
- `skills/file-todos/SKILL.md`

8
docs/plans/2026-03-01-fix-setup-skill-non-claude-llm-fallback-plan.md
View File

@@ -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
- `src/utils/codex-agents.ts` — Strengthen AskUserQuestion mapping (line 21)
- `plugins/compound-engineering/CLAUDE.md` — Add AskUserQuestion policy to skill compliance checklist
@@ -131,7 +131,7 @@ Add to the "Skill Compliance Checklist" in `plugins/compound-engineering/CLAUDE.
## Sources & References
- Issue: [#204](https://github.com/EveryInc/compound-engineering-plugin/issues/204)
- `plugins/compound-engineering/skills/setup/SKILL.md:13,44,67,85,104`
- `plugins/compound-engineering/skills/ce-setup/SKILL.md`
- `plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md:22,45`
- `src/utils/codex-agents.ts:21`
- `src/converters/claude-to-pi.ts:106` — Pi converter (reference pattern)

151
docs/plans/2026-03-24-001-refactor-todo-path-consolidation-plan.md
View File

@@ -1,151 +0,0 @@
---
title: "refactor: Consolidate todo storage under .context/compound-engineering/todos/"
type: refactor
status: completed
date: 2026-03-24
origin: docs/brainstorms/2026-03-24-todo-path-consolidation-requirements.md
---
# 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
- [ ] `bun run release:validate` passes
## Implementation Phases
### Phase 1: Update `file-todos` (Foundation)
**File:** `plugins/compound-engineering/skills/file-todos/SKILL.md`
This is the authoritative skill -- all other changes depend on getting this right first.
Changes:
1. **YAML frontmatter description** (line 3): Update `todos/ directory` to `.context/compound-engineering/todos/`
2. **Overview section** (lines 10-11): Update canonical path reference
3. **Directory Structure section**: Update path references
4. **Creating a New Todo workflow** (line 76-77):
- 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."
### Phase 2: Update Consumer Skills (Parallel -- Independent)
These 4 skills only **create** todos. They should delegate to `file-todos` rather than encoding paths inline (R5).
#### 2a. `ce-review` skill
**File:** `plugins/compound-engineering/skills/ce-review/SKILL.md`
Changes:
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)
#### 2b. `ce-review-beta` skill
**File:** `plugins/compound-engineering/skills/ce-review-beta/SKILL.md`
Changes:
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
#### 2c. `test-browser` skill
**File:** `plugins/compound-engineering/skills/test-browser/SKILL.md`
Changes:
1. **Line 228**: Change `Add to todos/ for later` to `Create a todo using the file-todos skill conventions`
2. **Line 233**: Update `{id}-pending-p1-browser-test-{description}.md` creation path or delegate to file-todos
#### 2d. `test-xcode` skill
**File:** `plugins/compound-engineering/skills/test-xcode/SKILL.md`
Changes:
1. **Line 142**: Change `Add to todos/ for later` to `Create a todo using the file-todos skill conventions`
2. **Line 147**: Update todo creation path or delegate to file-todos
### Phase 3: Update Reader Skills (Sequential after Phase 1)
These skills **read and operate on** existing todos. They need dual-path support.
#### 3a. `triage` skill
**File:** `plugins/compound-engineering/skills/triage/SKILL.md`
Changes:
1. **Line 9**: Update `todos/ directory` to reference both paths
2. **Lines 152, 275**: Change "Remove it from todos/ directory" to path-agnostic language ("Remove the todo file from its current location")
3. **Lines 185-186**: Update summary template from `Removed from todos/` to `Removed`
4. **Line 193**: Update `Deleted: Todo files for skipped findings removed from todos/ directory`
5. **Line 200**: Update `ls todos/*-ready-*.md` to scan both directories
#### 3b. `resolve-todo-parallel` skill
**File:** `plugins/compound-engineering/skills/resolve-todo-parallel/SKILL.md`
Changes:
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

367
docs/plans/2026-03-25-002-refactor-config-storage-redesign-plan.md Normal file
View File

@@ -0,0 +1,367 @@
---
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/<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
Project slug:
- identity source: `git rev-parse --path-format=absolute --git-common-dir`
- 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.
**Requirements:** R1-R5, R11-R14, R31-R32
**Dependencies:** None
**Files:**
- Modify: [AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/AGENTS.md)
- Modify: [plugins/compound-engineering/AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/AGENTS.md)
- Modify: [plugins/compound-engineering/README.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/README.md)
**Approach:**
- 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.
**Patterns to follow:**
- [plugins/compound-engineering/AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/AGENTS.md)
- [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)
**Test scenarios:**
- 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.
**Requirements:** R6-R10, R15-R16, R20, R24-R31
**Dependencies:** Unit 1
**Files:**
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [plugins/compound-engineering/skills/ce-doctor/references/dependency-registry.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/references/dependency-registry.md)
- Create: [tests/ce-setup-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/ce-setup-skill-contract.test.ts)
- Create: [tests/ce-doctor-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/ce-doctor-skill-contract.test.ts)
- Create: [tests/entry-skill-config-warning-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/entry-skill-config-warning-contract.test.ts)
**Approach:**
- 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.
**Patterns to follow:**
- [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-doctor/scripts/check-health](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/scripts/check-health)
- [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)
**Test scenarios:**
- 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/`.
**Requirements:** R17-R23, R31-R32
**Dependencies:** Unit 2
**Files:**
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [plugins/compound-engineering/skills/test-browser/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/test-browser/SKILL.md)
- Modify: [plugins/compound-engineering/skills/test-xcode/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/test-xcode/SKILL.md)
- Create: [tests/todo-storage-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/todo-storage-contract.test.ts)
**Approach:**
- 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.
**Patterns to follow:**
- [docs/solutions/workflow/todo-status-lifecycle.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/workflow/todo-status-lifecycle.md)
- [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)
**Test scenarios:**
- New todo creation writes to the per-project path under `user_state_dir`.
- Next-ID generation avoids collisions when IDs exist across both legacy directories and the new canonical path.
- `todo-triage` and `todo-resolve` still find pending/ready items from both legacy locations.
- `ce:review`, `test-browser`, and `test-xcode` continue to create actionable todos without embedding stale paths.
**Verification:**
- Todo contract tests prove canonical-write + legacy-read behavior.
- No todo-producing skill still claims `.context/compound-engineering/todos/` is the long-term canonical location.
- [ ] **Unit 4: Move per-run artifact skills to derived per-project paths**
**Goal:** Repoint per-run artifact instructions from repo-local `.context/compound-engineering/...` to `<user_state_dir>/projects/<project-slug>/<workflow>/...` without attempting historical migration.
**Requirements:** R17-R23, R31-R32
**Dependencies:** Unit 2
**Files:**
- Modify: [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)
- Modify: [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)
- Modify: [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)
- Modify: [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)
- Create: [tests/storage-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/storage-skill-contract.test.ts)
**Approach:**
- Update the run-artifact instructions to use the derived per-project path terminology rather than hardcoded `.context/compound-engineering/...`.
- Keep report-only prohibitions path-agnostic where possible so the policy survives future directory changes.
- Do not add active migration logic for old artifact directories; simply change future-write instructions.
**Patterns to follow:**
- [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)
- [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)
**Test scenarios:**
- `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.
**Requirements:** R31-R32
**Dependencies:** Units 1-4
**Files:**
- Modify: [src/utils/codex-agents.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/utils/codex-agents.ts)
- Modify: [src/converters/claude-to-pi.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/converters/claude-to-pi.ts)
- Modify: [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)
- Modify: [tests/converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/converter.test.ts)
- Modify: [tests/codex-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/codex-converter.test.ts)
- Modify: [tests/copilot-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/copilot-converter.test.ts)
- Modify: [tests/pi-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/pi-converter.test.ts)
**Approach:**
- 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.
**Patterns to follow:**
- [docs/solutions/codex-skill-prompt-entrypoints.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/codex-skill-prompt-entrypoints.md)
- 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.
## Sources & References
- **Origin document:** [docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md)
- 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)

2
plugins/compound-engineering/README.md
View File

@@ -73,7 +73,7 @@ The primary entry points for engineering work, invoked as slash commands:
|-------|-------------|
| `claude-permissions-optimizer` | Optimize Claude Code permissions from session history |
| `document-review` | Review documents using parallel persona agents for role-specific feedback |
| `setup` | Reserved for future project-level workflow configuration; code review agent selection is automatic |
| `ce-setup` | Diagnose and configure environment: checks CLI deps, MCP servers, env vars, plugin version, and repo-local config; offers guided installation for missing tools |
### Content & Collaboration

156
plugins/compound-engineering/skills/ce-setup/SKILL.md Normal file
View File

@@ -0,0 +1,156 @@
---
name: ce-setup
description: "Diagnose and configure compound-engineering environment. Checks CLI dependencies, plugin version, and repo-local config. Offers guided installation for missing tools. Use when troubleshooting missing tools, verifying setup, or before onboarding."
disable-model-invocation: true
---
# Compound Engineering Setup
## Interaction Method
Ask the user each question below using the platform's blocking question tool (e.g., `AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no structured question tool is available, present each question as a numbered list and wait for a reply before proceeding. For multiSelect questions, accept comma-separated numbers (e.g. `1, 3`). Never skip or auto-configure.
Interactive setup for compound-engineering — diagnoses environment health, cleans obsolete repo-local CE config, and helps configure required tools. Review agent selection is handled automatically by `ce:review`; project-specific review guidance belongs in `CLAUDE.md` or `AGENTS.md`.
## Phase 1: Diagnose
### Step 1: Determine Plugin Version
Detect the installed compound-engineering plugin version by reading the plugin metadata or manifest. This is platform-specific -- use whatever mechanism is available (e.g., reading `plugin.json` from the plugin root or cache directory). If the version cannot be determined, skip this step.
If a version is found, pass it to the check script via `--version`. Otherwise omit the flag.
### Step 2: Run the Health Check Script
Before running the script, display: "Compound Engineering -- checking your environment..."
Run the bundled check script. Do not perform manual dependency checks -- the script handles all CLI tools, repo-local CE file checks, and `.gitignore` guidance in one pass.
```bash
bash scripts/check-health --version VERSION
```
Or without version if Step 1 could not determine it:
```bash
bash scripts/check-health
```
Script reference: `scripts/check-health`
Display the script's output to the user.
### Step 3: Evaluate Results
**Platform detection (pre-resolved):** !`[ -n "${CLAUDE_PLUGIN_ROOT}" ] && echo "CLAUDE_CODE" || echo "OTHER"`
If the line above resolved to `CLAUDE_CODE`, this is a Claude Code session and `/ce-update` is available. Otherwise, omit any `/ce-update` references from output.
After the diagnostic report, check whether:
- any dependencies are missing (reported as yellow in the script output)
- `compound-engineering.local.md` is present and needs cleanup
- `.compound-engineering/config.local.yaml` does not exist or is not safely gitignored
- `.compound-engineering/config.local.example.yaml` is missing or outdated
If everything is installed, no repo-local cleanup is needed, and `.compound-engineering/config.local.yaml` already exists and is gitignored, display the tool list and completion message. Parse the tool names from the script output and list each with a green circle:
```
✅ Compound Engineering setup complete
Tools: 🟢 agent-browser 🟢 gh 🟢 jq 🟢 vhs 🟢 silicon 🟢 ffmpeg
Config: ✅
Run /ce-setup anytime to re-check.
```
If this is a Claude Code session, append to the message: "Run /ce-update to grab the latest plugin version."
Stop here.
Otherwise proceed to Phase 2 to resolve any issues. Handle repo-local cleanup (Step 4) first, then config bootstrapping (Step 5), then missing dependencies (Step 6).
## Phase 2: Fix
### Step 4: Resolve Repo-Local CE Issues
Resolve the repository root (`git rev-parse --show-toplevel`). If `compound-engineering.local.md` exists at the repo root, explain that it is obsolete because review-agent selection is automatic and CE now uses `.compound-engineering/config.local.yaml` for any surviving machine-local state. Ask whether to delete it now. Use the repo-root path when deleting.
### Step 5: Bootstrap Project Config
Resolve the repository root (`git rev-parse --show-toplevel`). All paths below are relative to the repo root, not the current working directory.
**Example file (always refresh):** Copy `references/config-template.yaml` to `<repo-root>/.compound-engineering/config.local.example.yaml`, creating the directory if needed. This file is committed to the repo and always overwritten with the latest template so teammates can see available settings.
**Local config (create once):** If `.compound-engineering/config.local.yaml` does not exist, ask whether to create it:
```
Set up a local config file for this project?
This saves your Compound Engineering preferences (like which tools to use and how workflows behave).
Everything starts commented out -- you only enable what you need.
1. Yes, create it (Recommended)
2. No thanks
```
If the user approves, copy `references/config-template.yaml` to `<repo-root>/.compound-engineering/config.local.yaml`. If `.compound-engineering/config.local.yaml` is not already covered by `.gitignore`, offer to add the entry:
```text
.compound-engineering/*.local.yaml
```
If the local config already exists, check whether it is safely gitignored. If not, offer to add the `.gitignore` entry as above.
### Step 6: Offer Installation
Present the missing dependencies using a multiSelect question with all items pre-selected. Use the install commands and URLs from the script's diagnostic output.
```
The following tools are missing. Select which to install:
(All items are pre-selected)
Recommended:
[x] agent-browser - Browser automation for testing and screenshots
[x] gh - GitHub CLI for issues and PRs
[x] jq - JSON processor
[x] vhs (charmbracelet/vhs) - Create GIFs from CLI output
[x] silicon (Aloxaf/silicon) - Generate code screenshots
[x] ffmpeg - Video processing for feature demos
```
Only show dependencies that are actually missing. Omit installed ones.
### Step 7: Install Selected Dependencies
For each selected dependency, in order:
1. **Show the install command** (from the diagnostic output) and ask for approval:
```
Install agent-browser?
Command: CI=true npm install -g agent-browser --no-audit --no-fund --loglevel=error && agent-browser install && npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser -g -y
1. Run this command
2. Skip - I'll install it manually
```
2. **If approved:** Run the install command using a shell execution tool. After the command completes, verify installation by running the dependency's check command (e.g., `command -v agent-browser`).
3. **If verification succeeds:** Report success.
4. **If verification fails or install errors:** Display the project URL as fallback and continue to the next dependency.
### Step 8: Summary
Display a brief summary:
```
✅ Compound Engineering setup complete
Installed: agent-browser, gh, jq
Skipped: rtk
Run /ce-setup anytime to re-check.
```
If this is a Claude Code session (per platform detection in Step 3), append: "Run /ce-update to grab the latest plugin version."

12
plugins/compound-engineering/skills/ce-setup/references/config-template.yaml Normal file
View File

@@ -0,0 +1,12 @@
# Compound Engineering -- local config
# Copy to .compound-engineering/config.local.yaml in your project root.
# All settings are optional. Invalid values fall through to defaults.
# --- Work delegation (Codex) ---
# work_delegate: codex # codex | false (default: false)
# work_delegate_consent: true # true | false (default: false)
# work_delegate_sandbox: yolo # yolo | full-auto (default: yolo)
# work_delegate_decision: auto # auto | ask (default: auto)
# work_delegate_model: gpt-5.4 # any valid codex model (default: gpt-5.4)
# work_delegate_effort: high # minimal | low | medium | high | xhigh (default: high)

179
plugins/compound-engineering/skills/ce-setup/scripts/check-health Executable file
View File

@@ -0,0 +1,179 @@
#!/usr/bin/env bash
# Compound Engineering environment health check
# Outputs a formatted diagnostic report in one pass
set -o pipefail
# =====================================================
# Dependency config
# =====================================================
# Format: name|tier|install_cmd|url
# Tiers: recommended (flagged if missing), optional (noted if missing)
# To add a dependency: add a line here. No other changes needed.
deps=(
"agent-browser|recommended|CI=true npm install -g agent-browser --no-audit --no-fund --loglevel=error && agent-browser install && npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser -g -y|https://github.com/vercel-labs/agent-browser"
"gh|recommended|NONINTERACTIVE=1 HOMEBREW_NO_AUTO_UPDATE=1 brew install -q gh|https://cli.github.com"
"jq|recommended|NONINTERACTIVE=1 HOMEBREW_NO_AUTO_UPDATE=1 brew install -q jq|https://jqlang.github.io/jq/"
"vhs|recommended|NONINTERACTIVE=1 HOMEBREW_NO_AUTO_UPDATE=1 brew install -q vhs|https://github.com/charmbracelet/vhs"
"silicon|recommended|NONINTERACTIVE=1 HOMEBREW_NO_AUTO_UPDATE=1 brew install -q silicon|https://github.com/Aloxaf/silicon"
"ffmpeg|recommended|NONINTERACTIVE=1 HOMEBREW_NO_AUTO_UPDATE=1 brew install -q ffmpeg|https://ffmpeg.org/download.html"
)
# =====================================================
# Args
# =====================================================
# --version VERSION (optional) plugin version to display (passed by the agent)
plugin_version=""
while [ $# -gt 0 ]; do
case "$1" in
--version) [ -n "$2" ] && plugin_version="$2" && shift 2 || shift ;;
*) shift ;;
esac
done
# =====================================================
# Helpers
# =====================================================
ok() { echo " 🟢 $1"; }
fail() { echo " 🔴 $1"; }
warn() { echo " 🟡 $1"; }
skip() { echo " ➖ $1"; }
detail() { echo " $1"; }
section() { echo ""; echo " $1"; }
has_brew=$(command -v brew >/dev/null 2>&1 && echo "yes" || echo "no")
in_repo=$(git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "yes" || echo "no")
# =====================================================
# Check tools
# =====================================================
cli_ok=0; cli_total=0; issues=0
results=()
for entry in "${deps[@]}"; do
IFS='|' read -r name tier install_cmd url <<< "$entry"
cli_total=$((cli_total + 1))
if command -v "$name" >/dev/null 2>&1; then
cli_ok=$((cli_ok + 1))
results+=("$name|$tier|ok|$install_cmd|$url")
else
results+=("$name|$tier|missing|$install_cmd|$url")
fi
done
# =====================================================
# Project checks (repo only)
# =====================================================
legacy_cfg="skip"
repo_cfg_gitignore="skip"
example_cfg="skip"
if [ "$in_repo" = "yes" ]; then
repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
legacy_cfg="missing"
[ -f "$repo_root/compound-engineering.local.md" ] && legacy_cfg="present"
if [ -e "$repo_root/.compound-engineering/config.local.yaml" ] || [ -d "$repo_root/.compound-engineering" ]; then
if git check-ignore -q "$repo_root/.compound-engineering/config.local.yaml" 2>/dev/null; then
repo_cfg_gitignore="ok"
else
repo_cfg_gitignore="missing"
fi
fi
script_dir="$(cd "$(dirname "$0")" && pwd)"
template="$script_dir/../references/config-template.yaml"
example="$repo_root/.compound-engineering/config.local.example.yaml"
if [ ! -f "$example" ]; then
example_cfg="missing"
elif [ -f "$template" ] && ! diff -q "$template" "$example" >/dev/null 2>&1; then
example_cfg="outdated"
else
example_cfg="ok"
fi
fi
# =====================================================
# Output
# =====================================================
echo ""
if [ -n "$plugin_version" ]; then
ok "Plugin version v${plugin_version}"
fi
# --- Tools ---
section "Tools ${cli_ok}/${cli_total}"
for result in "${results[@]}"; do
IFS='|' read -r name tier status install_cmd url <<< "$result"
if [ "$status" = "ok" ]; then
ok "$name"
else
warn "$name"
issues=$((issues + 1))
case "$install_cmd" in
*brew\ install*)
if [ "$has_brew" = "yes" ]; then detail "$install_cmd"
else detail "$url"; fi ;;
*)
detail "$install_cmd"
detail "$url" ;;
esac
fi
done
# --- Project ---
if [ "$in_repo" = "yes" ]; then
has_project_issues="no"
if [ "$legacy_cfg" = "present" ]; then
has_project_issues="yes"
fi
if [ "$repo_cfg_gitignore" = "missing" ]; then
has_project_issues="yes"
fi
if [ "$example_cfg" = "missing" ] || [ "$example_cfg" = "outdated" ]; then
has_project_issues="yes"
fi
if [ "$has_project_issues" = "yes" ]; then
section "Project"
if [ "$legacy_cfg" = "present" ]; then
warn "Outdated Compound Engineering config in this repo"
issues=$((issues + 1))
fi
if [ "$repo_cfg_gitignore" = "missing" ]; then
warn "Local config not safely gitignored"
issues=$((issues + 1))
fi
if [ "$example_cfg" = "missing" ]; then
warn "Example config missing (.compound-engineering/config.local.example.yaml)"
issues=$((issues + 1))
elif [ "$example_cfg" = "outdated" ]; then
warn "Example config outdated (new settings available)"
issues=$((issues + 1))
fi
fi
fi
# --- Bottom line ---
echo ""
if [ "$issues" -eq 0 ]; then
echo " ✅ All clear ${cli_ok}/${cli_total} tools"
else
echo " ⚠️ ${issues} issue(s) found ${cli_ok}/${cli_total} tools"
fi
echo ""

21
plugins/compound-engineering/skills/setup/SKILL.md
View File

@@ -1,21 +0,0 @@
---
name: setup
description: Configure project-level settings for compound-engineering workflows. Currently a placeholder — review agent selection is handled automatically by ce:review.
disable-model-invocation: true
---
# Compound Engineering Setup
Project-level configuration for compound-engineering workflows.
## Current State
Review agent selection is handled automatically by the `ce:review` skill, which uses intelligent tiered selection based on diff content. No per-project configuration is needed for code reviews.
If this skill is invoked, inform the user:
> Review agent configuration is no longer needed — `ce:review` automatically selects the right reviewers based on your diff. Project-specific review context (e.g., "we serve 10k req/s" or "watch for N+1 queries") belongs in your project's CLAUDE.md or AGENTS.md, where all agents already read it.
## Future Use
This skill is reserved for future project-level configuration needs beyond review agent selection.