AI Genie Factory

by Marvin Nahmias & Javier Hauss — Alpura, Mexico City Premiering at DATA+AI Summit 2026

mexmarv.github.io/ai-genie-factory

Built on @databricks Genie Code Agent Mode and Unity Catalog.

---

What Is This?

The AI Genie Factory is a methodology for building enterprise Databricks applications at scale using AI code generation that always adheres to your architecture.

The core insight: AI doesn't generate architecture — it generates code. Architecture has to be defined first, then enforced as constraints.

This repository contains two types of constraints:

• AGENTS.md — lean always-on guardrails (platform rules, stack, error handling, logging). Loaded once into Genie Code's instructions file. ~6,000 chars.
• skills/ — domain skills loaded on demand by Genie Code Agent mode, or @mentioned by name. Each skill is focused, contextual, and doesn't bloat every generation.

At Alpura, this system produced 90+ apps across Finance, Sales, Operations, and Marketing — most in days, some in hours.

---

The Factory Methodology

Platform (Lakehouse)
  └── Governance (Unity Catalog)
        └── Semantic Layer (Central KPIs, Gold Tables)
              └── Factory (AGENTS.md + Skills)
                    └── Genie Code Agent Mode
                          └── Apps / Pipelines / Notebooks

---

Repository Structure

ai-genie-factory/
│
├── AGENTS.md                          ← Lean always-on constraints (~6,000 chars)
├── GLOBAL_RULES.md                    ← Platform law (never override)
├── STACK.md                           ← Technology choices (never override)
├── build_agents.py                    ← Assembles AGENTS.md from core modules only
├── deploy.sh                          ← Deploys instructions + skills via Databricks CLI
│
├── modules/                           ← Source files compiled into AGENTS.md
│   ├── error_handling.md              ← try/except contracts, custom exceptions
│   └── logging.md                     ← Structured logging standard (_logger.py)
│
├── skills/                            ← Databricks Genie Code Agent skills (flat .md files)
│   ├── ui-ux-patterns.md              ← @ui-ux-patterns — design tokens, shadows, typography, KPI cards, charts, Dash + Streamlit shells
│   ├── databricks-app.md              ← @databricks-app — full app architecture, file layers, app.yaml, OAuth, deployment, debug
│   ├── databricks-dashboard.md        ← @databricks-dashboard — AI/BI Lakeview dashboards, dataset SQL, widget config, filters, scheduling
│   ├── dlt-pipeline.md                ← @dlt-pipeline — Bronze/Silver/Gold, Auto Loader, CDC, SCD2, schema evolution, streaming
│   ├── data-access.md                 ← @data-access — sql-connector + Config(), Unity Catalog, batching, DataAccessError
│   └── testing-scaffold.md            ← @testing-scaffold — pytest, mocked dbsql.connect(), pandas logic tests
│
├── templates/
│   ├── PROMPT_TEMPLATE.md             ← Exact prompt for every Genie Code session
│   └── APP_TEMPLATE.md                ← Blank APP spec — fill this out per app
│
├── docs/
│   └── index.html                     ← GitHub Pages landing page
│
└── apps/
    ├── nyc_taxi_explorer/
    │   └── APP.md                     ← Zero-permission starter: samples.nyctaxi.trips
    └── dbu_spend_app/
        └── APP.md                     ← Working example: DBU Spend Monitor

---

AGENTS.md vs Skills — When to Use Each

	AGENTS.md	Skills
When loaded	Every Genie Code session	Only when relevant to the request
Purpose	Non-negotiable platform guardrails	Domain knowledge, patterns, design systems
Size target	< 6,000 chars	As large as needed
Contents	Global rules, stack, error handling, logging	Charts, pipelines, testing, UX/UI design
How to invoke	Automatic	Automatic (Agent mode) or @skill-name

Rule of thumb: if it applies to every single generation, it goes in AGENTS.md. If it applies to a specific type of work, it's a skill.

---

Constraint Priority

Priority	Source	Purpose
1	GLOBAL_RULES.md	Platform law — never overridden
2	STACK.md	Technology choices — never redefined per app
3	modules/error_handling.md	Error contracts — never overridden
4	modules/logging.md	Logging standard — never overridden
5	@data-access skill	sql-connector + Config(), Unity Catalog, batching, DataAccessError
6	@ui-ux-patterns skill	Design tokens, shadows, typography, charts, KPI cards
7	@databricks-app skill	App file layers, app.yaml, OAuth M2M, deployment, debug checklist
8	@databricks-dashboard skill	AI/BI Lakeview dashboard SQL, widgets, filters, scheduling
9	@dlt-pipeline skill	Bronze/Silver/Gold, serverless DLT, CDC, SCD2, streaming
10	@testing-scaffold skill	pytest, mocked dbsql.connect(), pandas logic tests
11	APP.md	App-specific spec — only what's unique to this app

---

Setup: One-Time Deployment

Prerequisites

• Databricks CLI v0.200+ installed and configured
• Run databricks auth login if you haven't set up a profile yet

---

Step 1 — Deploy instructions + skills via deploy.sh

From the repo root, run:

# Deploy to your personal Genie Code folder (default)
./deploy.sh

# Deploy workspace-wide so all users get the skills (requires admin)
./deploy.sh --workspace

# Use a specific ~/.databrickscfg profile
./deploy.sh --profile my-profile

The script uploads:

• AGENTS.md → .assistant/instructions.md (Genie Code reads this as your instructions file)
• Each skills/<name>.md → .assistant/skills/<name>.md

What import-dir can't do: The Databricks CLI's import-dir only handles notebooks (.py, .sql, .ipynb). Plain .md skill files must be uploaded as raw files — deploy.sh handles this automatically using databricks workspace import --format RAW.

Redeploying after edits:

# After editing AGENTS.md or any skill, just re-run:
./deploy.sh

---

Step 2 — Verify in Genie Code

1. Open Genie Code in Databricks (sparkle icon, top-right)
2. Click ⚙️ → User instructions — instructions.md should appear loaded
3. Switch to Agent mode and @mention any skill to confirm it's available:

   @ui-ux-patterns  @databricks-app  @databricks-dashboard
   @dlt-pipeline  @data-access  @testing-scaffold
   

Genie Code picks up skills automatically — no restart needed.

---

Step 3 — Fill out an APP spec

Copy templates/APP_TEMPLATE.md and fill in every field before prompting.

---

Step 4 — Open Genie Code in Agent mode and prompt

Use templates/PROMPT_TEMPLATE.md as your prompt. Skills are loaded automatically, or @mention them:

@databricks-app @ui-ux-patterns build the sales dashboard per the spec below
@databricks-dashboard build a native Lakeview dashboard for daily revenue
@dlt-pipeline create the ingestion pipeline for the orders feed
@testing-scaffold add tests to the app I just built

---

Rebuilding AGENTS.md

After editing GLOBAL_RULES.md, STACK.md, or modules/*.md:

python build_agents.py

Output:

✅  LEAN  AGENTS.md — 5,989 / 20,000 chars (29.9%)
   Target: keep under 12,000 chars (60%) — domain knowledge belongs in skills/

  Skills to deploy separately (copy to Workspace/.assistant/skills/):
    @data-access
    @databricks-app
    @databricks-dashboard
    @dlt-pipeline
    @testing-scaffold
    @ui-ux-patterns

---

Debugging a Generated App

1. FILE STRUCTURE
   □ data.py / logic.py / ui.py / app.py / _logger.py all present?
   □ If no → re-prompt with PROMPT_TEMPLATE.md, @mention missing skill

2. LAYER VIOLATIONS
   □ dbsql.connect() outside data.py?  → @data-access, move inside a function
   □ Config() called at module level?  → @databricks-app — moves inside callback
   □ Business logic in ui.py?          → move to logic.py
   □ toPandas() called anywhere?       → Apps use pandas; data.py returns pd.DataFrame

3. DATA ACCESS
   □ Using sql-connector + Config() not WorkspaceClient().statement_execution?
   □ Batching both queries in one dbsql.connect() call (not two separate connections)?
   □ lat/lon/decimal columns CAST AS DOUBLE in SQL or pd.to_numeric() after load?

4. TABLE NAMES
   □ All refs three-part (catalog.schema.table)?
   □ Hardcoded strings outside app.py config dict?

5. LOGGING
   □ Each file imports from _logger?
   □ Check Databricks Apps logs for ERROR lines first

6. ERROR HANDLING
   □ data.py raises DataAccessError on failure?
   □ ui.py catches exceptions and shows _error_figure()?

7. DESIGN SYSTEM
   □ Background #0d1117, cards #161b22?  → @ui-ux-patterns
   □ All charts use plotly_dark template?
   □ No px.pie (use px.treemap), no #636efa (use #00bcd4)?

8. PIPELINE
   □ DLT tables named bronze_/silver_/gold_?  → @dlt-pipeline
   □ No spark.read() inside DLT notebooks?
   □ File paths use /Volumes/ not dbfs:/?
   □ New pipelines use serverless DLT?

---

Example Apps

App	Table	Permissions needed
NYC Taxi Explorer	samples.nyctaxi.trips	None — works in every Unity Catalog workspace out of the box
DBU Spend Monitor	system.billing.usage	Requires system tables enabled by an admin

Start with NYC Taxi Explorer to verify the factory is wired up before building on your own data.

---

Skill Reference

All skills are aligned with Databricks' official AI Dev Kit: github.com/databricks-solutions/ai-dev-kit

Key patterns enforced from ai-dev-kit:

• Apps auth: databricks-sql-connector + Config() credentials provider — never WorkspaceClient().statement_execution
• App startup: empty globals + dcc.Interval(max_intervals=1) — Config() never at module level
• app.yaml resources: valueFrom: sql-warehouse — never hardcode IDs
• DLT: serverless by default, dlt.read() not spark.read()
• Grants: SP applicationId UUID — never display name

---

Contributing

1. Edit GLOBAL_RULES.md, STACK.md, or modules/*.md → run python3 build_agents.py
2. Edit skills in skills/<name>.md → run ./deploy.sh to push changes
3. Never edit AGENTS.md directly — it's generated
4. Add new apps under apps/<app-name>/APP.md

---

License

MIT — use freely, adapt to your stack.

---

AI generates code. Not architecture. — Marvin Nahmias, DAIS 2026