How AEP works

The flow

Every AEP interaction follows the same six-step cycle:

Task → Apply AEP → Match Packs → Execute → Save → Improve

You start a task. The agent loads and scores packs from your repo. It applies the best matches to align itself with your intent and constraints before writing a single line. After a successful outcome, you save the pattern. The next run starts better than the last.

Apply flow
Save flow

When you tell your agent to apply packs before a task:

Resolve the install target

The agent detects which agent-specific directory is active in this repo (.claude/aep/, .opencode/aep/, .cursor/aep/, etc.) and reads packs from that location.

Load candidates from the index

The agent reads index.json to get a list of all packs, then loads each referenced pack file. Both "0.1" and "1.0-exp" packs are included — the apply flow is backwards compatible.

Compute a base match score

For each pack, the agent scores keyword and tag overlap against the current task description and repo context:

match.keywords
match.patterns
match.tags

Scores are normalized into the [0, 1] range.

Adjust with applies_to

For v1.0-exp packs, the agent checks whether the pack’s applies_to metadata aligns with the current context:

languages and frameworks in use
file paths being touched
domains (frontend, backend, infra, data)

Matching applies_to fields boost the score. Mismatching fields dampen it. These are soft filters — a pack is never hard-disqualified by applies_to alone.

Combine with strength

The final score blends the task-specific match score with the pack’s general reliability:

combined_score = 0.6 * match_score + 0.4 * strength

If strength is absent (v0.1 packs), the agent treats it as neutral (0.5).

Rank and select packs

Packs are ranked by:

Scope — task > project > user (always)
combined_score — higher is better
Recency — metrics.last_used_at or index.updated_at as a tiebreaker

The agent typically activates 1–3 packs. If no pack has strong alignment, it prefers fewer matches over forcing a weak one.

Activate and explain

The agent merges signals from the selected packs — task-scope signals override project-scope, which override user-scope. It reports which packs are active, their scores, and the key constraints and success checks now in effect.

Update metrics

After selecting packs, the agent increments metrics.times_applied and updates metrics.last_used_at for each applied pack.

When you tell your agent to save a successful collaboration as a new pack:

Extract signals

The agent reviews the session and extracts the six signal types:

intent — the goal
constraints — hard rules
preferences — soft style choices
workflow — step-by-step execution order
failure_traps — mistakes to avoid
success_checks — how to verify success

Infer applies_to

The agent infers applies_to metadata from what actually happened in the session:

languages and frameworks that were used
file paths that were touched
domain (frontend, backend, infra, etc.)

Initialize experimental fields

The agent sets the v1.0-exp tracking fields:

strength: starts at 0.7 for clearly successful tasks
metrics.times_applied: 0 on first creation
metrics.first_used_at and metrics.last_used_at: set to the current timestamp
history: one created event with a short reason
merge_suggestions: empty by default

Write pack and update index

The pack is saved to <agent-dir>/aep/tasks/<id>.aep.json with "version": "1.0-exp". The index.json is updated with the new entry including version, scope, path, tags, strength, and updated_at.

Update instruction files

The agent updates agent instruction files (AGENTS.md, CLAUDE.md, and others relevant to the active agent) to ensure future sessions know to load AEP packs by default before starting tasks.

Pack scopes

Every pack belongs to one of three scopes. Scope determines priority: higher-scope signals always override lower-scope ones when packs conflict.

Scope	File location	Purpose	Priority
Task	`tasks/<id>.aep.json`	Patterns for a specific kind of task (e.g., HTML to Next.js migration)	Highest
Project	`project.aep.json`	Defaults that apply to every task in this repo (e.g., never redesign the layout)	Middle
User	`user.aep.json`	Your personal collaboration style and preferences across all projects	Lowest

When packs from multiple scopes are active at the same time, the merge order is:

task overrides project overrides user

This means a task pack can tighten a constraint that a project pack leaves open, and a project pack can override a user-level default that does not fit this codebase.

Matching and scoring

Matching works in two layers. Layer 1 — keyword and tag overlap (works for all pack versions): The agent compares the current task description against each pack’s match block:

match.keywords — individual terms
match.patterns — short natural-language phrases
match.tags — categorical labels

The more overlap, the higher the raw match score. Layer 2 — applies_to context (v1.0-exp only): The agent checks the pack’s structured context hints:

"applies_to": {
  "languages": ["typescript"],
  "frameworks": ["nextjs"],
  "paths": ["app/**", "pages/**"],
  "domains": ["frontend"]
}

If the current task involves TypeScript and Next.js files under app/, this pack gets a boost. If you’re working on a Python backend service, it gets dampened. These are soft adjustments — not hard filters. The scoring formula:

combined_score = 0.6 * match_score + 0.4 * strength

The 60/40 split means task-specific relevance matters more than general pack quality, but a highly trusted pack (strength: 0.9) will consistently rank above a similar pack with strength: 0.5 when match scores are close. strength interpretation:

Value	Meaning
`0.3`	Weak or tentative pattern
`0.7`	Solid pattern that has worked multiple times
`0.9+`	Very strong, highly trusted pattern

Metrics tracking

Each time a pack is applied, AEP updates its usage metrics:

Field	Type	Description
`times_applied`	integer	How many times this pack has been actively applied
`first_used_at`	ISO 8601	Timestamp of first use
`last_used_at`	ISO 8601	Timestamp of most recent use
`avg_turns_saved`	number	Rough estimate of back-and-forth messages saved on average

These metrics feed back into ranking via the recency tiebreaker, and they help you identify packs that are genuinely earning their place — making them good candidates for promotion.

Pack evolution

Packs are not static. They improve as you use them.

History events

Every meaningful change to a pack is recorded in the history array:

"history": [
  {
    "at": "2026-03-31T10:00:00Z",
    "event": "created",
    "reason": "Initial successful HTML to Next.js migration"
  },
  {
    "at": "2026-04-05T09:15:00Z",
    "event": "updated",
    "reason": "Promoted constraint to avoid redesign without explicit request"
  }
]

Event types include created, updated, promoted, and merged.

Promotion

A task pack that proves itself across multiple tasks can be promoted to project scope — broadening its reach. A project pack that reflects your personal style across many repos can be promoted to user scope. Promotion adds history entries to both the source and target packs, creating an audit trail of how your patterns evolved.

Merge suggestions

When two packs have heavily overlapping intent and constraints, AEP can flag them for potential consolidation:

"merge_suggestions": [
  {
    "target_id": "landing-page-migration",
    "reason": "Very similar intent and constraints; consider merging packs."
  }
]

Merge suggestions are cues for you to review — agents do not auto-merge packs. Use aep inspect to surface any active merge suggestions.

Save a pack

Full guide to saving signals and initializing pack fields.

Apply packs

Step-by-step guide to the apply and scoring flow.

Matching and scoring

Deep dive into the scoring formula and applies_to behavior.

Schema reference

Complete field reference for v1.0-exp packs.

Get Started

Using AEP

Pack Types

Integration

The flow

Pack scopes

Matching and scoring

Metrics tracking

Pack evolution

History events

Promotion

Merge suggestions

Save a pack

Apply packs

Matching and scoring

Schema reference

Build docs developers (and LLMs) love

Get Started

Using AEP

Pack Types

Integration

​The flow

​Pack scopes

​Matching and scoring

​Metrics tracking

​Pack evolution

​History events

​Promotion

​Merge suggestions

Save a pack

Apply packs

Matching and scoring

Schema reference

Build docs developers (and LLMs) love

The flow

Pack scopes

Matching and scoring

Metrics tracking

Pack evolution

History events

Promotion

Merge suggestions