Pack schema reference

AEP packs are JSON files that capture reusable collaboration patterns between you and your agent. This page documents every field in the v1.0-exp pack schema.

v1.0-exp is an experimental extension of v0.1. All v0.1 fields remain valid. See Compatibility for guidance on mixing versions.

Complete example

{
  "version": "1.0-exp",
  "id": "html-to-nextjs-migration",
  "scope": "task",
  "title": "HTML to Next.js migration",
  "status": "approved",
  "source": {
    "type": "successful_collaboration",
    "created_at": "2026-03-31T10:00:00Z",
    "confidence": 0.91
  },
  "match": {
    "keywords": ["html", "nextjs", "migration", "template"],
    "patterns": [
      "convert static html to nextjs",
      "preserve design while migrating frontend"
    ],
    "tags": ["frontend", "migration", "nextjs", "html"]
  },
  "applies_to": {
    "languages": ["typescript"],
    "frameworks": ["nextjs"],
    "paths": ["app/**", "pages/**"],
    "domains": ["frontend"]
  },
  "strength": 0.9,
  "intent": [],
  "constraints": [],
  "preferences": [],
  "workflow": [],
  "failure_traps": [],
  "success_checks": [],
  "metrics": {
    "times_applied": 3,
    "first_used_at": "2026-04-01T10:00:00Z",
    "last_used_at": "2026-04-10T15:30:00Z",
    "avg_turns_saved": 6.0
  },
  "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"
    }
  ],
  "merge_suggestions": [
    {
      "target_id": "landing-page-migration",
      "reason": "Very similar intent and constraints; consider merging packs."
    }
  ],
  "artifacts": {
    "examples": [],
    "notes": "Use this pack when preserving fidelity matters more than architectural cleanup."
  }
}

Field reference

Top-level fields

version

string

required

Schema version. Always "1.0-exp" for experimental packs. Use "0.1" for packs that do not use any experimental fields.

string

required

Unique slug identifier for this pack. Use kebab-case. This id is referenced by index.json and by merge_suggestions in other packs.Example: "html-to-nextjs-migration"

scope

string

required

Declares which level this pack operates at. One of:

"task" — applies to a specific recurring task type.
"project" — project-wide defaults and constraints.
"user" — user collaboration style that travels between repos.

title

string

required

Human-readable title displayed when the agent reports active packs.Example: "HTML to Next.js migration"

status

string

Lifecycle status of the pack. One of:

"draft" — work in progress, not yet trusted for automatic application.
"approved" — reviewed and trusted.

source

object

Provenance metadata describing how this pack was created.

Show properties

source.type

string

How the pack was generated. Typically "successful_collaboration".

source.created_at

string

ISO 8601 timestamp of when the pack was first created.Example: "2026-03-31T10:00:00Z"

source.confidence

number

Initial confidence score in [0, 1] representing how reliable the source collaboration was. Higher values indicate stronger evidence.Example: 0.91

match

object

Signals used by the agent to decide whether this pack is relevant to the current task.

Show properties

match.keywords

string[]

Individual words that indicate this pack may be relevant.Example: ["html", "nextjs", "migration", "template"]

match.patterns

string[]

Short natural-language phrases describing the task this pack targets.Example: ["convert static html to nextjs", "preserve design while migrating frontend"]

match.tags

string[]

Category labels for grouping and filtering packs.Example: ["frontend", "migration", "nextjs", "html"]

applies_to

object

(v1.0-exp, recommended) Contextual hints that help the agent decide how well this pack fits the current repo and task. Agents treat these as soft filters — they boost or dampen scores but do not hard-disqualify a pack.

Show properties

applies_to.languages

string[]

Programming language names this pack is most relevant to.Example: ["typescript"]

applies_to.frameworks

string[]

Framework names this pack targets.Example: ["nextjs", "django", "rails"]

applies_to.paths

string[]

Glob-like path hints indicating which parts of the repo this pack applies to.Example: ["app/**", "pages/**", "src/api/**"]

applies_to.domains

string[]

High-level domain labels.Example: ["frontend", "backend", "infra", "data"]

strength

number

(v1.0-exp) A single scalar in [0, 1] representing how strongly this pack encodes a proven pattern.Interpretation:

0.3 — weak or tentative pattern.
0.7 — solid pattern that has worked multiple times.
0.9+ — very strong, highly trusted pattern.

Agents combine this with the task-specific match score: combined_score = f(match_score, strength).

intent

string[]

Short statements describing what this pack is trying to achieve.

constraints

string[]

Hard rules the agent must follow while this pack is active. Violations indicate the pack is being misapplied.

preferences

string[]

Soft preferences — the agent should follow these unless a strong reason not to exists.

workflow

string[]

Ordered or unordered steps describing the recommended workflow for this task type.

failure_traps

string[]

Known failure modes and anti-patterns to avoid when applying this pack.

success_checks

string[]

Conditions to verify before considering the task complete. The agent can use these as a checklist.

metrics

object

(v1.0-exp) Simple usage counters and timestamps. Agents may update these after each aep apply.

Show properties

metrics.times_applied

integer

How many times this pack has been actively applied to tasks.

metrics.first_used_at

string

ISO 8601 timestamp of the first time this pack was applied.Example: "2026-04-01T10:00:00Z"

metrics.last_used_at

string

ISO 8601 timestamp of the most recent application. Used for recency ranking.Example: "2026-04-10T15:30:00Z"

metrics.avg_turns_saved

number

Rough estimate of how many back-and-forth messages this pack saves on average.Example: 6.0

history

array

(v1.0-exp) Ordered log of meaningful changes to this pack. Each entry records what changed and why.

Show entry properties

history[].at

string

ISO 8601 timestamp of when the event occurred.Example: "2026-04-05T09:15:00Z"

history[].event

string

Type of event. Common values: "created", "updated", "promoted", "merged".

history[].reason

string

Short human-readable explanation of why the change was made.Example: "Promoted constraint to avoid redesign without explicit request"

merge_suggestions

array

(v1.0-exp) Hints that this pack overlaps with another and the two may be candidates for merging. Agents should not auto-merge based on these; they are cues for human review.

Show entry properties

merge_suggestions[].target_id

string

The id of the other pack that this pack potentially overlaps with.Example: "landing-page-migration"

merge_suggestions[].reason

string

Short explanation of why the merge might make sense.Example: "Very similar intent and constraints; consider merging packs."

artifacts

object

Supporting evidence and notes attached to this pack.

Show properties

artifacts.examples

string[]

Links or references to example files or run transcripts that illustrate this pack in action.

artifacts.notes

string

Free-text notes for human readers.Example: "Use this pack when preserving fidelity matters more than architectural cleanup."

Index schema reference

Field reference for the index.json file that tracks all packs.

Templates

Ready-to-use JSON templates for all three pack scopes.

Schema

Prompt Patterns

Complete example

Field reference

Top-level fields

Index schema reference

Templates

Build docs developers (and LLMs) love

Schema

Prompt Patterns

​Complete example

​Field reference

​Top-level fields

​Related pages

Index schema reference

Templates

Build docs developers (and LLMs) love

Complete example

Field reference

Top-level fields

Related pages