# 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
bunx 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()` |
| `router` | `routers/` | `defineRouter()` |
| `fixture` | `fixtures/` | YAML fixture definition |

## Examples

### Scaffold an Agent

```bash
bunx struere add agent scheduler
```

Creates `agents/scheduler.ts`:

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

export default defineAgent({
  name: "Scheduler",
  slug: "scheduler",
  version: "0.1.0",
  description: "Scheduler Agent",
  model: {
    model: "openai/gpt-5-mini",
    temperature: 0.7,
    maxTokens: 4096,
  },
  systemPrompt: `You are {{agentName}}, an AI assistant for {{organizationName}}.

Current time: {{currentTime}}

Your capabilities:
- Answer questions accurately and helpfully
- Use available tools when appropriate
- Maintain conversation context

Always be concise, accurate, and helpful.`,
  tools: ["entity.query", "entity.get"],
})
```

### Scaffold a Data Type

```bash
bunx 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", description: "Name" },
      email: { type: "string", format: "email", description: "Email address" },
      status: { type: "string", enum: ["active", "inactive"], description: "Status" },
    },
    required: ["name"],
  },
  searchFields: ["name", "email"],
  displayConfig: {
    listFields: ["name", "email", "status"],
  },
})
```

### Scaffold a Role

```bash
bunx struere add role support
```

Creates `roles/support.ts`:

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

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

### Scaffold an Automation

```bash
bunx 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: "ENTITY_TYPE_HERE",
    action: "created",
  },
  actions: [
    {
      tool: "entity.query",
      args: {
        type: "{{trigger.entityType}}",
        filters: { "data.id": "{{trigger.entityId}}" },
      },
    },
  ],
})
```

### Scaffold a Router

```bash
bunx struere add router support-router
```

Creates `routers/support-router.ts`:

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

export default defineRouter({
  name: "Support Router",
  slug: "support-router",
  mode: "rules",
  agents: [
    { slug: "agent-one", description: "Handles ..." },
  ],
  rules: [
    {
      conditions: [{ field: "channel", operator: "eq", value: "whatsapp" }],
      route: "agent-one",
    },
  ],
  fallback: "agent-one",
})
```

### Scaffold a Fixture

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

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

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

entities:
  - ref: "example-1"
    type: "ENTITY_TYPE_HERE"
    data:
      name: "Example Entity"
    status: "active"

  - ref: "example-2"
    type: "ENTITY_TYPE_HERE"
    data:
      name: "Another Entity"

relations:
  - from: "example-1"
    to: "example-2"
    type: "related_to"
```

## 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`)