AEP File Structure / Spec

JSON structure

An AEP is a JSON object that encodes reusable execution context for agents.

Required fields

• intent (string): desired outcome
• workflow (string[]): ordered execution steps
• success_checks (string[]): observable completion checks

Optional fields

• constraints (string[]): hard limits
• preferences (string[]): style/process defaults
• failure_traps (string[]): known pitfalls
• context (object | string[]): task/project assumptions
• version (string): spec or pack version tag

Validation guidance

• workflow should be actionable and ordered.
• success_checks should be testable (not subjective).
• constraints should avoid internal conflict.
• Keep pack size practical for quick loading and review.

Example AEP

{
  "version": "1.0-exp",
  "intent": "Implement docs updates without route regressions.",
  "constraints": [
    "Do not break existing URLs",
    "Keep changes scoped to docs app"
  ],
  "preferences": [
    "Use concise, actionable writing",
    "Prefer small, reviewable edits"
  ],
  "workflow": [
    "Inspect current docs structure",
    "Apply focused content updates",
    "Run type and route checks",
    "Report what changed"
  ],
  "failure_traps": [
    "Leaving stale links in sidebar",
    "Adding ambiguous success criteria"
  ],
  "success_checks": [
    "Typecheck passes",
    "Key docs routes return HTTP 200"
  ]
}

Naming and storage conventions

Common patterns:

• project.aep.json
• task.<name>.aep.json
• user.aep.json

Recommended directories:

• .codex/aep/
• .claude/aep/
• .cursor/aep/