Local product-structure compiler, compact UI/UX brain, and quality gate for your coding agent: a prompt becomes the right archetype, selected design system, runnable build-verified starter, and reviewed result.

version
1.0.1
GitHub stars
54

Install

/plugin install buildable@buildable

Run it inside Claude Code after adding the marketplace with /plugin marketplace add suntay44/buildable-plugin-skills.

Contents

Discovered from source

Skills 4

Buildable Mobile Builder Skill

Use this skill to generate or adapt local mobile prototypes.

Resolve all referenced paths from the Buildable plugin or repository root.

Reference Loading Contract

Mandatory order:

  1. Read .buildable/phase-plan.toon first when present. It is a summary: retrieve omitted details (such as full design rules or expected files) from the authoritative .buildable/phase-plan.json as needed. Without a saved plan, read buildable-app-spec.json. Reuse the plan for unchanged requirements rather than re-planning or reading all formats.
  2. Load only appSpec.references.
  3. Load current project files only as needed for the requested change.
  4. Do not load web templates or unrelated mobile archetypes.
  5. Load starter source only for the selected template and only when generating or editing it.

Default Stack

  • Expo
  • React Native
  • TypeScript
  • NativeWind
  • Expo Router when appropriate
  • local/mock data

Workflow

  1. Read the saved plan/app spec from the planner handoff.
  2. Check appSpec.planAudit.checks before editing; treat blocked/failed checks as gates, not suggestions.
  3. If questionsNeeded is true, ask the user before generating.
  4. Apply appSpec.designSystem for visual tone, density, palette intent, touch layout rules, component rules, accessibility, and anti-patterns.
  5. Apply appSpec.blocks as reusable micro-template guidance. Selected block docs are references to adapt to the current entity/design system, not generic code to paste blindly.
  6. If appSpec.auth.requested is true, implement the local/mock auth shape first and keep any named provider behind the auth seam.
  7. Load only the references listed in the app spec.
  8. If the template is generic-app, use the selected archetype reference to shape screens and entities instead of loading unrelated mobile templates.
  9. Generate touch-first screens and local state.
  10. Validate navigation, touch targets, and state coverage.
  11. Run buildable review from the selected app workspace when the CLI is available.

Build Order

  1. Create typed entities and local sample data.
  2. Build the first mobile screen around the main daily workflow.
  3. Add navigation only when the screen graph requires it.
  4. Add empty, completed, validation, and confirmation states as appropriate.
  5. Review against the selected mobile quality rubric.

Guardrails

  • Do not add accounts, push notifications, external APIs, or backend services unless requested.
  • Keep the mobile app runnable locally.

Buildable Planner Skill

Produce a local-first app spec and phase plan from the user's prompt, explicit reference files, and relevant existing-project context. Resolve bundled paths from the Buildable plugin or repository root.

CLI Workflow

  1. Run buildable plan "<prompt>" --compact. This retains the structured spec and phases while omitting the duplicate Markdown render; full .buildable/phase-plan.json, .md, and compact .toon files are still saved. Use --no-write only for terminal-only inspection. For MCP, use buildable_plan with its compact default.
  2. Pass explicit user files with --file <path>, --reference <path>, or --screenshot <path>; inspect appSpec.referenceInputs without pasting file contents into the prompt. For requested auth use --with-auth; record a named provider with --with-auth-provider <provider>. Keep auth local/mock behind a seam unless a provider is named.
  3. Use the returned classification, appSpec, and phasePlan as the planning result. Do not repeat classification or reopen registries/policies already applied by the CLI. Load only needed files from appSpec.references; load selected starter source only when generating or editing it. Never scan whole knowledge/template directories or unselected templates.
  4. Check appSpec.planAudit gates and ask blocking appSpec.questions when questionsNeeded is true before design or generation. Otherwise ask at most one or two promptRefinement.optionalQuestions only when the answer materially changes the plan; use defaults when the user wants to proceed.
  5. Summarize the plan once using the output guidance below. Keep implementation within the user's request; a planning-only request does not start app code. The included design system is sufficient to proceed; run buildable design only when a deeper UI/UX brief is useful.

CLI-Unavailable Fallback

