Instructions & memory
Give the agent persistent instructions and project context via AGENTS.md, .maestro/ config, and optional auto-memory. The agent reads these at the start of each session so it stays aligned with your standards and goals.
AGENTS.md
AGENTS.md is a Markdown file in your project root (or under .midcore/) that the agent loads first.
When to use AGENTS.md
- Coding standards (style, naming, test requirements)
- Architecture decisions (e.g. “APIs go in apps/api/”)
- Preferred libraries and versions
- Review checklists (e.g. “Always run lint before committing”)
Short example:
# Project instructions
## Stack
- Backend: Node 20+, TypeScript strict mode
- Tests: Vitest; aim for 80%+ coverage on new code
## Conventions
- Use REST for HTTP APIs; document in OpenAPI.
- Never commit secrets; use env vars and reference the security doc.
## Before committing
- Run `pnpm lint` and `pnpm test`
- Run `midcore gates run` if this repo uses gates
Discovery
.maestro config
The .maestro/ directory holds compiler and gate configuration:
- intent.yaml — Product intent and delivery tier (prototype, pilot, production). The Outcome Compiler uses this to scope work and select which gates apply.
- gates.yaml — Defines which gates run and their order. Evidence from each run is recorded in the evidence ledger.
The agent and CLI read these files to stay consistent with your release and proof requirements. See intent.yaml and Gates reference for schema and examples.
Auto memory (optional)
Some environments support saving learnings across sessions (e.g. build commands, common fixes) without you editing a file. When enabled, the agent can recall these in later sessions. This is optional and configurable; see your platform or Settings docs for how to enable or disable it.
Key takeaways
- AGENTS.md and .maestro config give the agent persistent instructions and project context.
- Use AGENTS.md for standards, architecture, and review checklists so every session starts aligned.
- intent.yaml and gates.yaml drive the Outcome Compiler and gate selection; the agent reads them automatically.