geenius-mvp

The agent workflow

This repo is built to be driven by any AI coding agent. AGENTS.md at the repo root is the canonical playbook — read it first; CLAUDE.md points there too. Every command is non-interactive by default, idempotent where it matters, validates inputs with the exact fix in the error message, and uses stable exit codes (0 = success; non-zero = the printed error tells you what to change).

The machine-readable surface, end to end

pnpm doctor --json          # 1. is this machine ready? execute the fix of any failing check
pnpm new --list --json      # 2. the FULL capability manifest in one call
pnpm new my-idea --title "My Idea" --type webapp --design prism --accent violet \
  --mode dark --layout sidebar --features all --json      # 3. scaffold
pnpm install
cd apps/my-idea && npx convex dev --once && pnpm exec tsc --noEmit
cd ../.. && pnpm deploy my-idea --json                    # 4. deploy
  • doctor --json → {ok, deployReady, checks:[{name, level, pass, detail, fix?}]}. Gate on ok; run each fix command for checks you need.
  • new --list --json → types, stacks, dbs (with per-db feature pools), layouts, all 100 designs with categories, 18 accents, modes, deployProviders, demos, and usage strings. Use it to validate choices before scaffolding — never hardcode catalogs.
  • new ... --json → scaffolds and ends with one result line (below). Parse the next array for the exact follow-up commands.
  • deploy <slug> --json → deploys and ends with a result line containing the live url.

Parsing the result line

With --json, the FINAL stdout line of pnpm new and pnpm deploy is @geenius-mvp:result followed by one JSON object. Take the last line, strip the prefix, JSON.parse the rest — ignore all human-readable output above it.

@geenius-mvp:result {"ok":true,"slug":"my-idea","dir":"apps/my-idea","type":"webapp","stack":"react","db":"convex","layout":"sidebar","design":"prism","accent":"violet","mode":"dark","port":"5200","features":["dashboard","settings",...],"next":["pnpm install","cd apps/my-idea && npx convex dev --once","pnpm exec tsc --noEmit","pnpm deploy my-idea"]}

The demos in the manifest

The --list --json manifest carries a demos object — one entry per built-in demo (crm, tasks, catalog), each with title, description, entities (table, labels, every field's key/type/label, and seedRows count), defaults (design/accent/layout), fieldTypes (the 9 valid types), and a ready-to-use usage string. Two sibling keys document the escape hatches: demoSpecFiles (pnpm new <slug> --demo ./my-spec.json with the expected spec shape) and fieldsWithoutDemo (--fields alone reshapes the generic records baseline). Prefer a demo over building a domain by hand whenever one is close to the user's ask — then reshape it with --fields/--table/--labels.

Synthesize a custom domain

When no built-in demo fits, don't hand-write the domain — write a spec file and let the codegen generate schema, backend, and the multi-view page:

cat > /tmp/habits.json <<'EOF'
{
  "title": "Habit Tracker",
  "entities": [{
    "table": "habits",
    "labels": ["Habit", "Habits"],
    "titleKey": "name",
    "statusKey": "cadence",
    "fields": [
      { "key": "name", "label": "Name", "type": "text", "required": true },
      { "key": "cadence", "label": "Cadence", "type": "select", "options": [
        { "value": "daily", "label": "Daily", "tone": "accent" },
        { "value": "weekly", "label": "Weekly" }
      ] },
      { "key": "streak", "label": "Streak", "type": "number" },
      { "key": "notes", "label": "Notes", "type": "longtext" }
    ],
    "seed": [{ "name": "Morning run", "cadence": "daily", "streak": 12 }]
  }]
}
EOF
pnpm new habits --demo /tmp/habits.json --json

The spec is validated with the exact error on failure (camelCase table, [singular, plural] labels, valid field types, options on selects, titleKey naming a field). The result line's demo object echoes the generated tables and field keys; the app's .demo.json manifest records featureId/path/titleKey per entity for downstream automation.

Hard rules (do not violate)

  • NEVER delete apps/<slug>/.env.local or run convex dev --configure=new on an app that has one — it mints a duplicate cloud project
  • convex codegen needs a configured deployment: npx convex dev --once first
  • After every backend change: npx convex codegen && pnpm exec tsc --noEmit — fix to zero
  • Pass explicit flags; do not rely on the wizard
  • Design/accent catalogs live only in packages/shell/src/shell/ui/chrome.ts — read them via --list --json