Only when the CLI is unavailable, build the spec manually:

  • Match core/archetype-registry.json tags, then apply core/ask-vs-build-policy.md and core/activation-policy.md. Use knowledge/INDEX.md and templates/INDEX.md only for discovery.
  • Load the selected archetype, matching data-model/screen-graph files when present, and the best target-specific template spec. Preserve runnable versus plan-only status.
  • Select design guidance from core/design-system-registry.json and compatible micro-blocks from blocks/registry.json; include only selected references.
  • Follow core/app-spec-schema.md: include realistic mockData and state coverage, explicit referenceInputs, promptRefinement assumptions/questions/defaults, planAudit gates, and requested auth/persistence seams. Keep data local/mock and state non-goals explicitly.
  • Include clarify, plan, mock-data, design, build, and review phases with blockers and completion criteria tied to the selected screens, features, and acceptance criteria.

Output And Handoff

Give a short decision summary: app direction, target/stack, screens and key behavior, non-goals, design/mock-data approach, blockers or important assumptions, and the next actionable phase. Link the saved plan instead of repeating the full app spec, audit checks, reference list, and phase plan in chat; expand those details when requested. On revisions, retain the accepted direction and constraints, update the saved plan, and summarize what changed.

For planning-only requests, end with one satisfaction checkpoint: revise in Buildable Planner if needed, or continue with Buildable Web Builder/Mobile Builder for the selected target. If the user already asked to build and there are no blockers, continue to that builder without another approval checkpoint.

The builder should read .buildable/phase-plan.toon first for compact context, then retrieve omitted details from .buildable/phase-plan.json as needed (for example, full design rules or expected files). TOON is a summary; JSON remains the source of truth. Reuse the saved plan rather than re-planning unchanged requirements, and load only selected appSpec.references, explicit user reference inputs, and necessary starter/project source.

Buildable Reviewer Skill

Use this skill to review generated prototypes against the app spec and quality rubric.

Resolve all referenced paths from the Buildable plugin or repository root.

buildable review is a static/local quality gate. Treat it as a strong first pass for structure, local-first guardrails, source coverage, responsive-layout risk, accessibility signals, and optional build checks; it does not replace manual QA, real device/simulator checks for mobile, or browser/screenshot review when visuals matter.

Reference Loading Contract

Mandatory order:

  1. Run buildable review from the selected app workspace when available. Pass a path only when reviewing a different folder.
  2. Load the app spec and selected rubric.
  3. Load only files related to reported issues.
  4. Do not load all templates.
  5. Do not load unrelated archetypes or starter source.

Workflow

  1. Run buildable review when the CLI is available. Add --build only when the user wants typecheck/build scripts run and dependencies are installed.
  2. Read the app spec and selected quality rubric.
  3. Run available build, typecheck, lint, or test commands (or rely on review --build).
  4. Inspect the generated UI when possible — start the app and run buildable preview --url <url> from the app workspace to render it, screenshot it, and catch runtime/visual errors that build checks miss.
  5. Check required interactions, state coverage, responsive behavior, and accessibility.
  6. Produce a focused fix list.
  7. Apply fixes when operating as the active coding agent.

Review Priorities

  • build correctness
  • primary workflow
  • missing interactions
  • empty/loading/error states
  • mobile and desktop layout
  • accessible form controls
  • unnecessary backend or hosted features

Output Format

Lead with blocking issues, then polish issues, then checks run. If no issues remain, say so and note residual risks.

Buildable Web Builder Skill

Use this skill to generate or adapt local web prototypes.

Resolve all referenced paths from the Buildable plugin or repository root.

Reference Loading Contract

Mandatory order:

  1. Read .buildable/phase-plan.toon first when present. It is a summary: retrieve omitted details (such as full design rules or expected files) from the authoritative .buildable/phase-plan.json as needed. Without a saved plan, read buildable-app-spec.json. Reuse the plan for unchanged requirements rather than re-planning or reading all formats.
  2. Load only appSpec.references.
  3. Load current project files only as needed for the requested change.
  4. Do not load all templates.
  5. Load starter source only for the selected template and only when generating or editing it.

Default Stack

  • Next.js
  • TypeScript
  • Tailwind CSS
  • shadcn-style component patterns
  • local/mock data

Workflow

  1. Read the saved plan/app spec from the planner handoff.
  2. Check appSpec.planAudit.checks before editing; treat blocked/failed checks as gates, not suggestions.
  3. If questionsNeeded is true, ask the user before generating.
  4. For fresh starts, prefer buildable generate "<prompt>" when a runnable template exists. Add --out <dir> only when the user requested a specific folder.
  5. Apply appSpec.designSystem for visual tone, density, palette intent, layout rules, component rules, accessibility, and anti-patterns.
  6. Apply appSpec.blocks as reusable micro-template guidance. Selected block docs are references to adapt to the current entity/design system, not generic code to paste blindly.
  7. If appSpec.auth.requested is true, implement the local/mock auth shape first and keep any named provider behind the auth seam.
  8. Load only the references listed in the app spec.
  9. If the template is generic-app, use the selected archetype reference to shape screens and entities instead of loading unrelated templates.
  10. Inspect the local project if generating inside an existing app.
  11. Generate or adapt a complete first-screen prototype.
  12. Keep data local unless the spec explicitly requires otherwise.
  13. Run build/typecheck/lint checks when available.

