|

Project Layout

The agent/ directory convention — every slot, how it maps to the manifest, and the rules Zett validates.

A Zett agent is a directory of well-known slots. Zett discovers the slots (static analysis, for arcie dev / arcie build) and loads them into an agent manifest — the object the runtime executes.

agent/
├── agent.ts            # required-ish — the agent config (model + Cencori)
├── instructions.md     # the system prompt
├── tools/              # defineTool — what the agent can do
├── skills/             # defineSkill — what the agent knows
├── hooks/              # defineHook — lifecycle callbacks
├── channels/           # defineChannel — HTTP / Slack / custom ingress
├── schedules/          # defineSchedule — cron jobs
├── subagents/          # nested specialist agents (directories)
├── sessions/           # config.ts — durable-execution config
├── policies/           # index.ts — security + budget guardrails
├── connections/        # outbound service connections (discovered)
└── lib/                # shared helpers (discovered)

Slot reference
SlotHoldsHelperLoaded into manifest
agent.tsAgent configdefineAgentYes — config
instructions.mdSystem prompt (text)—Yes — instructions
tools/*.tsCallable toolsdefineToolYes — tools
skills/*.tsLoadable knowledge/proceduresdefineSkillYes — skills
hooks/*.tsLifecycle callbacksdefineHookYes — hooks
channels/*.tsMessage ingressdefineChannelYes — channels
schedules/*.tsCron jobsdefineScheduleYes — schedules
subagents/<id>/Nested specialist agentsdefineAgentYes — subagents
sessions/config.tsSession behavior— (plain object)Yes — session
policies/index.tsGuards + budgets— (plain object)Yes — policy
connections/*.tsOutbound connections—Discovered only
lib/*.tsShared helpers—Discovered only

Each file in a slot directory default-exports its config; the file name (without extension) becomes the slot's name. Subagents are the exception — they're directories, each a small agent of its own (see Subagents).

Defaults
  • Missing agent.ts → the agent falls back to { model: "gpt-4o" }.
  • Missing instructions.md → defaults to "You are a helpful AI agent."
  • Empty slot directory → simply contributes nothing.

Naming rules

Slot names are validated against slug patterns. A bad name is a warning (INVALID_SLOT_NAME), not a hard failure.

SlotsPattern
tools, skills, schedules, hooks, subagents, lib[a-zA-Z][a-zA-Z0-9_-]{0,63}
channels, connections[a-z][a-z0-9-]{0,63} (lowercase)

Recognized module extensions: .ts, .mts, .cts, .js, .mjs, .cjs. Files named .gitkeep are ignored.

Diagnostics

arcie dev and arcie build run discovery first and report diagnostics. Any error-severity diagnostic stops the command (exit code 1); warnings are printed and execution continues.

CodeSeverityMeaning
AGENT_DIR_NOT_FOUNDerrorThe agent directory doesn't exist.
MODULE_SLOT_COLLISIONerrorMultiple agent.* files for one slot.
SUBAGENT_MISSING_CONFIGerrorA subagents/<id>/ has no agent.ts.
DIRECTORY_READ_ERRORerrorA slot directory couldn't be read.
INVALID_SLOT_NAMEwarningA file/dir name fails the slug pattern.
DEPRECATED_SYSTEM_SLOTwarningsystem.md found — rename to instructions.md.

The manifest

loadAgent(agentDir) resolves every slot into an AgentManifest:

interface AgentManifest {
  config: AgentConfig;
  instructions: string;
  tools: Record<string, ToolConfig>;
  skills: Record<string, SkillConfig>;
  hooks: Record<string, HookConfig>;
  channels: Record<string, ChannelConfig>;
  schedules: Record<string, ScheduleConfig>;
  subagents: Record<string, SubagentManifest>;
  session?: SessionConfig;
  policy?: PolicyConfig;
}

arcie build serializes a summary of this to .arcie/manifest.json. See the CLI reference.

Did you like the content?