Data Flow

How skills communicate through convention-based file discovery. No data is passed directly between skills -- every input and output lives in the spec directory.

Shared Memory

The Spec Directory

All skills in a pipeline communicate through files in .ai/specs/. Each skill reads predecessor output by filename convention.

Spec Directory Structure

.ai/specs/<ticket-id>-<slug>/
.branch                   -- ensure-feature-branch.sh
raw-story.md              -- dx-req (Phase 1: fetch)
explain.md                -- dx-req (Phase 3: explain, reads: raw-story.md)
research.md               -- dx-req (Phase 4: research, reads: raw-story.md + explain.md)
ticket-research.md        -- dx-ticket-analyze
share-plan.md             -- dx-req (Phase 5: share, reads: explain + research + dor-report)
dor-report.md             -- dx-req (Phase 2: DoR, reads: raw-story.md)
figma-extract.md          -- dx-figma-extract (optional)
figma-conventions.md      -- dx-figma-prototype Phase A (optional)
prototype/
  figma-reference.png     -- dx-figma-extract (Figma screenshot)
  index.html              -- dx-figma-prototype Phase B
  styles.css              -- dx-figma-prototype Phase B
  script.js               -- dx-figma-prototype Phase B (optional)
implement.md              -- dx-plan (reads: research + explain + raw-story)
dev-all-progress.md       -- coordinator progress tracking (optional)
verification.md           -- dx-bug-verify before (for bugs)
verification-local.md     -- dx-bug-verify after (post-fix local)
verification-qa.md        -- dx-bug-verify qa (post-merge QA)
docs/
  wiki-page.md            -- dx-doc-gen (demo walkthrough: summary, QA URLs, screenshots, Figma)
demo/
  dialog-*.png            -- aem-doc-gen (dialog screenshot)
  rendered-*.png          -- aem-doc-gen (publisher screenshot)
  authoring-guide.md      -- aem-doc-gen (editor-friendly guide)
  page-structure.md       -- aem-doc-gen (cached page structure)
images/                   -- dx-req (ADO attachments)
screenshots/              -- aem-fe-verify (component vs Figma)

No Direct Data Passing

Skills never pass data to each other through function arguments, environment variables, or shared memory. Every skill reads its inputs from files and writes its outputs to files. This makes every intermediate state inspectable and debuggable.

Chain

Dependency Chain

Each file depends on predecessors. The chain flows from raw story through to PR creation.

Primary Pipeline

Main data flow from story fetch through to code delivery.

raw-story.md dx-req (fetch)

dor-report.md dx-req (DoR)

explain.md dx-req (explain)

research.md dx-req (research)

implement.md dx-plan

Code Changes dx-step

Pull Request dx-pr

ADO Comment Chain

Work item comments posted at key milestones. Each is idempotent -- skip if unchanged, minimal update if changed.

[DoRAgent] BA checks checkboxes

[DevPlan] Scope + bullets

[DoD] Completion criteria

Optional Figma Branch

When a story includes a Figma URL, the pipeline adds a parallel branch: figma-extract.md and figma-conventions.md feed into prototype/, which then informs implement.md.

Idempotent ADO Comments

DoR, DevPlan, and DoD comments are posted with markers. Re-running the same skill detects existing comments and either skips or posts a minimal update. No duplicate spam.

State Machine

implement.md as State Machine

The only file that tracks execution state. Each step has a status that drives the coordinator loop.

Step Format

implement.md

### Step 3: Add ExporterModel
**Status:** done
**Files:** core/.../FooExporter.java
**What:** Create the Sling Model exporter
**Why:** Expose component data as JSON
**Test:** mvn test -pl core

### Step 3h: Fix missing import          -- added by dx-step-fix (escalation)
**Status:** done
**Files:** core/.../FooExporter.java
**What:** Corrective fix for compilation error

### Step 4: Add template
**Status:** blocked                       -- updated by dx-step-fix
**Blocked:** HTL compilation error: missing data-sly-use
**Files:** ui.apps/.../template.html

Status Values

Each step transitions through a fixed set of states:

pending — not yet started
in-progress — currently executing
done — completed successfully
blocked — failed, with diagnosis attached

Corrective Steps

When a step fails and the healer intervenes, it inserts new corrective steps with distinctive numbering: Step 3h (first heal), Step 3h2 (second heal), R1 / R2 (review fixes).

Config

Config as Global Context

.ai/config.yaml is read by many skills for project-specific values -- the single source of truth for branches, URLs, and commands.

Config Key	Used By
`scm.base-branch`	dx-pr, ensure-feature-branch.sh
`scm.org`	dx-req (ADO URLs)
`build.command`	dx-step, dx-step-build
`aem.url`	aem-verify, aem-snapshot, aem-editorial-guide
`preferences.auto_commit`	dx-agent-all
`preferences.auto_pr`	dx-agent-all

Knowledge

Knowledge Base as Read-Only Context

Init skills populate project knowledge. All other skills read but never write to these files.

File	Populated By	Read By
`.ai/project/*.md`	Init skills (aem-init, aem-refresh)	AEM agents, dx skills
`.ai/rules/*.md`	dx-init / aem-init + manual	dx-code-reviewer, automation agents
`.claude/rules/*.md`	dx-init + manual	Every Claude interaction (auto-loaded)

Convention Over Configuration

The entire data flow relies on naming conventions, not configuration. A skill that writes research.md does not need to know who will read it. A skill that reads research.md does not need to know who wrote it. The filename IS the contract.