ACP Primer

AI Context Protocol primer definition for AI context bootstrapping

Type object
File match primer.json *.primer.json primer.defaults.json
Schema URL https://catalog.lintel.tools/schemas/schemastore/acp-primer/latest.json
Source https://acp-protocol.dev/schemas/v1/primer.schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Defines the structure for AI context primers - the bootstrapping layer that teaches AI systems about ACP

Properties

version string required

Primer schema version (semver)

Examples: "1.0.0"
pattern=^\d+\.\d+\.\d+
sections section[] required

All available primer sections

$schema string

Reference to this schema

metadata object
7 nested properties
name string

Human-readable name for this primer definition

description string

Purpose and scope of this primer

author string

Author or organization

license string

License for this primer definition

minAcpVersion string

Minimum ACP CLI version required

pattern=^\d+\.\d+\.\d+
created string

When this primer definition was created

format=date-time
updated string

When this primer definition was last updated

format=date-time
capabilities Record<string, object>

Registry of tool capabilities that sections can require

Examples: {"shell":{"id":"shell","name":"Shell Execution","description":"Can execute shell/terminal commands","tools":["cursor","claude-code","aider","cline","windsurf"]},"mcp":{"id":"mcp","name":"Model Context Protocol","description":"Supports MCP tool integration","tools":["claude-code","continue","cline"]},"file-read":{"id":"file-read","name":"File System Read","description":"Can read files from the filesystem","tools":["cursor","claude-code","copilot","continue","cline","windsurf"]},"file-write":{"id":"file-write","name":"File System Write","description":"Can write/modify files","tools":["cursor","claude-code","aider","cline","windsurf"]},"http":{"id":"http","name":"HTTP Requests","description":"Can make HTTP requests to APIs","tools":["claude-code","cline"]}}
categories category[]

Section categories with metadata

selectionStrategy object

Configuration for how sections are selected within budget

7 nested properties
algorithm string

Selection algorithm

Default: "value-optimized"
Values: "priority-ordered" "value-optimized" "category-balanced" "custom"
weights object

Weights for multi-dimensional value calculation

4 nested properties
safety number

Weight for safety dimension

Default: 1.5
min=0
efficiency number

Weight for efficiency dimension

Default: 1.0
min=0
accuracy number

Weight for accuracy dimension

Default: 1.0
min=0
base number

Weight for base value

Default: 1.0
min=0
presets Record<string, object>

Named weight presets (e.g., 'safe', 'efficient', 'balanced')

phases selectionPhase[]

Selection phases in order

minimumBudget integer

Minimum tokens required (for required sections)

Default: 80
min=50
categoryConstraints Record<string, object>

Per-category budget constraints

dynamicModifiersEnabled boolean

Whether to evaluate dynamic value modifiers

Default: true
outputFormats object

Global output format configurations

3 nested properties
markdown object
4 nested properties
sectionSeparator string
Default: " "
headerLevel integer
Default: 2
min=1max=6
listStyle string
Default: "bullet"
Values: "bullet" "number" "dash"
codeBlockStyle string
Default: "fenced"
Values: "fenced" "indented"
compact object
3 nested properties
sectionSeparator string
Default: " | "
maxLineLength integer
Default: 120
abbreviate boolean
Default: true
json object
3 nested properties
pretty boolean
Default: false
includeMetadata boolean
Default: true
includeTokenCounts boolean
Default: true
knowledgeStore object

Configuration for the ACP knowledge base

5 nested properties
enabled boolean

Whether knowledge store features are enabled

Default: true
indexPath string

Path to keyword/tag index

Default: "~/.acp/knowledge/index.json"
semanticDbPath string

Path to optional vector database

Default: "~/.acp/knowledge/semantic.db"
fallbackToIndex boolean

Fall back to keyword index if semantic DB unavailable

Default: true
sections knowledgeSection[]

Knowledge content sections

Definitions

metadata object
name string

Human-readable name for this primer definition

description string

Purpose and scope of this primer

author string

Author or organization

license string

License for this primer definition

minAcpVersion string

Minimum ACP CLI version required

pattern=^\d+\.\d+\.\d+
created string

When this primer definition was created

format=date-time
updated string

When this primer definition was last updated

format=date-time
capabilitiesRegistry Record<string, object>

Registry of tool capabilities that sections can require

Examples:
  • { "shell": { "id": "shell", "name": "Shell Execution", "description": "Can execute shell/terminal commands", "tools": [ "cursor", "claude-code", "aider", "cline", "windsurf" ] }, "mcp": { "id": "mcp", "name": "Model Context Protocol", "description": "Supports MCP tool integration", "tools": [ "claude-code", "continue", "cline" ] }, "file-read": { "id": "file-read", "name": "File System Read", "description": "Can read files from the filesystem", "tools": [ "cursor", "claude-code", "copilot", "continue", "cline", "windsurf" ] }, "file-write": { "id": "file-write", "name": "File System Write", "description": "Can write/modify files", "tools": [ "cursor", "claude-code", "aider", "cline", "windsurf" ] }, "http": { "id": "http", "name": "HTTP Requests", "description": "Can make HTTP requests to APIs", "tools": [ "claude-code", "cline" ] } }
