Skip to main content
index.json is the single entry point agents use to discover all packs in a repo. It lives at .agent/aep/index.json and lists every pack with enough metadata for the agent to rank candidates before loading individual pack files.
The index can hold entries for packs of both "0.1" and "1.0-exp" versions. Agents should handle mixed-version indexes gracefully and not require all entries to have every field.

​
Complete example

This is the actual template from assets/templates/index.json: 
{
  "version": "1.0-exp",
  "packs": [
    {
      "id": "project-defaults",
      "scope": "project",
      "version": "1.0-exp",
      "path": "project.aep.json",
      "tags": [],
      "strength": 0.6,
      "updated_at": "2026-03-31T00:00:00Z"
    },
    {
      "id": "user-collaboration-style",
      "scope": "user",
      "version": "1.0-exp",
      "path": "user.aep.json",
      "tags": [],
      "strength": 0.6,
      "updated_at": "2026-03-31T00:00:00Z"
    },
    {
      "id": "generic-task-pattern-exp",
      "scope": "task",
      "version": "1.0-exp",
      "path": "tasks/generic-task-pattern-exp.aep.json",
      "tags": [],
      "strength": 0.5,
      "updated_at": "2026-03-31T00:00:00Z"
    }
  ]
}
A more detailed entry (with a real pack that has been applied): 
{
  "version": "1.0-exp",
  "packs": [
    {
      "id": "task-html-to-nextjs",
      "scope": "task",
      "version": "1.0-exp",
      "path": "tasks/html-to-nextjs.aep.json",
      "tags": ["frontend", "migration", "nextjs", "html"],
      "strength": 0.9,
      "updated_at": "2026-03-31T10:00:00Z"
    }
  ]
}

​
Field reference

​
version
string
The index schema version. Use "1.0-exp" when the index itself uses experimental fields such as strength on entries. Agents that do not understand "1.0-exp" should still be able to read the packs array.
​
packs
array
Array of pack entries. Each entry gives the agent enough information to rank packs before loading the full pack file.

​
File location

<repo-root>/
└── .agent/
    └── aep/
        ├── index.json          ← this file
        ├── project.aep.json
        ├── user.aep.json
        └── tasks/
            └── my-task.aep.json
The .agent/ directory lives at the root of your repository. Agents read index.json first to build the candidate list, then load individual pack files only for the top candidates.

​
Keeping the index in sync

When you run aep save, the agent updates index.json automatically, adding or refreshing the entry for the saved pack. The entry should always include version, strength, and updated_at for v1.0-exp packs. If you add or edit pack files manually, update index.json to match. An entry in index.json that points to a missing file will cause the agent to skip that entry with a warning.
Agents should handle entries that lack strength or updated_at — for example, entries that were written by older tooling. Treat missing strength as neutral (0.5) and missing updated_at as the oldest possible recency.

Pack schema reference

Full field reference for the individual pack files listed in this index.

Templates

A ready-to-use index.json template alongside all three pack templates.

Build docs developers (and LLMs) love

Get started for freeTalk to us