docs: onboarding guide for the autonomous loop and new-project setup (closes #19) - #32
Merged
Merged
Conversation
…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
approved these changes
Jul 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
## Autonomous loop & the issue queuesection (placed with the existing loop mechanics): the per-tick order poll → merge → address-feedback → advance, themodule:*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'spathboundary), 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 ingates.json.modules[]and the issue carries the matching label. Adds a one-line note that/pr-loopis the canonical definition of the tick order so the two loop descriptions can't drift.## New-project configuration checklist: a copy-pasteable numbered list (gates.json fields, CLAUDE.md, bot machine account +GH_BOT_TOKENin gitignored.env,module:*label creation, server-side gates workflow,/pr-looparming + session-scoped re-arm caveat, optional/harden).bot-gh.sh label create "module:$m" --forceone-liner to bootstrap labels-only through the bot.Gates
Docs-only.
gate.sh lintandgate.sh test_affectedboth report "not configured — skipping" (empty adapter, as expected for the template repo itself).Review (consensus: all four lenses APPROVED)
.claude/commands/pr-loop.md,merge-ready.sh,notify-poll.sh,pr-feedback.sh; all cross-links/anchors resolve.bot-gh.shconfirmed a pass-through wrapper so the documentedlabel createone-liner works;bash -n seed-issues.shpasses; gate claims matchgate.shoutput..envcorrectly described as gitignored; least-privilege bot; owner-approval gate faithful; snippet has no injection/eval.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