capability object
id string required

Unique capability identifier

pattern=^[a-z][a-z0-9-]*$
name string required

Human-readable name

description string

What this capability enables

tools string[]

Tools that have this capability

detectCommand string

Optional command to detect capability at runtime

category object
id string required

Unique category identifier

pattern=^[a-z][a-z0-9-]*$
name string required

Human-readable category name

description string

What this category covers

priority integer

Category-level priority (lower = higher priority)

min=1max=100
color string

Color for CLI visualization

pattern=^#[0-9a-fA-F]{6}$
icon string

Emoji or icon for display

budgetConstraints object
4 nested properties
minimum integer

Minimum tokens to allocate to this category

min=0
maximum integer

Maximum tokens to allocate to this category

min=0
minimumPercent number

Minimum percentage of budget for this category

min=0max=100
maximumPercent number

Maximum percentage of budget for this category

min=0max=100
section object
id string required

Unique section identifier

pattern=^[a-z][a-z0-9-]*$
category string required

Category this section belongs to

tokens integer | const: "dynamic" required

Token cost for this section

value object required

Multi-dimensional value scoring for section selection

5 nested properties
safety integer

How critical for preventing harmful AI actions (0-100)

Default: 0
min=0max=100
efficiency integer

How much it saves future tokens/queries (0-100)

Default: 0
min=0max=100
accuracy integer

How much it improves response quality (0-100)

Default: 0
min=0max=100
base integer

Baseline value independent of dimensions (0-100)

Default: 50
min=0max=100
modifiers valueModifier[]

Dynamic modifiers based on project state

formats Record<string, object> required

Output templates for different formats (at least one format required)

4 nested properties
markdown object
7 nested properties
template string

Handlebars template string

header string

Header text before items (for list sections)

footer string

Footer text after items

itemTemplate string

Template for each item in a list

separator string

Separator between items

Default: " "
emptyTemplate string

Template when no items

wrapWith object

Wrap entire output

compact object
7 nested properties
template string

Handlebars template string

header string

Header text before items (for list sections)

footer string

Footer text after items

itemTemplate string

Template for each item in a list

separator string

Separator between items

Default: " "
emptyTemplate string

Template when no items

wrapWith object

Wrap entire output

json null | formatTemplate
text object
7 nested properties
template string

Handlebars template string

header string

Header text before items (for list sections)

footer string

Footer text after items

itemTemplate string

Template for each item in a list

separator string

Separator between items

Default: " "
emptyTemplate string

Template when no items

wrapWith object

Wrap entire output

name string

Human-readable section name

description string

What this section provides to the AI

priority integer

Section priority within category (lower = higher priority)

min=1max=1000
required boolean

Always include regardless of budget optimization

Default: false
requiredIf string

Condition expression that makes this section required

capabilities string[]

Required capabilities (ANY of these)

capabilitiesAll string[]

Required capabilities (ALL of these)

dependsOn string[]

Section IDs that must be included before this one. Warning: circular references must be prevented by implementation

conflictsWith string[]

Section IDs that cannot be included with this one. Warning: self-references should be prevented by implementation

replaces string[]

Section IDs that this section supersedes

since string

ACP version that introduced this section

pattern=^\d+\.\d+\.\d+
deprecated object

Deprecation info if section is deprecated

3 nested properties
since string
message string
replacedBy string
data object

Data source configuration for dynamic sections

9 nested properties
source string required

Data path (e.g., 'cache.constraints.by_lock_level', 'vars.variables')

fields string[]

Fields to extract from each item

filter string[] | object
sortBy string

Field to sort by

sortOrder string
Default: "desc"
Values: "asc" "desc"
maxItems integer

Maximum number of items to include

min=1
itemTokens integer

Estimated tokens per item (for budget calculation)

min=1
emptyBehavior string

What to do when data source is empty

Default: "exclude"
Values: "exclude" "placeholder" "error"
placeholderText string

Text to show if emptyBehavior is 'placeholder'

tags string[]

Tags for filtering and searching sections

sectionValue object

Multi-dimensional value scoring for section selection

safety integer

How critical for preventing harmful AI actions (0-100)

Default: 0
min=0max=100
efficiency integer

How much it saves future tokens/queries (0-100)

Default: 0
min=0max=100
accuracy integer

How much it improves response quality (0-100)

Default: 0
min=0max=100
base integer

Baseline value independent of dimensions (0-100)

Default: 50
min=0max=100
modifiers valueModifier[]

Dynamic modifiers based on project state

valueModifier object

Conditional modifier that adjusts section value based on project state

condition string required

Expression evaluated against project state (e.g., 'hacks.count > 0')

add integer

Add this amount to final score

multiply number

Multiply final score by this amount

min=0
set integer

Override score to this value

min=0
dimension string

Which dimension(s) to modify

Default: "all"
Values: "safety" "efficiency" "accuracy" "base" "all"
reason string

