Skip to main content
Backwards compatibility is a core design principle of AEP. Every v1.0-exp pack can be read by an agent that only understands v0.1 — experimental fields are additive and agents may safely ignore anything they do not recognize.
v1.0-exp extends v0.1 without breaking it. The new fields (applies_to, strength, metrics, history, merge_suggestions) are all optional from the perspective of a v0.1 agent. Agents that do understand v1.0-exp get richer ranking, evolution tracking, and merge guidance.

​
What v1.0-exp adds

Fieldv0.1v1.0-exp
version"0.1""1.0-exp"
idyesyes
scopeyesyes
titleyesyes
statusyesyes
sourceyesyes
matchyesyes
intentyesyes
constraintsyesyes
preferencesyesyes
workflowyesyes
failure_trapsyesyes
success_checksyesyes
artifactsyesyes
applies_to—added
strength—added
metrics—added
history—added
merge_suggestions—added
All v0.1 fields carry exactly the same meaning in v1.0-exp.

​
Reading packs

Agents should support both "version": "0.1" and "version": "1.0-exp" when reading packs from .agent/aep/. The recommended approach:
  1. Read index.json to get the list of packs and their versions.
  2. Load each pack file regardless of version.
  3. Use whatever fields are present. Silently skip fields you do not recognize.
Graceful degradation: if your agent does not yet implement applies_to, metrics, or history handling, it can ignore those fields and rely on the v0.1 subset (match, constraints, preferences, etc.) to operate correctly.

​
Writing packs

New packs should use "version": "1.0-exp" and include all experimental fields. This gives agents the richest possible signal for ranking and evolution. Updating existing v0.1 packs — you have two options:
  • Keep on v0.1: only update v0.1 fields. Do not change the version field. The pack remains compatible with older agents.
  • Migrate to v1.0-exp: explicitly update the version to "1.0-exp", add the new fields, and record the migration in the history array.
When you are introducing v1.0-exp into a repo that already has v0.1 packs, use this pattern:
  1. Read both v0.1 and v1.0-exp packs from .agent/aep/.
  2. Prefer v1.0-exp packs when both exist for the same domain — they contain richer scoring metadata.
  3. Write new packs with "version": "1.0-exp" while leaving existing v0.1 packs untouched as fallbacks.
index.json may list packs of both versions simultaneously. This is a valid and intentional state: 
{
  "version": "1.0-exp",
  "packs": [
    {
      "id": "old-pattern",
      "scope": "task",
      "version": "0.1",
      "path": "tasks/old-pattern.aep.json",
      "tags": ["backend"],
      "updated_at": "2025-11-01T00:00:00Z"
    },
    {
      "id": "new-pattern",
      "scope": "task",
      "version": "1.0-exp",
      "path": "tasks/new-pattern.aep.json",
      "tags": ["backend"],
      "strength": 0.8,
      "updated_at": "2026-03-31T00:00:00Z"
    }
  ]
}
The agent uses strength and recency (updated_at) from the index entry to rank candidates before loading individual files. A v0.1 entry without strength should be treated as neutral (0.5).

​
Migrating a v0.1 pack to v1.0-exp

To migrate an existing pack:
1

Update the version field

Change "version": "0.1" to "version": "1.0-exp".
2

Add applies_to

Populate applies_to with the languages, frameworks, paths, and domains that best describe when the pack applies.
"applies_to": {
  "languages": ["typescript"],
  "frameworks": ["nextjs"],
  "paths": ["app/**"],
  "domains": ["frontend"]
}
3

Set strength

Assign an initial strength value based on how proven the pattern is. A pattern that has worked multiple times is typically 0.7–0.8.
"strength": 0.75
4

Initialize metrics

Add a metrics object. Set times_applied to reflect real usage if you know it, or 0 if uncertain.
"metrics": {
  "times_applied": 0,
  "first_used_at": "2026-03-31T00:00:00Z",
  "last_used_at": "2026-03-31T00:00:00Z",
  "avg_turns_saved": 0
}
5

Add a history entry

Record the migration in the history array so the pack’s evolution is traceable.
"history": [
  {
    "at": "2026-03-31T00:00:00Z",
    "event": "updated",
    "reason": "Migrated from v0.1 to v1.0-exp; added applies_to, strength, and metrics."
  }
]
6

Update index.json

Refresh the entry for this pack in index.json to use "version": "1.0-exp" and add the strength and updated_at fields.

​
Platform notes

v1.0-exp is fully opt-in. Adopting it does not break existing v0.1 workflows on any platform.
  • Cursor / Codex-style agents: v1.0-exp is adopted purely as a richer JSON format. All agent logic lives in prompts and file operations — no changes to tooling are required.
  • Claude Code / OpenCode: v1.0-exp works identically to v0.1 from the file perspective. Future MCP servers may optionally expose structured operations that interpret strength, metrics, and history, but this is not required for basic compatibility.

Pack schema reference

Full field reference for v1.0-exp packs, including all new fields.

Integration: repo setup

How to structure your .agent/aep/ directory for mixed-version deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us