One command, one session, always-on Kiwi. The Conductor auto-scales from a quick fix to
a full parallel pipeline and runs immediately by default. Pass --plan-only to preview. Real merges and PRs are human-gated. Never a silent green.
Very good, sir. Nav fix verified clean on all four rungs. No defects recorded.
Every path through the pipeline — a one-agent quick fix or a twelve-unit project — ends in a verified result. The console errors a screenshot misses are caught. Always.
Kiwi is the only interface. You describe what you need; the Conductor detects scale, decides how many agents to run, and orchestrates the full pipeline. You never call verify, queue, or run directly — those are stages Kiwi manages.
Single entry: /bgsd-sesh
The driver ladder checks console messages before it ever looks at the DOM or takes a
screenshot. React's validateDOMNesting warnings, hydration mismatches,
and missing-key errors all fire at console level — invisible to visual regression
tools. bgsd surfaces them on every run, at every scale.
Quick fix? One agent, direct execution, Loop 1 verify→fix. Full project? Decompose
into a DAG, parallel worktrees, Loop 1 per worktree, merge, Loop 2 integration, review
gate. The pipeline is the same — scale determines depth and width. --quick
still verifies. Always.
Every verification run writes a schema-validated verification-report.json:
per-criterion pass/fail, defect list with severity and source rung, screenshot index,
and a driver-ladder audit. Machine-readable. Actionable. No ambiguity.
If the Playwright MCP is absent, bgsd emits BLOCKED — not a fabricated
PASS. If evidence is insufficient, verdict is INSUFFICIENT_EVIDENCE.
Every non-clean stop produces a structured terminal state. Enforced in code, not just
aspirationally documented.
bgsd lives under bgsd/. It never edits vendored GSD directories
(commands/, agents/, gsd-core/, etc.). It reaches GSD
only through three stable seams: /gsd-* slash commands, the
.planning/ file contract, and config.json.
Defer scope mid-session and Kiwi queues it instead of losing it. Start
/bgsd-sesh with no prompt, or finish a session, and Kiwi proposes
the next backlog item. Work carries over without you re-typing a thing.
When Kiwi needs an answer, it asks with a GSD-style arrow-key selector: a few concrete options plus a type-your-own. A vague prompt, a gray-area call, the review gate, "which item next" all come as a pick, never a wall of prose.
AskUserQuestion
The goal-backward code check always runs. The heavier Playwright UI testing is
optional: pass --no-usage-verification, set it in BGSD.md,
or just tell Kiwi. Quick fixes and non-UI changes skip the browser, never the check.
Lost the Claude Code instance mid-run? Every unit's progress is on disk under
.bgsd/runs/. /bgsd-resume finds the latest in-flight
session and picks it back up from each unit's last phase. main stays protected.
Pass --gui and Kiwi opens a local dashboard: the parallel Loop 1
agents, verification, the Loop 2 integrator, and the review gate, each card
showing its GSD substage, status, and progress. Ask Kiwi to open or close it any time.
Cheapest and most reliable first. Vision is a last resort, not a crutch.
browser_navigate then browser_console_messages. Timing is
critical: navigate first so the MCP buffer captures React render-time warnings. This
rung caught the validateDOMNesting defect in the canary proof.
browser_network_requests. Flags any response where
ok === false or status ≥ 400 for a required resource.
Analytics beacons are noted but not automatically treated as failures.
browser_snapshot after domcontentloaded.
networkidle is explicitly prohibited (DRIVER-04) — apps with
WebSockets or analytics beacons can hang indefinitely. Semantic selectors
(roles, labels, headings) verify rendered content against criteria.
browser_take_screenshot. Fires only when rungs 1–3 cannot decide
a criterion. Vision tokens are expensive and screenshots are blind to console and
network defects. bgsd uses them last, not first.
Before any acceptance criterion is touched, bgsd calls
browser_snapshot as a no-op reachability check. If the MCP is absent,
the run halts immediately:
No result is fabricated. This is the "no silent green" invariant.
The only thing that reaches stdout is a single verdict line. The full JSON report lands on disk, never in the terminal.
These are the internal stages the Conductor runs on your behalf inside a
/bgsd-sesh session. You never call them directly.
Boots or attaches to a running app and verifies it against acceptance criteria.
Returns a single verdict line plus a structured verification-report.json.
Runs inside every Loop 1 and Loop 2 cycle. If the driver ladder can't drive a real
browser, it emits BLOCKED — never a fabricated pass.
Items move through classify → route → execute → verify → Loop 1 until a terminal state. The Conductor feeds items in from your prompt; each item's history is recorded in a durable, append-only store with content-key dedup.
For project-scale prompts: decompose into a verified DAG, fan units across parallel
git worktrees, run Loop 1 per worktree, conflict-check and merge verified branches
into the standing next integration branch, and checkpoint at every wave
boundary. The live path requires explicit --live.
Kiwi's always-on dashboard. Color-coded per-worktree badges, Loop 1 iteration counts,
merge history, budget and context telemetry, and a main-protected
indicator (marking that main is never written by an agent). Zero model
calls. The Conductor displays this automatically; you can also run it standalone with
--watch.
Integration verify→fix on the standing next branch: boot the
integrated app, dispatch parallel fix agents on defects, re-merge, re-verify.
Followed by the User Review Gate: per-criterion checklist, your explicit sign-off.
Never auto-passes.
Turns your review findings into a new fix pass. Aggregates per-agent CHANGELOGs
across Loop 1, Loop 2, and feedback rounds into a PR body. Opens an atomic PR into
next behind the --live guard; next →
main stays human-only.
A session runs by default. Pass --plan-only (or --dry-run) to preview without executing. A manual scale flag always wins, unconditionally. The pipeline integrates everything on the standing next branch; agents never write to main, and the next → main merge is human-only.
| --quick | --feature | --project | |
|---|---|---|---|
| Example | "change this button to blue" | "add a dark-mode toggle" | "build auth + billing + a dashboard" |
| Auto-scale trigger | ≤2 units, 1 surface | a few units, mid-size | ≥4 units or ≥3 surfaces |
| Upfront discussion | no | no | yes (intake/brainstorm) |
| Decompose + parallel worktrees | no — single | some, low concurrency | full fan-out |
| Integration loop (Loop 2) | no | yes if >1 unit | yes |
| Formal review gate | no (Loop 1 PASS + 1-line confirm) | yes | yes |
| Verification (Loop 1) | always | always | always |
No silent green at any scale.
Every path through the pipeline — quick, feature, or project — exits through Loop 1
with a real browser check. A structured verification-report.json is produced on
every run. BLOCKED if the MCP is absent. INSUFFICIENT_EVIDENCE if
evidence is thin. Never a fabricated PASS.
Each version de-risks the next. The core value was validated at v0, before any orchestration was built on top of it. v0 through v3 are all built.
Proven in isolation before any orchestration was built on top. The verify stage returned
FAIL on a <div>-in-<p> defect (a real
React console error invisible to a screenshot) and PASS on the clean route,
reproducibly across reruns. Tester, runtime-isolate, criteria parser, report assembler,
and schema all live.
Persistent fix-stream with classify → route → execute → verify → loop.
Queue, classify-item, route-item, and loop1 scripts with 85 unit tests across all four
layers. Live runs (Loop 1 autonomous spawn, Hyperpolymath cron) are guarded behind
--live and remain human-gated.
Full Conductor pipeline: decomposition, dependency graph, worktree fan-out, wave scheduler,
conflict pre-check + merge-resolver, integration onto the standing next branch,
doc aggregation, reversible cleanup,
context management, and the live status view. 14 test suites green across v0+v1+v2.
Live multi-process run is human-gated behind --live.
Integration verify→fix (Loop 2) on the standing next branch,
per-criterion User Review Gate (never auto-passes), feedback mode for rapid iteration,
per-agent CHANGELOG aggregation, and guarded gh pr create into
next. 19 test suites green across v0+v1+v2+v3.
Intake/proxy extension (E1–E6) for Conductor brainstorm and decision-oracle, drafted
in .planning/v2-intake/. Remote orchestration (off-machine worktrees,
distributed execution) planned for v4.
bgsd is an installable, standalone Claude Code plugin. Add the marketplace, install the plugin,
and reload. It is gsd-agnostic: it does not vendor GSD.
It uses the user-installed gsd-core plugin, and the Conductor (Kiwi) sets up what it
needs (gsd-core, Playwright) at the start of every sesh. You just talk to it.
The /buggy route looks identical to a working page in a screenshot.
The defect only exists in the browser console: exactly what bgsd catches. Run the
fixture in development mode: React's validateDOMNesting warning is
stripped from production builds. /bgsd-init creates the standing
next integration branch off your base branch, scaffolds the persistent
.bgsd/ master folder, and writes a user-editable BGSD.md settings
file. The Conductor ensures gsd-core is installed and kept up to date for you
(and runs claude plugin update gsd-core to refresh it); after any plugin update,
Claude Code needs /reload-plugins or a restart to apply, and Kiwi flags it.
Once installed, /bgsd-sesh is all you need.
These invariants are checked in code. bgsd tells you clearly when one is about to be violated.
| Invariant | Enforcement |
|---|---|
Agents never write to main |
main (production) is never written, committed, or PR'd by an agent. Integration lands on the standing next branch; the next → main merge is a manual, human-only step. |
| Additive only | bgsd lives under bgsd/ (plus runtime .bgsd*/ dirs). It never edits GSD's directories. |
| Never edit vendored GSD | The forked GSD source (commands/, agents/, gsd-core/, skills/, hooks/) is read-only to bgsd. |
| Seams only | bgsd reaches GSD only through (1) /gsd-* slash commands, (2) the .planning/ file contract, and (3) config.json. No reaching into GSD internals. |
| No silent green (NFR-06) | If evidence is insufficient: INSUFFICIENT_EVIDENCE, not PASS. If MCP is absent: BLOCKED. Every non-clean stop produces a structured terminal state. |
| Bounded, reversible autonomy (NFR-08) | Every loop is bounded by max_iterations; every Conductor run by --budget-cap; every wave requires your go/no-go. Cleanup writes a recovery file before deleting anything. |
| Live runs are human-gated | Sessions execute by default; --plan-only / --dry-run previews. Real irreversible actions (git merge, gh pr create) are still gated at merge-boundary checkpoints behind --live. The guard checks process.argv — not environment variables — and throws a detailed refusal if absent. |
bgsd is MIT-licensed and lives in the bgsd/ namespace of the
filippo-fonseca/better-gsd repo (a fork of @opengsd/gsd-core).
The Conductor Session doc is the best place to start after installing.
filippo-fonseca/better-gsd — source, issues, and PRs. Working branch:
feat/bgsd-v0. Agents never write to main; integration lands
on next.
The primary reference: /bgsd-sesh, auto-scale, flags, and the full pipeline
flowchart from prompt to done. Start here after the canary proof.
Install bgsd, add Playwright MCP, and run the canary proof. From zero to a verified first session in under ten minutes.
Internal stage reference: argument table, acceptance-criteria formats,
verification-report.json schema, and driver-ladder details. The Conductor
runs this on your behalf inside every Loop 1 and Loop 2 cycle.
Internal stage reference: fix-stream lifecycle, state machine, classification and routing table, Loop 1 behavior, and the queue store schema.
Internal stage reference: Conductor state machine, dependency graph, worktree fan-out,
wave scheduler, conflict pre-check, merge-resolver, integration onto the standing
next branch, and the human-gated --live checklist.
Kiwi's always-on dashboard: color-coded per-worktree badges, budget and context
telemetry, and the --watch live refresh mode. The Conductor surfaces this
automatically during every session.