From dx-core
Validate external requirements and create spec structure without ADO. Reads a requirements document, checks completeness, and generates explain.md + optional research.md. Use when you have requirements from a BA, Confluence page, or email instead of an ADO ticket.
npx claudepluginhub easingthemes/dx-aem-flow --plugin dx-coreThis skill is limited to using the following tools:
You read an external requirements document, validate its completeness, and create a spec directory with explain.md — the same structure that fetch + explain would produce, but from a standalone document instead of an ADO ticket.
Imports pre-existing spec documents (e.g., *spec.md, requirements.md) into Shipyard's PROJECT.md by parsing sections like name, goals, requirements; handles replace/merge.
Analyzes spec files for inconsistencies, missing information, ambiguities, and structure issues. Detects depth level (full-tech, detailed, high-level) and generates markdown/HTML reports.
Creates or updates SPEC.md documents from requirements, notes, or interview output, structuring into sections for goals, design, edge cases, security, testing, and success criteria. Use for feature specs.
Share bugs, ideas, or general feedback.
You read an external requirements document, validate its completeness, and create a spec directory with explain.md — the same structure that fetch + explain would produce, but from a standalone document instead of an ADO ticket.
The argument is a file path to a requirements document (markdown, text, or other readable format).
If no argument is provided, ask the user for the path.
Read the document contents.
Evaluate the document against this rubric (score each 0-2):
| Criterion | 0 (Missing) | 1 (Partial) | 2 (Complete) |
|---|---|---|---|
| What — what's being built/changed | Not stated | Vague description | Clear, specific description |
| Acceptance criteria — how to verify it works | None | Some criteria listed | Testable criteria for each requirement |
| Affected areas — which parts of the system change | Not stated | General area mentioned | Specific components/files/layers identified |
| Edge cases — what about errors, empty states, defaults | Not mentioned | Some noted | Key edge cases addressed |
Threshold: total >= 5 out of 8.
If below threshold:
/dx-req-import again."If at or above threshold, continue.
Create a short slug from the document's main topic (2-4 words, lowercase, hyphenated).
Example: "card grid layout" → card-grid-layout
mkdir -p .ai/specs/<slug>
Distill the requirements document into explain.md following the EXACT same format as /dx-req (Phase 3 — explain):
# <Title>
## What & Why
<2-3 sentences>
## Requirements
<Numbered list of concrete, testable requirements. One sentence each.>
## Changes by Area
<ONLY if requirements don't cover everything. Compact format.>
## Out of Scope
<1-3 bullets. OMIT if scope is unambiguous.>
## References
- Source: <original document path>
Apply the same writing principles as explain: ~50 line hard limit, one sentence per requirement, collapse overlapping sections, omit empty sections.
If the document mentions specific component names, classes, or files:
research.md with just:
Skip the full 4-agent research (user can run /dx-req manually for deeper analysis).
If no specific code references are found, skip research.md.
## Spec created from requirements
**<Title>**
**Directory:** `.ai/specs/<slug>/`
**Completeness score:** <X>/8
### Generated:
- explain.md — <N> requirements distilled
- research.md — <Y> files found (or "skipped — no code references")
### Next steps:
- Review `explain.md` — are the requirements accurate?
- `/dx-plan` — generate implementation plan
- `/dx-req` — deeper codebase analysis (if needed)
/dx-req-import docs/requirements/card-grid-layout.md — Reads the requirements document, scores it 6/8 (passes threshold), generates .ai/specs/card-grid-layout/explain.md with distilled requirements, and runs a lightweight codebase search for referenced component names.
/dx-req-import ~/Downloads/ba-notes.txt — Reads a plain-text BA document, scores it 3/8 (below threshold), prints specific gaps ("Missing: acceptance criteria, affected areas") and stops without creating any files.
/dx-req-import docs/feature-spec.md — Reads a detailed spec that mentions specific component classes, searches the codebase for those classes, and writes both explain.md and a lightweight research.md with discovered file paths.
"Document needs more detail before proceeding"
Cause: The requirements document scored below 5/8 on the completeness rubric.
Fix: Add the missing items listed in the score table (e.g., testable acceptance criteria, specific affected areas) and re-run /dx-req-import.
Spec directory uses slug instead of ID
Cause: This is expected behavior. Without an ADO ticket, the directory is named .ai/specs/<slug>/ instead of .ai/specs/<id>-<slug>/.
Fix: No fix needed. If you later create an ADO ticket, run /dx-req <id> to create the ID-prefixed directory and move your files.
Research.md not generated
Cause: The requirements document doesn't mention specific component names, classes, or files that can be searched.
Fix: Run /dx-req manually for a deeper codebase analysis after the spec is created.
.ai/specs/<slug>/ not .ai/specs/<id>-<slug>/.