# `ce-setup`

> Check Compound Engineering health, optional tool capabilities, and repo-local config safety.

`ce-setup` is the lightweight onboarding and troubleshooting skill. It reports which optional tools are available, cleans obsolete local config, refreshes the committed config example, and helps keep machine-local settings out of git.

It is explicit-invocation only (`disable-model-invocation: true`) so it never runs as a side effect of ordinary setup discussion.

---

## TL;DR

| Question | Answer |
|----------|--------|
| What does it do? | Runs a health check, reports optional tool capabilities, refreshes `.compound-engineering/config.local.example.yaml`, optionally creates `.compound-engineering/config.local.yaml`, and helps gitignore local config |
| When to use it | First install, after upgrades, when a skill says an optional tool is missing, or when onboarding a repo |
| What it produces | A setup report plus repo-local config fixes the user approved |
| What it does not do | Bulk-install every possible CE dependency |

---

## The Problem

Compound Engineering has two kinds of setup:

- **Repo-local state** that should be consistent and safe: the committed config example, the optional machine-local config file, and `.gitignore` coverage for local settings.
- **Optional external tools** used by specific workflows: `agent-browser` for browser testing/polish, `gh` for GitHub workflows, `jq` for shell JSON inspection, `ast-grep` for structural code search, and `ffmpeg` for Riffrec media analysis.

Those are different concerns. Missing optional tools should not make the whole plugin feel broken.

## The Solution

`ce-setup` runs a diagnostic, then only remediates repo-local project issues:

- Deletes obsolete `compound-engineering.local.md` after confirmation.
- Refreshes `.compound-engineering/config.local.example.yaml` from the bundled template.
- Offers to create `.compound-engineering/config.local.yaml` if missing.
- Offers to add `.compound-engineering/*.local.yaml` to `.gitignore` if needed.
- Prints install commands or URLs for missing optional tools, but does not bulk-install them.

---

## Optional Capabilities

| Tool | Capability |
|------|------------|
| `agent-browser` | Browser testing, dogfood QA, and visual polish inspection |
| `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 |

Missing tools are informational. Install only the tools needed for the workflows you actually use.

---

## Quick Example

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

```text
/ce-setup
```

The skill runs the health check and reports:

```text
Optional capabilities  3/5
  🟢 agent-browser -- browser testing, dogfood QA, and visual polish inspection
  🟢 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 local config yet (.compound-engineering/config.local.yaml)
  🟡 Example config missing (.compound-engineering/config.local.example.yaml)
```

It refreshes the example config. If you want local preferences, it asks before creating `.compound-engineering/config.local.yaml` and before adding the `.gitignore` entry.

---

## 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 and gitignore state.
- A workflow reports an optional tool is missing and you want the install command.
- You are onboarding a new repo to `.compound-engineering/config.local.yaml`.

Skip it when:

- You already know the exact tool you need to install.
- You are trying to update the plugin itself; use the host plugin manager for that.

---

## Reference

| Phase | Step |
|-------|------|
| Diagnose | Determine plugin version, run health check, report optional capabilities and project config |
| Fix | Remove obsolete local config, refresh example config, create local config if wanted, ensure gitignore safety |
| Summary | Report fixes applied, skipped actions, and missing optional tools |

---

## FAQ

**Why does setup no longer install everything?**
Most CE workflows do not need every optional tool, and modern coding harnesses now provide their own capture and browser affordances. Setup reports capabilities instead of forcing a broad dependency footprint.

**What's `compound-engineering.local.md` and why is it obsolete?**
It was the old machine-local config format. Surviving machine-local settings now live in `.compound-engineering/config.local.yaml`, and review-agent selection is automatic.

**Why is `.compound-engineering/config.local.yaml` gitignored?**
It carries machine-local preferences and integration settings. The committed `.compound-engineering/config.local.example.yaml` shows available settings; each user opts in locally.

**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.

---

## See Also

- [`/ce-test-browser`](./ce-test-browser.md) — uses `agent-browser` when no capable host-native browser is available
- [`/ce-dogfood`](./ce-dogfood.md) — uses `agent-browser` for diff-scoped QA
- [`/ce-product-pulse`](./ce-product-pulse.md) — uses `.compound-engineering/config.local.yaml` for pulse settings