repo github.com View on GitHub ↗

Buildable — A Local, Build-Verified App-Builder Brain for Coding Agents

TL;DR

suntay44/buildable-plugin-skills (MIT, 48★, JavaScript, v1.0.1) is a local-first, file-based skills/plugin pack that gives a coding agent the product intelligence hosted no-code builders hide — archetypes, golden templates, UI/UX playbooks, and a review loop — so it goes from a vague prompt to a real prototype using only a small slice of context per request. It is not a hosted builder or a replacement agent: a dependency-free CLI (buildable plan/design/generate/review, plus /buildable-* slash commands and an optional MCP bridge) that runs in your repo, on Claude Code / Codex / Cursor. Its one genuinely new idea for the graph is Golden Templates — "adapt, don't invent": start from a curated, build-verified exemplar (every runnable starter is compiled/type-checked in CI) and adapt it, rather than reconstructing app structure from scratch. Everything else is a tight embodiment of concepts the graph already holds: it is CLI-first with MCP as a thin bridge (CLI Tools over MCP Servers), loads only the ~10% of its bundled "brain" a prompt needs via a plan-selected reference-loading contract (Search-Then-Get, Context Routing), runs a Plan → Design → Generate → Review chain with a real gate (Agentic Workflow Patterns), treats review as an enforceable local quality gate graded against rubrics (Eval-Driven Development), and makes the appSpec an audited, ask-first build contract (Spec-Driven Development). Should you care? As an artifact it is one author's product, not a source of principles — but it is a clean, load-bearing second witness that the graph's context-efficiency, CLI-over-MCP, and eval-gate theses are what people actually ship. Worth a look if you build agent skill-packs; the distinctive takeaway is the golden-template discipline, not the CLI surface.

What it is / how it is organized

A repo triaged at altitude — what it is, how it's structured, what to take from it — not a per-file reading:

What: a local plugin/skills package (a "brain") that a coding agent loads, not a hosted service and not a new agent. It decides what to build (archetype → screens/entities/features/ states), selects reusable blocks, gives the app a designSystem, copies a build-verified starter, and reviews the result. It never sends code anywhere; there is no billing, accounts, cloud, or managed DB (explicit non-goals).
Shape: a JavaScript monorepo whose load-bearing content is knowledge, not code. core/ (classifier, app-spec schema, ask-vs-build + reference-loading policy, archetype/design-system registries), knowledge/ (archetypes, data models, screen graphs, UI patterns, playbooks, quality rubrics), templates/ (15 runnable + 16 planned golden templates), blocks/ (micro-template registry + per-block guidance), skills/ (planner, web-builder, mobile-builder, reviewer), commands/ (Claude Code slash commands), adapters/ (Claude/Codex/Cursor), bin/ (a dependency-free CLI + an MCP bridge), and evals/ (prompts, fixtures, rubric).
Entry points: bin/buildable.mjs (the CLI engine, zero runtime deps) and bin/buildable-mcp.mjs (an optional stdio MCP bridge that calls the same engine). Three surface adapters (.claude-plugin/, .codex-plugin/, .cursor/) wrap the same core.
The workflow, concretely: plan classifies the prompt against a compact tag registry, emits an appSpec + .buildable/phase-plan.{md,json,toon} (an audit-first build contract), and stops to ask when product direction or an architecture-changing choice is unclear; design turns the selected design system into concrete tokens/rules; generate copies a runnable starter (or writes a planned/augment pack); review audits the output against the saved spec and rubrics. Commands are interchangeable but the recommended chain is Plan → Design → Generate → Review.
Not concept-worthy here: the per-template source, the CLI flag surface, and the 24-row template catalog are implementation detail — an on-demand deep-research burst, not this.

Concepts introduced

Golden Templates — new page. Curated, build-verified exemplar apps the agent adapts ("adapt, don't invent") rather than reconstructing structure from scratch; two tiers (runnable copy-source vs. planned implementation-pack), paired with a reusable micro-block registry. The one idea in this capture the graph did not already hold.

