Skip to main content
AEP organizes experience into three scopes: task, project, and user. Each scope captures a different layer of context, and together they give agents a complete picture of how you want to work — before any task begins.

​
The three scopes

Task packs capture patterns for specific recurring tasks. They encode intent, constraints, workflow steps, and failure traps that proved useful for a particular type of work — for example, converting HTML to Next.js without redesigning the layout. Task packs are the most targeted scope and carry the highest override priority. Project packs capture cross-task constraints and preferences that apply broadly across a repo. They encode things like code style rules, architectural preferences, and team conventions that should be consistent regardless of what task is running. A single project.aep.json lives at the root of the AEP directory and applies automatically to every task in that repository. User packs capture personal collaboration style and preferences that travel with you between repositories. They encode how you like agents to explain things, how you make decisions, and how you prefer to communicate — preferences that are independent of any particular project or task.

​
Override order

When multiple packs are active, signals are merged in a defined priority order: 
task overrides project overrides user
A constraint set in a task pack takes precedence over the same field in the project pack, which in turn takes precedence over the user pack. This means you can set broad defaults at the user level, refine them per project, and override them precisely for individual task types.

​
Where packs are stored

AEP packs are stored inside the active agent’s directory under aep/: 
<agent-dir>/
  aep/
    index.json
    project.aep.json
    user.aep.json
    tasks/
      html-to-nextjs-migration.aep.json
      ...
The <agent-dir> matches the agent you are using:
AgentDirectory
Claude.claude/
OpenCode.opencode/
Cursor.cursor/
Codex.codex/
Gemini.gemini/
  • Task packs: <agent-dir>/aep/tasks/<id>.aep.json
  • Project pack: <agent-dir>/aep/project.aep.json
  • User pack: <agent-dir>/aep/user.aep.json

​
The index.json file

<agent-dir>/aep/index.json is the registry that ties everything together. It lists every pack across all scopes with its path, scope, tags, strength, and last-updated timestamp. Agents load the index first to discover available packs before deciding which ones to apply. 
{
  "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": "html-to-nextjs-migration",
      "scope": "task",
      "version": "1.0-exp",
      "path": "tasks/html-to-nextjs-migration.aep.json",
      "tags": ["frontend", "migration", "nextjs"],
      "strength": 0.9,
      "updated_at": "2026-03-31T00:00:00Z"
    }
  ]
}

​
Scope comparison

ScopePurposeFile locationWhen to use
taskPatterns for a specific recurring task type<agent-dir>/aep/tasks/<id>.aep.jsonWhen a task type repeats with similar constraints
projectCross-task defaults for a single repo<agent-dir>/aep/project.aep.jsonWhen conventions apply to all tasks in a project
userPersonal collaboration style across all work<agent-dir>/aep/user.aep.jsonWhen preferences should follow you between repos

​
How signals merge

When aep apply runs before a task, the agent loads all relevant packs and merges their signals in scope order:
1

Load the index

The agent reads index.json to discover available packs and their metadata.
2

Score and rank

Each pack receives a match score based on keyword overlap, applies_to fields (languages, frameworks, paths, domains), and the pack’s strength value. Task packs are ranked above project packs, which rank above user packs.
3

Merge signals

Signals — intent, constraints, preferences, workflow, failure_traps, success_checks — are merged. Task-level values override project-level values, which override user-level values.
4

Activate

The agent reports which packs are active, their scores and strength, and the key constraints and checks that will govern the task.
Agents should treat applies_to fields as soft filters. If a pack matches on keywords but not on language or framework, it can still be applied at reduced weight.

​
Explore each pack type

Task packs

Save and reuse patterns for specific recurring tasks.

Project packs

Define project-wide constraints and preferences for all tasks.

User packs

Encode your personal collaboration style across all projects.

Schema reference

Full field reference for all pack types and the index schema.

Build docs developers (and LLMs) love

Get started for freeTalk to us