# {{PROJECT_TITLE}} — Copilot Instructions

> Auto-generated by `create-objectstack`. Customise freely.

## Project Context

This is an **ObjectStack** application — a metadata-driven low-code project
that defines business objects, views, automations, and AI agents in TypeScript.

- **Entry point:** `objectstack.config.ts` (uses `defineStack()`)
- **Spec package:** `@objectstack/spec` (Zod-first schemas and types)

## Naming Conventions

| Context | Convention | Example |
|:--------|:-----------|:--------|
| Config keys (TS props) | `camelCase` | `maxLength`, `defaultValue` |
| Machine names (data values) | `snake_case` | `project_task`, `first_name` |
| Metadata type names | singular | `'agent'`, `'view'`, `'flow'` |
| File names | `{name}.{type}.ts` | `task.object.ts`, `main.app.ts` |

## Key Rules

1. **Zod First** — All schema definitions start with Zod. Types are derived via `z.infer<>`.
2. `defineStack()` is the single configuration entry point in `objectstack.config.ts`.
3. Use `Object.values()` barrel pattern for metadata arrays.
4. Import from `@objectstack/spec` — never use relative paths into the spec package.

## Project Structure

```
{{PROJECT_NAME}}/
├── objectstack.config.ts    # defineStack() — the single entry point
├── src/
│   ├── objects/              # Business object definitions (snake_case names)
│   ├── views/                # UI view definitions (list, form, kanban, calendar)
│   ├── apps/                 # App navigation & page structure
│   ├── flows/                # Automation flows & workflows
│   ├── actions/              # Custom actions (buttons, bulk ops)
│   ├── dashboards/           # BI dashboards
│   ├── reports/              # Analytics reports
│   ├── agents/               # AI agent definitions
│   ├── i18n/                 # Translation bundles
│   └── handlers/             # Runtime hook handlers
```

## AI Skills

This project uses ObjectStack skills from `objectstack-ai/framework`.
Install or update skills with the standard [skills CLI](https://skills.sh/):

```bash
npx skills add objectstack-ai/framework
```

Skills are triggered automatically based on task context:

| Skill | Trigger Context |
|:------|:----------------|
| **objectstack-platform** | Project setup, defineStack(), driver/adapter selection, plugin lifecycle, DI, services, kernel hooks/events |
| **objectstack-data** | Define objects, fields, relationships, validations, indexes, lifecycle hooks, permissions/RLS, seed fixtures (`defineDataset`) |
| **objectstack-query** | Filters, sorting, pagination, aggregation, ObjectQL |
| **objectstack-ui** | Views, dashboards, apps, reports, actions, navigation |
| **objectstack-api** | REST endpoints, authentication, service contracts |
| **objectstack-automation** | Flows, workflows, triggers, approvals, state machines |
| **objectstack-ai** | Agents, tools, skills, RAG pipelines, LLM config |
| **objectstack-i18n** | Translation bundles, locale config, coverage detection |
| **objectstack-formula** | CEL formula fields, predicates, conditions, dynamic seed values |

## Learn More

- [ObjectStack Documentation](https://objectstack.com/docs)
- [GitHub: objectstack-ai/framework](https://github.com/objectstack-ai/framework)
- [Skills CLI](https://skills.sh/) — Manage AI skills across agents