Held, not dropped (themes the capture touches that don't warrant their own page yet — spin out on demand):

TOON compact handoff format. The build contract is serialized in a compact, dependency-free toon-style-v1 format (~22 KB JSON → ~4.4 KB, the source claims ~80% smaller) as the preferred agent handoff. Held as an instance of token-efficient agent-to-agent serialization; promote if a second source frames compact handoff formats as a pattern rather than one tool's choice.
Local-first persistence ladder + swappable seam. Default to local/mock data and auth behind a vendor-neutral repository seam; a named backend/provider is supported only when the user asks and is treated as a swappable adapter, never a platform dependency — and review then allows that one vendor while flagging others. A software-architecture principle (dependency-inversion for agent-generated apps); held.
Ask-vs-build / audit-first policy. plan asks blocking product-direction questions when intent is vague and pauses generate on architecture-changing choices (auth, DB, payments, deploy) unless forced. This is Spec-Driven Development's plan-first + a human approval gate; folded there and noted rather than spun out.
Micro-blocks as a composable UI-unit registry. Reusable product units (filterable table, detail panel, stat-card grid, entity form, empty state) selected per app and composed by the agent. Folded into Golden Templates; promote if a source frames reusable UI blocks as a concept in their own right.
Design-token discipline as a graded review dimension. review flags components that hard-code colors instead of using theme tokens, grading against surface-specific rubrics (content-marketing / data-dense / forms-auth) backed by shared token scales. Folded into Eval-Driven Development as "design quality as an enforceable local gate."
Multi-surface agent packaging. One knowledge pack fronted by adapters for Claude Code, Codex, and Cursor. The "harness-over-many-agents" / vendor-neutral tooling theme also held under Nimbalyst — Visual Workbench for Supervising Coding Agents; held until a source argues vendor-neutrality as a design principle.

Key claims

Attributed to the source (a README + repo structure); the groundable numbers are flagged as the source's claims for a later verification pass, not verified here.

Adapt a proven, build-verified exemplar instead of reconstructing app structure from a blank slate ("adapt, don't invent"). (best practice) — context: common app types with a recognizable shape; skip it for one-off/throwaway work. → Golden Templates
A template is "golden" only if it is build-verified — the source claims every one of 15 runnable starters is built and type-checked in CI, the CLI has 77 tests and zero runtime dependencies, and screenshots are unedited single-prompt output ("proof it's real, not a prompt wrapper"). observation — the source's groundable claim. → Golden Templates / Eval-Driven Development
Ship two tiers: runnable starters copy real source; planned packs emit a scoped implementation plan + app spec + reference list so the long tail (61 recognized archetypes) builds from a contract, not a blank slate. observation → Golden Templates
Load only the references a prompt needs — the source claims ~10% of the bundled-brain reference bytes per plan (~90% less than loading the whole brain), provable via buildable eval --compare. observation — the source's groundable measurement; the discipline is progressive disclosure of a shipped knowledge pack. → Search-Then-Get / Context Routing
Classify the prompt against one compact tag registry (core/archetype-registry.json) instead of reading every archetype file, then emit the exact reference list to load. (best practice) — context: routing over a large bundled knowledge base; the classifier + reference list is what keeps context lean. → Context Routing
Keep the CLI engine as the brain and expose MCP as a thin bridge — "MCP does not load the whole Buildable brain"; each tool calls the same CLI and returns a compact plan + the exact references to inspect. (best practice) — context: desktop/tool clients that can't run project slash commands; MCP is the compatibility bridge, not the primary surface. → CLI Tools over MCP Servers
Run a Plan → Design → Generate → Review chain with a real gate between generation and acceptance; commands are interchangeable but the chain is the recommended path. (best practice) — context: prompt-to-prototype workflows where a review gate catches drift. → Agentic Workflow Patterns
Make review an enforceable local quality gate graded against surface-specific rubrics — design-token discipline, local-first seam, accessibility signals, state coverage, responsive risk — with --strict failing (not warning) on guardrail drift. (best practice) — context: static/local quality gating (not a replacement for manual QA or device checks); "this is the part a hosted builder can't give you: design quality as an enforceable local gate." → Eval-Driven Development
Treat the appSpec as an audited, ask-first build contract — plan before code, ask blocking questions when product direction or architecture is unclear, and revise the saved plan rather than the generated code when it's wrong. (best practice) — context: agent app-building where a solid front-loaded plan prevents downstream surprises. → Spec-Driven Development
Serialize the build contract in a compact TOON format for handoff — the source claims ~22 KB JSON → ~4.4 KB (~80% smaller), MCP tools return compact JSON by default. observation — the source's groundable claim; held theme.

Why this is novel (and what it corroborates)

The dominant stance is novel on one axis only: the capture introduces Golden Templates — build-verified exemplars an agent adapts rather than generates from scratch — which no existing concept covered. On every other axis this repo is a corroboration, not a new region, and its value to the graph is precisely as a second (or third) independent witness that the theses hold up in a shipped tool:

Corroborates CLI Tools over MCP Servers. Buildable is CLI-first by construction: a dependency-free CLI is the engine, and MCP is explicitly a compatibility bridge that "does not load the whole brain" and returns compact results. An independent author converging on CLI-as-primary, MCP-as-thin-bridge — noted, not duplicated.
Corroborates Search-Then-Get and Context Routing. "Load only the ~10% slice a prompt needs" via a plan-emitted reference-loading contract is progressive disclosure over a shipped knowledge pack: classify → point at the exact files → load only those. Same attention-budget discipline as the memory-retrieval two-tool split, here applied to a bundled brain rather than a memory store.
Corroborates Eval-Driven Development. Two ways: CI build-verification is the eval that makes a template "golden," and review is a real, rubric-graded gate (--strict fails on drift) — "measure, don't vibe" turned into an enforceable local artifact.
Corroborates Spec-Driven Development. The appSpec/phase-plan is the audited build contract; plan-first with ask-first blocking questions, and "revise the plan, not the broken code" is exactly the spec-first, fix-the-plan stance the graph already holds.
Corroborates Agentic Workflow Patterns. Plan (classify/route) → Design → Generate → Review is prompt-chaining with a gate plus routing, the two simplest composable patterns wired together.