github-featured/everyinc--compound-engineering-plugin

Files

T

Trevin Chow 15ab6f76bb fix(skills): complete below-cap refactor sweep (#1490 )

2026-08-19 19:34:17 -07:00

9.0 KiB

Raw Permalink Blame History

`ce-setup`

Check Compound Engineering health, optional tool capabilities, and repo-local config safety. It does not bulk-install the plugin's dependencies.

ce-setup is a diagnosis and config utility. It reports which optional tools are on PATH, creates repo config.yaml when missing (after you approve), refreshes the committed config example, and offers to gitignore a local override or CE scratch space. It also reports where artifacts will land and can repair an invalid docs_root or a broken CE Work engine block.

It is explicit-invocation only (disable-model-invocation: true). Talking about setup does not start it.

Outside a git repository it reports capabilities and stops. It does not create repo files there.

See Compound Engineering configuration for every option and how local defaults interact with session and project instructions.

TL;DR

Question	Answer
What does it do?	Runs a health check, reports optional tools, refreshes the example config, and applies only the repo-local fixes you approve
When to use it	First install, after an upgrade, when a skill says a tool is missing, or when onboarding a repo
What it produces	A setup report, plus any config or gitignore edits you accepted
What it does not do	Bulk-install every optional CE dependency, update the plugin itself, or create `config.local.yaml`

Example invocations

The skill takes no feature argument. The same command covers first install, a later re-check, and a repo that is not a git checkout.

# First install, or a later re-check of tools and repo config
/ce-setup

# Same command after a plugin upgrade, to refresh
# .compound-engineering/config.example.yaml and notice new keys
/ce-setup

# Same command when a skill said gh, agent-browser, or another
# optional tool is missing. The report prints the install command.
/ce-setup

# Same command in a directory that is not a git repo.
# It reports optional tools and stops without writing files.
/ce-setup

On oh-my-pi the invocation is /skill:ce-setup. On Codex it is $ce-setup when that host uses dollar-prefixed skills.

The Problem

Compound Engineering has two different setup surfaces:

Repo-local state that should stay consistent and safe: the committed config example, the repo config.yaml, gitignore coverage if a config.local.yaml override exists, and (optionally) gitignore coverage for .context/compound-engineering/ scratch.
Optional external tools used by specific workflows: agent-browser for browser testing and dogfood QA, gh for GitHub, jq for shell JSON, ast-grep for structural search, ffmpeg for Riffrec media analysis.

A missing optional tool is not a broken plugin. Treating those as one install step forces a dependency footprint most workflows never use.

The Solution

ce-setup diagnoses first, then remediates only repo-local project issues. The example config is refreshed on its own. Other writes wait for approval:

Deletes obsolete compound-engineering.local.md if you say yes.
Refreshes .compound-engineering/config.example.yaml from the bundled template. Always, inside a git repo.
Offers to create .compound-engineering/config.yaml if it is missing. Does not create config.local.yaml. Does not overwrite either file if it already exists.
Offers to add .compound-engineering/*.local.yaml to .gitignore only when config.local.yaml already exists and is not ignored.
Offers to add .context/compound-engineering/ to .gitignore whether or not that directory exists yet. An uncovered path is a note, not a project issue.
Reports the resolved artifact root and which config layer supplied it. An invalid docs_root is a project issue. CE artifacts will not be written until it is fixed. See Artifact root.
Explains and repairs an invalid CE Work implementation-engine block, or leftover retired routing keys, in the layer that supplied the bad value.
Prints install commands or URLs for missing optional tools. It does not bulk-install them.

Each question uses the host's blocking question tool when one exists. It does not silently auto-configure.

What Makes It Novel

Capabilities are informational

Missing ffmpeg or ast-grep does not fail setup. The report says which workflows those tools serve and how to install them. You install only what you use.

Repo files are opt-in writes

The example config is the one file it refreshes on its own (it is the committed template copy). Creating config.yaml, appending gitignore lines, deleting the obsolete local-md file, and editing a broken docs_root or work-engine block all wait for approval. Existing config.yaml and config.local.yaml are never overwritten wholesale.

It tells you where artifacts will land

The health report includes the resolved artifact root (docs/ by default, or a valid docs_root from config.yaml). docs_root in config.local.yaml is ignored. If local still has one, setup says so and offers to move it into config.yaml.

Optional Capabilities

Tool	Capability
`agent-browser`	browser testing and dogfood QA
`gh`	GitHub PR, issue, and review workflows
`jq`	JSON inspection in shell-based workflows
`ast-grep`	Syntax-aware structural code search
`ffmpeg`	Media chunking and screenshot extraction for Riffrec analysis

Quick Example

You just installed compound-engineering and want to check a repo:

/ce-setup

The health check reports something like:

Optional capabilities  3/5
  🟢  agent-browser -- browser testing and dogfood QA
  🟢  gh -- GitHub PR, issue, and review workflows
  🟡  ast-grep -- unavailable: syntax-aware structural code search
       brew install -q ast-grep

Project config
  🟢  No obsolete compound-engineering.local.md
  ➖  No repo config yet (.compound-engineering/config.yaml)
  🟡  Example config missing (.compound-engineering/config.example.yaml)

It refreshes the example config and asks whether to create .compound-engineering/config.yaml. It does not create config.local.yaml. Missing optional tools stay in the summary as install hints.

When the bundled health script is not runnable, the skill runs the same checks inline and still offers the repo-local fixes.

When to Reach For It

Use ce-setup when:

You just installed or upgraded the plugin
You want to verify a repo's CE config, artifact root, and gitignore state
A workflow reported an optional tool missing and you want the install command
You are onboarding a repo to .compound-engineering/config.yaml
Health marked docs_root or the CE Work engine block invalid

Skip it when:

You already know the exact tool to install
You are trying to update the plugin itself (use the host plugin manager)
You want every possible CE binary installed in one shot. This skill will not do that.

Use Standalone

ce-setup is not a pipeline stage. Run it when you need a diagnosis or a safe config write. Re-run anytime. The summary prints the same invocation so you can do that.

Reference

Argument	Effect
(empty)	Diagnose, then remediate repo-local issues you approve. Outside a git repo: report optional tools and stop.

Phase	Step
Diagnose	Plugin version when the host exposes it, optional capabilities, project config, artifact root, work-engine block
Fix	Obsolete local-md, example refresh, create repo config if wanted, gitignore safety, scratch-space gitignore, repair invalid `docs_root` or work-engine prefs
Summary	Fixes applied, skipped actions, missing optional tools

FAQ

Why does setup not install everything? Most CE workflows do not need every optional tool, and modern harnesses already provide some capture and browser affordances. Setup reports capabilities instead of forcing a broad install.

What is compound-engineering.local.md and why is it obsolete? It was the old machine-local config file. Team defaults now live in .compound-engineering/config.yaml. config.local.yaml is the optional per-checkout override. Review-agent selection is automatic.

Why might .compound-engineering/config.local.yaml be gitignored? It is the optional override. The committed config.example.yaml shows available settings. Setup creates the repo file, not the override.

Does it run on non-Claude-Code platforms? Yes. When the bundled health script is not directly runnable, the skill falls back to equivalent inline checks and still performs repo-local config remediation.

9.0 KiB Raw Permalink Blame History Unescape Escape

ce-setup