Seed Data Guide
Teach the AI about your project -- components, architecture, file conventions, and markets
Why Seed Data Matters
Without seed data, agents guess. With it, they know.
Project Knowledge
Without seed data, agents have only the auto-scanned component list. They do not know your architecture, features, file conventions, markets, or AEM content structure. Every skill — component lookup, ticket analysis, planning, help — produces significantly better output when agents have project context.
| Seed Data Level | Quality Impact |
|---|---|
component-index.md only | Component names exist. Agents guess at everything else. |
+ project.yaml | Agents know brands, markets, AEM paths, platform prefixes, QA URL. |
+ file-patterns.yaml | Agents find source files reliably instead of using generic globs. |
+ architecture.md + features.md | /help answers from docs instead of guessing. Better planning. |
+ content-paths.yaml | Page search uses correct content tree patterns and language defaults. |
File Reference
All files live in .ai/project/. Every file is optional -- missing file means that capability is skipped.
| File | Format | Created By | Purpose |
|---|---|---|---|
component-index.md | Markdown table | aem-init (auto) | Local repo components |
component-index-project.md | Markdown + sections | You | Cross-repo components, detailed specs |
project.yaml | YAML | You | Repos, brands, markets, platforms |
file-patterns.yaml | YAML | You | How to find source files per repo |
content-paths.yaml | YAML | You | AEM content tree structure |
architecture.md | Free-form Markdown | You | Rendering pipelines, key libs |
features.md | Free-form Markdown | You | Domain features (auth, commerce, forms) |
project.yaml
Structured project configuration -- repos, brands, markets, platforms.
ado:
org: myorg.visualstudio.com
brands:
- name: MySite
markets:
- code: US
platform: [DXN]
aem-paths: ["/content/mysite/us/en"]
languages: [en]
default-language: en
commerce: none
repos:
- name: MySite-AEM
platform: DXN
ado-project: My Project
base-branch: develop
platforms:
- id: DXN
resource-type-prefix: mysite/components
css-prefix: mysite-
component-prefixes: [mysite-]
defaults:
qa-author-url: https://qa-author.mysite.com Rules
ado.org— domain only, nohttps://prefixbrands[].markets[].code— 2-letter country codes, used as keys everywherebrands[].markets[].aem-paths— must match actual AEM content treeplatforms[].id— referenced by repos and markets, must match exactly
file-patterns.yaml
Tells agents how to find source files for a component.
DXN:
backend:
repo: My-Platform-Repo
resolve-from: component-index-project
files:
- label: HTL template
path: "{basePath}/{name}.html"
- label: Dialog
path: "{basePath}/_cq_dialog/.content.xml"
- label: Component def
path: "{basePath}/.content.xml"
java-search:
module: "my-core-module"
patterns: ["{Name}Model.java", "{Name}ModelImpl.java"]
frontend:
- repo: My-Platform-Repo
base-path: "my-clientlibs/frontend/publish/components/{name}/"
extensions: [.clientlibs.js, .config.js, .clientlibs.scss]
flat: true Placeholders
{name}— lowercase component name as-is{Name}— PascalCase (derived from name){basePath}— extracted from component-index Source Link
Fallback
If file-patterns.yaml does not exist, agents fall back to generic AEM Glob patterns like **/components/**/{name}/.
content-paths.yaml
Tells agents how to find AEM pages that use a component.
content-roots:
pages: "/content/{brand}/{country}/{language}"
experience-fragments: "/content/experience-fragments/{brand}/{country}/{language}"
author-url-pattern: "{qa-author-url}/editor.html{pagePath}.html"
search:
tool: mcp__AEM__searchContent
limit-per-path: 5
always-search-xf: true
primary-language-only: true
language-defaults:
US: en
CA: en
MX: es
DE: de Placeholders
{brand}, {country}, and {language} are substituted from project.yaml brand/market definitions. {qa-author-url} comes from defaults.qa-author-url.
architecture.md and features.md
Free-form Markdown that agents search by keyword.
architecture.md
Suggested sections:
- Rendering Pipeline — how components render (HTL, JS, hybrid)
- Module Structure — directory tree, Maven modules, FE build
- Key Libraries — shared libs, base classes, utilities
- Key Patterns — component anatomy, data flow, config patterns
- Platform Differences — Legacy vs DXN, if applicable
features.md
One ## section per feature. Include:
- Component names — agents cross-reference with component index
- Config details — CAC, OSGi, environment variables
- Page paths — where the feature is authored in AEM
- Practical focus — what a developer needs to modify the feature
Rules for Free-Form Files
Be specific — include actual class names, file paths, config keys. Agents grep for these. Section headings (##) help agents return matching sections with context. Do not duplicate structured data — repo lists and file paths belong in the YAML files.
How Agents Use Each File
Which agents read which files, and what happens when files are missing.
| Agent | File | If Missing |
|---|---|---|
| doc-searcher | component-index.md, architecture.md, features.md | Skip search |
| file-resolver | file-patterns.yaml, project.yaml | Fall back to generic Glob |
| page-finder | content-paths.yaml, project.yaml | Ask user for paths |
| *-component | All above (orchestrates sub-agents) | Degrades per missing file |
| *-help | architecture.md, features.md | Code search only |
Setup Levels
Start minimal and grow.
Bare Minimum
.ai/project/ └── component-index.md # auto-generated
Run /aem-init only. Agents know component names but guess everything else.
Recommended
.ai/project/ ├── component-index.md ├── project.yaml ├── file-patterns.yaml ├── architecture.md └── features.md
Agents know your project. Lookups find the right files. Help answers from docs.
Full Setup
.ai/project/ ├── component-index.md ├── component-index-project.md ├── project.yaml ├── file-patterns.yaml ├── content-paths.yaml ├── architecture.md └── features.md
Full capabilities. Multi-repo, multi-brand, detailed component specs.