Build Order

  1. Create typed entities and sample data.
  2. Build the primary screen and state operations.
  3. Add empty, filtered, and edited states.
  4. Apply responsive layout rules.
  5. Review against the selected quality rubric.

Guardrails

  • Do not add auth, accounts, billing, cloud previews, managed databases, telemetry, or deployment.
  • Do not create marketing landing pages for app requests.
  • Do not leave generic placeholder UI.

Commands 7

Create a Buildable design brief for: $ARGUMENTS

  1. Run the design command:

    if command -v buildable >/dev/null 2>&1; then
      buildable design "$ARGUMENTS"
    else
      node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" design "$ARGUMENTS"
    fi
    

    Use --page "login" or similar when the user asks for a specific page/component. Add --dark (or say "dark mode" in the prompt) to make the dark palette the active theme. Add --write only when the user wants the brief saved into the current app workspace.

  2. If a buildable-app-spec.json exists, treat it as the app context. Otherwise, let design classify the prompt.

  3. Use the returned design brief as the UI/UX source of truth: design system profile, color tokens, typography, spacing, motion, component emphasis, anti-patterns, and references.

  4. Treat buildable design as UI/UX-only. Do not add backend code, databases, auth, payments, hosted infrastructure, telemetry, or deployment from this command.

  5. Load only the references listed in the brief. Do not load all templates or all design playbooks.

  6. Apply the brief to the requested app, page, or component while preserving the existing stack and local-first guardrails.

  7. End by asking whether the user is satisfied with the UI/UX direction and mockup-data plan. If yes, offer the brief's nextSuggestedCommand (usually buildable generate "<prompt>") as the build phase. Do not generate unless the user asked for building too.

Generate a Buildable prototype for: $ARGUMENTS

  1. Plan first, then generate. If .buildable/phase-plan.json exists and the prompt matches, generation reuses that saved audit-first plan. For runnable templates this copies a polished starter; for planned templates add --plan-pack:

    if command -v buildable >/dev/null 2>&1; then
      buildable generate "$ARGUMENTS"
    else
      node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" generate "$ARGUMENTS"
    fi
    
    • If the CLI reports the prompt has architecture-changing choices, ask the user those questions, then rerun with --force only if the prompt already answers them.
    • If the CLI reports the template is not runnable yet, rerun with --plan-pack to write an instruction pack.
    • Add --name "App Name" to brand the generated app, or pass a name in the prompt ("...called FocusList").
    • Add --with-auth when the user explicitly wants login/accounts but did not include it in the prompt. Use --with-auth-provider <provider> only when the user names a provider.
    • To add a feature to an existing app instead of scaffolding a new one, use --augment (writes a plan that adapts to the current project without overwriting code).
  2. Read buildable-app-spec.json in the output directory and load only appSpec.references. Use .buildable/phase-plan.toon when present as the compact build contract for audit gates, references, screens, entities, features, and guardrails.

  3. Adapt the starter (or implement the plan pack) to the user's specific request. Keep data local/mock by default. Do not add auth, billing, databases, telemetry, or deployment unless explicitly requested.

  4. When code exists, verify it builds, then run /buildable:buildable-review on the output directory and fix blocking issues before handoff.

Initialize Buildable in the current workspace.

  1. For an existing app, profile the repo without overwriting code:

    if command -v buildable >/dev/null 2>&1; then
      buildable init --existing
    else
      node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" init --existing
    fi
    

    For a fresh workspace, omit --existing.

  2. Read the generated .buildable/repo-profile.json (existing apps) to learn the detected framework, language, and styling so later generation matches the project's conventions.

  3. Tell the user the workspace is ready and suggest /buildable:buildable-plan as the next step.

