From dx-core
Generate an implementation plan with status-tracked steps. Creates implement.md from explain.md + research.md. Uses extended thinking for deep reasoning. Use after requirements are ready (from ADO flow or import).
npx claudepluginhub easingthemes/dx-aem-flow --plugin dx-coreThis skill is limited to using the following tools:
You read the spec documents and use extended thinking to generate `implement.md` — a concrete, step-by-step development plan with status tracking for automated execution.
Generates structured implementation plans from feature descriptions or requirements, grounded in repo patterns and research. Deepens existing plans via interactive sub-agent review.
Creates structured plans for multi-step tasks including software features, implementations, research, or projects. Deepens plans via interactive sub-agent reviews.
Generates sectioned implementation plans from markdown spec files via research, simulated interviews, synthesis, planning, multi-LLM reviews. Resumes from existing files for complex features.
Share bugs, ideas, or general feedback.
You read the spec documents and use extended thinking to generate implement.md — a concrete, step-by-step development plan with status tracking for automated execution.
Use ultrathink for this skill — implementation planning benefits from deep reasoning about dependencies, ordering, and edge cases.
SPEC_DIR=$(bash .ai/lib/dx-common.sh find-spec-dir $ARGUMENTS)
If the script exits with error, ask the user for the work item ID or slug.
Read these files from $SPEC_DIR (in order of importance):
research.md — codebase findings (required for a good plan)explain.md — distilled requirementsraw-story.md — original story for reference (may not exist for non-ADO flows)If research.md doesn't exist, warn the user: "No research.md found — run /dx-req first for a better plan. Proceeding with explain.md only."
Read shared/provenance-schema.md for the schema definition.
After reading each input file, parse its YAML frontmatter provenance: block (if present). Evaluate input quality:
research.md provenance:
confidence: low → warn: "⚠ research.md has low confidence (degraded mode or incomplete data). Plan quality may be affected — consider re-running /dx-req with better search hints."confidence: medium or high → no warning neededmodel: haiku → note: "ℹ research.md was produced at Haiku tier. For complex features, consider re-running /dx-req at higher tier."explain.md provenance:
confidence: low → warn: "⚠ explain.md has low confidence. Requirements may be incomplete — verify with the original ticket."Confidence propagation: Use the lowest confidence from input files as the ceiling for implement.md provenance. If research.md is low, implement.md cannot be higher than low — regardless of planning quality, the plan is only as reliable as its inputs.
Also check for Figma prototype files (from /dx-figma-prototype):
figma-conventions.md — discovered project conventions (design tokens, naming, patterns)prototype/index.html — standalone HTML prototypeprototype/styles.css — CSS with project token mappingsfigma-extract.md — raw Figma extraction dataIf prototype files exist, the plan MUST reference them. Implementation steps should adapt the prototype into project-native code rather than building from scratch.
Component Reuse Map: If figma-conventions.md contains a ### Component Reuse Map section, the plan MUST respect it:
<component> at <path>" — NO new file creationRead shared/hub-dispatch.md for hub detection logic.
If hub mode is active (hub.enabled: true AND cwd is .hub/):
research.md → ## Cross-Repo Scope for per-repo scopecd <repo.path> && claude -p "/dx-plan <ticket-id>" --output-format json --allowedTools "Bash,Read,Edit,Write,Glob,Grep" --permission-mode bypassPermissions
c. Each repo generates its own implement.md locally
d. Collect and summarize: "Plans generated in repos"If hub mode is not active: continue with normal flow below.
implement.md exists in the spec directoryimplement.md match the current spec?research.md?research.md or explain.md changed since implement.md was generated?implement.md is current → print implement.md already up to date — skipping and STOPimplement.md exists but is outdated — regenerating and continueIf .ai/rules/plan-format.md exists (project override), read and follow it. Otherwise read the plugin's rules/plan-format.md.
If .github/instructions/ (or .ai/instructions/) exists, read instruction files relevant to the file types in this spec — these provide detailed code examples and framework patterns for generating concrete implementation steps.
If this is a complex feature with multiple valid approaches, check if superpowers:brainstorming is available and invoke it to explore the design space before planning.
Fallback (if superpowers not installed): Before generating the plan, briefly consider:
If a brainstorming spec already exists in docs/superpowers/specs/, read it for design context.
Decision capture: Any non-obvious design decision surfaced during exploration MUST be recorded in the ## Key Decisions section of implement.md. This includes:
If the change is trivial (single-file edit, config-only, straightforward bug fix) or every decision is obvious from requirements, omit the Key Decisions section.
Check if .ai/graph/nodes/patterns/ exists and contains YAML files:
find .ai/graph/nodes/patterns/ -name "*.yaml" -type f 2>/dev/null
If pattern files exist, read shared/pattern-schema.md for the schema, then read each pattern file. Match patterns against the current ticket by:
tags against component names, file types, and architectural concepts from research.mdfiles against files listed in research.md's ## Files Inventory or ## Key Findingsdescription against the current ticket's requirements in explain.mdIf relevant patterns found:
## Relevant Patterns section in implement.md (before ## Steps):## Relevant Patterns
| Pattern | Confidence | Tickets | Relevance |
|---------|-----------|---------|-----------|
| <title> | <confidence> | <count> | <why it matches> |
> **<pattern-id>:** <approach summary from pattern>. (from <ticket list>)
**What:** section: "Follow established pattern <pattern-id> — ."If no patterns found (directory empty or doesn't exist): continue without the section. This is normal for new projects or early tickets.
If research.md contains an ## AEM Component Intelligence section, apply these three rules during step generation:
When a step modifies a component, check AEM Component Intelligence for variants:
<name> in <repo> may need the same change. Verify in a separate session."Every step that touches a component MUST account for all known variants. Missing a variant is a plan defect.
When a step references an AEM dialog field (e.g., for aria-label, display text, image alt), verify the field's semantic meaning from AEM Component Intelligence:
Label and Sample Authored Valuesheading for product name" but AEM shows heading Label="Product Price", Value="$29.99" → step must note: "Use text (Product Name), NOT heading (Product Price)"When a step renders a dialog field value in the UI (link text, label, display content):
<field> is empty on <page>. Wrap rendering in conditional to prevent empty elements (empty <a>, <span>, etc.)."These rules are technology-agnostic — they specify WHAT to guard, not HOW. The project's .claude/rules/ files provide syntax-specific patterns (HTL conditionals, HBS {{#if}}, etc.).
If research.md contains a ## Cross-Repo Scope section with Scope: Multi-repo:
[This repo], [{Repo-Name}]Steps tagged [{Backend-Repo}] must be implemented in that repo. Deploy before starting [This repo] steps.
**Other repos required:** line at plan completion lists all non-current repos from the scope sectionExample:
Files: ui.apps/.../component/_cq_dialog/.content.xml
What: Add newField to dialog
Verification: Field appears in dialog XML
Steps tagged [{Backend-Repo}] must be implemented in that repo. Deploy before starting [This repo] steps.
Files: ui.frontend/src/.../component.js
What: Read newField from data model
Verification: Field renders on page
If research.md has no Cross-Repo Scope section or scope is "This repo only", do not add repo tags.
Analyze all inputs and write implement.md in the same spec directory.
Include the provenance frontmatter block at the top of implement.md, before the # Implementation Plan: heading. Use agent: dx-plan. Set confidence using the propagation rule from the Provenance Check step: the lowest input confidence is the ceiling, then apply the standard downgrade rule (no research.md → low). Default is medium when all inputs have medium or high confidence.
Read .ai/templates/spec/implement.md.template and follow that structure exactly. Key rules:
**Status:** pending (initial state)If implement.md contains a ## Key Decisions section (i.e., non-trivial decisions were made), externalize each decision as a structured YAML file.
Read shared/decision-schema.md for the schema definition.
mkdir -p .ai/graph/nodes/decisions
For each decision in the ## Key Decisions section, write a YAML file to .ai/graph/nodes/decisions/<ticket>-<slug>.yaml:
<ticket> is the work item ID (from spec directory name)<slug> is a kebab-case summary of the decision title (e.g., extend-layout-dropdown)**Chosen:** → chosen:, **Why:** → why:, **Alternatives considered:** → alternatives:, **Affects steps:** → affects_steps:confidence from the same propagation logic used for implement.md provenancetrust_tier: shared, status: activetags from technology names, component types, and architectural concepts mentioned in the decisionlineage with references to the input spec files that informed this decision (e.g., requirement-<ticket>-raw, research-<ticket>)files from files mentioned in the decision or the affected stepsIf decision YAML files already exist for this ticket (re-planning), overwrite them. Set status: superseded on any old decision files that are no longer in the new plan's Key Decisions section.
The YAML files contain the same information as the markdown Key Decisions section — they are the structured counterpart for machine consumption. Do not add or remove decisions between the two formats.
After writing decision nodes, write (or update) the per-ticket edge file. Read shared/edge-schema.md for the schema.
mkdir -p .ai/graph/edges
Write .ai/graph/edges/<ticket>.yaml with edges derived from the planning context:
requirement-<ticket>-raw and research-<ticket> to the decision ID (these come from the decision's lineage field)step-<ticket>-<N> for each step in affects_steps## Relevant Patterns, add an edge from step-<ticket>-<N> to the pattern IDIf the edge file already exists (re-planning), replace all edges where agent: dx-plan but preserve edges from other agents (e.g., dx-step-verify).
Every step MUST have a **Status:** line with one of:
pending — not yet started (initial state)in-progress — currently being worked ondone — completed and verifiedblocked — cannot proceed, with reasonThe step-* skills update these statuses as they execute.
prototype/ exists, implementation steps adapt it into the project's build system. The step should reference specific prototype files:
prototype/index.html into the HBS template"prototype/styles.css into component SCSS, replacing flat values with project variables/mixins"prototype/figma-reference.png"figma-conventions.md exists, implementation steps should cite it for specific variable names, mixin usage, and naming patterns. E.g., "Use @include media-breakpoint-up(lg) for desktop breakpoint (see figma-conventions.md)."## implement.md created
**<Title>**
- Steps: <count> (all pending)
- Key decisions: <count or "none"> (decision nodes written to `.ai/graph/nodes/decisions/`)
- Files to modify: <count>
- Files to create: <count>
- Tests planned: <count> unit, manual verification included
- Risks identified: <count or "none">
### Next steps:
- `/dx-plan-validate` — verify plan covers all requirements
- `/dx-step` — execute first step
- `/dx-step-all` — execute all steps autonomously
/dx-plan 2416553
Reads .ai/specs/2416553-add-layout-switcher/explain.md and research.md, generates implement.md with 6 steps covering model changes, dialog updates, HTL template, JS logic, SCSS, and tests. All steps start as pending.
/dx-plan 2416553
Detects that research.md has changed since implement.md was generated. Prints "implement.md exists but is outdated — regenerating" and creates a fresh plan.
/dx-plan 2416553
If research.md doesn't exist, warns "No research.md found — run /dx-req first for a better plan" and generates from explain.md only. Plan will lack specific file paths and line numbers.
Cause: No .ai/specs/ directory matches the given ID or slug.
Fix: Run /dx-req <id> first to create the spec directory, or check the ID is correct.
Cause: research.md is missing or has thin results.
Fix: Run /dx-req <id> with search hints to get better codebase findings, then re-run /dx-plan.
Cause: research.md didn't find existing utilities, or the "Existing Implementation Check" section is missing.
Fix: Run /dx-req <id> again — it may find more with different search terms. Or manually add findings to research.md before re-planning.
Change set identified →
├── All files share one concern (same component) → 1 step (up to ~8 files)
├── Files split across concerns (FE + BE + test) → split by concern
├── >8 files in one concern → split by component boundary
└── Test files →
├── Unit tests for single component → include in component step
└── Integration tests spanning components → separate step
Scenario: Plan step says "add form validation for phone numbers"
Discovery: src/core/scripts/libs/forms.js has validateField() with email, text, number patterns
Decision: EXTEND — add phone regex to existing validateField(). Don't create new util.
Why: Existing utility covers >70% of need. Only a new regex pattern is needed.
Key Decision entry:
### Form validation approach
**Chosen:** Extend existing `validateField()` in `forms.js`
**Why:** Covers >70% of need — only a new regex pattern is required
**Alternatives considered:**
- New `phoneValidator.js` utility — rejected because existing utility handles all other field types; a separate file fragments validation logic
**Affects steps:** 2
Scenario: Need color-coded severity badge component for QA dashboard
Discovery: Closest match is HighlightBox (callout alert) — wrong abstraction (alert vs badge)
Decision: CREATE — no existing component serves this purpose
Why: Repurposing HighlightBox would fight its design. Clean creation is simpler.
Scenario: Change touches hero.js (FE), HeroModel.java (BE), hero.html (template), hero-test.js (test) Decision: 2 steps — Step 1: BE (HeroModel.java), Step 2: FE (hero.js + hero.html + hero-test.js) Why: BE and FE are independent concerns. FE files change together (same concern).
Before presenting the generated plan:
explain.md — list every requirementimplement.md exists in spec directory**Status:** pending**Files:**Common excuses for weak planning — and why they're wrong:
| False Logic | Reality Check |
|---|---|
| "I'll figure it out as I code" | Coding without a plan produces twice the rework. Plan first, code once. |
| "The requirements are obvious" | "Obvious" requirements produce the most bugs. Write them down explicitly. |
| "We don't need tests in the plan" | Every step needs a verification command. Untested steps are unverified steps. |
| "I'll create a new utility for this" | Search first. 80% of the time an existing utility covers the need. |
| "This is too simple for a plan" | If it touches >2 files, it needs a plan. "Simple" changes cause unexpected ripple effects. |
| "I'll plan all the edge cases later" | Edge cases discovered during coding cause scope creep and rework. Surface them now. |
When ordering steps, tackle highest-uncertainty pieces first:
Change sizing: Aim for steps that produce ~100 lines of diff each. Smaller is reviewable; larger hides problems.
**Status:** pending is mandatory**Other repos required:** header line but do NOT create steps for those repos. The developer runs the workflow in each repo separately.