convez.ai
SkillDesenvolvimento WebAvançado
suntay44

Buildable: Cérebro Local para Construtores de Apps IA

suntay44/buildable-plugin-skills

Conhecimento de builder em arquivo local para agentes de código

Ver no GitHub
BomPluginScore · de 0 a 100

Skill que dota agentes de código (Claude Code, Codex, Cursor) com inteligência de produto: arquétipos de apps, templates ouro, playbooks UI/UX e loops de revisão. Funciona localmente, reduzindo contexto bundled em avaliações e acelerando prototipagem guiada.

Instalação

$npx convez-ai suntay44/buildable-plugin-skills

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
54
Forks
8
Acompanhando
0
Saúde
100%
Último commit
há 2 meses
Versão
v1.0.1
Issues abertas
12
Contribuidores
1

Casos de uso

  • Acelerar protótipos de apps web/mobile com orientação de arquitetura
  • Reduzir tokens e contexto em avaliações de agentes IA de coding
  • Guiar agentes na seleção de padrões UI/UX e componentes reutilizáveis
  • Implementar quality gates automáticos (build, layout, acessibilidade, estado)

Veredito

Solução técnica sólida para quem quer embutir inteligência de produto em agentes de código sem depender de plataformas hosted. Excelente para contextos onde eficiência de tokens e velocidade de prototipagem são críticas; requer setup local e familiaridade com arquétipos de produto.

README

A tradução para o português deste README ainda está na fila.

⭐ Stars are appreciated!

Local-first AI app-builder brain for Claude Code, Codex, and Cursor.

Buildable gives your coding agent the product intelligence that hosted no-code builders (Lovable, Replit Agent, Base44, Emergent) hide behind their infrastructure — archetypes, golden templates, UI/UX playbooks, and a review loop — so it goes from a vague prompt to a polished prototype, using only a small slice of context per request.

It does not replace your agent or run as a hosted platform. It is a file-based skills/plugin package that runs locally. Buildable is independent and is not affiliated with, endorsed by, or sponsored by those products.

CI License: MIT Works with Claude Code Works with Codex Works with Cursor Expo React Native

Contents


Why Buildable

A raw coding agent starts every app from a blank slate. Hosted builders feel magical because they already know what a "todo app" or "CRM" should contain. Buildable packages that same knowledge locally:

  • Curated archetypes — 55 app types with default screens, entities, and interactions.
  • Micro-blocks — small reusable UI/product units (filterable table, detail panel, stat-card grid, form, empty state) that plan selects per app and the agent composes, instead of reinventing each one.
  • Golden templates — runnable, build-verified starters the agent adapts instead of inventing.
  • UI/UX system guidance — compact design profiles plus patterns for forms, tables, filters, empty states, and responsive layout.
  • Plan + review loop — a CLI that classifies prompts, emits an app spec, and audits the result.
  • Progressive loading — the agent reads only the references a prompt needs, not the whole repo.

What it is (and when to use it)

Buildable is a product-structure compiler, compact UI/UX brain, and quality gate for your coding agent: it decides what to build (archetype → screens, entities, features, states), selects reusable blocks, gives the app a selected designSystem, copies a runnable, build-verified starter, and reviews the result (build, layout, accessibility, state coverage, local-first). It is not a hosted builder.

BuildableDesign plugins (e.g. Frontend Design)Hosted builders (Lovable, v0, Replit)
Decides product structure✅—✅
Runnable, build-verified code✅—hosted
Reviews / grades the output✅——
Local — your repo, your agent✅✅—
Gives UI/UX direction✅✅✅
Deep brand/art directionguided✅✅

Pairs with dedicated design skills: Buildable decides what to build, gives compact product-specific UI/UX direction, and proves it works; add a design skill when you want high-end brand exploration, custom art direction, or multiple visual concepts.

  • Use it when you want consistent, real prototypes for common app types — fast, in your own stack, no lock-in.
  • Skip it when you need a one-off component or throwaway script; a raw agent is enough.

Example workflows

Buildable is audit-first: before code is written, plan creates a reusable build contract with the chosen app type, target, template, selected micro-blocks, screens, entities, features, references, guardrails, design profile, mock-data needs, and review gates. If the prompt is vague, it stops and asks the product-direction question first. If the prompt is clear, it adds optional prompt-refinement questions with sensible defaults so the agent can keep momentum without oversteering.

