Ch3. Project Layout and Discovery
How Eve turns agent directory slots into a source manifest, and why path-derived identity is an operations contract.
Key takeaways
agent/is a declarative interface for context, authority, and execution capability.- Discovery derives identity from paths, so filenames become operational contracts.
- Root agents, subagents, instructions, skills, and tools should be separated at the folder boundary first.
In Eve, agent/ is not just a folder. It is the interface that declares what the agent is, what it can see, and what it can ask the runtime to do.
Root Resolution: Nested And Flat
Eve supports a recommended nested layout and a flatter form.
| Layout | Shape | Recommendation |
|---|---|---|
| nested | app root contains agent/ | Preferred for production apps |
| flat | current directory itself contains agent.ts, instructions.md, tools/ | Useful for small experiments |
Recommended structure:
my-agent/
├── package.json
├── agent/
│ ├── agent.ts
│ ├── instructions.md
│ ├── tools/
│ ├── skills/
│ ├── connections/
│ ├── channels/
│ ├── sandbox/
│ └── subagents/
└── evals/Slots Discovery Reads
| Slot | Root agent | Subagent | Purpose |
|---|---|---|---|
agent.ts | yes | yes | model, output schema, compaction, experimental flags |
instructions.md / .ts | yes | yes | always-on prompt |
tools/*.ts | yes | yes | authored actions |
skills/** | yes | yes | load-on-demand procedures |
connections/*.ts | yes | yes | external MCP/OpenAPI tools |
sandbox/** | yes | yes | workspace and backend config |
hooks/** | yes | yes | stream-event hooks |
channels/** | yes | no | inbound delivery surfaces |
schedules/** | yes | no | cron or scheduled work |
subagents/** | yes | nested local agents | delegation units |
Path-derived Identity
| Path | Derived identity |
|---|---|
agent/tools/refund_charge.ts | refund_charge |
agent/connections/linear.ts | linear |
agent/skills/release/SKILL.md | release |
agent/subagents/reviewer/agent.ts | reviewer |
Names are public contracts. They appear in evals, traces, approval logs, and model behavior. Rename with the same care you would use for an API endpoint.
Diagnostics Are Release Artifacts
Discovery and compilation produce diagnostics when files are in the wrong slot, missing default exports, or shaped incorrectly. Treat .eve/diagnostics.json as release evidence.
| Diagnostic | Action |
|---|---|
| tool not discovered | verify file path and default export |
| subagent missing description | add description to child agent.ts |
| schedule under subagent | move to root agent |
| unexpected skill layout | normalize SKILL.md location |
Instructions Strategy
Use instructions for stable identity and policy:
- role and scope
- safety and escalation rules
- answer style
- allowed and forbidden behavior
- when to use skills or tools
Do not place every procedure in always-on instructions. Long task procedures belong in skills/.
Skills As Progressive Disclosure
Skills are procedure memory. A good skill description is a routing contract for the model.
| Good skill | Poor skill |
|---|---|
| "Release checklist for production deployment incidents." | "Useful notes." |
| "Refund escalation policy for billing support." | "Support stuff." |
Use skills for long playbooks, team policies, domain procedures, and operational templates.
Subagent Boundaries
agent/subagents/<id>/agent.ts defines a child agent root. Declared subagents do not inherit the root agent's tools, skills, sandbox, or state by default. This makes them valuable security and quality boundaries.
Example split:
| Subagent | Capabilities |
|---|---|
researcher | read-only docs and warehouse connections |
operator | approval-gated write tools |
reviewer | structured risk output schema |
Discovery Checklist
| Area | Standard |
|---|---|
| file names | stable, descriptive, risk-visible |
| tools | one capability per file, scoped inputs |
| skills | clear descriptions, no secrets |
| connections | allow/block filters and approval documented |
| channels | root-only, explicit auth |
| subagents | description, model, tools, and sandbox reviewed |
| diagnostics | clean before release |