GitHub Copilot — LumiBase Agent Setup

GitHub Copilot is an editor extension and CLI with agent mode, workspace context, and native PR integration. Made by GitHub.

Tags: Terminal · Cloud · Extension

Quick setup (recommended)

Open GitHub Copilot Chat in VS Code and paste:

code

Read docs/en/agent-setup/prompt.md and follow all setup instructions.

Manual setup

Step 1 — Open the project in VS Code

bash

code /path/to/lumibase

Ensure the GitHub Copilot extension is installed and authenticated.

Step 2 — Create a workspace instructions file

Create .github/copilot-instructions.md in the project root:

markdown

# LumiBase — Copilot workspace instructions

You are working on LumiBase, an Edge-native Headless CMS.

## Stack
- **API**: Hono.js (apps/cms) — dual-runtime: Cloudflare Workers + Docker/Node.js
- **DB**: PostgreSQL + Drizzle ORM (packages/database), JSONB hybrid schema
- **Studio**: React + Vite + TanStack Router (apps/studio)
- **Runtime abstraction**: @lumibase/runtime — use this, never call CF APIs directly
- **Auth**: Logto OIDC, multi-tenant (every request carries siteId)
- **AI**: OpenAI / Anthropic / CF Workers AI — via packages/ai-skills

## Mandatory rules
1. IDs: NanoID or UUIDv7 only. No serial/auto-increment.
2. Multi-tenancy: `site_id` on every domain table, every query scoped.
3. AI safety: Skills with `schema:write` or `delete*` → HITL via ai_approvals table.
4. Performance: Aggregated 1-roundtrip responses, cache-tagged invalidation.

## Key documentation
Read these files before making changes in their area:
- docs/en/data-model.md (schema)
- docs/en/features/ai-copilot.md (AI Copilot)
- docs/en/api/hono-api-spec.md (API spec)
- docs/en/features/flows-automation.md (Flows engine)
- docs/en/features/permissions-rbac.md (permissions)

Step 3 — Set up the MCP server (optional)

Add to .vscode/mcp.json:

json

{
  "servers": {
    "lumibase": {
      "type": "http",
      "url": "http://localhost:1989/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LUMIBASE_TOKEN}",
        "X-Site-Id": "${env:LUMIBASE_SITE_ID}"
      }
    }
  }
}

Set LUMIBASE_TOKEN and LUMIBASE_SITE_ID in your shell environment or .env.

Reload VS Code and check the MCP panel (Cmd+Shift+P → "MCP: List Servers").

Agent mode

Enable GitHub Copilot Agent Mode in VS Code (Cmd+Shift+P → "GitHub Copilot: Enable Agent Mode").

Example agent prompts for LumiBase:

code

#file:docs/en/features/flows-automation.md
Add a "retry" mechanism to the Flow runner so failed operations retry up to 3 times with exponential backoff.
Modify apps/cms/src/services/flow-service.ts and update the flow_runs schema in packages/database.

code

#file:docs/en/features/ai-copilot.md #file:packages/ai-skills/src/skills.ts
Add a new AI skill "exportCollection" that exports all items from a collection as CSV.
Mark it as safe (no HITL needed). Register it in CORE_SKILLS and implement the handler.

Workspace context tips

Copilot workspace context (#workspace) works well when:

You've opened the monorepo root as the VS Code workspace
The relevant source files are open in editor tabs
You reference docs files with #file: in your prompt

Recommended files to keep open when working on LumiBase:

docs/en/README.md
docs/en/data-model.md
apps/cms/src/index.ts
The specific route/service file you're editing

PR summaries

GitHub Copilot can generate PR descriptions for LumiBase changes. Ask it to:

code

Write a PR description for these changes. Reference the relevant docs files
(docs/en/features/, docs/en/data-model.md) and follow conventional commits format.

CLI integration

With GitHub Copilot CLI:

bash

# Ask about a specific LumiBase pattern
gh copilot suggest "how do I add a new Hono route with multi-tenant middleware in LumiBase"

# Explain existing code
gh copilot explain "apps/cms/src/services/ai-harness.ts"

Troubleshooting

Copilot doesn't know LumiBase conventions: Ensure .github/copilot-instructions.md is committed and VS Code has reloaded the workspace.

MCP server not showing up: The MCP server requires apps/cms to be running locally. Start it with pnpm -F @lumibase/cms dev.

Type errors in generated code: Run pnpm typecheck in the affected package to identify mismatches, then show the error to Copilot.

← Back to Agent Setup