Fresh app

buildable plan "Build me a CRM for tracking leads"
buildable design "Build me a CRM for tracking leads"
buildable generate "Build me a CRM for tracking leads"
cd leadflow
buildable review

What happens:

  • plan writes .buildable/phase-plan.md, .buildable/phase-plan.json, and .buildable/phase-plan.toon. These are decision/context files, not app source.
  • plan also selects compatible appSpec.blocks; block docs are appended to appSpec.references, so agents load only the reusable building blocks this app actually needs.
  • design turns the selected design system into concrete UI/UX tokens, page rules, component states, and realistic mockup-data guidance.
  • generate creates the app folder. If the selected template is runnable, it copies build-verified starter source. If the selected template is planned-only, --plan-pack writes an implementation pack instead of source.
  • review audits the generated app against the saved spec, local-first rules, UI completeness, accessibility signals, responsive layout, and optional build output.

Behind the scenes this distinction is explicit: plan outputs a buildable-phase-plan with workflowStage: decision; generate writes a buildable-generated-project config with workflowStage: generated-files and sourcePlan set to either saved-phase-plan or inline-prompt-plan.

Existing app

cd my-existing-app
buildable init --existing
buildable plan "Add a local-first customer notes workflow"
buildable design --page customer-notes --write
buildable generate "Add a local-first customer notes workflow" --augment
buildable review

What happens:

  • init --existing makes the current repo Buildable-aware without overwriting code.
  • plan records the intended feature direction and selected references in .buildable/.
  • design --page can be used mid-session for one screen or component.
  • generate --augment writes Buildable implementation guidance for the existing app instead of copying a new starter over it.

With screenshots or files

buildable plan "Use this screenshot for a CRM dashboard" --file ./crm-mockup.png
buildable design --write
buildable generate "Use this screenshot for a CRM dashboard"

Buildable stores explicit user files in appSpec.referenceInputs, so the agent inspects only those files plus the selected appSpec.references. It does not scan every template or every knowledge file.

The recommended flow is Plan > Design > Generate > Review, but the commands are interchangeable: use design before planning for visual exploration, after planning to sharpen the UI, or mid-build for a specific page. After plan or design, the agent should ask whether the user is satisfied. If not, revise the saved phase plan; if yes, continue to generate or implementation.

Quick start

npm install
npm link
buildable check
buildable plan "Build me a task manager"
buildable design "Build me a task manager"
buildable generate "Build me a task manager"
cd taskflow
buildable review

With a screenshot or file reference:

buildable plan "Use this screenshot for a CRM" --file ./crm-mockup.png
buildable design --write
buildable generate "Use this screenshot for a CRM"

Prefer not to link a global command? Run through Node:

node ./bin/buildable.mjs check
node ./bin/buildable.mjs plan "Build me a mobile habit tracker"

See docs/install.md for Codex Desktop, Claude Code, Cursor, and CLI setup notes.

Install as a plugin

Claude Code

Buildable ships a plugin manifest (.claude-plugin/plugin.json) and a local marketplace (.claude-plugin/marketplace.json):

/plugin marketplace add suntay44/buildable-plugin-skills
/plugin install buildable@buildable

This auto-discovers the planner, web-builder, mobile-builder, and reviewer skills and registers these slash commands:

CommandWhat it does
/buildable-planCreate or revise the audit-first phase plan, app spec, selected references, and prompt-refinement questions
/buildable-designCreate a UI/UX-only brief from the prompt, saved plan, or current app spec
/buildable-generateCreate local project files from the saved plan: copy a runnable starter, write an augment pack, or write a planned-template pack
/buildable-reviewAudit a prototype against the saved app spec (--build runs typecheck/build)
/buildable-previewOptional: render the running app, screenshot it, catch runtime errors
/buildable-initMake the current workspace Buildable-aware

Cursor

Use the slash commands in .cursor/commands/ plus the rule at .cursor/rules/buildable.mdc.

Codex

Load .codex-plugin/plugin.json when your Codex surface supports local plugins/skills. For desktop or tool clients that cannot run project slash commands directly, register the MCP bridge shown below.

CLI commands

