Skip to main content
A task pack captures everything that made a specific type of collaboration successful: the intent behind the task, the constraints to enforce, the workflow to follow, and the failure traps to avoid. When you run the same kind of task again, the agent starts with all of that already loaded — no re-explaining required.

​
What task packs capture

Task packs encode the full pattern of a recurring task type:
  • Intent — what the task is trying to achieve and what success looks like
  • Constraints — hard rules the agent must respect (e.g. do not redesign, reuse existing CSS)
  • Preferences — softer style or approach preferences (e.g. prefer composition over abstraction)
  • Workflow — the ordered sequence of steps that worked well
  • Failure traps — common mistakes to avoid for this task type
  • Success checks — criteria to verify before declaring the task done

​
File location

Each task pack is a standalone JSON file stored inside the tasks/ subdirectory: 
<agent-dir>/aep/tasks/<id>.aep.json
For example: 
.claude/aep/tasks/html-to-nextjs-migration.aep.json
.opencode/aep/tasks/api-endpoint-refactor.aep.json
Use a descriptive slug for the filename that reflects what the task actually does — not a generic label. html-to-nextjs-migration is better than migration-task because it tells you exactly when to reach for that pack.

​
Naming convention

The pack id and filename should be a lowercase hyphen-separated slug that describes the specific task type: 
html-to-nextjs-migration
api-endpoint-refactor
landing-page-copy
backend-service-extraction
Avoid generic names like task-1 or refactor. The name is how agents and humans alike identify when a pack is relevant.

​
Fields specific to task packs

​
match

The match object is how agents discover whether a task pack is relevant: 
"match": {
  "keywords": ["html", "nextjs", "migration", "template"],
  "patterns": [
    "convert static html to nextjs",
    "preserve design while migrating frontend"
  ],
  "tags": ["frontend", "migration", "nextjs", "html"]
}
  • keywords — individual terms the agent looks for in the task description
  • patterns — natural-language phrases that describe the task intent
  • tags — broader labels used for filtering and grouping

​
applies_to

The applies_to object provides structured hints about when this pack is most relevant: 
"applies_to": {
  "languages": ["typescript"],
  "frameworks": ["nextjs"],
  "paths": ["app/**", "pages/**"],
  "domains": ["frontend"]
}
Agents treat these as soft filters. A pack can still apply even if only some fields match.

​
strength

A scalar from 0 to 1 that represents how well-established this task pattern is:
ValueMeaning
0.3Weak or tentative — only tried once or twice
0.7Solid — has worked consistently multiple times
0.9+Very strong — highly trusted, battle-tested

​
How matching works

When you run aep apply, the agent computes a match score for each task pack using:
  1. Keyword and tag overlap between the task description and the pack’s match fields
  2. applies_to signals — language, framework, path, and domain alignment
  3. strength — combined with the match score to produce a final ranking score:
combined_score = f(match_score, pack.strength)
Task packs are ranked above project and user packs by scope, then sorted by final score, then by recency (metrics.last_used_at).

​
Template

This is the complete task pack template from the AEP source: 
{
  "version": "1.0-exp",
  "id": "generic-task-pattern-exp",
  "scope": "task",
  "title": "Generic task pattern (experimental)",
  "status": "draft",
  "source": {
    "type": "successful_collaboration",
    "created_at": "2026-03-31T00:00:00Z",
    "confidence": 0.5
  },
  "match": {
    "keywords": [],
    "patterns": [],
    "tags": []
  },
  "applies_to": {
    "languages": [],
    "frameworks": [],
    "paths": [],
    "domains": []
  },
  "strength": 0.5,
  "intent": [
    "Capture a reusable pattern for a recurring task so future runs start aligned, with experimental metadata for better ranking and evolution"
  ],
  "constraints": [],
  "preferences": [],
  "workflow": [],
  "failure_traps": [],
  "success_checks": [],
  "metrics": {
    "times_applied": 0,
    "first_used_at": "2026-03-31T00:00:00Z",
    "last_used_at": "2026-03-31T00:00:00Z",
    "avg_turns_saved": 0
  },
  "history": [
    {
      "at": "2026-03-31T00:00:00Z",
      "event": "created",
      "reason": "Initial experimental generic task AEP template"
    }
  ],
  "merge_suggestions": [],
  "artifacts": {
    "examples": [],
    "notes": "Use this as a starting point for any task type. Fill in match fields, applies_to, signals, and checks after a specific successful collaboration."
  }
}

​
When to create a task pack vs reuse an existing one

Create a new task pack when:
  • You are doing a type of task you have not done before with this agent
  • The task has specific constraints that don’t exist in any current pack
  • A completed task produced noticeably better results than usual, and you want to capture why
  • The task type is recurring — you expect to run it again in future sessions
Tell the agent: "Use the AEP skill and save this collaboration as <slug>."

​
Promoting task packs to project scope

When a task pack’s constraints start showing up repeatedly across different tasks in the same repo, it is a signal that those constraints belong at the project level.
1

Identify the pattern

Use aep inspect to review which task packs have high metrics.times_applied values and which constraints appear in multiple packs.
2

Promote to project scope

Tell the agent: "Use the AEP skill and promote the constraints from <pack-id> to the project pack." The agent moves the relevant signals to project.aep.json and adds history entries to both packs recording the promotion event.
3

Update the task pack

After promotion, the task pack can remove the promoted constraints or keep them as task-specific overrides if needed. Task-level values always override project-level values.
After promoting, the task pack’s strength should reflect only the task-specific patterns that remain — not the broader constraints that moved to the project pack.

Pack types overview

Understand all three scopes and how they work together.

Project packs

What happens after you promote task patterns to project scope.

Save guide

Step-by-step guide to saving a task pack after a successful collaboration.

Schema reference

Full field reference for all task pack fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us