Human-readable explanation for this modifier

sectionData object

Data source configuration for dynamic sections

source string required

Data path (e.g., 'cache.constraints.by_lock_level', 'vars.variables')

fields string[]

Fields to extract from each item

filter string[] | object
sortBy string

Field to sort by

sortOrder string
Default: "desc"
Values: "asc" "desc"
maxItems integer

Maximum number of items to include

min=1
itemTokens integer

Estimated tokens per item (for budget calculation)

min=1
emptyBehavior string

What to do when data source is empty

Default: "exclude"
Values: "exclude" "placeholder" "error"
placeholderText string

Text to show if emptyBehavior is 'placeholder'

sectionFormats Record<string, object>

Output templates for different formats (at least one format required)

markdown object
7 nested properties
template string

Handlebars template string

header string

Header text before items (for list sections)

footer string

Footer text after items

itemTemplate string

Template for each item in a list

separator string

Separator between items

Default: " "
emptyTemplate string

Template when no items

wrapWith object

Wrap entire output

2 nested properties
before string
after string
compact object
7 nested properties
template string

Handlebars template string

header string

Header text before items (for list sections)

footer string

Footer text after items

itemTemplate string

Template for each item in a list

separator string

Separator between items

Default: " "
emptyTemplate string

Template when no items

wrapWith object

Wrap entire output

2 nested properties
before string
after string
json null | formatTemplate
text object
7 nested properties
template string

Handlebars template string

header string

Header text before items (for list sections)

footer string

Footer text after items

itemTemplate string

Template for each item in a list

separator string

Separator between items

Default: " "
emptyTemplate string

Template when no items

wrapWith object

Wrap entire output

2 nested properties
before string
after string
formatTemplate object
template string

Handlebars template string

header string

Header text before items (for list sections)

footer string

Footer text after items

itemTemplate string

Template for each item in a list

separator string

Separator between items

Default: " "
emptyTemplate string

Template when no items

wrapWith object

Wrap entire output

2 nested properties
before string
after string
selectionStrategy object

Configuration for how sections are selected within budget

algorithm string

Selection algorithm

Default: "value-optimized"
Values: "priority-ordered" "value-optimized" "category-balanced" "custom"
weights object

Weights for multi-dimensional value calculation

4 nested properties
safety number

Weight for safety dimension

Default: 1.5
min=0
efficiency number

Weight for efficiency dimension

Default: 1.0
min=0
accuracy number

Weight for accuracy dimension

Default: 1.0
min=0
base number

Weight for base value

Default: 1.0
min=0
presets Record<string, object>

Named weight presets (e.g., 'safe', 'efficient', 'balanced')

phases selectionPhase[]

Selection phases in order

minimumBudget integer

Minimum tokens required (for required sections)

Default: 80
min=50
categoryConstraints Record<string, object>

Per-category budget constraints

dynamicModifiersEnabled boolean

Whether to evaluate dynamic value modifiers

Default: true
dimensionWeights object

Weights for multi-dimensional value calculation

safety number

Weight for safety dimension

Default: 1.5
min=0
efficiency number

Weight for efficiency dimension

Default: 1.0
min=0
accuracy number

Weight for accuracy dimension

Default: 1.0
min=0
base number

Weight for base value

Default: 1.0
min=0
selectionPhase object

A phase in the section selection process

name string required

Phase name for logging/debugging

filter object

Filter criteria for sections in this phase

6 nested properties
required boolean
requiredIf boolean
safetyMinimum integer
categories string[]
tags string[]
custom string
sort string
Default: "value-per-token"
Values: "priority" "value" "value-per-token" "safety" "random"
budgetPercent number

Maximum percentage of budget for this phase

min=0max=100
outputFormats object

Global output format configurations

markdown object
4 nested properties
sectionSeparator string
Default: " "
headerLevel integer
Default: 2
min=1max=6
listStyle string
Default: "bullet"
Values: "bullet" "number" "dash"
codeBlockStyle string
Default: "fenced"
Values: "fenced" "indented"
compact object
3 nested properties
sectionSeparator string
Default: " | "
maxLineLength integer
Default: 120
abbreviate boolean
Default: true
json object
3 nested properties
pretty boolean
Default: false
includeMetadata boolean
Default: true
includeTokenCounts boolean
Default: true
knowledgeStore object

Configuration for the ACP knowledge base

enabled boolean

Whether knowledge store features are enabled

Default: true
indexPath string

Path to keyword/tag index

Default: "~/.acp/knowledge/index.json"
semanticDbPath string

Path to optional vector database

Default: "~/.acp/knowledge/semantic.db"
fallbackToIndex boolean

Fall back to keyword index if semantic DB unavailable

Default: true
sections knowledgeSection[]

Knowledge content sections

knowledgeSection object
id string required

Knowledge section identifier

content string required

Knowledge content (markdown)

title string

Section title

tags string[]

Searchable tags

keywords string[]

Keywords for index lookup

relatedSections string[]

Related knowledge section IDs

sourceFile string

Source documentation file