setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# /commandeck:setup

Ask each question once, show the owner every change before it is made, then
run one script. Do not edit any settings or rules file yourself: `setup.sh`
records what was there before it changes it and copies an owner's file beside
it first, and an edit made around it cannot be undone by uninstall.

Rule: a refused or failed question call is not an answer: say which question it was and the error (such as `Invalid tool parameters`), ask the same thing again in plain text, and never skip it or assume a default.

Rule: a question has 2 to 4 options, or the call fails. Where only one answer is always there (no saved value, nothing detected), a second option takes the typed value: "Type my own", "Write my own", "Name some" or "Add one". Choosing it asks for the value in plain text, once; the picker's own text answer takes the value directly.

Rule: every question goes through `AskUserQuestion`, with exactly the headers and options written here, recommended option first, and each option's one-line description as written. The recommended option's label ends in " (recommended)", as written below, in every question. While setup asks, the picker guard's decoy is off (`--questions begin` below), so a question has up to four options of its own. A typed value is a question too: its options are the likely values (the saved one first when there is one), and the picker's own free-text answer takes any other. Never print a list of follow-up questions in plain text. An answer setup cannot use as given is asked again as a picker that offers only the choices setup supports.

Rule: free text the owner types (the relay's name and its line, the merge check command, a host name) is passed to `setup.sh` exactly as typed, never corrected, completed or reformatted; a suspected slip may be asked about before anything is sent, and the original is sent unless the owner changes it.

Rule: a saved answer is offered first, marked "(saved)" (and "(recommended)" too when it is that one: the same answer once case and surrounding spaces are set aside, offered as one option and sent as the saved text). Only the questions that apply are asked: the step says when one is skipped.

Before the first question, run one probe: `bash -c 'command -v orca-ide; true'`.
It changes nothing, and no answer from it is a failure. If a hook that is not
this plugin's refuses it (its file is not under `${CLAUDE_PLUGIN_ROOT}`), stop
there. Tell the owner which hook refused, that this plugin cannot run in this
project until that rule allows `orca-ide`, and the one command to run in their
own terminal, in this folder, with the plugin's folder written out:
`bash <plugin folder>/scripts/setup.sh --profile claude|claude-openai`. Never
edit, switch off or work round the project's own guard.

## 0. Check first

Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh --questions begin`. It checks
the requirements, says what it found, and turns the picker guard's decoy off
until setup ends. It writes nothing else.

If it stops on `requirements are missing`, show what it printed, as printed.
The "yours to do" lines are the owner's: plain text, never a question. If
there is a "can install" group, show its commands exactly as printed, then ask:

   Ask "Install": Install (recommended) | I'll do it myself | Stop
   - Install: runs the commands shown above, and no other.
   - I'll do it myself: stop now; run /commandeck:setup again after.
   - Stop: set nothing up.

Only "Install" runs `setup.sh --questions begin --install-missing`; any other
answer runs `setup.sh --questions end` and stops.

Then tell the owner, in three lines: Commandeck turns this session into an
orchestrator that hands each build to a Builder pane in its own worktree, has
each build reviewed, and merges it locally only after review and tests pass.
Setup will write its config (`.claude/commandeck.json`), permission rules,
git's local exclude list, two background jobs (a watcher and, if chosen, the
dashboard), and only what the answers below choose; nothing is written until
the owner has seen the full list and said Apply. Then read back the "Found"
lines `--questions begin` printed, in plain words.

## 1. The questions

Ask them in this order, up to four questions per call.

1. Who reviews each build?
   Ask "Reviewer": Claude (recommended) | Codex
   - Claude: a second Claude session reviews; nothing else to install. `--profile claude`
   - Codex: OpenAI's Codex CLI reviews (it must be signed in). `--profile claude-openai`
   Offer Codex only if the check said "Codex reviewer: ready".
2. Where do permission rules go?
   Ask "Permissions": This project (recommended) | Every project
   - This project: in `.claude/settings.local.json`, which git never sees. `--scope project`
   - Every project: in `~/.claude/settings.json`, for every project on this machine. `--scope machine`
   A changed answer moves the rules; setup says so.
3. Only when the check printed "your project rules":
   Ask "Your rules": Merge (recommended) | Keep both
   - Merge: sessions leave out the plugin's rules your CLAUDE.md and `.claude/rules/` already state word for word. `--rules merge`
   - Keep both: sessions load the plugin's rules as they are, beside yours. `--rules skip`
   On Merge, find rules that say the same thing in other words, or disagree:
   run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/merge-rules.py ${CLAUDE_PLUGIN_ROOT}/templates/AGENT_STARTUP.md --against <each rules file> --units`
   (and the same for `templates/main-session.md`), read each printed rule
   against the owner's files, and for each one that matches only in meaning or
   conflicts, ask one question (up to four per call). Its header is "Rule <n>",
   counting from 1 (keep the printed id for the flag; never show it). Its question
   says in words what the two rules have in common, then quotes both texts whole:
   the owner's line, with its file, and the plugin's rule. For example: "Your
   CLAUDE.md and the plugin both set when to run tests. Yours: 'Run the suite
   before every commit.' The plugin's: 'Run the smallest set of tests that would
   fail.' Which should sessions follow?"
   Ask "Rule <n>": Keep mine (recommended) | Use the plugin's | Keep both
   - Keep mine: sessions leave the plugin's rule out. `--rules-drop <id>`
   - Use the plugin's / Keep both: both load (setup never edits your own text). `--rules-keep <id>`
   `--rules-drop ''` clears every earlier answer. On a rerun, an id
   already under `mergeDecisions` in `.claude/commandeck.json` is not asked
   again: only new or changed plugin rules are (a changed rule has a new id).
4. For each "your own AGENT_STARTUP.md" or "your own .claude/main-session.md"
   line the check printed, every time setup runs:
   Ask "Own startup": Merge (recommended) | Replace | Skip
   Ask "Own main": Merge (recommended) | Replace | Skip
   - Merge: yours keeps loading, and the plugin's rules it lacks are added in a marked block (shown in the preview; uninstall takes the block out); each session leaves out of the block what the project rules it loads already state. `--own-startup merge` / `--own-main-session merge`
   - Replace: sessions load the plugin's version; yours stays on disk, untouched. `replace`
   - Skip: yours loads instead of the plugin's whole version, as today. `skip`
5. Only when the check printed "your global rules", else offer Install (recommended) | Skip:
   Ask "Global rules": Merge (recommended) | Add as block | Skip
   Ask "Global CLAUDE": Merge (recommended) | Add as block | Skip
   - Merge: only the plugin's rules your `~/.claude/CLAUDE.md` lacks, in a marked block. `--global-rules merge` / `--global-claude merge`
   - Add as block: all of them, in a marked block. `block`
   - Install (no file yet): creates the file with them. `install`
   - Skip: the file is left alone. `skip`
   "Global rules" are the plugin's working, review, agent and test rules; "Global CLAUDE" its general instructions (working rules, code exploration, root-cause discipline). Your own text is never changed, and a copy of the file is made first.
6. The settings. Every `/plugin` config option has a recommended value in the plugin's recommended profile: the
   `recommended <key>: <value> (takes: ...)` lines `--questions begin` printed. They are the one source of recommended
   values and of every value a key takes; never answer either from this text. An answer is sent as `--option <key>=<value>`
   (any key `/plugin` config lists; a key with its own flag, below, is sent either way) and saved as that key in `/plugin`
   config, where it can be changed later. A value `--plan` says it skipped (a Codex model on the Claude profile) is not
   an error.
   Ask "Settings": Recommended set (recommended) | Choose groups | Keep saved
   - Recommended set: every setting from the recommended profile, listed by the `--plan` preview; nothing else is asked about them. `--recommended`
   - Choose groups: `--recommended`, then each chosen group's answers override it.
   - Keep saved: sends none of these flags. Offer it only on a rerun (`--questions begin` printed "earlier answers").
   On "Choose groups", two multi-select questions (`multiSelect: true`):
   Ask "Groups": Models | Plan seats | Reviewer | Review workflow
   Ask "More groups": Caches | Builders and wakes | Units views | Auto-decide
   A chosen group asks each of its keys once, up to four keys per call. The question names the key and what it sets; its
   options are the recommended value first, marked "(recommended)", then up to three other values from the key's `takes:`
   list (a model's other families, an effort's neighbours, a boolean's other value); the owner's own text answer takes any

From pushprove-max/Commandeck, Apache-2.0.

More from pushprove-max/Commandeck