Setup
Three steps to get dx running in your project. Works with Claude Code, GitHub Copilot CLI, and VS Code Chat.
Install plugins, configure project, teach the AI your conventions.
Install Plugins
Add the shared marketplace and install the plugins your project needs.
# Add marketplace (one-time) /plugin marketplace add easingthemes/dx-aem-flow # Install plugins /plugin install dx-core@dx-aem-flow /plugin install dx-aem@dx-aem-flow # AEM projects only /plugin install dx-hub@dx-aem-flow # Multi-repo orchestration only
Updating Later
/plugin marketplace update dx-aem-flow updates all installed plugins to the latest version.
After upgrading, run /dx-upgrade to sync project files to the new plugin version.
Initialize & Configure
Create project config, install convention rules, detect project structure.
AEM Projects — Set Environment Variables First
The AEM MCP server requires the AEM_INSTANCES environment variable. Set it before running
/aem-init so component discovery can scan your running AEM instance for dialog fields,
variants, and pages.
# Format: name:host:user:pass — comma-separated for multiple instances export AEM_INSTANCES="local:http://localhost:4502:admin:admin" # Multi-instance example (local + QA): # export AEM_INSTANCES="local:http://localhost:4502:admin:admin,qa:https://qa-author.example.com:USER:PASS" # Optional: accessibility testing + QA Basic Auth # export AXE_API_KEY="your-axe-api-key" # export QA_BASIC_AUTH_USER="your-qa-username" # export QA_BASIC_AUTH_PASS="your-qa-password"
Restart your terminal or run source ~/.zshrc after adding these.
These env vars work in both Claude Code and Copilot CLI.
Run these commands in order:
/dx-init
Core initialization — creates .ai/config.yaml, convention rules, MCP config, agent templates, shared scripts. Interactive — asks about your Azure DevOps or Jira project, build commands, and base branch.
If it detects an AEM project, automatically runs /aem-init to append the aem: section, install BE/FE rules by project role, and auto-generate component-index.md via AEM MCP.
/dx-adapt
Auto-detects project type (aem-fullstack, aem-frontend, etc.), toolchain (Node version, build tool, CSS compiler), and writes project.type, project.role, and toolchain: to config.
/dx-init # Core config + rules + MCP (chains to /aem-init for AEM projects) /aem-init # Only if not already run as part of /dx-init /dx-adapt # Project type + toolchain auto-detection
/aem-init
/dx-init automatically chains to /aem-init when it detects an AEM project.
Run /aem-init separately only if you skipped it during init or are adding AEM support to an existing project.
What gets created
| Path | Purpose | Created By |
|---|---|---|
.ai/config.yaml | Project config (branches, Azure DevOps/Jira, build commands, AEM) | dx-init + aem-init + dx-adapt |
.claude/rules/ | Convention rules (generic templates at this stage) | dx-init + aem-init |
.mcp.json | MCP server configuration (ADO, Jira/Confluence, Figma, axe) | dx-init |
.github/agents/ | Copilot agent templates | dx-init |
.ai/project/component-index.md | Component catalog (auto-discovered from AEM) | aem-init |
.ai/templates/ | Spec file and work item comment templates | dx-init |
.ai/rules/ | Shared rules (PR review, pragmatism) for local + automation | dx-init |
Scan Your Project
Teach the AI your actual conventions — replace generic placeholders with real values from your codebase.
After init, your .claude/rules/ files contain generic templates and .ai/project/ seed data is minimal.
/dx-scan reads your actual source code, discovers conventions interactively, and writes project-specific values.
/dx-scan
Phase 1: Frontend
Discovers CSS variables, breakpoints, naming conventions (BEM/utility), component registration patterns,
base classes, clientlib categories. Updates fe-styles.md, fe-javascript.md,
fe-components.md, fe-clientlibs.md.
Phase 2: Backend
Discovers Sling Model annotations, exporter patterns, dialog structure, HTL conventions,
test framework, package structure. Updates be-sling-models.md, be-components.md,
be-dialog.md, be-htl.md, be-testing.md.
Phase 3: Seed Data
Generates architecture.md, features.md, file-patterns.yaml,
and content-paths.yaml in .ai/project/. Skips component-index.md
if already created by /aem-init.
Interactive Process
/dx-scan presents each discovery with concrete examples from your code and asks for confirmation
before writing. You can correct, enrich, or skip any phase. This is a one-time step — run it once after
initial setup, then only again if your project structure changes significantly.
Before vs After /dx-scan
Before (generic rules)
fe-styles.md says: “Use project CSS variables for spacing and colors.” Agents don’t know
your actual variable names, breakpoints, or color tokens.
After (project-specific)
fe-styles.md says: “Use $bp-mobile: 768px, $bp-tablet: 1024px.
Colors: $color-primary: #1a1a1a. Naming: BEM.” Agents write code that matches your project.
MCP Configuration
/dx-init creates .mcp.json with all MCP servers pre-configured. You only need to verify ADO authentication.
MCP Servers — Already Configured
/dx-init creates .mcp.json with ADO, AEM, Figma, axe, and Chrome DevTools servers.
ADO MCP uses browser-based OAuth — on first use, it opens a browser to authenticate. No PAT needed.
For platform-specific details (permissions, settings scope, Copilot CLI differences), see:
Setup Complete
You're ready to go
Run /dx-doctor to verify everything is connected (MCP servers, config, rules).
Then start with /dx-req <ticket-id> to pull your first story.
/dx-doctor # Check health of all dx workflow files /dx-help "how does this project work?" # Test if AI understands your project