Run Buildable planning for the request: $ARGUMENTS

  1. Get the structured spec and phases without the duplicate Markdown render:

    if command -v buildable >/dev/null 2>&1; then
      buildable plan "$ARGUMENTS" --compact
    else
      node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" plan "$ARGUMENTS" --compact
    fi
    

    Pass explicit user files as --file <path> or --screenshot <path> instead of pasting contents into the prompt. For requested auth/login/accounts, use --with-auth; for a named provider, use --with-auth-provider <provider> and keep it behind the auth seam.

  2. Use the CLI result rather than repeating classification. Follow appSpec.referenceLoadingContract: load only needed appSpec.references and explicit appSpec.referenceInputs, and selected starter source only when generating or editing it. Do not scan whole knowledge/template directories.

  3. Ask blocking appSpec.questions before design or generation when questionsNeeded is true. Otherwise ask at most one or two promptRefinement.optionalQuestions only if they materially improve the plan; use defaults when the user wants to proceed.

  4. Summarize direction, target/stack, screens/key behavior, non-goals, design/mock-data approach, important assumptions or blockers, and the next phase. Link the saved .buildable/phase-plan.md instead of repeating the full spec and references. The plan already includes design guidance; a deeper buildable design pass is optional.

  5. For planning-only requests, ask one satisfaction checkpoint: revise the saved plan in Buildable Planner or continue with Buildable Web Builder/Mobile Builder for the target. On revisions, retain accepted constraints and summarize changes. If the user already asked to build and no blockers remain, continue without another checkpoint. The builder should read .buildable/phase-plan.toon first and retrieve omitted details from the JSON source of truth as needed; reuse the saved plan for unchanged requirements.

Visually verify the prototype at: ${ARGUMENTS:-.}

  1. Start the app's dev server if it isn't already running (e.g. npm run dev), and note the local URL (default http://localhost:3000).

  2. Render and capture it:

    if command -v buildable >/dev/null 2>&1; then
      buildable preview "${ARGUMENTS:-.}" --url http://localhost:3000
    else
      node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" preview "${ARGUMENTS:-.}" --url http://localhost:3000
    fi
    
    • This needs Playwright. If preview reports it is skipped, install it once: npm i -D playwright && npx playwright install chromium. If you have your own preview/screenshot tool, use that instead.
  3. Open the screenshot at .buildable/preview.png and read .buildable/preview-report.md. Confirm the first screen looks intentional: visible primary actions, real sample data, non-generic empty states, no overlap, no blank render.

  4. Fix anything the screenshot or runtime errors reveal (things tsc/build cannot catch), then re-run preview until it passes.

Review the selected workspace by default. If a path is provided, review: ${ARGUMENTS}

  1. Run the Buildable reviewer:

    if command -v buildable >/dev/null 2>&1; then
      buildable review "${ARGUMENTS:-.}"
    else
      node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" review "${ARGUMENTS:-.}"
    fi
    

    Add --build only when the user wants the reviewer to also run the project's typecheck/build scripts and dependencies are installed. Add --strict to fail (not just warn) on local-first guardrail drift (unrequested billing, managed databases, telemetry, etc.).

  2. Read the generated .buildable/review-report.md. Load only the files named by reported issues.

  3. Fix blocking issues first (missing entities, missing features, non-local-first drift, build failures), then polish issues. Keep changes local-first.

  4. Report what you fixed and any residual risks. If the review now passes, say so plainly.

  5. Relay the advisory Readiness section as the honest "what's left to ship" summary (mocked vs persisted data, mock vs named-provider auth, no deploy). It is guidance, not a failure — do not auto-add a backend, auth provider, or deploy config unless the user asks; point them at the persistence/auth seams instead.

Inspect the selected workspace by default. If a path is provided, inspect: ${ARGUMENTS}

  1. Run the Buildable status inspector:

    if command -v buildable >/dev/null 2>&1; then
      buildable status "${ARGUMENTS:-.}"
    else
      node "${CLAUDE_PLUGIN_ROOT:-.}/bin/buildable.mjs" status "${ARGUMENTS:-.}"
    fi
    
  2. Treat the output as the current workflow handoff:

    • If no plan exists, suggest /buildable:buildable-plan.
    • If scope is blocked, ask the listed questions before design/generate.
    • If a plan exists, use /buildable:buildable-design.
    • If design is ready and no app is generated, use /buildable:buildable-generate.
    • If generated files exist, use /buildable:buildable-review.
  3. Do not load unrelated templates or references. status is read-only; it tells you where the workspace is, not what to build.

MCP servers 1

Sponsors

Details

Marketplace
suntay44/buildable-plugin-skills
Category
Community
License
MIT
Keywords
app-builder, local-first, prototype, nextjs, expo