Skip to main content
Before starting a task, an AEP-aware agent scores every available pack against the current context and selects the best 1–3 to activate. This page explains each step of that process.

​
The apply scoring flow

The full ranking process runs in eight steps:
1

Load candidates

The agent loads all known packs from two sources:
  • <agent-dir>/aep/index.json — the pack registry listing every available pack with its path, tags, and strength.
  • Individual pack files referenced by the index (e.g. tasks/html-to-nextjs.aep.json).
Both "0.1" and "1.0-exp" packs are included. The agent is backwards compatible and can score v0.1 packs alongside v1.0-exp packs in the same run.
2

Compute a base match score

For each pack, the agent computes a base match score using the task description and repo context. The score is derived from three match fields:
  • match.keywords — individual terms that signal relevance.
  • match.patterns — short phrases describing typical use cases.
  • match.tags — categorical labels (e.g. "frontend", "migration").
The raw overlap count is normalized into [0, 1] to produce the base match score.
3

Adjust with applies_to (v1.0-exp)

For v1.0-exp packs, the base score is adjusted using the applies_to block:
  • Languages and frameworks — if the current task clearly involves TypeScript and a pack declares "languages": ["typescript"], the score is boosted.
  • Paths — if touched files fall under "paths": ["app/**"], the score is boosted.
  • Domains — if the task is clearly frontend work and the pack declares "domains": ["frontend"], the score is boosted.
Mismatches dampen the score. Neutral or absent context leaves the score unchanged.
applies_to filters are always soft. A mismatch reduces a pack’s score but never hard-disqualifies it. A pack that scores highly on keywords can still be selected even if its applies_to hints do not perfectly align with the current task.
4

Combine with strength

The agent combines the adjusted match score with the pack’s strength field to produce a final combined score:
combined_score = 0.6 * match_score + 0.4 * strength
If a pack does not have a strength field (e.g. a v0.1 pack), the agent treats it as neutral:
strength = 0.5  (default for packs without the field)
This means a strong-matched v0.1 pack can still rank well, while a v1.0-exp pack with explicit strength benefits from carrying that signal forward across sessions.
5

Scope-aware ranking

Packs are sorted using a three-level priority:
  1. Scope — task packs rank above project, which rank above user.
  2. Combined score — higher is better within the same scope.
  3. Recency — metrics.last_used_at (v1.0-exp) or index.updated_at (v0.1) breaks ties.
This ensures that the most specific, relevant, and recently confirmed pack rises to the top.
6

Select 1–3 active packs

The agent selects the top 1–3 packs from the ranked list.
  • If at least one pack has strong alignment, the agent may activate fewer packs to avoid noise.
  • If no pack has clear alignment, the agent prefers fewer packs over activating weakly matched ones.
Selected packs are merged into a unified set of signals: intent, constraints, preferences, workflow, failure traps, and success checks. Task pack signals override project pack signals, which override user pack signals.
7

Update metrics

After selecting active packs, the agent updates usage metrics for each selected pack:
  • metrics.times_applied — incremented by 1.
  • metrics.last_used_at — set to the current timestamp.
These updates are written back to the pack files. Over time, times_applied and last_used_at inform future scoring (via recency) and help identify strong candidates for promotion.
8

Explain to the user

The agent reports the result before starting work:
  • Which packs are active.
  • Their combined scores and strength values.
  • Key constraints and success checks currently in force.
This keeps scoring transparent and gives you the opportunity to override pack selection before the task begins.

​
The strength field

strength is a single scalar in [0, 1] that represents how reliably a pack’s pattern has worked. You or your agent set it when saving a pack, and it can be updated as the pack accumulates usage history.
Strength valueInterpretation
0.3Weak or tentative pattern — early signal, limited evidence
0.5Neutral — default for v0.1 packs or newly created packs
0.7Solid pattern — has worked reliably across multiple tasks
0.9+Very strong, highly trusted — use with high confidence
When saving a new pack from a clearly successful task, the recommended starting value is 0.7–0.8. Strength can be bumped upward when a pack is promoted from task to project scope.

​
Scoring formula

# Step 1: normalize raw keyword/pattern/tag overlap
match_score = normalize(keyword_overlap + pattern_overlap + tag_overlap)  # in [0, 1]

# Step 2: soft-adjust with applies_to
match_score = adjust(match_score, applies_to)  # boost or dampen, still in [0, 1]

# Step 3: combine with strength
combined_score = 0.6 * match_score + 0.4 * strength

# Step 4: rank
rank by: scope (task > project > user), then combined_score desc, then last_used_at desc

# Step 5: select top 1–3
active_packs = top_k(ranked_packs, k=3)

​
Backwards compatibility

v0.1 packs do not have applies_to, strength, or metrics. The agent handles them gracefully:
  • strength defaults to 0.5 — neutral, neither boosted nor penalized.
  • applies_to is skipped — only the base match score from keywords, patterns, and tags is used.
  • metrics.last_used_at falls back to index.updated_at for recency ranking.
This means v0.1 and v1.0-exp packs coexist in the same index and are ranked together without any manual migration required.

Agent compatibility

How agents choose which directory to install packs into

Setting up a repo

Wire AEP into any repository in three steps

Apply guide

Step-by-step guide to running aep apply

Schema reference

Full field definitions including applies_to, strength, and metrics

Build docs developers (and LLMs) love

Get started for freeTalk to us