Bootstrap a New Neexo Project

## Overview

When starting a new Neexo project, the `.github/` structure is as important as the code. This recipe gives your project an AI setup that matches production-grade Neexo standards from day one. Pick a [stack playbook](https://awesome.neexo.dk/playbooks) on the hub for tailored recommendations.

## Step 1: Install the Guardrails Plugin

```bash
# Register the Neexo marketplace (one-time)
copilot plugin marketplace add NeexoCore/awesome-neexo

# Install guardrails (cost, security, database, testing instructions)
copilot plugin install neexo-guardrails@awesome-neexo

# Install developer tools (code review, commit messages)
copilot plugin install neexo-developer@awesome-neexo
```

## Step 2: Create the .github Structure

```
.github/
├── copilot-instructions.md    # Project-specific rules
├── instructions/               # Path-specific instructions
│   └── (your domain files)
├── agents/                     # Optional: specialized agents
├── prompts/                    # Optional: scaffolding prompts
├── skills/                     # Optional: custom skills
└── workflows/                  # CI/CD
```

## Step 3: Write copilot-instructions.md

Use this template and fill in your project's details:

```markdown
---
applyTo: '**'
description: 'Global project rules for <project-name>'
---

# <Project Name> — Project Rules

## Stack

- **Framework:** (e.g., Next.js 16 App Router)
- **Language:** (e.g., TypeScript 5 strict)
- **Styling:** (e.g., Tailwind CSS 4 + shadcn/ui v4)
- **Database:** (e.g., Drizzle ORM + PostgreSQL/Neon)
- **Auth:** (e.g., Clerk v7)
- **Validation:** (e.g., Zod v4 — import from "zod/v4")
- **Package manager:** (npm/pnpm)
- **Deployment:** (e.g., Vercel via GitHub Actions)

## Critical Conventions

(List your non-negotiable rules here — things every agent must know)

## Project Structure

(Outline key directories and their purpose)

## Build & Validation

(List the commands to run before committing)

## Do NOT

(List common mistakes specific to your project)
```

## Step 4: Add Path-Specific Instructions

Create instruction files in `.github/instructions/` for specific domains:

```markdown
---
applyTo: '**/db/**'
description: 'Database and migration rules'
---

# Database Rules

- Always scope queries by orgId
- Keep schema + migration + code in the same commit
```

## Step 5: Verify Setup

Open VS Code, start a Copilot chat, and ask:

```
What instructions and plugins are loaded for this workspace?
```

Use **Copilot Chat Diagnostics** (Command Palette → "Chat: Show Diagnostics") to confirm all instructions are active.

## Stack-Specific Recommendations

### Multi-Tenant SaaS (`saas-multi-tenant` playbook)

Install guardrails + developer plugins, then add instructions for:
- `nextjs-conventions` (from marketplace)
- `drizzle-database` (from marketplace)
- `clerk-auth` (from marketplace)
- `zod-v4` (from marketplace)
- `shadcn-ui-v4` (from marketplace)
- Domain-specific rules in `.github/instructions/`

### 3D Marketing Website (`marketing-3d-site` playbook)

Add instructions for:
- `nextjs-conventions` (from marketplace)
- `react-three-fiber` (from marketplace)
- `next-intl` (from marketplace)
- 3D component patterns in `.github/instructions/3d.instructions.md`

### Blender Asset Pipeline (`blender-pipeline` playbook)

Add instructions for:
- `blender-python` (from marketplace)
- Subprocess and rendering rules in `.github/instructions/`

### Unity Editor Tooling (`unity-editor-tools` playbook)

Add instructions for:
- Singleton patterns, versioning rules in `.github/instructions/`

## Pro Tips

- **Keep the copilot-instructions.md under 500 lines** — split domain knowledge into separate instruction files
- **Add prompts for scaffolding** — if your team creates the same file types often (API routes, components, pages), create `.github/prompts/` templates
- **Reference the hub** — share `https://awesome.neexo.dk/llms.txt` with agents (one link; they self-navigate to playbooks and resources)
- **Review monthly** — as your project evolves, update instructions to match current patterns