Skip to main content
aep promote moves constraints and preferences that have proven their value at one scope up to a broader one. A pattern that worked for a specific task becomes a project-wide default; a collaboration style that you use consistently across projects becomes your user-level default.

​
What promotion means

AEP has three scopes, each broader than the last:
ScopeWhere storedWhat it covers
task<agent-dir>/aep/tasks/Patterns for a specific recurring task type
project<agent-dir>/aep/project.aep.jsonDefaults shared across all tasks in a repo
user<agent-dir>/aep/user.aep.jsonPersonal collaboration style across all projects
Promotion moves selected constraints and preferences up one level:
  • task → project: extract constraints and preferences that worked across multiple task runs
  • project → user: focus on collaboration style and high-level defaults
During apply, task packs override project packs, which override user packs. Promoted rules therefore set baselines that more specific packs can refine.

​
When to promote

Good candidates for promotion are packs with:
  • high times_applied — the pattern has been used repeatedly
  • recent last_used_at — it is still relevant, not stale
  • consistent positive outcomes — no accumulated failure_traps pointing to edge-case failures
You can also promote explicitly when you notice you are restating the same instruction across multiple task saves.

​
Example user phrases

"We've used this migration pattern several times; promote its rules to the project level."
"Take the collaboration style from these tasks and make it my user-level default AEP."

​
What the promote flow does

1

Inspect pack metrics

The agent reads metrics for all task-scoped packs and surfaces candidates ranked by:
  • times_applied (higher = stronger candidate)
  • last_used_at (more recent = more relevant)
It also reads history to understand how each pack has evolved and whether it has already been partially promoted.
2

Suggest candidates and confirm

The agent proposes which constraints and preferences to extract, and to which target scope. You review the suggestion and confirm (or adjust) before any files are written.If two task packs are similar — overlapping intent, keywords, and applies_to — the agent may also suggest merging them before promoting, to avoid duplicating rules in the target pack.
3

Update the target pack

On confirmation, the agent creates or updates the target pack (project.aep.json or user.aep.json) using "version": "1.0-exp", adding the promoted constraints and preferences.A history entry is appended to the target pack:
{
  "at": "2026-04-05T09:15:00Z",
  "event": "promoted",
  "reason": "Promoted constraint to avoid redesign without explicit request from task-html-to-nextjs"
}
4

Update the source pack

A matching history entry is also appended to the source pack so you can trace where each rule ended up:
{
  "at": "2026-04-05T09:15:00Z",
  "event": "updated",
  "reason": "Constraint promoted to project scope in project.aep.json"
}
5

Apply a strength boost

Rules that survive promotion have demonstrated value beyond their original context. The agent optionally bumps strength for the promoted rules in the target pack to reflect this higher confidence level.A rule that enters the project pack with strength: 0.7 might be recorded at strength: 0.85 in the project pack.
6

Record merge suggestions (if applicable)

If two source task packs are similar enough that they should be merged rather than separately promoted, the agent adds merge_suggestions entries to both packs pointing at each other:
{
  "target_id": "landing-page-migration",
  "reason": "Intent, constraints, and match metadata are highly similar."
}
These entries are cues for you to act on — the agent does not merge automatically.
Agents do not auto-merge packs. merge_suggestions entries are cues for human review or higher-level tooling. You decide when and how merges happen. This keeps packs auditable and prevents silent loss of information.

​
After promotion

Once rules are promoted to project scope, every future aep apply session in that repo will include them as a baseline — even for task types that do not have their own saved pack. User-scope promotions apply across all repos where the agent runs. To verify what is now active, run aep inspect.

aep inspect

Surface active packs, scores, and history

aep save

Save a successful workflow as a new pack

Project packs

Learn about project-scoped packs

User packs

Learn about user-scoped packs

Build docs developers (and LLMs) love

Get started for freeTalk to us