Skip to content

docs: onboarding guide for the autonomous loop and new-project setup (closes #19) - #32

Merged
robercano-ghbot merged 1 commit into
mainfrom
feat/issue-19-onboarding-loop-docs
Jul 3, 2026
Merged

docs: onboarding guide for the autonomous loop and new-project setup (closes #19)#32
robercano-ghbot merged 1 commit into
mainfrom
feat/issue-19-onboarding-loop-docs

Conversation

@robercano-ghbot

Copy link
Copy Markdown
Collaborator

What & why

Distills issue #19 into a single onboarding reference so a new adopter has one explicit path to configure the orchestrator — and understands the convention that trips people up: the autonomous loop only builds issues you have explicitly queued with a module:* label.

Changes

  • docs/USAGE.md — new ## Autonomous loop & the issue queue section (placed with the existing loop mechanics): the per-tick order poll → merge → address-feedback → advance, the module:* label as an explicit opt-in work queue (lowest-numbered first, one at a time, only when zero open PRs; unlabelled issues never touched; label maps issue → module → the worker's path boundary), the owner-approval merge gate (bot authors PRs; the loop only merges owner-APPROVED, CI-green, mergeable PRs and never self-approves), and the corollary that non-module work isn't loop-eligible until its area is a module in gates.json.modules[] and the issue carries the matching label. Adds a one-line note that /pr-loop is the canonical definition of the tick order so the two loop descriptions can't drift.
  • docs/GETTING_STARTED.md — new ## New-project configuration checklist: a copy-pasteable numbered list (gates.json fields, CLAUDE.md, bot machine account + GH_BOT_TOKEN in gitignored .env, module:* label creation, server-side gates workflow, /pr-loop arming + session-scoped re-arm caveat, optional /harden).
  • README.md — links the checklist from the "Use it" onboarding section.
  • docs/PROMPTS.md — "Brand-new project?" pointer near the top so a new project lands on the checklist + loop section first.
  • .claude/scripts/seed-issues.sh — header NOTE (no logic change) documenting that this script is the module→label anti-drift mechanism, plus a bot-gh.sh label create "module:$m" --force one-liner to bootstrap labels-only through the bot.

Gates

Docs-only. gate.sh lint and gate.sh test_affected both report "not configured — skipping" (empty adapter, as expected for the template repo itself).

Review (consensus: all four lenses APPROVED)

  • Correctness ✅ — tick order, queue rules, and merge gate verified against .claude/commands/pr-loop.md, merge-ready.sh, notify-poll.sh, pr-feedback.sh; all cross-links/anchors resolve.
  • Tests/verifiability ✅ — bot-gh.sh confirmed a pass-through wrapper so the documented label create one-liner works; bash -n seed-issues.sh passes; gate claims match gate.sh output.
  • Security ✅ — no secrets committed; .env correctly described as gitignored; least-privilege bot; owner-approval gate faithful; snippet has no injection/eval.
  • Performance/conciseness ✅ — distillation not duplication; new module:* queue rationale is genuinely new; overlapping merge-gate content defers via cross-link.

Note for the owner

The single commit is unsigned: the owner's global git config enforces SSH commit signing, and this sandboxed run cannot read the signing key under ~/.ssh. Amend/re-sign locally if a verified commit is required (git commit --amend -S --no-edit); content is unchanged.

Closes #19

…checklist

New adopters need one explicit path for wiring a project into the autonomous
loop, plus the one convention that trips people up: the loop only ever picks
up open issues carrying a `module:<name>` label (opt-in intent gate + the
issue->module->path worker boundary), and only merges PRs the owner has
approved. Add a "New-project configuration checklist" to GETTING_STARTED.md,
a matching "Autonomous loop & the issue queue" mental model section to
USAGE.md, cross-link both from README.md and PROMPTS.md, and note the
label/module anti-drift mechanism already implemented in seed-issues.sh
(with a bot-gh.sh one-liner to bootstrap labels-only).

Closes #19

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgW1rGVf89mwhnVfJjbY28
@robercano-ghbot
robercano-ghbot merged commit dd39514 into main Jul 3, 2026
6 checks passed
@robercano-ghbot
robercano-ghbot deleted the feat/issue-19-onboarding-loop-docs branch July 3, 2026 06:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants