# struere add

> Scaffold new agents, data types, roles, and automations

The `add` command scaffolds a new resource file with a starter template in the appropriate directory.

## Usage

```bash
npx struere add <type> <name>
```

## Resource Types

| Type | Directory | Definition Function |
|------|-----------|-------------------|
| `agent` | `agents/` | `defineAgent()` |
| `data-type` | `entity-types/` | `defineData()` |
| `role` | `roles/` | `defineRole()` |
| `trigger` | `triggers/` | `defineTrigger()` |
| `eval` / `suite` | `evals/` | `defineEvalSuite()` |
| `fixture` | `fixtures/` | YAML fixture definition |

## Examples

### Scaffold an Agent

```bash
npx struere add agent scheduler
```

Creates `agents/scheduler.ts`:

```typescript
import { defineAgent } from 'struere'

export default defineAgent({
  name: "Scheduler",
  slug: "scheduler",
  version: "0.1.0",
  systemPrompt: "You are a scheduling assistant...",
  model: {
    model: "openai/gpt-5-mini",
  },
  tools: ["entity.query", "event.emit"],
})
```

### Scaffold a Data Type

```bash
npx struere add data-type customer
```

Creates `entity-types/customer.ts`:

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Customer",
  slug: "customer",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      email: { type: "string", format: "email" },
    },
    required: ["name", "email"],
  },
  searchFields: ["name", "email"],
})
```

### Scaffold a Role

```bash
npx struere add role support
```

Creates `roles/support.ts`:

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "support",
  description: "Support team role",
  policies: [
    { resource: "customer", actions: ["list", "read"], effect: "allow" },
  ],
})
```

### Scaffold an Automation

```bash
npx struere add trigger notify-on-signup
```

Creates `triggers/notify-on-signup.ts`:

```typescript
import { defineTrigger } from 'struere'

export default defineTrigger({
  name: "Notify on Signup",
  slug: "notify-on-signup",
  on: {
    entityType: "customer",
    action: "created",
  },
  actions: [
    {
      tool: "event.emit",
      args: {
        eventType: "customer.signup",
        entityId: "{{trigger.entityId}}",
      },
    },
  ],
})
```

### Scaffold a Fixture

```bash
npx struere add fixture classroom-data
```

Creates `fixtures/classroom-data.fixture.yaml`:

```yaml
name: "Classroom Data"
slug: "classroom-data"

entities:
  - ref: "example-entity"
    type: "ENTITY_TYPE_HERE"
    data:
      name: "Example"

relations: []
```

## With Dev Running

If you have `struere dev` running in another terminal, newly scaffolded files will be detected and synced to Convex automatically. You can immediately edit the generated file and see your changes reflected in the development environment.

## Naming Conventions

The `<name>` argument is used to generate both the filename and the resource slug:

- Filename: `<name>.ts` (e.g., `scheduler.ts`, `notify-on-signup.ts`)
- Slug: derived from the name (e.g., `scheduler`, `notify-on-signup`)
- Display name: derived from the name with capitalization (e.g., `Scheduler`, `Notify on Signup`)