Config Reference

Every field in .ai/config.yaml -- generated by /dx-init, extended by /aem-init

Migration Note: project.yaml Deprecated

The .ai/project.yaml file is deprecated. Its fields have been absorbed into config.yaml under project:, toolchain:, and build: sections. Run /dx-upgrade to migrate automatically. The seed data file .ai/project/project.yaml is NOT affected.

Overview

Config File

All skills read .ai/config.yaml at runtime. Never hardcode project-specific values.

Generated by

/dx-init creates the base file. /aem-init appends the aem: section.

Override Precedence

.ai/rules/ > config.yaml overrides: > plugin defaults

Config-Driven

Build commands, branch names, URLs, paths — all read from config. Zero hardcoded values.

Required

project

Project identity

Field	Type	Required	Description
`name`	string	yes	Human-readable project name
`prefix`	string	yes	Short prefix used in naming conventions
`type`	string	yes	Project type detected by `/dx-adapt` (e.g., `aem-fullstack`, `aem-frontend`, `frontend`, `java`)
`role`	string	yes	Repo role: `frontend` \| `backend` \| `fullstack` \| `config`. Determines which AEM rule templates are installed.

Example

project:
name: "My Project"
prefix: "myproject"
type: aem-fullstack
role: fullstack

Required

scm

Source control and wiki configuration

Field	Type	Required	Description
`provider`	string	yes	`ado` or `github`
`org`	string	yes	Organization URL
`project`	string	yes	Project name within the org
`repo-id`	string	no	Repository UUID (auto-discovered if not set)
`base-branch`	string	yes	Default PR target (e.g., `develop`, `main`)
`wiki-id`	string	no	ADO wiki identifier UUID (for `/dx-doc-gen`, `/dx-pr-review-report`)
`wiki-project`	string	no	ADO project that owns the wiki (if different from `scm.project`)
`wiki-doc-root`	string	no	Root wiki path for technical documentation (sprint subfolders created beneath)
`wiki-pr-review-root`	string	no	Root wiki path for PR review reports
`wiki-dor-url`	string	yes	Full URL to the DoR wiki page — `/dx-req` fetches checklist from here
`wiki-dod-url`	string	yes	Full URL to the DoD wiki page — `/dx-req-dod` fetches checklist from here

Optional

tracker

Work item tracking provider override

Field	Type	Required	Description
`provider`	string	no	`ado` or `jira`. Preferred over `scm.provider` for work item tracking. Falls back to `scm.provider` if not set.

Jira

jira + confluence

Required when tracker.provider is jira

Field	Type	Required	Description
`jira.url`	string	yes (if jira)	Jira Cloud instance URL
`jira.project-key`	string	yes (if jira)	Jira project key (e.g., `MYPROJ`)
`confluence.url`	string	no	Confluence Cloud URL
`confluence.space-key`	string	no	Default Confluence space key

Required

build

Build and test commands

Field	Type	Required	Description
`command`	string	yes	Full build command
`test`	string	yes	Test execution command
`serve`	string	no	Dev server command
`lint-js`	string	no	JavaScript lint command
`lint-scss`	string	no	SCSS lint command
`lint-css`	string	no	CSS lint command
`lint-fix`	string	no	Auto-fix lint issues command

Example

build:
command: "mvn clean install"
test: "mvn test"
serve: "npm run dev"
lint-js: "npm run lint:js"
lint-scss: "npm run lint:scss"
lint-fix: "npm run lint:fix"

Optional

toolchain

Build stack details -- auto-detected by /dx-adapt

Field	Type	Description
`node`	string	Node.js runtime version (e.g., `18.0.0`)
`build-tool`	string	`webpack` \| `gulp4` \| `vite` \| `rollup`
`css-compiler`	string	`dart-sass` \| `node-sass`
`js-transpiler`	string	`babel` \| `esbuild` \| `tsc`
`template-engine`	string	`htl` \| `jsx` (consumer may add others)
`component-base-class`	string	Framework base class name
`module-system`	string	`esm` \| `iife` \| `cjs`

Example

toolchain:
node: "18.0.0"
build-tool: webpack
css-compiler: dart-sass
js-transpiler: babel
template-engine: htl
component-base-class: "BaseComponent"
module-system: esm

Auto-Detection

/dx-adapt detects these values from package.json, .nvmrc, webpack.config.js, and other project files. All fields are optional — only set what /dx-adapt can discover.

Optional

markets + repos

Multi-market support and cross-repo awareness

markets

Field	Type	Description
`brand`	string	Brand name
`countries`	list	Country codes for this brand

repos

Field	Type	Description
`name`	string	Repository name
`path`	string	Relative path to local checkout
`role`	string	`backend`, `frontend`, `fullstack`, or `config`
`platform`	string	`Legacy` or `DXN` (AEM only, added by `/aem-init`)
`ado-project`	string	ADO project (if different from `scm.project`)
`base-branch`	string	Default branch (defaults to `scm.base-branch`)
`capabilities`	list	Rule templates for sync (auto-detected if omitted)

Example

repos:
- name: My-Backend-Repo
  path: ../My-Backend-Repo
  role: backend
  platform: Legacy
  base-branch: develop
  capabilities: [fe, be, sling]

Optional

preferences + overrides

Behavior customization without replacing plugin files

preferences

Field	Type	Default	Description
`auto_commit`	bool	false	Commit after each step without asking
`auto_pr`	bool	false	Create PR after all steps complete

overrides

Override	Fields	Affects
`pr-review`	`tone`, `severity-threshold`, `extra-rules`	`/dx-pr-review`, `/dx-pr-review-all`
`pr-answer`	`persona`	`/dx-pr-answer`

