gsd-loop

A human-gated agent work loop for GitHub. Foggy efforts become decision maps, clear ideas become contract-grade issues, issues become PRs, and PRs get audited verdicts — while every irreversible step stays human.

The loop is four agent-neutral playbooks in loop/ that any coding agent can execute (Codex, Claude Code, Cursor, Gemini CLI, Grok Build, ...). They use Node.js and an authenticated gh CLI; the installed skills bundle the deterministic guards their playbooks invoke, so direct one-pass use does not require a global gsd-loop command. The installer keeps canonical skills in ~/.agents/skills/ and adds native adapters for hosts that use their own global skill directory.

 foggy idea ──discover──▶ decision map ──slices──┐
 clear idea ─────────────────────────────────────┴─▶ spec ─▶ issue(s)
                                                              │ human: gsd:ready each
                                                              ▼
             ┌────────────────────────────── build lane ◀── queue
             ▼
            PR ◀──── fix gsd:rework items ────┐
             │                                │
             ▼                                │
          review lane ── blocking? ── yes ────┘  (3 strikes → gsd:escalated)
             │
             no
             ▼
       gsd:approved ──▶ human merges

The four playbooks

Playbook	Mode	One pass does
loop/discover.md	interactive	Chart a large uncertain effort, resolve one frontier decision, or re-chart and graduate or stop after the frontier clears
loop/spec.md	interactive	Interview you about a raw idea, or turn a cleared map's slices into separate GitHub issues with O-N outcome / X-N exclusion contracts
loop/build.md	unattended	Repair one gsd:rework PR, or claim the oldest safe gsd:ready issue and open a PR
loop/review.md	unattended	Audit one PR against its issue contract and required CI, post a gsd-loop verdict, synchronize outcome checkboxes, set labels

Label state machine

Label	Applied by	Cleared by	Meaning
gsd:map	discover	map closes after specification	Multi-session planning state; never a build-queue item
gsd:ready	human	merge (issue closes)	Approved for the build queue
gsd:blocked	builder	human	One specific question awaits an answer
gsd:rework	reviewer	builder or reviewer	Verdict has blocking findings
gsd:approved	reviewer	reviewer under the approval invalidation rules	Evidence complete and issue outcomes checked; merge is yours
gsd:escalated	either	human	Out of automation until a human resolves it

Quick start

Install the five skills at any time, including before you create or connect a GitHub repository:

npx @opengsd/gsd-loop@latest install

Once the repository is on GitHub, run its bootstrap from the local checkout:

npx @opengsd/gsd-loop@latest init

init is the combined convenience path: it previews one plan and asks before it changes anything. It installs or updates the five global skills, checks Git and GitHub access and review readiness, creates the queue/review labels, and can configure an existing successful CI check as required when the GitHub plan and repository permissions support rulesets. It does not choose, launch, or configure an agent harness.

Start a new harness session after bootstrap. All ongoing work runs as skills inside that harness:

Agent	Discover	Spec	Build one pass	Review one pass	Schedule
Codex	$gsd-loop-discover	$gsd-loop-spec	$gsd-loop-build	$gsd-loop-review	$gsd-loop-schedule
Claude Code	/gsd-loop-discover	/gsd-loop-spec	/gsd-loop-build	/gsd-loop-review	/gsd-loop-schedule
Cursor	/gsd-loop-discover	/gsd-loop-spec	/gsd-loop-build	/gsd-loop-review	/gsd-loop-schedule
Gemini CLI	Use the gsd-loop-discover skill	Use the gsd-loop-spec skill	Use the gsd-loop-build skill	Use the gsd-loop-review skill	Use the gsd-loop-schedule skill
Grok Build	/gsd-loop-discover	/gsd-loop-spec	/gsd-loop-build	/gsd-loop-review	/gsd-loop-schedule
Kimi Code	/skill:gsd-loop-discover	/skill:gsd-loop-spec	/skill:gsd-loop-build	/skill:gsd-loop-review	/skill:gsd-loop-schedule

Use discover only when an effort is too large and uncertain to specify. Each invocation charts a map or performs one bounded advance with you present. An advance resolves at most one decision; after the frontier clears, it may instead re-chart and graduate or stop. Once the map is clear, it records one or more delivery slices; spec files each slice as its own issue. For an already clear idea, start with spec directly. Read every filed issue and add gsd:ready individually. Build processes those issues over bounded passes. Build and review belong in separate harness sessions so their state cannot mix.

Each build or review invocation executes exactly one bounded pass. To keep a lane running, invoke the scheduling skill inside that lane's session using the syntax above. The skill uses the harness's native recurring-task facility, backs idle work off from 15 to 60 minutes, and pauses after three idle passes. A host without native repetition reports that scheduling is unsupported; gsd-loop does not launch a second agent process.

The installer and deterministic setup helpers are native Node.js programs tested on macOS, Linux, and Windows. WSL is not required. See the installation guide for selective installs, unattended flags, the support matrix, and recovery.

Your four duties

The playbooks reserve these actions for humans:

1. Apply gsd:ready after reading a filed issue — nothing builds without it.
2. Answer gsd:blocked questions, then remove the label.
3. Resolve gsd:escalated items, then remove the label.
4. Merge. The loop never merges, never enables auto-merge, and treats gsd:approved as evidence for your decision, not a substitute for it.

Requirements

Standalone installation, repository setup, and skill execution have separate prerequisites; see the installation guide for the complete requirements. Before review, the default branch must have required status checks configured. The reviewer refuses to treat missing CI as green. init configures an existing successful check when the GitHub plan and repository permissions support rulesets; it never creates a fake always-green workflow.

The bootstrap reports missing prerequisites or review protections before the first skill run. After it finishes, invoke the skills from any GitHub checkout; no project files need to be copied. The installation guide also covers selective installation, unattended bootstrap, diagnostics, and recovery.

Maintainer releases

Releases use GitHub Actions trusted publishing rather than a stored npm token. One main-only workflow publishes npm and creates the matching GitHub Release. See the release guide for the exact publisher settings and procedure.

Design notes

• One head, linked issue, and contract version, one verdict. Trusted verdicts identify the commit, issue number, and issue-body fingerprint. Crashed passes repair checkboxes and labels from matching evidence. New commits or contract edits require a fresh review. Outcome checkbox changes alone preserve the fingerprint.
• Crash-anywhere recovery. The builder reconstructs state from git and GitHub (dirty trees, orphaned gsd/NNN-* branches, stale claims) rather than from memory, so a pass can die on any line without wedging the queue.
• Three strikes. Three blocking verdicts on distinct SHAs — counted since the last human-cleared escalation — route the PR to gsd:escalated instead of looping forever.
• Contracts bind product scope. The builder implements only O-N outcomes; the reviewer audits functional behavior against them; X-N exclusions fence both. Independent required-CI and dependency-security gates still apply.
• Dependency diffs are audited. Any manifest or lockfile change requires a machine-readable baseline-versus-branch advisory comparison. New high or critical advisories block approval even when the issue did not ask for a security audit.
• Idle back-off. Empty queues push the loop to its longest interval. The scheduling skill pauses after three idle passes because new work only appears when a human files, unblocks, or merges.
• Maps absorb uncertainty before contracts. Discovery maps hold a durable destination, decision history, unresolved fog, explicit scope boundary, and delivery slices. They never enter the ready queue; spec turns each cleared slice into its own contract-grade issue.
• One writer per map. Discovery decisions advance serially within a map because GitHub issue-body updates are not conditional. This trades Wayfinder-style parallel frontier work for recoverable, inspectable state; separate maps may still advance independently.