Onboarding: configure the orchestrator for a new project (modules, labels, the autonomous loop)

[robercano-ghbot]

Goal

Give a new adopter a single, explicit path to configure this orchestrator for their own project — and document the one convention that trips people up: the autonomous loop only builds issues you have explicitly queued. This issue doubles as the reference until it's distilled into the docs (see "Deliverables").

How the autonomous loop decides what to work on (the mental model)

The cron loop (/pr-loop) runs ticks. Each tick, in order: poll → merge → address-feedback → advance. The two human control points are:

1. What gets built — the module:* label is an opt-in work queue.
   The ADVANCE step only picks up open issues labelled module:<name>, lowest-numbered first, one at a time, and only when there are zero open PRs. An unlabelled issue is never touched. This is deliberate:

   • Intent gate: most issues are discussions, questions, or half-scoped bugs that a bot shouldn't auto-implement. The label is you saying "this is scoped and ready for an autonomous worker."
   • Mechanism: every worker runs in an isolated git worktree and MUST NOT edit outside its module's path (from .claude/gates.json → modules). The module:<name> label maps the issue to exactly one module → one path → the worker's hard boundary. No module ⇒ no boundary ⇒ can't be delegated safely.

2. What ships — you approve the bot's PR.
   Workers open PRs as the bot (.claude/scripts/bot-gh.sh). The loop's MERGE step only merges PRs that you (the repo owner) have Approved on GitHub and that are CI-green + mergeable. It never approves on your behalf. Your GitHub Approve is the ship-it gate.

Corollary: docs / infra / "non-module" work is not second-class — it just isn't loop-eligible until (a) its area exists as a module in gates.json, and (b) the issue carries the matching module:* label. Commenting "approved" on an issue does nothing; nothing watches issue text.

New-project configuration checklist

1. .claude/gates.json — the only per-project file that must be filled:
   • project.{name,language,packageManager}
   • modules[] — one entry per independently-ownable area, each with a non-overlapping path. These paths are the worker boundaries AND the set of module:<name> labels the loop understands. Include non-code areas you want automatable (e.g. { "name": "docs", "path": "docs" }).
   • gates.* — real shell commands for build/lint/typecheck/test/test_affected/coverage/e2e/security (empty string = skip). coverage_threshold.
   • review.{lenses,consensus}, budget.* (model routing, max_parallel_workers), merge.{policy,baseBranch}.
2. CLAUDE.md — project context, conventions, definition of done, merge policy.
3. Bot machine account — create it, add as a write collaborator, put GH_BOT_TOKEN in .env (gitignored). All agent/loop gh calls run as the bot via bot-gh.sh; only git commits/pushes stay as the owner so the owner can approve bot PRs. Setup notes are in .claude/scripts/bot-gh.sh.
4. Create the module:* labels that match your modules[] names (gh label create module:<name> ... via bot-gh.sh). Without the label, ADVANCE can't queue the issue.
5. Server-side gates — .github/workflows/gates.yml already ships (see Ship a CI workflow that runs gates.json gates on PRs (server-side gate enforcement) #8); confirm it runs your gate commands and set branch protection / required checks if on a plan that supports it.
6. Arm the loop — run /pr-loop (re-run each session; the cron is session-scoped). It self-adjusts cadence: FAST when there's ≥1 open PR or ≥1 open module:* issue, else IDLE.
7. (optional) Hardening — /harden for the bypass + strict-sandbox profile (see docs/HARDENING.md).

Deliverables (the actual work for this issue)

• Add an "Autonomous loop & the issue queue" section to docs/GETTING_STARTED.md (or docs/USAGE.md) covering the mental model above — especially the module:* opt-in and the owner-approval merge gate.
• Add the new-project configuration checklist as a copy-pasteable list (link it from the README/onboarding).
• Consider a small label-bootstrap helper (or a note in seed-issues.sh) that creates module:* labels from gates.json.modules[] so labels and the module map can't drift.
• Cross-link from docs/PROMPTS.md (onboarding prompt) so a brand-new project lands here first.

Why file this

Every one of these steps is currently tribal knowledge spread across script header comments and this conversation. A single onboarding reference removes the "why didn't the loop pick up my issue?" foot-gun for the next adopter.

Note: to make THIS issue loop-eligible it would itself need a module (e.g. module:docs) once docs/.claude are added to gates.json.modules[]; otherwise drive it manually via the orchestrator.

[robercano-ghbot]

Status update — pivoted to an interactive command

The primary deliverable here is now a command, not hand-written docs:

• ✅ /setup-orchestrator shipped (PR chore: route all agent gh through the bot + add /setup-orchestrator #20 → .claude/commands/setup-orchestrator.md). It runs the full interactive onboarding — interview → write gates.json + CLAUDE.md → gitignore hygiene → create module:* labels → verify the bot → confirm CI gates → offer to arm /pr-loop → offer /harden (last). It also explains the model up front (the module:* opt-in queue + owner-approval merge gate), which was the core content this issue asked to capture.
• ✅ Discoverability pointers to the command added to GETTING_STARTED.md + PROMPTS.md (PR docs + loop: /setup-orchestrator pointers and responsive PR-loop cadence #22).

Remaining (smaller) scope for this issue

• Label-bootstrap helper — create module:* labels from gates.json.modules[] (or a note in seed-issues.sh) so labels can't drift from the module map. /setup-orchestrator creates them at setup time; this keeps them in sync afterward.
• Optional: distill any residual prose from this issue's body into USAGE.md if the command + GETTING_STARTED callout leave gaps.

The "why only module:* issues are picked up" explanation now lives in the command (step 2) and this issue body; once the label-bootstrap lands, this can close.