Example

overrides:
pr-review:
  tone: "direct, no praise"
  severity-threshold: 80
  extra-rules: |
    - Check for CSS custom properties over hardcoded values
    - Flag console.log left in code
pr-answer:
  persona: "senior developer, brief responses"

AEM

aem

Added by /aem-init -- AEM project configuration

Field	Type	Required	Description
`component-path`	string	yes	JCR path to component definitions
`component-prefix`	string	yes	Component naming prefix
`component-group`	string	no	Default componentGroup value
`resource-type-pattern`	string	yes	Resource type template (`<name>` is replaced)
`java-package`	string	no	Java package root
`frontend-dir`	string	no	Frontend source directory
`brands`	list	no	Brand names for multi-brand projects
`content-paths`	list	no	AEM content paths to search
`author-url`	string	no	Local AEM author URL (default: `http://localhost:4502`)
`author-url-qa`	string	no	Remote QA author URL — for clickable links in output
`publish-url`	string	no	Local AEM publisher URL (default: `http://localhost:4503`)
`publish-url-qa`	string	no	Remote QA publisher URL
`demo-parent-path`	string	no	Parent path for all AI-created demo pages
`selector`	string	no	Exporter selector for JSON endpoints
`current-repo`	string	no	Current repo name (for cross-repo scope detection)
`platform`	string	no	`legacy` (custom Web Components/Gulp) or `dxn` (@netcentric/Webpack)
`active-brands`	list	no	Active brands (scopes component and page searches)
`active-markets`	list	no	Active markets with brand + countries (scopes searches)
`qa-basic-auth`	object	no	QA/Stage HTTP Basic Auth credentials (`username`, `password`). Used by `aem-editorial-guide-capture` and `aem-doc-gen`.

Optional

roles

Agent role configuration

Role	Fields	Description
`re-agent`	`enabled`, `output-format`	Requirements Engineering agent. Output format: `json` or `markdown`.
`qa-agent`	`enabled`, `canModifyCode`, `requiresAEM`, `bugPolicy`	QA agent. `bugPolicy.onlyFor` restricts bug types. `requiresHumanConfirmation` gates bug creation.

Example

roles:
re-agent:
  enabled: true
  output-format: json
qa-agent:
  enabled: true
  canModifyCode: false
  requiresAEM: true
  bugPolicy:
    onlyFor: "ui-functional"
    requiresHumanConfirmation: true

Automation

Pipeline Environment Variables

Set on ADO pipeline runs, NOT part of config.yaml

Not Config Fields

These environment variables are set on ADO pipeline runs and read by skills at runtime. They are separate from .ai/config.yaml.

All CLI Pipelines

Variable	Description
`DX_PIPELINE_MODE`	Set to `“true”` in all CLI pipelines. Enables cross-repo delegation and pipeline-only behaviors.
`ANTHROPIC_API_KEY`	Claude API key for Claude Code CLI authentication.
`ADO_ORG_URL`	ADO org URL. Used for plugin marketplace auth and cross-repo delegation.
`ADO_ORG_NAME`	Short ADO org name. Read by `pipeline-agent.js` for org identification.
`DX_MARKETPLACE_URL`	Git URL with ref for the plugin marketplace repo. Only used when `dx-aem-flow/` is not available locally.

Code-Writing Pipelines (BugFix, DevAgent, DoD-Fix)

Variable	Description
`SOURCE_REPO_NAME`	Set to `$(Build.Repository.Name)`. Skills compare against cross-repo scope to decide delegation.
`CROSS_REPO_PIPELINE_MAP`	JSON mapping repo names to pipeline IDs. Used by the delegation YAML step.

Auto

Learning Directory

Auto-generated by coordinator skills -- no config needed

.ai/learning/

Coordinator skills automatically create this directory to store run metrics and patterns. Promoted patterns are written to .claude/rules/learned-fix-*.md — auto-loaded on every future run. No config is needed — the directory is created on first coordinator run.

Directory structure

.ai/learning/
├── fixes.md                    # Aggregated fix patterns
├── review-issues.md            # Aggregated review findings
├── patterns.md                 # Build error catalog
├── conventions-discovered.md   # Discovered conventions
├── metrics.md                  # Execution metrics summary
├── retro/
│   └── YYYY-WNN-summary.md    # Weekly retrospective
└── raw/                        # .gitignored
  ├── runs.jsonl              # Run records from coordinators
  ├── fixes.jsonl             # Fix patterns from dx-step-all
  ├── bugs.jsonl              # Bug patterns from dx-bug-all
  └── review-issues.jsonl     # Review findings from dx-step-verify

Promotion Flow

Raw signals in .ai/learning/raw/*.jsonl accumulate over runs. When a fix pattern reaches 3+ successes with 0 failures, it is promoted to .claude/rules/learned-fix-*.md — auto-loaded on every future Claude run. Convention patterns require 5+ occurrences and developer confirmation before promotion. Security patterns are promoted immediately with no threshold.

Precedence

Precedence Rules

How prompt, rule, and config values are resolved when multiple sources exist.

Prompt / Rule Content

For prompt and rule content, the highest-priority source wins:

.ai/rules/<topic>.md (project-level overrides)
config.yaml overrides: section
Plugin defaults (rules/*.md inside the plugin)

Project-Specific Fields

For project-specific configuration values:

User-provided URL values (explicit override)
config.yaml values
Auto-detected defaults (from /dx-init or /aem-init)

aem.repos Removed

The aem.repos field has been removed. Cross-repo configuration is now in the top-level repos: section. /aem-init enriches the top-level repos: entries with platform and ado-project fields instead.