v0.4.0 · Spec-Build-Review Queue Workflow

GSD LoopThe queue-driven spec-build-review loop for continuous AI coding.

Turn foggy ideas into decision maps, contract-grade GitHub issues, pull requests, and reviewed code. Work a continuous GitHub queue with bounded agent passes, leaving the irreversible merges strictly to you.

Install GSD Loop Skills

Work GitHub Queue

View on GitHub npm package Discord

gsd-loop · v0.4.0 · verified

THE 4 BOUNDED PASSES

Continuous

01 · Discover

Decision mapping & uncertainty resolution

02 · Spec

Contract-grade GitHub issue creation

03 · Build

Queue dispatch, code & pull requests

04 · Review

Contract audit & CI test validation

Humans steer & mergeDeterministic

Design Tenets

Why GSD Spec-Build-Loop?

Built to solve the fundamental failure modes of autonomous coding: ambiguity, runaway context, and lack of human oversight.

Human-Gated by Design

Agents open and review pull requests but never merge or enable auto-merge. Irreversible decisions stay strictly with humans.

Guaranteed

Contract-Grade Issues

Discovery maps resolve open architecture decisions before issues are written, giving build passes a real contract to satisfy.

Guaranteed

Crash-Safe Queues

Workflow state is reconstructed from git and GitHub labels rather than volatile agent memory, with idle backoff when queues run dry.

Guaranteed

Runtime Compatible

Drop the loop skills into Claude Code, Cursor, Codex, Gemini CLI, or run standalone from your CI/CD pipelines.

Guaranteed

Live Simulator

Explore the 4 Loop Passes

Click through the four bounded passes to see how an uncertain idea evolves into contract issues, pull requests, and human merges.

GSD SPEC-BUILD LOOP

Interactive 4-Stage Queue Simulator

Human Gated · No Auto-Merge

AGENT QUEUE PASSLabel: gsd:discovery

$ npx @opengsd/gsd-loop discover --issue=104● running

› Working GitHub repository queue...

› State reconstructed from git labels & commit logs.

› Phase: Discover pass in progress.

Zero memory dependencies — state is 100% durable in git & GitHub.

Automatic idle backoff when the labeled queue is dry.

Human reviews and merges; agents never trigger auto-merge.

Pass 01 of 04

DECISION_MAP_#104.md

gsd:discovery

Architecture & Trade-off Resolution

Identified 3 core architectural choices (local sqlite-vec vs in-memory).

Decision: Use sqlite-vec with WAL mode for crash-safety.

Resolved edge case: Multi-threaded write contention handled via mutex.

3 Decisions Cleared · 0 Open Questions

Continuous queue processing with strict bounded passes

Execution Stages

The Four Skills in Detail

Each skill is an isolated command with explicit inputs, outputs, and label transitions.

Discover

gsd-loop:discover

Charts an uncertain effort, probes trade-offs, and resolves open questions into an unambiguous decision map.

Label:gsd:discovery

Spec

gsd-loop:spec

Transforms cleared decision maps into contract-grade GitHub issues with explicit acceptance criteria and edge case tests.

Label:gsd:ready

Build

gsd-loop:build

Works the gsd:ready queue on clean git branches, implementing features, running checks, and opening pull requests.

Label:gsd:building

Review

gsd-loop:review

Audits each PR against its issue contract, verification evidence, and CI status before alerting a human to merge.

Label:gsd:review-ready

Automated CI/CD

Run in GitHub Actions or Local CLI

Configure GSD Loop as a scheduled GitHub Action or run it directly on your machine. Whenever an issue is labeled gsd:ready, the agent picks it up, writes code in an isolated branch, and opens a PR for you to review.

Label-driven: Control dispatch with GitHub labels like gsd:ready, gsd:blocked, and gsd:review-ready.

Zero context pollution: Every issue is built in a fresh branch with dedicated context.

Human oversight: Full audit logs attached to every PR so you can merge with confidence.

.github/workflows/gsd-loop.ymlGitHub Action

name: GSD Spec-Build Loop

on:
  issues:
    types: [labeled]
  schedule:
    - cron: '*/15 * * * *'

jobs:
  gsd-worker:
    if: contains(github.event.issue.labels.*.name, 'gsd:ready')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Run GSD Build Pass
        run: npx @opengsd/gsd-loop@latest build --repo=${{ github.repository }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Get Started

Supercharge Your GitHub Issue Queue

Stop context drift and vague agent prompts. Install GSD Loop today and let agents build against verified issue contracts.

Star open-gsd/gsd-spec-build-loop Join the Discord Community