Rules & instructions
You can give the Pathvela agent standing instructions it follows on every turn — your coding standards, the commands it should use, facts about a project, or how you like it to work. You write them in plain Markdown files, and the agent loads them automatically.
This is the single highest-leverage way to make the agent fit your project. A model with no context guesses; a model that has read your conventions gets it right the first time.
The files
The agent reads up to four files, if they exist, and folds them into its context each turn:
| File | Scope | What it's for |
|---|---|---|
AGENTS.md | Project (in the working folder) | Instructions and standards for this project. |
~/AGENTS.md | Global (your home directory) | Instructions that apply to every project. |
LILY.md | Project (in the working folder) | Background and context about this project. |
~/.lily/LILY.md | Global (your Lily data directory) | Context about you — how you work, your preferences. |
AGENTS.md is the one you'll reach for most. It's the same filename other agent tools use, so a project that already has one works with Pathvela out of the box.
Writing an AGENTS.md
Put an AGENTS.md in the root of your project. Keep it short and specific — it's read every turn, so treat it as a briefing, not a manual.
# Project: acme-api
A TypeScript REST API. Node 20, Express, Postgres via Prisma.
## Conventions
- Use `pnpm`, not npm or yarn.
- Prefer async/await; no `.then()` chains.
- All routes validate input with Zod schemas in `src/schemas/`.
## Commands
- Build: `pnpm build`
- Test: `pnpm test` (Vitest)
- Lint: `pnpm lint --fix`
## Don't
- Don't edit anything under `src/generated/` — it's produced by Prisma.
- Don't commit; leave that to me.
Good things to include:
- The stack — language, framework, package manager, database.
- Conventions — naming, formatting, patterns you want followed.
- Commands — how to build, test, run, and lint, so the agent uses the right ones.
- Boundaries — files or areas to leave alone.
Global vs project
- Project files (
AGENTS.md,LILY.mdin the folder) travel with the repo — commit them so your whole team shares the same guidance. - Global files (
~/AGENTS.md,~/.lily/LILY.md) are yours alone and apply everywhere. Use~/AGENTS.mdfor personal defaults ("always explain your plan before large changes") and~/.lily/LILY.mdfor context about you the agent should carry between projects.
When several files are present, the agent reads all of them — project instructions layer on top of your global ones.
Rules, memory, and skills
- Rules (this page) are what you tell the agent, up front, every time.
- Memory is what the agent records as it works, and recalls later.
- Skills are reusable procedure packs the agent pulls in when a task matches.
If you find yourself correcting the agent the same way repeatedly, that correction belongs in AGENTS.md.