Agent Guide

Agents should treat eve as durable repository memory, not as another place to dump a transcript.

Before changing behavior, read relevant snapshots to understand previous product decisions and validation expectations. After completing and verifying behavior, write a new snapshot that records the product meaning and evidence.

eve init installs the same concise EVE guidance in AGENTS.md for Codex and compatible harnesses and in CLAUDE.md for Claude Code. EVE owns only the content between its managed markers; other repository instructions remain user-authored. Run eve instructions status or eve doctor to detect missing, stale, modified, or malformed guidance.

Agent workflow

1. Inspect the repository and recent snapshots.
2. For non-trivial product work, call declare_plan with a stable planRequestId.
3. Wait for a locked Plan revision before editing code.
4. Implement the requested product change.
5. Run relevant verification.
6. Commit implementation changes to Git when the repository workflow calls for it.
7. Complete an eve snapshot with the locked Plan reference, title, type, summary, validation, artifacts, and relationships.
8. Commit the generated .eve/ record to Git.

If declare_plan times out, is cancelled, or the agent restarts, recover with get_plan_request or call declare_plan again with the same planRequestId.

What agents should write

Good eve records are concise, specific, and evidence-oriented.

Include:

• What changed for users or maintainers
• Why notable decisions were made
• Which validation was run and whether it passed
• Which artifacts demonstrate the result
• Known risks or follow-up concerns
• Related snapshot IDs

Avoid:

• Long conversational transcripts as the primary summary
• Claims without verification
• Secrets, tokens, or private data
• Implementation-only detail that Git already captures better

Prefer MCP when available

When the MCP server is available, prefer the structured MCP tools over shell-only flows. MCP lets an agent complete snapshots without relying on fragile text parsing.

Call declare_plan before snapshot-worthy implementation and wait for approval. Call complete_snapshot after a coherent, completed unit of product work. If the work is trivial or incomplete and should not enter product history, call skip_snapshot with a short reason.

Use the CLI fallback when MCP is not connected.

Agent rule of thumb

If a future agent would need the fact to avoid repeating a mistake, include it. If Git already shows the detail clearly, leave it in Git.