Skip to main content
A project pack captures the cross-task conventions and constraints that apply broadly across a repository. Instead of repeating the same rules in every task pack, you encode them once at the project level — and the agent loads them automatically for every task it runs in that repo.

​
What project packs capture

Project packs encode the stable, repo-wide layer of your working style:
  • Cross-task constraints — rules that apply regardless of what kind of task is running (e.g. always use TypeScript strict mode, never introduce new third-party dependencies without discussion)
  • Code style preferences — formatting conventions, naming patterns, and structural preferences the entire codebase follows
  • Architectural preferences — how the project is structured and what patterns it uses (e.g. prefer composition over inheritance, keep API surface minimal)
  • Team conventions — shared expectations about how work should be done in this repo
Because the project pack applies to all tasks, keep it focused on things that are genuinely universal to the repo. Patterns that only apply to a specific task type belong in a task pack instead.

​
File location

There is exactly one project pack per repo, stored at: 
<agent-dir>/aep/project.aep.json
For example: 
.claude/aep/project.aep.json
.opencode/aep/project.aep.json
The <agent-dir> matches the agent you are using. The project pack is automatically discovered and loaded by the agent whenever it reads the AEP index.

​
How project pack constraints apply

When aep apply runs, the agent loads and merges signals from all relevant packs. The project pack’s signals form the baseline that applies to every task: 
user pack signals
  ↑ overridden by
project pack signals
  ↑ overridden by
task pack signals  ← highest priority
If a task pack defines a constraint that conflicts with the project pack, the task pack wins. This lets you set sensible defaults at the project level while still allowing task-specific exceptions.

​
Fields specific to project packs

​
scope

Always "project" — this identifies the pack as repo-wide in scope. 
"scope": "project"

​
applies_to

For a project pack, applies_to can reflect the technology stack and domain of the entire project: 
"applies_to": {
  "languages": ["typescript"],
  "frameworks": ["nextjs", "tailwind"],
  "paths": ["**"],
  "domains": ["frontend", "backend"]
}
Using "paths": ["**"] signals that the pack applies to all files in the repo.

​
strength

The project pack’s strength reflects how established and trusted the project-wide patterns are. A newly created project pack typically starts at 0.6. As the patterns prove reliable over time, the strength can be increased. 
"strength": 0.6

​
Template

This is the complete project pack template from the AEP source: 
{
  "version": "1.0-exp",
  "id": "project-defaults",
  "scope": "project",
  "title": "Project-wide defaults (experimental)",
  "status": "draft",
  "source": {
    "type": "successful_collaboration",
    "created_at": "2026-03-31T00:00:00Z",
    "confidence": 0.7
  },
  "match": {
    "keywords": [],
    "patterns": [],
    "tags": []
  },
  "applies_to": {
    "languages": [],
    "frameworks": [],
    "paths": [],
    "domains": []
  },
  "strength": 0.6,
  "intent": [
    "Capture project-wide preferences and constraints that apply across many tasks in this repo"
  ],
  "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 project-level AEP for this repo"
    }
  ],
  "merge_suggestions": [],
  "artifacts": {
    "examples": [],
    "notes": "Populate with cross-task constraints and preferences that have proven useful across multiple successful collaborations."
  }
}
The artifacts.notes field in the template is a plain text field for human-readable context. Use it to explain to future collaborators (or future agents) why specific constraints exist in this project pack.

​
When to update the project pack

Update the project pack when patterns that started as task-specific have proven to apply universally across the repo.
1

Recognize the pattern

After running aep inspect, look for constraints or preferences that appear in multiple task packs. If the same rule keeps showing up across different task types, it belongs at the project level.
2

Promote from a task pack

Tell the agent: "Use the AEP skill and promote the constraints from <task-pack-id> to the project pack." The agent extracts the relevant signals, adds them to project.aep.json, and records history entries in both packs.
3

Update the project pack directly

You can also edit project.aep.json directly when you have a new cross-task convention to encode. Add a history entry describing the change:
{
  "at": "2026-04-10T09:00:00Z",
  "event": "updated",
  "reason": "Added constraint to always run type checks before marking tasks complete"
}
4

Adjust strength over time

As project-wide patterns prove reliable across many tasks, increase the strength value toward 0.9 to signal higher trust to the agent’s ranking algorithm.

​
Override behavior

Task packs always override the project pack. This is by design — you can set broad rules at the project level and then carve out task-specific exceptions without touching the project pack. 
task pack: "constraints": ["Do not introduce CSS variables for this migration task"]
project pack: "constraints": ["Use CSS variables for all new styling"]
In this case, the task pack’s more specific constraint wins for that task type. All other tasks still pick up the project-level CSS variable rule.
Be careful about adding task-specific patterns to the project pack. If a constraint only makes sense for one type of task, it belongs in a task pack. Overly specific project-level constraints can create confusing conflicts.

Pack types overview

Understand all three scopes and how they work together.

Task packs

How task-level constraints override the project pack.

Promote guide

Step-by-step guide to promoting task patterns to project scope.

Schema reference

Full field reference for project pack fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us