Architecture & Internals

Auto-loaded by Claude Code. Concise, path-scoped rules. Claude reads these automatically when working on matching files.

# paths: ["**/*.js"]

- Use ES module imports
- Externalize selectors to config
- No console.log in production

Single source for both tools. Claude Code reads paths:, Copilot CLI reads applyTo: via COPILOT_CUSTOM_INSTRUCTIONS_DIRS.

# paths: ["**/*.js"]
# applyTo: "**/*.js"

## Component Structure
[Rules, patterns, conventions...]

Deep reasoning tasks that require understanding complex interactions across files and systems.

• Implementation plans
• Code review
• Root cause analysis

Execution tasks that need good judgment but not maximum reasoning depth.

• Step execution
• PR review
• AEM inspection

Simple lookups and searches where speed matters more than depth.

• File resolution
• Doc search
• Test running

Project-level (not in a plugin)

• wit_get_work_item
• repo_create_pull_request
• search_code
• pipelines_run_pipeline

Project-level (not in a plugin)

• jira_get_issue
• jira_search
• confluence_create_page
• jira_add_comment

HTTP — local Figma desktop app

• get_design_context
• get_screenshot
• get_variable_defs
• get_metadata

Docker — Deque axe accessibility engine

• analyze — scan for violations
• remediate — suggest fixes

HTTP — live AEM JCR instance

• getNodeContent
• scanPageComponents
• createPage
• updateComponent

stdio — real browser automation

• navigate_page
• take_screenshot
• click
• evaluate_script

Every build/lint fix is logged to .ai/learning/raw/fixes.jsonl with the error, fix applied, and component name.

3+ successful fixes for the same pattern get promoted to .claude/rules/learned-fix-*.md — auto-loaded on future runs.

Run metrics logged to runs.jsonl. Bug hotspot detection per component. Weekly retrospective aggregation.

Full plugin system with MCP servers, subagents, hooks, and shared libraries.

Same 76 skills auto-discovered from plugins. 25 Copilot agents with allowed-tools for auto-approval and handoffs: for navigation.

stop-guard.sh — prevents accidental /stop during long-running operations. Prompts for confirmation before terminating.

PostToolUse hook on get_screenshot — auto-saves Figma screenshots to disk, avoiding repeated MCP calls for the same design.

PostToolUse hook on get_design_context — caches design context responses locally so repeat lookups are instant.

• explain.md — developer requirements
• research.md — codebase research
• implement.md — implementation plan
• figma-extract.md — design tokens
• figma-gaps.md — design vs code gaps
• prototype/ — HTML prototype
• dod.md — definition of done

• dor-check — Definition of Ready
• dod-summary — Definition of Done
• re-summary — requirements summary
• pr-review-summary — review report
• share-plan — team share format

• feature-doc — feature documentation
• authoring-guide — AEM component guide

Templates ensure every output follows the same structure, making it safe to rely on AI-generated documentation.

Core setup — installs plugin templates, creates .ai/config.yaml, scaffolds rules and instructions.

AEM-specific seed data — component index, file patterns, content paths, architecture docs in .ai/project/.

Autonomous agent setup — ADO service hooks, pipeline configs, Lambda routing for webhook events.

Four independently installable plugins in a single monorepo. Non-AEM projects only need dx-core; multi-repo projects add dx-hub; AEM projects add dx-aem; any project wanting 24/7 autonomous agents adds dx-automation. Single repo simplifies maintenance.

All project-specific values read from .ai/config.yaml at runtime. The original skills had 50+ hardcoded values (org URLs, component paths, repo names). Replacing each with a config lookup makes skills reusable across any project.

Coordinators invoke skills directly via Skill() calls instead of routing through an intermediary executor agent. Simpler architecture, fewer context switches, lower token cost.

file override > config override > plugin default. Config overrides for quick tweaks, file overrides for deep customization, plugin defaults as sensible starting points. Projects can also shadow entire skills.

Relies on Claude Code built-in skill precedence (project .claude/skills/ > plugin skills) rather than custom override logic. No custom code needed — just create a file with the same name.

dx-file-resolver, dx-doc-searcher, and aem-page-finder use Haiku. These agents do simple lookups — glob files, grep docs, call MCP search. Haiku is 10x faster and cheaper than Sonnet with no quality loss.

Only dx-code-reviewer uses Opus. Code review is the one task where deep reasoning directly impacts quality (catching subtle bugs, understanding architectural implications). Other tasks are well-served by Sonnet.

All per-ticket output goes to .ai/specs/<id>-<slug>/ with predictable file names. Skills find each other’s output by convention — no data passing needed.

Learning (run logging, fix patterns, pattern promotion) lives in coordinator skills, not leaf skills. Coordinators see the full picture — how many fixes, which heals worked. JSONL for machine data, promoted rules for proven patterns (3+ successes, 0 failures).

Shell scripts for common operations, not Node.js or Python. Shared functions in dx-common.sh eliminated 26+ copies of duplicated helper scripts. No runtime dependencies — works everywhere Claude Code runs.