Set up a project

/echo:setup onboards one repository onto Echo. Run it once, from that repo’s root. It inspects the repo to pre-fill proposals, interviews you for anything it can’t detect, provisions the GitHub Project board, writes the per-project config, registers the project, and finally gates on a clean dry-run sweep — nothing dispatches until that passes.

Re-running /echo:setup on an already-onboarded repo is always safe: an existing .claude/echo/config.json puts setup into reconfigure mode, and every write backs up the previous file with a timestamp before overwriting.

What the interview walks through

1. Inspect (read-only). Setup runs inspect.sh, which parses your origin remote for the owner/repo slug, finds the default branch, checks for a CLAUDE.md, guesses a test command, and detects an existing config. It never writes anything or hits the network — it just pre-fills every proposal.

2. Interview (one question at a time). Each question shows a proposal you can accept with a bare Enter. You’ll confirm or provide:

   • the repo (owner/repo) and whether the owner is an org or user account (user-owned boards need the project scope)
   • whether to create a new GitHub Project or adopt an existing one by number
   • the status columns — the default eight are Backlog, Ready, Planning, In progress, AI reviewing, Needs Human, Building & Deploying, Done
   • priorities (default P0/P1/P2) and an optional path-prefix → Category map
   • optional supporting repos (ArgoCD/Helm, Terraform, infra) that deploys may need to sync
   • deploy verification: none (“trust CI”), command (a stored read-only health check), or k8s-argocd (follow the build → image-tag-bump → ArgoCD-sync → rollout pipeline)
   • gated paths (default [".claude/echo/**"]), design-doc / LESSONS.md locations, an optional Discord channel, and worker caps / model tiers (default workers.slots: 2)

3. Preflight. preflight.sh runs the readiness checks (gh installed + authenticated, repo read access, Projects v2 scope, jq >= 1.6, git >= 2.30) and prints a full punch-list. Setup stops here until a re-run exits clean.

4. Provision the board. provision_board.sh runs first as a --dry-run that prints [DRY-RUN] would: ... lines for your confirmation, then for real. It creates-or-adopts the Projects v2 board and ensures the Status, Category, Priority, and Size fields and their options exist — preserving any options already present. If it created a new project, it reports the new PROJECT_NUMBER, which setup folds into the config.

5. Write config + register. write_config.sh writes .claude/echo/config.json (backing up any existing one with a timestamp), and register_project.sh adds — or replaces, never appends — this repo’s entry in the machine registry at ~/.config/echo/registry.json (override with ECHO_REGISTRY). If you gave a Discord channel, setup posts a one-time confirmation to verify it’s reachable.

6. Bootstrap CLAUDE.md (optional). If your repo has no CLAUDE.md or a thin one, setup offers to draft a subsystem-map CLAUDE.md for your review — applied only once you approve.

7. Final gate. Setup runs tick.sh --dry-run --project <name>. Nothing dispatches for this project until this passes cleanly — its output is your closing confirmation that onboarding is complete.

What setup writes

Two files, in two places:

• .claude/echo/config.json — committed in your repo. Holds only the keys you changed from the plugin defaults; the rest are merged in at read time from the plugin’s defaults.json. This is the full per-project contract: board coordinates, status names, priorities, worker caps, deploy verify block, gated paths, review policy, and so on. (See the config reference for every key.)

• ~/.config/echo/registry.json — the machine-level registry, not in your repo. One entry per onboarded project: its name, physically-resolved repoRoot, enabled flag, and Discord channel. The hub sweep reads this to know which projects to visit.

First worker seeds LESSONS.md

You don’t create a LESSONS.md here. The first worker Echo spawns for a project finds none and auto-seeds one from the plugin’s template (a house-style header with zero entries) — so don’t be surprised when a fresh project’s first spawn log mentions “seeded LESSONS.”

Next step

With the board provisioned and the project registered, kick off your first run →.