# Folder Structure

The OrchaJS folder layout for agents, actions, skills, tests, and the registry.

Source: https://orcha.sh/docs/folder-structure
Markdown: https://orcha.sh/docs/folder-structure.mdx

The `orcha/` directory is the source of truth. Placement determines behavior, so an agent remains understandable by opening its folder.

```text
orcha/
  index.ts
  supportAgent/
    index.json
    instructions.md
    actions/
      lookupOrder/
        index.json
        index.js
    skills/
      delayedOrderHandling/
        index.json
        instructions.md
    tests/
      delayedOrder/
        index.json
    evaluations/
      supportQuality/
        index.json
```

## `orcha/index.ts`

Initializes providers and explicitly registers agents:

```ts

orcha.init({
  providers: {
    openai: process.env.OPENAI_API_KEY ?? "",
  },
  agents: {
    supportAgent: "./supportAgent",
  },
});
```

Only registered agents are compiled. The registration key becomes the runtime property: `orcha.supportAgent`.

## Agent files

### `agent/index.json`

Chooses the provider, model, output type, and model limits. `name`, `provider`, and `model` are required.

```json
{
  "name": "Support Agent",
  "description": "Resolves order questions using confirmed order data.",
  "provider": "openai",
  "model": "gpt-5-mini",
  "maxTokens": 4000,
  "outputType": "text"
}
```

### `agent/instructions.md`

Contains stable behavior: role, boundaries, decision rules, and guidance for tools. Keep changing user input out of this file and pass it to `run()` instead.

```md
You help customers understand their orders.

Always look up an order before making claims about its status.
Never invent order data.
```

Prompt variables use `{{ variableName }}` and are supplied once when the session is created.

## `actions/`

Actions let the model do work. Every direct child folder has metadata in `index.json`. Local actions also have executable `index.js`.

```text
actions/
  lookupOrder/
    index.json
    index.js
```

- Omit `execution` for a local action.
- Use `"execution": "client"` when the caller must do the work.
- Direct child folders are discovered automatically.

## `skills/`

Skills are procedures loaded only when relevant:

```text
skills/
  delayedOrderHandling/
    index.json
    instructions.md
```

`index.json` is the small discovery card. `instructions.md` is the full procedure. Orcha initially exposes only the card, keeping the base prompt small.

## `tests/`

Each direct child is one model-backed contract test:

```text
tests/
  delayedOrder/
    index.json
```

The test defines an input, action mocks, and deterministic expectations. The folder name is its CLI selector: `orcha test supportAgent/delayedOrder`.

## `evaluations/`

Each direct child configures an asynchronous model judge:

```text
evaluations/
  supportQuality/
    index.json
```

Evaluations score qualities such as grounding or clarity. Tests check deterministic contracts; evaluations check probabilistic quality.

## Generated `.orcha/`

`.orcha/` is generated output, not source:

```text
.orcha/
  dist/
    bundle.js
  sessions/
    supportAgent/
      ses_...jsonl
  .build/
  .cli/
```

`dist/` is the production agent bundle. `.build/` and `.cli/` are temporary compiler artifacts. Do not edit or commit any of them. Access sessions through `agent.get()`, `history()`, `events()`, and `list()` rather than reading storage files directly.

## Discovery rules

- Agents and subagents must be registered in `orcha/index.ts`.
- Actions, skills, tests, and evaluations are discovered from direct child folders.
- Set `"enabled": false` in an item's `index.json` to keep work in progress inactive.
- Enabled entries must contain their required files.
- Model-facing names must be unique within an agent.
- Invalid files and schemas fail during `orcha dev` or `orcha build`, before a user run.