From dx-core
Generate wiki documentation from completed spec files — architecture decisions, usage guide, API changes. Posts to ADO Wiki or Confluence depending on provider config. Use as the final step after implementation is done. Invoked automatically by /dx-agent-all Phase 7 and /dx-req-dod.
npx claudepluginhub easingthemes/dx-aem-flow --plugin dx-coreThis skill is limited to using the following tools:
You generate wiki-style documentation from completed spec files. The output captures what was built, why, and how to use it. In pipeline/wiki mode, it posts to the correct sprint subfolder in the ADO wiki or Confluence (depending on `tracker.provider`).
Guides project documentation structure, file organization, content requirements by project phase, and best practices for README.md, ARCHITECTURE.md, API docs, and more.
Writes, edits, and maintains documentation collaboratively or autonomously via git PRs. Defaults to human-led mode; verifies context before drafting Markdown/MDX content.
Share bugs, ideas, or general feedback.
You generate wiki-style documentation from completed spec files. The output captures what was built, why, and how to use it. In pipeline/wiki mode, it posts to the correct sprint subfolder in the ADO wiki or Confluence (depending on tracker.provider).
SPEC_DIR=$(bash .ai/lib/dx-common.sh find-spec-dir <work-item-id-if-provided>)
If the script exits with error, ask the user for the work item ID.
Read .ai/config.yaml for:
tracker.provider — ado (default) or jirascm.org — ADO org URLscm.project — ADO project namescm.wiki-id — ADO wiki identifier (if configured)scm.wiki-project — project that owns the wiki (may differ from scm.project)scm.wiki-doc-root — root wiki path for technical documentationconfluence.space-key — Confluence space key (if provider = jira)confluence.doc-root — parent page title for generated docs (if provider = jira)Read these files from $SPEC_DIR (all optional — generate from what's available):
raw-story.md — original story for title, ID, acceptance criteria, iteration pathexplain.md — distilled developer requirementsshare-plan.md — non-technical summaryimplement.md — step-by-step plan with statusresearch.md — codebase context and patterns found.sprint — sprint name (e.g., Sprint 41) saved by /dx-req (Phase 1).branch — feature branch name.pr — PR number and URL (if PR was created)demo/authoring-guide.md — AEM authoring guide with screenshots (produced by /aem-doc-gen)figma-extract.md — Figma design data (produced by /dx-figma-extract)aem-fe-verify.md — FE verification verdict (produced by /aem-fe-verify)aem-after.md — post-deployment component state (produced by /aem-verify)qa-handoff.md — QA testing steps with page URLs (produced by /aem-qa-handoff)If none exist (excluding authoring-guide.md), print "No spec files found — nothing to generate from" and STOP.
Read $SPEC_DIR/.sprint for the sprint name. If the file doesn't exist, try to extract it from the Iteration Path in raw-story.md. If still unknown, set sprint to Unknown and warn the user.
docs/wiki-page.md exists in the spec directorydocs/wiki-page.md already up to date — skipping and STOPdocs/wiki-page.md exists but is outdated — regeneratingCreate $SPEC_DIR/docs/ directory if it doesn't exist.
If demo/authoring-guide.md exists, read .ai/templates/wiki/wiki-page-aem.md.template and follow that structure exactly. The template is structured as a demo walkthrough — sections are ordered to match a typical demo presentation flow (story → design → implementation → QA page → authoring/dialog → frontend → Figma comparison).
Authoring section is the core of the demo page. It merges what was previously split across Configuration, Dialog Changes, and Authoring Guide into one presenter-friendly section. Every action MUST have a clickable link — the AEM Author Edit URL where the component exists, the real component name, and a field-by-field table of what to change. The presenter should be able to follow this section to configure and demo the component live without searching for anything.
Screenshot references — repo-relative paths: ADO wiki does not support binary upload via current MCP tools. All screenshot references MUST use repo-relative paths so they can be committed and linked from the ADO wiki.
Compute <repo-relative-path> = .ai/specs/<id>-<slug> (relative to repo root). Use this for all image references in the generated wiki page:
<repo-relative-path>/demo/dialog-<component>.png<repo-relative-path>/demo/rendered-<component>.png<repo-relative-path>/prototype/figma-reference.png<repo-relative-path>/screenshots/component-rendered.pngConditional sections: The template contains sections guarded by comments (e.g., "ONLY if figma-extract.md exists"). Check for each source file and OMIT the entire section (heading included) if the source data is not available. Specifically:
figma-extract.md or prototype/ dir existsQA Verification (MANDATORY for AEM projects): AEM pages are the deliverable — this is what the customer wants to see. Every AEM wiki page MUST include QA page URLs. Read QA URLs from .ai/config.yaml (aem.author-url-qa, aem.publish-url-qa).
Two views are required per page:
<author-url-qa>/editor.html<page>.html — dialog/config view for authors<author-url-qa><page>.html?wcmmode=disabled — FE rendering without editor chrome, for demoPage selection rule: New demo pages are ONLY for new components. For updates to existing components (enhancements, a11y fixes), the page should be the best representative existing page that already has the component — not a newly created demo page.
Extract demo page path from (in priority order):
qa-handoff.md — QA-specific URLsdemo/authoring-guide.md — Author URL, Publisher URLaem-after.md — Test/Demo page pathMulti-component coverage: If several components are affected, determine whether they can all be demoed on one page or need separate pages. Provide a QA URL table for each page needed. If a new component was created but not yet on a QA page, flag: ⚠️ Component <name> needs to be added to a QA page and configured for demo.
If demo/authoring-guide.md does NOT exist, read .ai/templates/wiki/wiki-page.md.template and follow that structure exactly. This standard template includes a ## Usage section instead of Authoring/Website.
If the environment variable PIPELINE_MODE is set to true, OR if the user explicitly asks to post to wiki:
Read tracker.provider from .ai/config.yaml (default: ado).
ado → follow Section 6a (ADO Wiki posting).jira → follow Section 6b (Confluence posting).scm.wiki-id, scm.wiki-project, and scm.wiki-doc-root from .ai/config.yamlscm.wiki-id is not configured, print: Wiki ID not configured — wiki page saved locally only. and STOP wiki posting.WIKI_ROOT = <scm.wiki-doc-root> # e.g., /My-Wiki/Technical-Documentation/Sprint-wise
SPRINT = <sprint name from .sprint> # e.g., Sprint 42
PAGE_TITLE = <id>-<slug-from-title> # e.g., 2357516-Enhance-PLP-Filter-Sticky
WIKI_PATH = "${WIKI_ROOT}/${SPRINT}/${PAGE_TITLE}"
mcp__ado__wiki_get_page
wikiIdentifier: <scm.wiki-id>
project: <scm.wiki-project>
path: "${WIKI_ROOT}/${SPRINT}"
mcp__ado__wiki_create_or_update_page
wikiIdentifier: <scm.wiki-id>
project: <scm.wiki-project>
path: "${WIKI_ROOT}/${SPRINT}"
content: "# ${SPRINT}\n\nTechnical documentation for stories in ${SPRINT}."
mcp__ado__wiki_list_pages
wikiIdentifier: <scm.wiki-id>
project: <scm.wiki-project>
path: "${WIKI_ROOT}/${SPRINT}"
Scan the returned child pages for any whose name starts with <id>- (e.g., 2451742-). If found, set WIKI_PATH to that existing page's path — do NOT use the newly generated slug.
mcp__ado__wiki_create_or_update_page
wikiIdentifier: <scm.wiki-id>
project: <scm.wiki-project>
path: "${WIKI_PATH}"
content: <contents of docs/wiki-page.md>
Wiki page created/updated at ${WIKI_PATH}If the sprint is Unknown, post under ${WIKI_ROOT}/Unsorted/${PAGE_TITLE} instead (apply the same ID-prefix lookup in Unsorted) and warn: Sprint unknown — page placed under Unsorted. Move it manually after confirming the sprint.
Read confluence.space-key and confluence.doc-root from .ai/config.yaml.
If confluence.space-key is not configured, print: Confluence space key not configured — wiki page saved locally only. and STOP wiki posting.
Find the doc root parent page:
mcp__atlassian__confluence_search
cql: "title = '<confluence.doc-root>' AND space = '<confluence.space-key>'"
Extract page_id from results → DOC_ROOT_ID. If not found, print: Doc root page "<confluence.doc-root>" not found in space <space-key> — create it in Confluence first. and STOP.
SPRINT = <sprint name from .sprint> # e.g., Sprint 42
mcp__atlassian__confluence_search
cql: "title = '<SPRINT>' AND ancestor = '<DOC_ROOT_ID>' AND space = '<confluence.space-key>'"
If not found, create it:
mcp__atlassian__confluence_create_page
space_key: "<confluence.space-key>"
title: "<SPRINT>"
body: "<h1><SPRINT></h1><p>Technical documentation for stories in <SPRINT>.</p>"
parent_id: "<DOC_ROOT_ID>"
Save the sprint page ID → SPRINT_PAGE_ID.
PAGE_TITLE = <id>-<slug-from-title> # e.g., 2357516-Enhance-PLP-Filter-Sticky
mcp__atlassian__confluence_search
cql: "title = '<PAGE_TITLE>' AND ancestor = '<SPRINT_PAGE_ID>' AND space = '<confluence.space-key>'"
Skills generate markdown (same as for ADO wiki). Before posting to Confluence, test if the MCP server accepts markdown directly by making a test call. If the page renders correctly with raw markdown, use markdown. If it renders as raw text, convert markdown to basic Confluence storage format (XHTML):
# Heading → <h1>Heading</h1>**bold** → <strong>bold</strong>*italic* → <em>italic</em>- item → <ul><li>item</li></ul>1. item → <ol><li>item</li></ol>`code` → <code>code</code><ac:structured-macro ac:name="code"><ac:plain-text-body><![CDATA[...]]></ac:plain-text-body></ac:structured-macro><table><tr><th>...</th></tr><tr><td>...</td></tr></table>[text](url) → <a href="url">text</a><p>...</p>7a. If page doesn't exist — create:
mcp__atlassian__confluence_create_page
space_key: "<confluence.space-key>"
title: "<PAGE_TITLE>"
body: "<converted content>"
parent_id: "<SPRINT_PAGE_ID>"
7b. If page exists — update:
mcp__atlassian__confluence_update_page
page_id: "<existing page ID>"
title: "<PAGE_TITLE>"
body: "<converted content>"
version_number: <current version + 1>
Wiki page created/updated in Confluence: <confluence.space-key> > <SPRINT> > <PAGE_TITLE>If the sprint is Unknown, create the page under DOC_ROOT_ID directly with an "Unsorted" parent page (create if needed), and warn: Sprint unknown — page placed under Unsorted. Move it manually after confirming the sprint.
## dx-doc-gen complete
**<Title>** (ADO #<id>)
- Sprint: <sprint name>
- Output: `<spec-dir>/docs/wiki-page.md`
- Sections: <list of included sections>
- Template: AEM (demo walkthrough) / Standard (technical doc)
- Screenshots: <count> referenced (<list of screenshot files found>)
- Committable screenshots: `git add <spec-dir>/demo/*.png <spec-dir>/prototype/*.png <spec-dir>/screenshots/*.png`
- Figma: Yes / No
- QA URLs: Yes / No
- Word count: <N> words
- Mode: Local / Wiki (posted to <wiki path>)
/dx-doc-gen 2416553 — Reads spec files, generates docs/wiki-page.md with Summary, What Changed and Why, Usage, Files Changed. Standard template.
/dx-doc-gen 2416553 (AEM project with authoring guide) — Detects demo/authoring-guide.md. Uses AEM template: Summary → Design Reference → What Changed and Why → QA Verification → Authoring (page URL + component + field table + dialog screenshot) → Frontend Preview → Figma Comparison → Files Changed. Screenshots use repo-relative paths.
/dx-doc-gen 2416553 (pipeline mode) — PIPELINE_MODE=true triggers wiki posting. Creates the sprint subfolder (Sprint 42) in the ADO wiki if it doesn't exist, then creates the wiki page at the configured doc root path. Summary includes git add command for committing screenshots.
"No spec files found — nothing to generate from"
Cause: The spec directory exists but contains no recognized files (explain.md, implement.md, etc.).
Fix: Run the requirements and planning pipeline first (/dx-req <id> or /dx-plan <id>). Even raw-story.md alone is enough for a basic page.
"docs/wiki-page.md already up to date — skipping"
Cause: The wiki page was already generated and the source files haven't changed.
Fix: Delete the existing docs/wiki-page.md and re-run, or modify one of the source spec files to trigger regeneration.
Wiki posting fails with "Wiki ID not configured"
Cause: scm.wiki-id is not set in .ai/config.yaml.
Fix: Add scm.wiki-id, scm.wiki-project, and scm.wiki-doc-root to your config. These can be found in ADO under Project Settings > Wiki.
demo/authoring-guide.md exists, use the AEM demo walkthrough template; otherwise use the standard template with Usage section.ai/specs/<id>-<slug>/... paths so screenshots can be committed to the repo and linked from ADO wikiwcmmode=disabled for FE demo.