Lemma skills

---
name: lemma-builder
description: "Design and build complete Lemma pods: model tables/files/functions/agents/workflows/schedules/connectors/surfaces/apps from a problem statement, author a local pod bundle, import progressively with the Lemma CLI, and verify every layer. Use for pod design, creation, restructuring, import/export, and app development. Do not use for day-to-day operation of an existing pod; use lemma-user instead."
---

# Lemma Builder

## What Is A Pod

A **pod** is one team's operating system: a shared workspace inside an organization
that holds everything one use case needs — **tables** and **files** (data, with
documents auto-indexed for built-in RAG), **functions**, **agents**, **workflows**,
**schedules**, and **connectors** (automation), and **apps** and **surfaces**
(interfaces) — under one permission boundary. Two rules run through all of it: every
workload starts with **zero access** and is granted resources explicitly by name,
and a workload acts under the **delegated identity** of the user who invoked it — so
RLS and the personal `/me` area resolve to that user, and the run can do only what
that user could do *and* the workload was granted. Good pod scope = one team,
one operating loop, one coherent data model.

> **Read `references/pod-model.md` first.** It is the canonical model every other
> doc grounds in — identity & permissions, the data/automation/interface layers,
> how the resources interact, and how a pod is authored. This file is the build
> entry point on top of it.

## The Resources

| Resource | What it is | What it solves |
| --- | --- | --- |
| **Tables** | Typed-column data store; per-table row-level security (RLS-on by default = each member's own rows; `enable_rls: false` = shared team data), foreign keys, enums | The pod's database: tickets, leads, approvals — durable structured state |
| **Files** | Document store under shared `/…` folders (e.g. `/knowledge`) and personal `/me`; uploaded documents are auto-indexed and semantically searchable — **built-in RAG** — with converted-markdown reading | The pod's knowledge and artifacts: contracts, manuals, reports, generated deliverables |
| **Functions** | Typed Python entrypoints run server-side as workload principals | Deterministic logic: validation, multi-table writes, external API calls, transforms |
| **Agents** | LLM workers with instructions, toolsets, and granted resources | Judgment: classification, drafting, extraction, research, conversation |
| **Workflows** | Node graphs of FORM / AGENT / FUNCTION / DECISION / LOOP / WAIT_UNTIL steps with durable runs | The process layer — orchestrates functions, agents, **and humans** (form nodes are assigned to pod members) |
| **Schedules** | Time-based (TIME cron) or event-based — DATASTORE (table row events) and WEBHOOK (connector events) | Starting agents or workflows automatically |
| **Connectors** | Third-party apps (Gmail, Slack, …) via org auth configs, accounts, and executable operations | Acting on external systems |
| **Surfaces** | One pod agent exposed on Slack/Teams/Telegram/WhatsApp/email | Meeting users where they already chat |
| **People outside** | Contacts (known by their channel), web chat visitors, and tables opened to outside rows — none of them sign in | Customer support, sign-ups, intake, "where is my order" — see `references/people-outside.md` and the `lemma-form` skill |
| **Apps** | Custom browser apps deployed into the pod — single-file HTML (no build) for one page, or Vite + lemma-sdk for multi-page apps | The product UI: dashboards, queues, detail views, workflow inboxes |

**Choosing among them — six heuristics** (full text in `references/pod-model.md` → "Choosing a primitive"; `pod-design.md` turns them into decision tables):

1. **One step, one agent.** One agent returning rich `output_schema` beats an agent→agent chain; split only for *orthogonal* judgments.
2. **Workflow = checkpoints + humans.** Reach for a workflow when people approve, are assigned steps, or watch progress — not for a lone call.
3. **Surface = a human is talking.** A chat-platform conversation is a surface; a *system event* driving unattended work is a schedule → workflow/agent.