# OpenCode Setup Guide

This document has two parts:

1. **Part I — Cursor Agent Prompt** — copy into Cursor to implement the setup automatically
2. **Part II — Setup Tutorial** — manual reference with every file, config, and step

Attach this entire file to Cursor and paste the prompt from Part I.

---

# Part I — Cursor Agent Prompt

## How to use

1. Attach this file (`opencode_setup.md`) to your Cursor chat
2. Copy the **full prompt** or **short prompt** below and paste it
3. The agent will follow **Part II** as the source of truth for what to create

---

## Full prompt (copy from here)

```
You are setting up OpenCode globally on this machine. Follow the attached tutorial (Part II of `opencode_setup.md`) as the single source of truth. Do not improvise a different structure.

## Goal

Implement the full global OpenCode configuration:
- Rules layer: `AGENTS.md` + `instructions` (session logging, UI/UX, `.cursor/rules/`)
- Skills layer: `ui-ux-design` and `session-log` skills in `~/.config/opencode/skills/`
- Agents layer: customized `build`, `plan`, `explore`, and five subagents with prompt files
- Environment layer: `.env` model vars + shell profile sourcing for `{env:VAR}` substitution
- Session logs: Markdown files in `<project>/sessions/DDMMYYYY_HHMM.md`

Default model: **Big Pickle** (`opencode/big-pickle` via `OPENCODE_PRIMARY_MODEL`).

## Before you write any files

1. Check OpenCode is installed: `which opencode` and `opencode --version` (or equivalent)
2. Discover this workspace's absolute path and list `.cursor/rules/` — only include rule files that actually exist in `instructions`
3. Detect the user's shell profile (`~/.zshrc` or `~/.bashrc`)
4. Check whether `~/.config/opencode/` already exists and what is already configured — merge/update, do not blindly overwrite user customizations without noting what changed
5. Run `opencode models` (with any existing API keys in the environment) to list valid `provider/model-id` values

## Files to create or update

### Global OpenCode config (`~/.config/opencode/`)

| File | Action |
|------|--------|
| `opencode.jsonc` | Create or update per tutorial Step 7 |
| `AGENTS.md` | Create or update per tutorial Step 3 |
| `instructions/session-logging.md` | Create |
| `instructions/ui-ux-design.md` | Create |
| `skills/session-log/SKILL.md` | Create |
| `skills/ui-ux-design/SKILL.md` | Create |
| `prompts/build.txt` | Create |
| `prompts/plan.txt` | Create |
| `prompts/explore.txt` | Create |
| `prompts/code-reviewer.txt` | Create |
| `prompts/security-auditor.txt` | Create |
| `prompts/supabase.txt` | Create |
| `prompts/ui-builder.txt` | Create |
| `prompts/wiki-docs.txt` | Create |

Use `{file:./prompts/...}` paths in `opencode.jsonc` (relative to config dir).

### Environment

| File | Action |
|------|--------|
| `.env` | Create or update in the workspace root (or user-preferred location outside git) |
| Shell profile | Add OpenCode to PATH and source `.env` with `set -a` / `set +a` |
| `~/.config/opencode/.env` | Optional symlink to the main `.env` |

### `.env` variables (required)

```
ANTHROPIC_API_KEY=
ANTHROPIC_DEFAULT_MODEL=

GROQ_API_KEY=
GROQ_DEFAULT_MODEL=

MISTRAL_API_KEY=
MISTRAL_DEFAULT_MODEL=

OPENCODE_PRIMARY_MODEL=
OPENCODE_DEFAULT_MODEL=
```

- `OPENCODE_PRIMARY_MODEL` — default LLM (use `opencode/big-pickle`)
- `OPENCODE_DEFAULT_MODEL` — `small_model` for titles/light tasks (e.g. `opencode/north-mini-code-free`)

- If the user already has API keys in an existing `.env`, preserve them — only add missing vars
- If keys are missing, use empty values or `your-*-key` placeholders and tell the user to fill them in
- Model IDs must be exact matches from `opencode models` output, in `provider/model-id` format
- Never commit `.env` or print API keys in your response

### `opencode.jsonc` requirements

- `"model": "{env:OPENCODE_PRIMARY_MODEL}"` (Big Pickle)
- `"small_model": "{env:OPENCODE_DEFAULT_MODEL}"`
- `"enabled_providers": ["opencode", "groq", "mistral", "anthropic"]`
- Global `"permission.skill"` allowing `ui-ux-design` and `session-log`
- `"instructions"`: include `{file:./instructions/session-logging.md}`, `{file:./instructions/ui-ux-design.md}`, plus absolute paths to `<workspace>/.cursor/rules/`
- `"agent"` block: all agents with correct `mode`, `model`, `temperature`, `permission`, `prompt`, and per-agent `skill` permissions

### Agent model assignment

| Agent | Model env var |
|-------|---------------|
| build (primary) | `OPENCODE_PRIMARY_MODEL` |
| plan (primary) | `MISTRAL_DEFAULT_MODEL` |
| explore | default (inherits) |
| code-reviewer | `ANTHROPIC_DEFAULT_MODEL` |
| security-auditor | `ANTHROPIC_DEFAULT_MODEL` |
| supabase | `GROQ_DEFAULT_MODEL` |
| ui-builder | `OPENCODE_PRIMARY_MODEL` |
| wiki-docs | `MISTRAL_DEFAULT_MODEL` |

### Permissions (do not skip)

- **build**: `git push*` and `git commit*` → `ask`; `security-auditor` task → `ask`; skills `ui-ux-design`, `session-log` → `allow`
- **plan**: `edit` deny except `sessions/*`; `bash: deny`; skill `session-log` → `allow`
- **code-reviewer**: `edit: deny`, `bash: deny`
- **security-auditor**: `edit: deny`; bash allow only `git diff*`, `git log*`, `grep *`
- **supabase**: bash `ask` except `npx supabase gen types*`, `grep *`; skill `session-log` → `allow`
- **ui-builder**: bash `ask` except `npx shadcn@latest add*`, `npm run typecheck*`; skills `ui-ux-design`, `session-log` → `allow`
- **wiki-docs**: `bash: deny`

## Adapt to this workspace

- Replace tutorial placeholders (`PATH_TO_YOUR_PROJECT`) with the actual workspace path
- In `instructions`, include only `.cursor/rules/` files that exist — skip missing ones
- If `.cursor/rules/` is empty or missing, create a minimal `AGENTS.md` and omit `instructions` until rules exist
- If the project has no `.wiki/` workflow, keep wiki sections in prompts but note they are optional

## Verification (run before finishing)

1. Confirm all 8 prompt files exist under `~/.config/opencode/prompts/`
2. Confirm `instructions/` and `skills/` directories with both skill files
3. Confirm `opencode.jsonc` is valid JSONC (schema, no trailing issues)
4. With env sourced, verify each model var appears in `opencode models` output
5. Confirm shell profile sources the `.env` file
6. Do not start a long-running `opencode` session — just verify config and models

## Output format

When done, respond with:

1. **Created/updated** — list of files with one-line description each
2. **Model mapping** — table of env var → chosen model ID (no API keys)
3. **Manual steps** — what the user must do (fill keys, open new terminal, restart OpenCode)
4. **Usage** — how to switch Build/Plan (Tab), invoke subagents (@name)
5. **Skipped** — anything you could not do and why

## Constraints

- Do not commit changes unless the user explicitly asks
- Do not expose API keys, tokens, or absolute home directory paths in your summary (use `~` shorthand)
- Do not edit `.wiki/` files
- Follow the tutorial's rules-vs-agents separation: conventions in `instructions`, role behavior in `prompts/`
- Minimize scope — only files required for this OpenCode setup
```

---

## Short prompt (minimal)

```
Read the attached `opencode_setup.md` (Part II) and implement the complete global OpenCode setup on my machine.

Discover `.cursor/rules/` in this workspace, verify model IDs via `opencode models`, create `~/.config/opencode/` (config, AGENTS.md, instructions, skills, 8 prompts), update `.env` and my shell profile. Default model: Big Pickle (`opencode/big-pickle`). Include session logging and UI/UX skills. Preserve existing API keys. Do not commit secrets. Summarize what was created and what I must do manually.
```

---

## Tips for best results

1. **Attach this file** — the agent needs Part II in context
2. **Open the workspace** that contains `.cursor/rules/` so paths resolve correctly
3. **Have API keys ready** — or let the agent use placeholders and fill them in after
4. **New terminal** — env vars only load after sourcing the shell profile

---
---
---

# Part II — Setup Tutorial

A step-by-step guide to configure [OpenCode](https://opencode.ai) with global rules, custom agents, model routing via environment variables, and integration with existing Cursor rules.

**Official docs referenced:**
- [Rules](https://opencode.ai/docs/rules/)
- [Agents](https://opencode.ai/docs/agents/)
- [Config](https://opencode.ai/docs/config/)
- [Skills](https://opencode.ai/docs/skills/)

---

## What this setup provides

| Layer | Purpose |
|-------|---------|
| **Rules** (`AGENTS.md` + `instructions`) | Conventions, session rituals, UI/UX principles, logging protocol |
| **Skills** (`skills/*/SKILL.md`) | On-demand deep guidance (`ui-ux-design`, `session-log`) |
| **Agents** (`agent` block + prompt files) | Roles, permissions, per-task models |
| **Environment** (`.env` + shell profile) | API keys and model IDs via `{env:VAR}` |
| **Session logs** (`<project>/sessions/`) | Per-session Markdown work logs (`DDMMYYYY_HHMM.md`) |

After setup you get:

- **Build** — primary dev agent (Big Pickle, full tools, session logging, UI skill access)
- **Plan** — read-only planning (may write `sessions/*.md` only)
- **Explore** — read-only codebase search (wiki-first)
- **Subagents** — `@code-reviewer`, `@security-auditor`, `@supabase`, `@ui-builder`, `@wiki-docs`
- **Default model** — `opencode/big-pickle` via `OPENCODE_PRIMARY_MODEL`
- **UI/UX** — anti–AI-slop design skill + instructions for 2026 usability patterns
- **Session logs** — automatic Markdown logs in each project's `sessions/` folder

---

## Prerequisites

1. [OpenCode](https://opencode.ai) installed (`opencode` on your `PATH`)
2. API keys for the providers you use (Groq, Mistral, Anthropic; OpenCode Zen if applicable)
3. A project with Cursor rules in `.cursor/rules/` (optional but recommended)
4. A shell profile (`~/.zshrc` or `~/.bashrc`)

Run `opencode models` with your API keys exported to see valid `provider/model-id` values for your account.

---

## Directory layout

Create this structure under the global OpenCode config directory:

```
~/.config/opencode/
├── opencode.jsonc          # Main config (models, agents, instructions, skills permissions)
├── AGENTS.md               # Global rules (session start, logging, UI/UX, principles)
├── .env                    # Symlink or copy of your secrets file (optional)
├── instructions/
│   ├── session-logging.md  # Always-loaded session log protocol
│   └── ui-ux-design.md     # Always-loaded UI anti-patterns + 2026 principles
├── skills/
│   ├── session-log/SKILL.md
│   └── ui-ux-design/SKILL.md
└── prompts/
    ├── build.txt
    ├── plan.txt
    ├── explore.txt
    ├── code-reviewer.txt
    ├── security-auditor.txt
    ├── supabase.txt
    ├── ui-builder.txt
    └── wiki-docs.txt
```

Per-project session output (created automatically by agents):

```
<your-project>/
└── sessions/
    └── DDMMYYYY_HHMM.md    # e.g. 12062026_1430.md — one file per session
```

OpenCode also uses (automatically, no setup needed):

```
~/.opencode/bin/            # OpenCode binary
~/.local/state/opencode/    # Runtime state
~/.local/share/opencode/    # Database, logs, sessions
```

Per-project overrides (optional):

```
<your-project>/
├── opencode.jsonc          # Project-specific config
├── AGENTS.md               # Project-specific rules
└── .opencode/agents/       # Project-specific agents
```

---

## Step 1 — Environment variables

Create a `.env` file **outside version control** (e.g. in your main dev folder or `~/.config/opencode/.env`).

```bash
# AI/LLM — replace values with your own keys and model IDs from `opencode models`

ANTHROPIC_API_KEY=your-anthropic-key
ANTHROPIC_DEFAULT_MODEL=anthropic/claude-sonnet-4-6

GROQ_API_KEY=your-groq-key
GROQ_DEFAULT_MODEL=groq/meta-llama/llama-4-scout-17b-16e-instruct

MISTRAL_API_KEY=your-mistral-key
MISTRAL_DEFAULT_MODEL=mistral/codestral-latest

OPENCODE_PRIMARY_MODEL=opencode/big-pickle
OPENCODE_DEFAULT_MODEL=opencode/north-mini-code-free
```

**Model ID format:** always `provider/model-id` (e.g. `opencode/...`, `groq/...`, `mistral/...`, `anthropic/...`).

**Model assignment:**

| Env var | Example | Used for |
|---------|---------|----------|
| `OPENCODE_PRIMARY_MODEL` | `opencode/big-pickle` | **Default**, Build, UI builder |
| `GROQ_DEFAULT_MODEL` | `groq/openai/gpt-oss-120b` | Supabase subagent |
| `MISTRAL_DEFAULT_MODEL` | `mistral/codestral-latest` | Plan, wiki-docs |
| `OPENCODE_DEFAULT_MODEL` | `opencode/north-mini-code-free` | `small_model` (titles, lightweight tasks) |
| `ANTHROPIC_DEFAULT_MODEL` | `anthropic/claude-sonnet-4-6` | Code review, security audit |

> **Important:** OpenCode resolves `{env:VAR}` in config at startup from your **shell environment**, not from `.env` files automatically. You must source the file in your shell profile (Step 2).

---

## Step 2 — Load env in your shell profile

Add to `~/.zshrc` (or `~/.bashrc`):

```bash
# OpenCode
export PATH="$HOME/.opencode/bin:$PATH"

# Load OpenCode env vars (adjust path to your .env file)
if [ -f "$HOME/path/to/your/.env" ]; then
  set -a
  source "$HOME/path/to/your/.env"
  set +a
fi
```

Open a **new terminal** after editing. Verify:

```bash
echo "$OPENCODE_PRIMARY_MODEL"
opencode models | grep -E 'big-pickle|groq|mistral|anthropic|opencode'
```

---

## Step 3 — Global `AGENTS.md`

Create `~/.config/opencode/AGENTS.md`:

```markdown
# Global Agent Rules

These rules apply to every OpenCode session. Project-specific `AGENTS.md` in repos takes precedence.

## Session start

Before starting work in a project:

1. Read `.wiki/INDEX.md` fully (if it exists)
2. Read `.wiki/architecture.md` and `.wiki/structure.md`
3. Confirm with a 3-sentence summary: what the project does, the main tech stack, and the most important service or workflow
4. Then wait for the first task

If `.wiki/INDEX.md` does not exist, say so and ask the user to run `npm run wiki` first.

## Codebase wiki

If a `.wiki/` folder exists, it is the authoritative knowledge base.

- Always read `.wiki/INDEX.md` before architectural decisions
- Never edit `.wiki/*.md` directly — regenerate with `npm run wiki`
- Never overwrite `<!-- manual -->` sections
- After schema/API/service/env changes, remind the user to run `npm run wiki`

## Session logging

Every session writes a work log to `sessions/DDMMYYYY_HHMM.md` in the **active project root**.

- **Format:** Markdown (human-readable, structured timeline)
- **Start:** create file at session start (`mkdir -p sessions`)
- **During:** append actions, file changes, commands, decisions
- **End:** complete Summary and Outcome sections

Load the `session-log` skill for the full template. Do not log secrets or API keys.

## UI & UX design

For all frontend work, load the `ui-ux-design` skill or use `@ui-builder`.

Avoid generic AI aesthetics (purple gradients, stock hero layouts, uniform cards). Prioritize usability, accessibility (WCAG AA), and 2026 design patterns.

## Cursor rules

Detailed conventions are loaded via the `instructions` field in `opencode.jsonc` from your project's `.cursor/rules/` directory. Apply them by context — do not load everything for every task.

## Model assignment

| Model | Env var | Used for |
|-------|---------|----------|
| **Big Pickle** (default) | `OPENCODE_PRIMARY_MODEL` | Global default, Build, UI builder |
| Groq | `GROQ_DEFAULT_MODEL` | Supabase subagent |
| Mistral | `MISTRAL_DEFAULT_MODEL` | Plan, wiki-docs |
| OpenCode mini | `OPENCODE_DEFAULT_MODEL` | `small_model` |
| Anthropic | `ANTHROPIC_DEFAULT_MODEL` | Code review, security audit |

## Subagents

| Agent | Purpose |
|-------|---------|
| `@explore` | Read-only codebase search |
| `@code-reviewer` | Review without edits |
| `@security-auditor` | Security audit without edits |
| `@supabase` | Migrations, RLS, typed services |
| `@ui-builder` | Distinctive React UI (loads `ui-ux-design` skill) |
| `@wiki-docs` | Documentation guidance |

Switch primary agents with **Tab**: **Build** ↔ **Plan**.

## Core principles

1. Minimize scope — simplest correct diff only
2. Match existing conventions in the codebase
3. No hardcoded secrets — use `src/config/`
4. Only commit when explicitly asked
```

Customize wiki/session sections if your projects do not use a `.wiki/` folder.

---

## Step 4 — Instruction files

Create `~/.config/opencode/instructions/` with these always-loaded rule files (referenced in `opencode.jsonc` via `{file:./instructions/...}`).

### `session-logging.md`

```markdown
# Session logging

Every OpenCode session in a project must leave a log in `sessions/`.

## Protocol

1. **Start** — `mkdir -p sessions`, create `sessions/DDMMYYYY_HHMM.md` (local time at session start)
2. **During** — append to Timeline after each meaningful action
3. **End** — complete Summary, Files changed, and Outcome sections

Load the `session-log` skill for the full template and rules.

**Format:** Markdown (`.md`) — human-readable, diff-friendly.

**Do not log:** API keys, tokens, or `.env` values.
```

### `ui-ux-design.md`

```markdown
# UI & UX Design Principles (2026)

Apply these rules to all UI work. Load the `ui-ux-design` skill for full guidance.

## Anti-patterns — never ship these

- Purple/violet gradient heroes, neon glows, or "AI startup" aesthetics
- Generic stock layouts: centered hero + 3 feature cards + CTA
- Overused fonts (Inter, Roboto) without brand intent
- Uniform rounded corners and shadows on every element
- Low-contrast gray text; empty states with no action

## What to aim for

- Usability first: obvious primary action per screen
- Visual hierarchy: type scale, weight, spacing
- 2026 trends (thoughtful, not decorative): refined minimalism, distinct typography pairing,
  bento/asymmetric layouts, dark mode as first-class, WCAG AA+ contrast, purposeful motion

## Process

1. Match existing product patterns first
2. Delegate polish to `@ui-builder` with `ui-ux-design` skill loaded
3. Verify: can a new user complete the main task without instructions?
```

---

## Step 5 — Agent skills

Create skills per [OpenCode Skills docs](https://opencode.ai/docs/skills/). Each skill is a folder with a `SKILL.md` file.

### `skills/session-log/SKILL.md`

```markdown
---
name: session-log
description: Create and maintain session work logs in the project sessions folder with ddmmyyyy_hhmm filenames
license: MIT
compatibility: opencode
---

## Location & naming

- Folder: `sessions/` at the project root
- Filename: `DDMMYYYY_HHMM.md` (session start local time, e.g. `12062026_1430.md`)
- One file per session

## When to write

1. Session start — create file after confirming project context
2. During work — append after each meaningful action
3. Session end — finalize Summary and Outcome

## Template

See skill body for full Markdown template with frontmatter, Goal, Summary, Timeline, Files changed, and Outcome sections.
```

### `skills/ui-ux-design/SKILL.md`

```markdown
---
name: ui-ux-design
description: Design usable, modern UI that avoids generic AI aesthetics — typography, hierarchy, 2026 patterns, accessibility
license: MIT
compatibility: opencode
---

## Hard rules

1. No AI slop: reject purple gradients, generic heroes, cookie-cutter card grids
2. Usability over novelty: every element earns its place
3. Hierarchy: one clear primary action per view
4. Accessibility: WCAG AA contrast; visible focus; touch targets ≥ 44px on mobile
5. Consistency: extend existing tokens and components before inventing new patterns

## Typography, layout, color, motion

See full skill for 2026 typography pairing, 8px spacing grid, bento layouts,
semantic color use, and `prefers-reduced-motion` rules.
```

Agents load skills on demand via the `skill` tool. Grant access in `opencode.jsonc` under `permission.skill`.

---

## Step 6 — Prompt files

Create `~/.config/opencode/prompts/` with these files.

### `build.txt`

```
You are the Build agent — the default development assistant with full tool access.

## Session start
Before substantive work in a project:
1. Read `.wiki/INDEX.md`, `.wiki/architecture.md`, and `.wiki/structure.md` if they exist
2. Give a 3-sentence summary (purpose, stack, key workflow), then proceed
3. If `.wiki/INDEX.md` is missing, ask the user to run `npm run wiki` first
4. Create session log — load `session-log` skill; `mkdir -p sessions`; create `sessions/DDMMYYYY_HHMM.md`

## Session logging (required)
Append to the log after each meaningful action. Complete Summary and Outcome before finishing.

## UI work
For frontend tasks: load `ui-ux-design` skill or delegate to `@ui-builder`.

## Working style
- Minimize scope — simplest correct diff only
- Match existing conventions in the codebase
- No hardcoded secrets — use `src/config/`
- Only commit when explicitly asked

Delegate: @explore, @code-reviewer, @supabase, @ui-builder, @security-auditor.
```

### `plan.txt`

```
You are the Plan agent — read-only analysis and planning.
Do not edit files or run bash — except writing to `sessions/*.md` for session logs.

## Session log
Load `session-log` skill. Create `sessions/DDMMYYYY_HHMM.md` at start; complete Summary when done.

## Focus
- Break work into clear, ordered steps
- Call out risks, dependencies, and verification steps
- Prefer minimal, incremental changes

Present the plan and wait for the user to switch to Build for implementation.
```

### `explore.txt`

```
You are the Explore agent — fast, read-only codebase exploration.
Never modify files.

If `.wiki/INDEX.md` exists, read it before searching.
Find files by pattern, search code for keywords, report paths with brief context.
```

### `code-reviewer.txt`

```
You are a code reviewer. Do not make changes — only analyze and report.

Focus on: quality, bugs, performance, security, type safety.
Provide actionable feedback by severity (critical / warning / suggestion).
```

### `security-auditor.txt`

```
You are a security auditor. Do not make changes — only analyze and report.

Look for: input validation, auth/authz flaws, data exposure, dependency risks, config issues.
Report findings by severity with remediation steps.
```

### `supabase.txt`

```
You are a Supabase specialist.

- Migrations in `supabase/migrations/` with timestamp prefix
- Always include `id uuid`, `created_at`, `updated_at`
- RLS on ALL tables
- Regenerate types after schema changes
- Never use admin client on frontend or public routes
```

### `ui-builder.txt`

```
You are the UI builder agent for React + shadcn/ui + Tailwind CSS.

Before any UI work: load the `ui-ux-design` skill.

## Design mandate
Ship usable, modern interfaces — not generic AI-generated layouts.

### Never
- Purple gradients, stock hero + 3 cards templates, Inter-by-default without brand intent
- Equal-weight buttons, low-contrast text, empty states with no next step

### Always
- Clear visual hierarchy; WCAG AA contrast; keyboard navigation
- Match existing project tokens and patterns first
- Mobile-first (mental model at 375px)

## Implementation
- Install shadcn via CLI — never edit `src/components/ui/` directly
- Wrap and extend; typed props; `cn()` for className
```

### `wiki-docs.txt`

```
You are a documentation agent.

- Clear structure, code examples, user-friendly language
- Remind user to run `npm run wiki` to regenerate wiki — do not edit `.wiki/` directly
- Never overwrite manual wiki sections
```

---

## Step 7 — `opencode.jsonc`

Create `~/.config/opencode/opencode.jsonc`. Replace `PATH_TO_YOUR_PROJECT` with the absolute path to the project whose `.cursor/rules/` you want to load.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_PRIMARY_MODEL}",
  "small_model": "{env:OPENCODE_DEFAULT_MODEL}",
  "autoupdate": true,
  "enabled_providers": ["opencode", "groq", "mistral", "anthropic"],
  "permission": {
    "skill": {
      "*": "allow",
      "ui-ux-design": "allow",
      "session-log": "allow"
    }
  },
  "instructions": [
    "{file:./instructions/session-logging.md}",
    "{file:./instructions/ui-ux-design.md}",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/main.mdc",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/wiki.mdc",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/frontend-ui.mdc",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/component-design-consistency.mdc",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/supabase.mdc",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/llm-workflows.mdc",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/new-project.md",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/new-supabase-table.md",
    "PATH_TO_YOUR_PROJECT/.cursor/rules/opencode-session-start.md"
  ],
  "agent": {
    "build": {
      "mode": "primary",
      "model": "{env:OPENCODE_PRIMARY_MODEL}",
      "temperature": 0.3,
      "prompt": "{file:./prompts/build.txt}",
      "permission": {
        "bash": {
          "*": "allow",
          "git push*": "ask",
          "git commit*": "ask"
        },
        "task": {
          "*": "allow",
          "security-auditor": "ask"
        },
        "skill": {
          "*": "allow",
          "ui-ux-design": "allow",
          "session-log": "allow"
        }
      }
    },
    "plan": {
      "mode": "primary",
      "model": "{env:MISTRAL_DEFAULT_MODEL}",
      "temperature": 0.1,
      "prompt": "{file:./prompts/plan.txt}",
      "permission": {
        "edit": {
          "*": "deny",
          "sessions/*": "allow"
        },
        "bash": "deny",
        "skill": {
          "session-log": "allow"
        }
      }
    },
    "explore": {
      "prompt": "{file:./prompts/explore.txt}"
    },
    "code-reviewer": {
      "description": "Reviews code for quality, security, and best practices without making changes",
      "mode": "subagent",
      "model": "{env:ANTHROPIC_DEFAULT_MODEL}",
      "temperature": 0.1,
      "color": "accent",
      "prompt": "{file:./prompts/code-reviewer.txt}",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "security-auditor": {
      "description": "Performs security audits and identifies vulnerabilities",
      "mode": "subagent",
      "model": "{env:ANTHROPIC_DEFAULT_MODEL}",
      "temperature": 0.1,
      "color": "warning",
      "prompt": "{file:./prompts/security-auditor.txt}",
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "deny",
          "git diff*": "allow",
          "git log*": "allow",
          "grep *": "allow"
        }
      }
    },
    "supabase": {
      "description": "Creates Supabase migrations, RLS policies, and typed service functions",
      "mode": "subagent",
      "model": "{env:GROQ_DEFAULT_MODEL}",
      "temperature": 0.2,
      "color": "success",
      "prompt": "{file:./prompts/supabase.txt}",
      "permission": {
        "bash": {
          "*": "ask",
          "npx supabase gen types*": "allow",
          "grep *": "allow"
        },
        "skill": {
          "session-log": "allow"
        }
      }
    },
    "ui-builder": {
      "description": "Builds distinctive, usable React UI with shadcn/ui and Tailwind — avoids generic AI aesthetics",
      "mode": "subagent",
      "model": "{env:OPENCODE_PRIMARY_MODEL}",
      "temperature": 0.35,
      "color": "info",
      "prompt": "{file:./prompts/ui-builder.txt}",
      "permission": {
        "bash": {
          "*": "ask",
          "npx shadcn@latest add*": "allow",
          "npm run typecheck*": "allow"
        },
        "skill": {
          "ui-ux-design": "allow",
          "session-log": "allow"
        }
      }
    },
    "wiki-docs": {
      "description": "Writes and maintains project documentation and wiki guidance",
      "mode": "subagent",
      "model": "{env:MISTRAL_DEFAULT_MODEL}",
      "temperature": 0.2,
      "color": "secondary",
      "prompt": "{file:./prompts/wiki-docs.txt}",
      "permission": {
        "bash": "deny"
      }
    }
  }
}
```

**Customize `instructions`:** list only the `.cursor/rules/` files that exist in your project. Omit stacks you do not use (e.g. remove `supabase.mdc` if you have no Supabase).

**Alternative — glob patterns** (per [Rules docs](https://opencode.ai/docs/rules/)):

```jsonc
"instructions": ["PATH_TO_YOUR_PROJECT/.cursor/rules/*.mdc"]
```

---

## Step 8 — Optional symlink for `.env`

If your `.env` lives in a project folder, symlink it into the OpenCode config dir for reference:

```bash
ln -sf /path/to/your/.env ~/.config/opencode/.env
```

This does **not** replace shell sourcing — OpenCode still needs vars in the process environment.

---

## Step 9 — Verify

1. Open a new terminal (env vars loaded)
2. Run `opencode` and start a session
3. Press **Tab** — you should cycle **Build** ↔ **Plan**
4. Type `@` — subagents should appear in autocomplete
5. Confirm the default model is `opencode/big-pickle` (`OPENCODE_PRIMARY_MODEL`)
6. Start work in a project — verify `sessions/DDMMYYYY_HHMM.md` is created
7. For UI work — confirm `ui-ux-design` skill is available in the skill tool

---

## Daily usage

| Action | How |
|--------|-----|
| Switch primary agent | **Tab** (Build ↔ Plan) |
| Invoke subagent | `@code-reviewer review this diff` |
| UI with design skill | `@ui-builder` or load `ui-ux-design` skill |
| Read-only exploration | `@explore find the auth middleware` |
| Planning without edits | Switch to **Plan** agent |
| Session log | Auto-written to `sessions/DDMMYYYY_HHMM.md` |
| Project-specific rules | Add `AGENTS.md` or `opencode.jsonc` in project root |

---

## Rules vs agents — quick reference

| Concern | Where |
|---------|-------|
| Stack, naming, git conventions | `instructions` → `.cursor/rules/*.mdc` |
| Session logging protocol | `instructions/session-logging.md` + `session-log` skill |
| UI/UX anti-patterns & 2026 trends | `instructions/ui-ux-design.md` + `ui-ux-design` skill |
| Session start ritual | `AGENTS.md` + `prompts/build.txt` |
| Role behavior ("you are a reviewer…") | `prompts/*.txt` |
| Model per role | `agent` block in `opencode.jsonc` |
| Tool & skill restrictions | `permission` per agent |

Do not duplicate full rule content inside agent prompts — reference loaded instructions and add role-specific behavior only.

---

## Customization checklist

- [ ] Set `OPENCODE_PRIMARY_MODEL=opencode/big-pickle` in `.env`
- [ ] Adjust `instructions` to match your `.cursor/rules/` files
- [ ] Add `sessions/` to project `.gitignore` if you do not want logs committed
- [ ] Remove subagents you do not need (e.g. `supabase`, `ui-builder`)
- [ ] Change model assignments per agent after running `opencode models`
- [ ] Add project-level `opencode.jsonc` for repo-specific overrides
- [ ] Tighten bash permissions if you want more `ask` prompts
- [ ] Run `/init` in a project to generate project `AGENTS.md` ([Rules docs](https://opencode.ai/docs/rules/))

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `{env:VAR}` empty in config | Source `.env` in shell profile; open new terminal |
| Model not found | Run `opencode models`; use exact `provider/model-id` |
| Big Pickle unavailable | Confirm OpenCode Zen access; check `opencode/big-pickle` in `opencode models` |
| Rules not loading | Check `instructions` paths exist; use absolute paths for `.cursor/rules/` |
| Session log not created | Confirm Build/Plan prompts include session-log; check `sessions/` write permission |
| Generic-looking UI | Load `ui-ux-design` skill; use `@ui-builder` |
| Skill not available | Check `permission.skill` in `opencode.jsonc`; verify `SKILL.md` frontmatter |
| Subagent missing from `@` menu | Confirm `description` and `mode: subagent` in config |
| Plan agent edits codebase | Check `edit`: deny except `sessions/*`; `bash: deny` |

---

*Last updated: June 2026 — based on OpenCode docs for Rules, Agents, and Config.*