CommandPurpose
buildable plan "<prompt>" [--file <path>] [--with-auth] [--no-write]Create or revise the audit-first decision files: .buildable/phase-plan.md/json/toon. It classifies the prompt, preserves explicit screenshots/files, selects compatible micro-blocks, asks blocking product questions when needed, adds optional refinement questions with defaults, and selects only the references the agent should load.
buildable design "<prompt>" [--page <surface>] [--dark] [--write]Produce a UI/UX-only brief with concrete tokens (every profile ships light and dark palettes; --dark activates the dark theme), mockup-data guidance, and page/component rules; can use the current app spec
buildable generate "<prompt>" [--out <dir>]Create local project files from the saved plan. Runnable templates copy starter source; --plan-pack writes implementation files for planned templates; --augment writes guidance into an existing app.
buildable review [path] [--build]Audit the current app by default; optional path reviews another folder, optional --build runs typecheck/build
buildable preview [path] --url <url>Optional: render the running app in a headless browser; screenshot + catch runtime errors
buildable init [--existing]Create .buildable config for a workspace
buildable mcpStart the optional Buildable MCP stdio bridge for desktop/agent clients
buildable checkVerify local assets, adapters, and template references
buildable listList archetypes and runnable/planned template status
buildable eval [--compare]Score classification, efficiency, and spec quality (--compare vs a raw prompt)

plan emits an enhancedPrompt and appSpec with the selected archetype, target, stack, template, micro-blocks, design system, references, expected features, acceptance criteria, explicit user referenceInputs, audit-first planAudit, smart promptRefinement questions, and no-hosted-feature guardrails. Matching uses compact tags in core/archetype-registry.json, so the agent classifies against one small registry instead of reading every archetype file.

A few things worth knowing about the flow:

  • plan is the routing source. It classifies the prompt, picks the archetype/template/blocks, lists the exact references to load, and asks blocking questions only when product direction or architecture-changing choices are unclear. Not satisfied? Revise the saved .buildable/phase-plan.* and keep planning before you generate.
  • generate reuses the saved plan. If .buildable/phase-plan.json matches the prompt, it builds from that audited plan instead of re-planning, then writes the compact .toon contract into the generated app. Use --augment to plan into an existing app instead of copying a new starter.
  • review is a real gate. Add --build to run typecheck/build, and --strict to fail (not just warn) on local-first guardrail drift.

Review

buildable review audits the app spec, source representation, local-first guardrails, responsive-layout risk, accessibility signals, state coverage, design-token discipline (components that hard-code colors instead of using theme tokens get flagged), and — when persistence was requested — whether storage sits behind the repository seam. Add --build only when you also want it to run installed typecheck/build scripts. It is a static/local quality gate, not a replacement for manual QA, browser screenshots, or real device/simulator checks when visuals matter.

Design quality is graded against surface-specific rubrics, not taste: every plan loads the base web/mobile rubric plus a specialized one (content-marketing, data-dense, or forms-auth) selected by the app's design profile, backed by the shared token scales in core/design-system-registry.json (foundations). This is the part a hosted builder can't give you: design quality as an enforceable, local gate.

review also prints an advisory readiness section — an honest "what's left to productionize" list derived from the spec. It names what's intentionally mocked (in-memory vs local-persisted data, mock vs named-provider auth, no deploy) and points at the seam that makes each real (the persistence ladder, the auth seam). It is advice, not a gate: Buildable never auto-adds a backend — it tells you the local-first path to a real one.

Slash Commands and MCP

Buildable is command-first. Use the lightest integration your agent surface supports:

  • Terminal / CLI: run buildable plan, buildable design, buildable generate, buildable review, and the other commands above.
  • Project slash commands/rules: Claude Code uses /buildable-*; Cursor uses .cursor/commands/ and .cursor/rules/buildable.mdc; Codex can load the plugin manifest when local plugins are supported.
  • MCP bridge: use buildable mcp only for desktop or agent tool clients that cannot run those project commands directly. The client sees local tools named buildable_plan, buildable_design, buildable_generate, buildable_review, buildable_init, buildable_list, buildable_check, buildable_eval, and buildable_preview.

MCP does not load the whole Buildable brain. Each tool calls the same CLI engine, which returns a compact plan/spec and the exact appSpec.references the agent should inspect. Keep BUILDABLE_WORKSPACE pointed at the app folder you want the desktop client to work in.

Example local MCP config:

{
  "mcpServers": {
    "buildable": {
      "command": "node",
      "args": ["/absolute/path/to/buildable-plugin-skills/bin/buildable-mcp.mjs"],
      "env": {
        "BUILDABLE_WORKSPACE": "/absolute/path/to/your-app"
      }
    }
  }
}

Use that shape in Claude Desktop's local MCP settings, Cursor's .cursor/mcp.json / ~/.cursor/mcp.json, or the equivalent Codex MCP config. For Codex config TOML, the same server is typically:

[mcp_servers.buildable]
command = "node"
args = ["/absolute/path/to/buildable-plugin-skills/bin/buildable-mcp.mjs"]
env = { BUILDABLE_WORKSPACE = "/absolute/path/to/your-app" }

This makes the same Buildable actions available in desktop apps, but the UI may show them as tools instead of slash commands. If a desktop app already supports project slash commands or a local plugin install, prefer that; use MCP as the compatibility bridge.

Most of the time you can just open localhost yourself, and agents that already have a screenshot/preview tool (such as Claude Code's preview) should use that. buildable preview exists for the cases that have neither — a fully autonomous or CI run that still needs to know whether the page actually renders. Start the dev server, then:

buildable preview --url http://localhost:3000

It loads the page in a headless browser (Playwright — optional, resolved from the app or Buildable), writes .buildable/preview.png, and fails on a blank render or uncaught runtime errors — the visual issues tsc/build can't see. It is the only feature that needs a browser binary, so it stays optional and skips gracefully when Playwright is absent. It targets browser-rendered web apps today; native mobile visual checks would need a simulator and remain future work.

Templates

Golden templates are Buildable's approved starting points. They come in two levels:

  • Runnable starters copy real, build-verified source into the user's local folder.
  • Planned template packs do not copy app source yet; they write a scoped IMPLEMENTATION_PLAN.md, buildable-app-spec.json, and reference list so Claude, Codex, Cursor, or another agent can implement the app without reading every template.

Only templates marked ✅ runnable are copied by buildable generate without extra flags. Templates marked 📝 planned need buildable generate "<prompt>" --plan-pack; that writes instructions and specs, not runnable source.

What it generates

Real, unedited output — each rendered straight from a single prompt against its runnable starter:

TemplateTargetStatus
templates/web/task-managerweb✅ runnable
templates/web/crmweb✅ runnable
templates/web/dashboardweb✅ runnable
templates/web/marketplaceweb✅ runnable
templates/web/notesweb✅ runnable
templates/web/ecommerce-adminweb✅ runnable
templates/web/landing-pageweb✅ runnable
templates/web/portfolioweb✅ runnable
templates/web/blog-cmsweb✅ runnable
templates/web/recipe-appweb✅ runnable
templates/web/job-boardweb✅ runnable
templates/web/inventory-managerweb✅ runnable
templates/mobile/habit-trackermobile✅ runnable
templates/mobile/bookingmobile✅ runnable
templates/mobile/task-managermobile✅ runnable
templates/web/generic-appweb📝 planned fallback
templates/mobile/expense-trackermobile📝 planned
templates/mobile/travel-plannermobile📝 planned
templates/mobile/fitness-trackermobile📝 planned
templates/mobile/meal-plannermobile📝 planned
templates/mobile/chat-appmobile📝 planned
templates/mobile/subscription-trackermobile📝 planned
templates/mobile/maintenance-requestmobile📝 planned
templates/mobile/field-servicemobile📝 planned
templates/mobile/generic-appmobile📝 planned fallback
  • Default web stack: Next.js, TypeScript, Tailwind CSS, shadcn-style patterns, local/mock data.
  • Default mobile stack: Expo, React Native, TypeScript, NativeWind, Expo Router, local/mock data.

Fresh start vs existing app

# Fresh: copy a runnable starter and an app spec
buildable generate "Build me a todo app"
cd taskflow
buildable review

# Existing: profile the app and get guidance without overwriting code
cd my-existing-app
buildable init --existing
buildable plan "Add a booking workflow to this app"
buildable review

How much it guides

Buildable applies three levels of guidance so it reduces blank-page ambiguity without overstepping.

  • Defaults (applied automatically) — task managers get create/edit/delete/complete/reopen; dashboards get metrics, charts/tables, filters, empty states; forms get labels and validation; prototypes get meaningful sample data; local/mock data is the default.
  • Design system (applied automatically) — every plan includes appSpec.designSystem: visual tone, palette intent, typography mood, density, layout rules, component rules, motion, accessibility, and anti-patterns. Run buildable design only when you want a deeper UI/UX brief.
  • Micro-blocks (applied automatically) — every plan includes appSpec.blocks: selected reusable UI/product guidance such as filterable tables, detail panels, stat cards, entity forms, mobile list filters, and empty states. Blocks are not automatic code composition; they are compact references the builder adapts to the selected template and entities.
  • Mockup data (applied automatically) — every plan includes appSpec.mockData: 6-10 realistic local records per entity, domain-specific values, edge cases, and populated/empty/filtered/loading/error states so the design can be judged honestly before backend work exists.
  • Recommendations (agent may adapt) — task priority/due dates/tags, CRM stage summaries, dashboard date ranges, mobile-first touch layouts, and product-specific UI choices.
  • Ask first (never decided silently) — unclear product direction, auth, database/persistence, payments, collaboration/roles, external APIs, notifications, maps/camera/device permissions, deployment. buildable plan "I have a restaurant" asks what kind of restaurant product to build; buildable generate pauses when architecture-changing choices appear in a prompt unless you force it.
  • Auth shape (opt-in) — when the user explicitly asks for login/accounts or passes --with-auth, Buildable adds appSpec.auth and auth references. The default is local/mock auth behind a seam; named providers are treated as swappable adapters, not screen-level dependencies.
  • Persistence ladder (opt-in) — when the user asks to save/persist/remember data, Buildable adds appSpec.persistence and the knowledge/data-layer/ references: default to local browser/file storage behind a vendor-neutral repository seam, climbing to a hosted database only when the user names one — and buildable review then allows that one vendor while still flagging others.

Token efficiency

Agents load only the references a prompt needs (the appSpec.referenceLoadingContract), never the whole repo. Across the golden prompts, each plan loads ~9% of the bundled-brain reference bytes — about 91% less than loading the whole brain — while still specifying, on average, 6 features, 9 typed entity fields, and 4 acceptance criteria that a raw prompt gives you none of. (This measures Buildable's bundled context, not your total Claude/Codex session tokens.) Prove it yourself:

buildable eval --compare

Compact plan handoffs (TOON). The plan an agent reads back is itself token-optimized. Buildable serializes the build contract in TOON — a compact, dependency-free toon-style-v1 format (no install; it's built into the CLI). The same plan that is ~22 KB as full JSON is ~4.4 KB as TOON (~80% smaller), so:

  • buildable plan "<prompt>" --toon prints the compact contract; --compact prints slim JSON (drops the human planMarkdown render).
  • The MCP tools return the compact form by default (full JSON via verbose: true, the TOON contract via toon: true), so desktop/agent clients spend ~20–80% fewer tokens per plan with no loss of structured information.

Supported app types

~55 common categories — task managers, CRMs, dashboards, marketplaces, notes, ecommerce admin, booking, habit/fitness trackers, blogs, job boards, inventory, and more (tag-matched via core/archetype-registry.json). See the full list and which are runnable in CONTRIBUTING.md.

Non-goals

Buildable V1 does not include billing, builder accounts, cloud previews, managed databases, hosted deployments, telemetry, or central template services. Those may become optional extensions later — the core works from a local repository.

Repository map

core/           Prompt classification, app spec, workflow, ask-vs-build policy
knowledge/      Archetypes, data models, screen graphs, UI patterns, playbooks, rubrics
templates/      Golden templates (15 runnable starters + 10 planned specs)
skills/         Agent skills: planner, web-builder, mobile-builder, reviewer
commands/       Claude Code slash commands
adapters/       Codex, Claude, Cursor integration notes
bin/            Dependency-free CLI entrypoint
scripts/        Maintenance scripts (starter config sync)
.claude-plugin/ Claude Code plugin manifest + local marketplace
.codex-plugin/  Codex Desktop plugin manifest
.cursor/        Cursor rule and slash commands
evals/          Prompts, fixtures, and scoring rubric (buildable eval)
examples/       Generated reference apps

Templates catalog

See CONTRIBUTING.md for the full list of archetypes, golden templates, UI/UX playbooks, rubrics, and simple contribution instructions.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados