buildloop

Webinar DEMO variant of the release phase — runs the real SECURITY audit (the star of this act) and prints a pre-deploy CHECKLIST, for a live before/after demo. Use only for the vibe-coding course demo, NOT for real releases (that's release-product). By default it spawns the genuine audit-security skill as a fresh, read-only subagent and renders its findings as a green/red pre-deploy checklist — the payoff being to SHOW that the method finds real security problems before shipping (leaked keys, missing auth, injection) versus a vibe-coder who just deploys and hopes. Performance is OPTIONAL (--with-performance). REPORT-ONLY: it does NOT file rework tasks, does NOT loop fixes, and does NOT cut a release / bump versions. Reuses the real audit; only the fix/ship machinery is stripped.

Webinar DEMO variant of the spec pipeline — the REAL staged flow (gather-context → product requirements → architecture → dev-architecture), just compressed, NOT the full create-project-spec. Use only for the vibe-coding course demo. It runs four real, SEQUENTIAL stages with an approval gate between each: (1) gather-context interviews the user AND critically pushes back on what they propose; (2) it drafts the functional/product requirements and stops for ok/not-ok; (3) it proposes an architecture (options + trust boundaries) and stops for ok/not-ok; (4) it proposes the dev-architecture (the verification tooling — e.g. Playwright — the build act later uses) and stops. Shorter than the real pipeline (no research subagents, no adversarial-review subagents, no dual outputs, drops validate-idea/user-flows/design phases) but keeps the staged, gated, critical structure. Writes the same filenames the build/release demos read, so the three acts chain.

Webinar DEMO variant of the build loop — builds ONE feature with the real implementer/verifier two-agent mechanism, for a live before/after demo. Use only for the vibe-coding course demo, NOT for real builds (that's build-product). It skips the kanban planning entirely: it writes a single throwaway task file for the feature you name, spawns the real implementer agent to build it, then spawns the SEPARATE, fresh verifier agent to independently find bugs and hand them back — the whole point being to SHOW the second agent catching real bugs in the first agent's work, versus a naive 'it works, ship it'. HARD-CAPPED at 2 implement↔verify iterations (usually 1 is enough) so it fits a webinar slot. Reuses the genuine agents/mechanism — only the surrounding kanban is stripped.

Design the development-time architecture that lets the product be built fast and well with AI: how to run the whole product locally (Docker Compose topology, local stand-ins for cloud/managed services with prod-equivalent APIs, seed data), how it is tested in an AI-drivable way (test levels + purpose-built developer/test scripts + an e2e harness an agent can run and verify, e.g. Playwright for web), how concurrent access to the single shared local environment is coordinated (lock and/or per-run isolation), and how the AI tooling is configured for the chosen stack (Claude Code config, which Anthropic plugins/skills to install, MCP servers, other agents) — including the custom, project-local Claude Code skills to author that wrap those dev/test scripts and the e2e harness so future agents run the verification loop by name — backed by research into the current tools and an adversarial review pass. Use after design-architecture (reads .buildloop/project-spec/architecture.research.md and .buildloop/project-spec/us

Turn the finished project spec into a buildable backlog. Use after setup-dev-environment, as the planning step of the build/development phase, to read the committed feature set (.buildloop/project-spec/product-requirements.research.md), the user flows, the architecture, and the dev-architecture (incl. its developer/test scripts and the custom project skills that wrap them, which become build-out/authoring tasks), and emit a kanban backlog under .buildloop/build-plan/: one markdown file per task (type, status, blockers, acceptance criteria, provenance), plus a derived board.md and a short plan.summary.md. Single pass — each task's blocked_by list IS the dependency graph; there is no parallel scheduling. For an existing project (project_type: existing) it runs in delta mode: it diffs the target spec against the reverse-engineered codebase-map and emits ONLY the gap (rework for divergent code, new tasks for unbuilt features, verify tasks for adopted features, a quality-gate setup task), marking already-matching

Turn the dev-architecture spec into a real, runnable local environment. Use after the project-spec pipeline (reads .buildloop/project-spec/dev-architecture.research.md and architecture.research.md + adr/*), as the first step of the build/development phase, to scaffold the repo and bring up the inner loop: install tooling, init the repo (.gitignore, project CLAUDE.md, settings.json), write the Docker Compose stack + seed data + one-command bring-up, wire the AI tooling (MCP servers, plugins), and scaffold skeleton stubs of the developer/test scripts and the custom project skills (.claude/skills/) the dev-architecture specified. Runs an internal plan → approve → execute: it plans everything but auto-executes only repo-local scaffolding; global installs, API keys, and Claude plugins run only with explicit confirmation. Idempotent (safe to re-run), detect-state-first. For an existing project (project_type: existing) it runs in adopt mode: it reads the reverse-engineered codebase-map, adopts and extends what's alr

Audit the built product's accessibility against the spec's accessibility decisions. Use in the release phase (run by release-product, or standalone) for a product with a UI; it self-skips cleanly for a CLI / library / API with no UI. A fresh, independent accessibility specialist: it reads the target conformance (e.g. WCAG 2.2 AA), viewports, and platforms from .buildloop/project-spec/design-decisions.research.md and drives the real UI to prove them — automated checks (axe-core) PLUS what automation misses: keyboard-only operability and focus order, visible focus, screen-reader semantics (roles/labels/landmarks/alt), color contrast, motion / reduced-motion, and forms + error messaging. Read-only: it drives and ranks (blocker = a WCAG-A failure on a core journey, per the rubric) but NEVER edits product code — it files blockers/majors as rework tasks into the backlog and writes .buildloop/release/accessibility-audit.md. Brings the UI up through the coordinated entrypoint (env lease). Re-runs after a fix to confi

Audit whether the built codebase ages well — the whole-codebase health the per-commit quality gate does not measure. Use in the release phase (run by release-product, or standalone). A fresh, independent staff engineer: where the gate fails a single red commit (lint/type/format/tests), this measures the rot the gate can't see across the whole tree — duplication clusters and the refactor-vs-clone ratio (GitClear-style signals), oversized files/functions, dead code, standing suppression debt (accumulated eslint-disable / type:ignore / noqa the gate only blocks when NEW), and TEST-SUITE QUALITY (coverage on critical modules + mutation testing — does the suite actually catch an injected bug, not just execute the line). Read-only: it measures and ranks (mostly major/minor; blocker only when rot is a real reliability risk) but NEVER edits product code — it files majors as rework tasks and writes .buildloop/release/code-health-audit.md. Mostly static, so it fans out freely. Re-runs after a fix to confirm the signal

Audit the built product's performance at the system level, against the spec's quality-attribute scenarios. Use in the release phase (run by release-product, or standalone) once features are built. A fresh, independent performance engineer: it reads the latency/throughput/cost/scale scenarios from .buildloop/project-spec/architecture.research.md and MEASURES whether the running system meets them — p50/p95 on the hot paths, throughput under the target load, bundle/asset weight and client render cost, query plans (N+1, missing index), and the resource/cost envelope. Read-only: it measures, reproduces the slow path, and ranks (blocker = a missed budget, major = met with no margin, per the rubric) but NEVER edits product code — it files blockers/majors as rework tasks into the backlog and writes .buildloop/release/performance-audit.md. Brings the stack up through the coordinated entrypoint (env lease) so it doesn't collide with other audits. Re-runs after a fix to confirm the number actually moved.

Audit the built product end-to-end against the spec's user flows. Use in the release phase (run by release-product, or standalone) once features are built. A fresh, independent QA lead: it reads the user flows + their acceptance criteria from .buildloop/project-spec/user-flows.research.md and drives the WHOLE running product through each journey — proving the cross-feature integration that per-task verify-feature could not see (state carried across steps, the seams between features, the flow's success outcome and its significant/error states). Read-only: it drives, observes, and ranks (blocker = a broken core journey, per the rubric) but NEVER edits product code — it files blockers/majors as rework tasks into the backlog and writes .buildloop/release/qa-report.md. Brings the stack up through the coordinated entrypoint (env lease) so it doesn't collide with other audits. Re-runs after a fix to confirm the journey now completes.

Audit the built product for security at the system level, against the spec's threat model. Use in the release phase (run by release-product, or standalone) once features are built. A fresh, independent security engineer: it reads the STRIDE-lite threat model + trust boundaries from .buildloop/project-spec/architecture.research.md and proves, with evidence, whether the running system upholds them — secrets in code/history, authn/authz on every protected path, injection (SQL/command/template/path), the lethal trifecta (private data + untrusted input + external exfiltration in one agent/tool path), insecure data handling (PII, crypto, logging), and dependency/supply-chain exposure. Read-only: it probes, reproduces, and ranks (blocker/major/minor per the rubric) but NEVER edits product code — it files blockers/majors as rework tasks into the backlog and writes .buildloop/release/security-audit.md. Runs the shared audit machine; re-runs after a fix to confirm the hole is closed.

Build the product from the backlog, one task at a time. Use after plan-development, as the execution step of the build/development phase. A thin orchestrator: it reads .buildloop/build-plan/, repeatedly picks one ready task (status todo with all blockers done), and drives it through the loop — implement-feature builds it, then verify-feature runs as a SEPARATE fresh agent (bounded by max_verify_iterations; at the cap the task escalates to needs_human), then a checkpoint commit carrying the task id — regenerating board.md and continuing until no ready task remains. Sequential, single working tree, no parallelism. Resumable: the backlog is the source of truth, so a killed run restarts without rebuilding done tasks. Conducts the focused sub-skills (setup-dev-environment / implement-feature / verify-feature / commit); it does not duplicate their logic.

Commit session changes with intelligent splitting for large changesets

Turn the design DIRECTION into a concrete, committed design system — a root DESIGN.md (Google's open, tool-neutral format: YAML design tokens + prose rationale). Use in the build phase, AFTER the project is scaffolded (so candidates can be rendered in the real stack), normally invoked by setup-dev-environment for a UI project, or standalone. Reads .buildloop/project-spec/design-decisions.research.md (the direction: system needed?, adopt-vs-bespoke, type/color intent) and product-requirements (brand/audience). Produces SEVERAL candidate DESIGN.md variants from one of three sources — IMPORT an existing DESIGN.md, ADOPT a UI kit (Material 3 / shadcn / Tailwind UI / Radix), or GENERATE from brand intent — renders each as mockups via generate-mockups so the human can compare, then writes the chosen one to the repo root and a .buildloop/project-setup/design-system.md record. Self-skips for a no-UI project or when design-decisions says no system is needed. Idempotent; installs/global changes gated (the careful patte

Produce a project's initial documentation end to end, from a raw idea to a buildable spec. Use when starting a new project (or a major new initiative) and you want the full guided flow rather than running each step by hand. Orchestrates the pipeline — gather-context → validate-idea → define-product-requirements → create-user-flows → define-design-decisions → design-architecture → design-dev-architecture — where each phase researches real-world facts, runs an adversarial review (merged in, then removed), and emits a detailed research doc + a short human summary. Opens with gather-context, which interviews the user to turn a short brief into a rich shared understanding the whole pipeline builds on. Works for a NEW (greenfield) project or an EXISTING codebase: for an existing project (project_type: existing) it runs map-codebase first to reverse-engineer the as-is facts, then every phase reconstructs a target spec from them. Asks three setup choices up front (interactive vs autopilot; final combined summary; gre

Map how users actually move through the product to get value — the customer journey and the step-by-step flows for each feature, informed by conventional patterns for the category and an adversarial review pass. Use after define-product-requirements (reads .buildloop/project-spec/product-requirements.research.md) and before design-architecture. Writes a detailed, source-cited .buildloop/project-spec/user-flows.research.md plus a short human summary; an internal reviewer pass checks the draft and is merged in, then removed. The second product-layer step: it describes the experience (WHAT the user does), never the technical HOW and never visual UI design.

Cut a release: update the docs, bump the version if needed, write the changelog / release notes, and tag + commit + open the PR — in one gated step. Use as the final step of the release phase (run by release-product once the audits are clean, or standalone). A release engineer + tech writer: it FIRST checks the preconditions (clean working tree, no open 🔴 blocker from the audits), then refreshes the human-facing docs (README, the project documentation map, release notes), proposes the version bump (semver — proposed and confirmed, NEVER decided silently), updates the changelog from the work since the last release, and via the commit skill commits, tags, and opens the PR. Always confirms before acting, in BOTH modes (the careful pattern), and STOPS before any production deploy (deploy + post-deploy canary are out of scope by design). Never edits product code. The only outward-facing step of the release phase.

Decide the design direction that shapes scope and architecture — design system (or none), the inventory of key screens, responsive/viewport behavior, target platforms and their conventions, media-heaviness, offline/connectivity expectations, and the accessibility target — WITHOUT producing pixel layouts, colors, components, or mockups (those are implementation). Use after create-user-flows (reads .buildloop/project-spec/user-flows.research.md and .buildloop/project-spec/product-requirements.research.md) and before design-architecture, because these decisions feed the architecture's quality-attribute scenarios. Writes a detailed, source-cited .buildloop/project-spec/design-decisions.research.md plus a short human summary; an internal reviewer pass checks the draft and is merged in, then removed. The bridge from the product layer to the technical layer — design decisions only, never visual production.

Turn a validated idea into the product definition: who it is for, and the full set of features being built — backed by real-world research (comparable products, table-stakes features) and an adversarial review pass. Use after validate-idea (reads .buildloop/project-spec/idea-validation.research.md) and before create-user-flows and design-architecture. Writes a detailed, source-cited .buildloop/project-spec/product-requirements.research.md plus a short human summary; an internal reviewer pass checks the draft and is merged in, then removed. Defines the product layer (WHAT and for WHOM) — never the technical HOW, which is the separate design-architecture step.

Design the system's technical architecture from the product spec: elicit measurable quality-attribute scenarios first, then co-design the components AND the concrete technologies that realize them together — researching each candidate tool's current capabilities/pricing/limits, weighing 2–3 integrated options against the scenarios, and recording significant choices as ADRs. Use after create-user-flows (reads .buildloop/project-spec/user-flows.research.md and .buildloop/project-spec/product-requirements.research.md) as the first technical step, before design-dev-architecture. Writes a detailed, source-cited .buildloop/project-spec/architecture.research.md (+ adr/*) plus a short human summary; an internal reviewer pass checks the draft and is merged in, then removed. Requirements-first: scenarios always precede any tool talk, but the available toolbox is allowed to shape the decomposition.

Interview the human to extract maximum context before (and during) spec work — a relentlessly curious discovery grill that turns a short brief into a rich, shared understanding of what to build. Two roles. As the FIRST step of the create-project-spec pipeline it runs a full intake interview after the user's brief and writes .buildloop/project-spec/project-brief.research.md plus a short human summary, which every later phase reads as settled intent. On demand it is a reusable grill: any phase can invoke it scoped to a fork that's blocked on context only the human holds, and the user can invoke it directly at any time to be interviewed on any topic. Captures the user's intent, audience, scope, constraints, and developer preferences (stack, code style, design taste, tooling, architecture leanings — kept as soft priors for later phases) — it does NOT validate the idea or define features (those are validate-idea and define-product-requirements).

Generate several stub UI variants for a screen and render them so a human can compare and choose — no business logic, just static pages styled against the design system (the root DESIGN.md). Use on demand when working a feature and you want to see UI options before implementing, or in showcase mode to render a candidate DESIGN.md for design-system selection. Two modes: feature mode (given a task id or a free screen description, produces N variants against the committed DESIGN.md and records the chosen one as a design-note on the task so implement-feature follows it) and showcase mode (--showcase <DESIGN.md>, renders representative key screens against a candidate system — used by create-design-system). Rendering degrades gracefully: render in the project's own stack via .buildloop/project-setup/verification.md when runnable, else standalone HTML against the DESIGN.md tokens + any available screenshot tool, else generate files only with view instructions. Mockups are throwaway scratch under .buildloop/build-pla

Build one backlog task's feature in the working tree. Use as the implementation stage of the build loop — normally spawned fresh per task by build-product, or standalone on a task id. Reads the task's ## Description and acceptance criteria, builds the feature on the current branch following the project's CLAUDE.md conventions and the existing codebase patterns, then self-verifies the happy path against the verification contract (.buildloop/project-setup/verification.md) — optionally writing its own tests and running the environment for a fast inner loop — and gets the quality gate (make check) green before handing off, to catch obvious breakage before the independent verifier runs. Appends a ## Log note of what was done and moves the task to in_progress; it does NOT run the separate verifier and does NOT commit — build-product orchestrates verify-feature and the checkpoint commit. On a re-round after a failed verification, it reads the verifier's findings and runs the verifier's committed tests to reproduce t

Reverse-engineer an existing codebase into a factual as-is map before spec work — a forensic code archaeologist that charts what is actually built so the rest of the pipeline can reconstruct a spec from it. The brownfield front phase: when create-project-spec runs on a project that already has code (project_type: existing), this runs FIRST — before gather-context — and writes .buildloop/project-spec/codebase-map.research.md plus a short human summary that every later phase reads as the as-is ground truth. It charts structure, stack, domain model, surfaces/flows, tests, and build/run/CI/env, separating what's observed in the code from what's claimed from what's unknown. It maps as-is only — it does NOT validate the idea, define the target feature set, or design anything (those are the later phases, in existing-project mode).

Reconcile the downstream documents after an upstream spec change. Use when a stage document in .buildloop/project-spec/ has been edited (e.g. product vision changed) and the later stages — architecture, dev-architecture — and the build backlog need to be brought back in line. A thin cross-cutting conductor: it walks the dependency chain FORWARD from the changed stage, invoking each downstream stage's own skill in amend mode to surgically update its document (preserving the Forks/Decisions log), then continues into the backlog via plan-development (add/modify/cancel/reopen-as-rework task deltas). Runs automatically — no 'do you want to propagate?' gate — and pauses only for critical or destructive questions (cancelling a task, reopening a done one). It never writes code; rebuilding the affected features is a separate build-product run.

Take a built, verified product to a cut release. Use after build-product, as the release phase — the third pipeline, after the project-spec and build phases. A thin orchestrator: it reads the spec's quality-attribute contracts and runs the system-level audits (audit-security / audit-performance / audit-product / audit-code-health / audit-accessibility) as fresh, independent subagents in PARALLEL (they are read-only — they mutate nothing and collide on nothing), collects and ranks their findings by severity, files blockers/majors as rework tasks into the backlog (via plan-development's amend mode), drives a build-product run to fix them and re-audits — bounded by max_audit_iterations — until clean or escalated, then invokes cut-release (version + changelog + release notes + tag + commit + PR, always with confirmation, stopping before prod deploy). Audits never fix code; the cut is the only outward-facing step and always stops for the human. Resumable: the findings docs + backlog are the source of truth. Conduc

Pressure-test a raw product idea before any design or code. Use at the very start of a new project (or a major new feature) when the idea is still vague — to validate demand, audience, the problem, and the business model through adversarial forcing questions, backed by real-world research and an adversarial review pass. Writes a detailed, source-cited .buildloop/project-spec/idea-validation.research.md plus a short human summary; an internal reviewer pass checks the draft and is merged in, then removed. The first validation step of the create-project-spec pipeline; runs after gather-context (reads .buildloop/project-spec/project-brief.research.md if present) and before define-product-requirements, create-user-flows, and design-architecture (or let the create-project-spec orchestrator sequence them).

Independently verify that a built feature task actually meets its acceptance criteria. Use as the verification stage of the build loop — normally spawned by build-product as a separate, fresh agent so the verifier carries no bias from the implementer. Generic: it reads the project's run/drive/prove commands from .buildloop/project-setup/verification.md and the task's own acceptance criteria, authors and runs adversarial automated tests for those criteria (committed — the regression net), drives the real running stack, and proves observable outcomes (a screenshot, a DB row, a log line, an asserted response) — never trusting 'it ran'. Writes only tests, never the feature's implementation. Appends a dated batch of findings to the task's ## Log, sets a pass/fail verdict, bumps verify_attempts, and at the max_verify_iterations cap escalates the task to needs_human instead of looping. Runs after implement-feature; can also be invoked standalone on a task id.