Create and manage Brickend projects — scaffold production-ready backends with composable bricks on Supabase Edge Functions. Use this skill whenever the user wants to create a new backend, REST API, or app project, add CRUD endpoints, define database schemas, set up authentication, configure RBAC roles, manage multi-tenant workspaces, modify installed bricks (add/remove fields, endpoints), regenerate code, or check project status. Also trigger when the user mentions Brickend, bricks, Supabase Edge Functions, TypeScript API scaffolding, or wants to build a backend incrementally. Even if they just say "create an API" or "I need a backend" — this skill applies.
Brickend scaffolds backend projects incrementally using composable modules called bricks. Each brick declares a database schema, REST API endpoints, and RBAC rules, then generates TypeScript code for Supabase Edge Functions. Projects track state in brickend.state.json so every session knows what was built before.
Brickend requires Bun. It will not work with Node.js alone.
Before recommending templates or bricks, discover what's available. The catalog changes — never hardcode or guess.
Primary (CLI):
brickend list --json
Returns { templates: [...], bricks: [...] } with names, descriptions, dependencies, and settings. Use --templates or --bricks to filter.
Fallback (MCP): If the Brickend MCP server is configured, use brickend_list_templates and brickend_list_bricks tools.
Rules:
multi_tenant: true include workspace isolationtype: "extension" are auto-installed by their parent — never suggest them directlystarter.bricks.yaml files. Always use brickend create-brick <name> to create new bricks. The command registers the brick in brickend.state.json, pre-fills RBAC roles, and resolves dependencies. Manually created YAML files are NOT registered in state and brickend generate will reject them.brickend.state.json. The CLI manages state automatically.brickend add <name>brickend create-brick <name> then brickend generate <name>brickend/<name>/ then brickend generate <name>| Command | Purpose |
|---|---|
brickend init [name] | Create a new project (use . or omit for current directory) |
brickend add [bricks...] | Add bricks to an existing project (resolves dependencies) |
brickend create-brick <name> | Create a custom brick definition in the project |
brickend generate <brick> | Regenerate code after editing a brick's manifest |
brickend status | Show installed bricks, roles, settings |
brickend list | List available templates and bricks |
brickend lint [path] | Validate brick YAML files |
brickend install-skill | Install Brickend skill into Claude Code (~/.claude/skills/) |
All commands support --dry-run to preview without writing. Run brickend <command> --help for full options.
Discover available templates and bricks
Confirm with the user: project name (lowercase, hyphens OK) and template choice
Initialize:
# Create in new subdirectory:
brickend init <project-name> --template <template>
# Or initialize in current directory:
mkdir <project-name> && cd <project-name>
brickend init . --template <template>
# (omitting the name also defaults to current directory: brickend init --template <template>)
Sets up git + Supabase, generates shared infrastructure (CORS, auth, RBAC, errors), installs baseline bricks, runs migrations, and starts Supabase locally.
Add optional bricks:
brickend add <brick-name>
Dependencies resolve automatically. Run brickend add with no args for interactive selection.
Verify and start:
brickend status
supabase functions serve
API available at http://localhost:54321/functions/v1/.
When working inside a project that already exists:
Understand what's installed:
brickend status
Shows installed bricks with versions, roles, migration count, multi-tenant flag.
Decide the action:
brickend add <brick>brickend create-brick <name> then brickend generate <name>brickend generate <brick>brickend lintAlways use the CLI command — never write .bricks.yaml files manually. Manual files won't be registered in brickend.state.json and brickend generate will reject them.
When a user needs a brick that doesn't exist in the catalog (a custom entity, table, or feature):
Create the brick (one command — creates manifest + generates code):
# Full specification via flags (recommended for AI agents):
brickend create-brick invoices \
--fields "title:string:required,amount:numeric:required,due_date:string,status:string:required" \
--owner \
--search-field title \
--description "Invoice management"
This creates the YAML manifest, registers it in state, AND generates all code (schema, services, entrypoint, migration) automatically.
Scaffold mode (create YAML only, edit before generating):
brickend create-brick invoices --no-generate
# Edit brickend/invoices/invoices.bricks.yaml
brickend generate invoices
Flags reference:
| Flag | Description |
|---|---|
--table <name> | Table name (default: brick name) |
--primary-key <name> | PK column name (default: singularized table + _id) |
--fields <defs> | Field definitions: name:type[:required][:nullable][:ref=brick] |
--owner | Add owner_id referencing auth (with-owner create mode) |
--endpoints <list> | Handlers: list,get,create,update,softDelete (default: all) |
--auth-required / --no-auth-required | Require authentication (default: true) |
--search-field <field> | Field for ?q= search |
--requires <bricks> | Comma-separated brick dependencies |
--description <desc> | Brick description |
--version <ver> | Version (default: 1.0.0) |
--dry-run | Preview YAML without writing |
--no-generate | Create manifest only, skip code generation |
--no-workspace | Opt out of workspace scoping in multi-tenant projects |
Field definition format: name:type[:required][:nullable][:ref=brick]
string, text, email, uuid, boolean, numeric, url"title:string:required,price:numeric:required,category_id:uuid:ref=categories"What it does:
brickend/<name>/<name>.bricks.yaml with the brick definitionaccess: rules from the project's configured rolesbrickend.state.json (required for generate)auth to requires: when --owner is usedrequires:ref=<name> — dependencies resolve from both catalog and project manifestsmulti_tenant: true, auto-sets workspace_scoped: true and requires workspaces brick (opt out with --no-workspace)Note: By default, create-brick creates the manifest AND generates all code automatically. Use --no-generate if you want to edit the YAML before generating. Use --dry-run to preview the YAML without writing anything.
Recovery: If a manifest was created manually (without create-brick), running brickend generate <name> will auto-detect it, register it in state, and generate code.
This is for bricks already installed via brickend add or brickend create-brick + brickend generate. To create a NEW brick, use the "Create a Custom Brick" workflow above.
When a user wants to add/remove fields, change endpoints, or update access rules on an already-installed brick:
Edit the manifest:
brickend/<brick-name>/<brick-name>.bricks.yaml
Regenerate:
brickend generate <brick-name>
Options:
--dry-run — preview without writing--force — overwrite even manually modified files--no-migration — skip ALTER TABLE generation--no-reset — skip local database reset after migrationWhat CAN be changed:
schema.fields — generates ALTER TABLE migrationapi.endpoints — regenerates entrypoint + servicesaccess — regenerates RBAC permission seedsWhat CANNOT be changed via generate:
brick.name, schema.table, schema.primary_key — require manual migrationrequires — use brickend add for new dependenciesapi.type (rest ↔ auth) — fundamentally different code pathsFile safety: Files manually edited by the user are detected via content hashes and skipped with a warning. Use --force to overwrite.
Migrations: Field additions generate ALTER TABLE ADD COLUMN. Removals generate DROP COLUMN IF EXISTS. Type changes emit -- TODO comments for manual review. After creating a migration, the local database is automatically reset (supabase db reset) to apply it. Use --no-reset to skip.
Original manifest has: