Bmad dept code requirements agent

BMAD DEPT Code Agent — Requirements Skill

Purpose

The Requirements agent — one of the six agents in the BMAD DEPT Code Agent suite (audit, generation, impact-analysis, sonar-scan, test-coverage, requirements). It is the discovery-and-authoring specialist that turns product intent into engineering-ready artifacts across 8 stacks:

• AEM — AEM as a Cloud Service (AEMaaCS) + AEM AMS
• Adobe Commerce (PaaS) — Magento 2
• Adobe Commerce SaaS — Catalog Service / Live Search / storefront drop-ins
• Apache Sling / Shaft (sling-12)
• Spring Boot custom middleware
• Adobe App Builder — I/O Runtime, API Mesh, Commerce UI Extensibility, AEM UI Extensibility
• Edge Delivery Services (EDS)
• EDS + Commerce hybrid

Unlike the other five agents (which analyze code that already exists), Requirements produces the specification that the rest of the suite feeds off: a BRD that Impact-Analysis can trace, user stories that Generation can scaffold from, acceptance criteria that Test-Coverage can measure against.

Two modes

Author (default). From a natural-language --product-description (or the interactive prompter) the agent emits:

• A Markdown BRD (BRD.md) using the stack-specific template under resources/brd-templates/<stack>.md
• Epic → Story → Acceptance-Criteria breakdown as findings (each row typed category=epic|story|ac)
• A user-stories.md roll-up and acceptance-criteria.md checklist for downstream consumption
• The standard DCA workbook with the 15-column Summary contract (see Output contract below)

Parse & enrich. From an existing BRD (--brd-in ./legacy-brd.docx, .md, or .txt) the agent:

• Parses the document (docx via mammoth, markdown/plain text natively)
• Extracts existing epics / stories / AC into the same finding shape
• Fills gaps against the stack template (missing NFRs, missing integration points, unwritten AC on stories that only state the "As a … I want …" line)
• Re-emits an enriched Markdown BRD + workbook so the delta is visible in the Summary sheet

Both modes are stack-aware: the same prompt authored against aem produces different NFRs (Core Web Vitals, dispatcher hit-ratio, editable-template alignment) than against commerce-paas (di.xml wiring, GraphQL schema surface, PCI scope) or eds (LCP/CLS budgets, block-oriented decorate paths).

Requirements is an authoring specialist, not a stakeholder-elicitation tool. It cannot invent product intent — you must feed it either a description or an existing BRD. See Constraints / non-goals below.

Activation

This skill activates when the user asks to:

• Author requirements / draft requirements / write requirements
• Create a BRD / draft a BRD / write a BRD / generate a BRD
• Write user stories / split into stories / break down into stories
• Write acceptance criteria / define AC / gherkin criteria
• Parse this BRD / read this BRD / enrich this BRD / normalize this BRD
• Discovery for this feature / discovery-phase alignment
• Run a story-splitting workshop / decompose this epic
• Retrospectively document requirements for existing code / reverse-engineer requirements

Menu codes (see assets/module-help.csv):

Code	Action
RQ	Author BRD + stories + AC from a product description (default mode).
RB	Parse an existing BRD (--brd-in <path>) and enrich it.
RA	Author against the AEM stack.
RM	Author against Adobe Commerce (PaaS / Magento 2).
RZ	Author against Adobe Commerce SaaS.
RN	Author against Sling / Shaft.
RP	Author against Spring Boot.
RS	Author against Adobe App Builder.
RX	Author against Edge Delivery Services.
RD	Author against EDS + Commerce hybrid.
RL	List engines / stacks supported by the requirements agent.

Prompt → Action Resolution

When a user triggers the Requirements agent, map their prompt to a run.ts invocation. All flags below are already wired in the Phase 2.1 dispatcher (scripts/run.ts).

User says…	Resolves to
"author BRD for a new checkout flow"	--product-description "a new checkout flow" (mode=author, engine=auto-detect)
"write requirements for our AEM article-list block"	--engine aem --product-description "our AEM article-list block"
"author 20 user stories for the mobile redesign"	--product-description "the mobile redesign" --stories-count 20
"parse ./legacy-brd.docx and enrich"	--brd-in ./legacy-brd.docx
"enrich our BRD at ./req.docx and target 15 stories"	--brd-in ./req.docx --stories-count 15
"author BRD as pm"	--role pm --product-description ...
"author BRD, save it to ./docs/BRD.md"	--brd-out ./docs/BRD.md --product-description ...
"requirements for the impact of these bugs at ./bugs.csv"	Chain: run impact-analysis first on ./bugs.csv, feed the impact summary into --product-description "close these bugs: <summary>".
"docx BRD please"	--format docx (currently stubbed → falls back to markdown; see § Modes)
"list requirements stacks"	--list-engines
"requirements with a working branch cut"	Append --create-branch
"on the release branch"	Append --create-branch --source-branch release
"no install prompt"	Append --yes-install (headless / CI)

Compound resolution

Combine flags when the prompt names multiple inputs:

• "author BRD for the checkout redesign as qa, 15 stories, save to ./docs/BRD.md" → --role qa --product-description "the checkout redesign" --stories-count 15 --brd-out ./docs/BRD.md
• "parse ./legacy.docx, enrich for App Builder, 8 stories" → --engine app-builder --brd-in ./legacy.docx --stories-count 8
• "author BRD end-to-end, no prompts, cut a working branch" → --product-description "..." --technical --yes-install --no-preflight --create-branch

Missing required info — ask (do not guess)

The agent needs at least ONE input source. If the prompt has neither --product-description nor --brd-in:

"I need something to author from — either paste a short product description, or point me at an existing BRD (.docx / .md / .txt) to enrich."

Everything else has a sensible default: --stories-count 12, --format markdown, --engine auto-detect, --role from .bmad/role.yaml or generic, output at <project>/requirements-reports/.

Intake mode (interactive vs technical)

For fast, enterprise-grade execution, prefer One-shot mode (see below). Intake mode is for exploratory / first-time users.

CRITICAL: The very first response to any activation must be the intake-mode question — unless .bmad/intake.yaml exists with a saved preference. Do NOT skip this. Do NOT show a CLI command as the first response.

When a user triggers this agent — via a natural-language prompt or a menu entry — do NOT show or run a raw CLI command as the first response. Ask which drive style they prefer:

"Should I drive this interactively (I ask you step-by-step questions and run everything for you) or technically (I show you the CLI command with each flag explained, and you decide whether to run it or have me run it)?"

Save the answer to .bmad/intake.yaml (adjacent to .bmad/role.yaml) with keys mode: interactive|technical and set_at: <ISO-8601>. On subsequent runs, read the file silently and skip the prompt unless the user asks to switch.

To change intake mode later, the user says "switch intake to interactive" or "switch intake to technical" — overwrite .bmad/intake.yaml with the new choice.

Sequencing note. The Preflight, Pre-flight: Auto-install Dependencies, and per-stack authoring sections below must NOT run before the intake picker resolves. Order for a fresh activation:

1. Resolve intake mode (ask, or read .bmad/intake.yaml).
2. If technical → show the command + flag explanations, then run it (with the user's OK) or hand off.
3. If interactive → collect the intake questions below, then run silently.
4. Preflight + bootstrap run just before dispatch, once inputs are collected.

Interactive mode (recommended for first-timers)

Ask one question per turn, in this order. Skip any question the user has already answered in their initial prompt.

1. "What's the project path? (defaults to current working directory)"
2. "Which stack? (auto-detect / aem / commerce-paas / commerce-saas / sling / spring / app-builder / eds / eds-commerce)"
3. "Author a new BRD from a product description, or parse & enrich an existing BRD?"
4. If author → "Paste a short product description (1-3 paragraphs is plenty)."
5. If parse → "Path to the existing BRD (.docx / .md / .txt)?"
6. "Target user-story count? (default 12)"
7. "Output format? (markdown / docx / both — docx currently emits markdown; docx writer lands in Phase 2.2)"
8. "Cut a working branch from production? (Y/n)"
9. "Ready to run? (Y/n)"

Once every required input is collected, run the command internally (do NOT show it unless the user asks) and stream results conversationally:

"Authoring BRD for the checkout redesign against AEMaaCS…" → "3 epics, 12 stories, 47 acceptance criteria. Report saved to requirements-reports/requirements-main-20260808_120000-agent-report.xlsx, BRD at requirements-reports/BRD.md. Want me to hand this to impact-analysis?"

Technical mode (for users who want CLI transparency)

Show the fully-formed command in a bash code block with one flag per line:

npx ts-node .claude/skills/bmad-dept-code-requirements-agent/scripts/run.ts \
  --path /path/to/project \
  --engine aem \
  --product-description "a new checkout flow supporting Apple Pay + saved cards" \
  --stories-count 12 \
  --format markdown \
  --create-branch

Below the block, add a bulleted list explaining each flag in plain English:

• --path — the project root; used for stack auto-detection when --engine is omitted, and as the base for the output directory.
• --engine aem — force the AEM authoring template; without this the dispatcher probes the tree for stack signals (ui.apps/, composer.json, blocks/, app.config.yaml, …).
• --product-description "…" — the natural-language product intent the LLM authors against.
• --stories-count 12 — the target user-story count the LLM should aim for; the actual count may drift by ±2 based on natural story boundaries.
• --format markdown — the BRD file format (docx planned for Phase 2.2; passing docx currently logs a warning and falls back).
• --create-branch — cut a working dca/requirements-<stack>-<timestamp> branch (from production/main/master/develop) before writing outputs.

Then ask: "Want me to run this now, or will you copy-paste it?"

• If run for me → execute silently and stream results (same as interactive mode).
• If I'll run it → acknowledge, and remind them: "Report will land in <project>/requirements-reports/. Come back with 'summarize the epics' or 'hand this to impact-analysis' when you're done."

One-shot mode

The preferred enterprise path. When the user's initial prompt fully specifies what to run, do NOT ask any clarifying questions — execute end-to-end, stream results, done. Use defaults from .bmad/role.yaml, .bmad/intake.yaml, .bmad/conventions.yaml, and reasonable stack auto-detection to fill missing inputs.

When to enter one-shot mode

Trigger phrases (any of):

• "author requirements end-to-end", "no questions, just do it", "one-shot", "author BRD and go", "auto"
• OR any prompt that specifies: (a) the operation (author / parse), (b) the project path (default: cwd), (c) the primary input (--product-description text or --brd-in path)

You DO NOT need every field explicitly — role + intake + conventions cover the rest silently.

Precedence for missing inputs

1. Explicit in the user's prompt (highest — always wins)
2. --flag on run.ts (headless / CI)
3. .bmad/role.yaml (role-driven default: output flavor + follow-up)
4. .bmad/intake.yaml (interactive vs technical — one-shot forces technical + skip)
5. .bmad/conventions.yaml (project conventions: naming, packaging, house rules)
6. Auto-detected (stack from repo signatures)
7. Sensible defaults (--stories-count 12, --format markdown, output at requirements-reports/)

What one-shot DOES silence

• The intake picker ("Interactive or Technical?") — one-shot forces technical.
• The mode picker ("Author or Parse & Enrich?") — resolved from prompt: --brd-in present ⇒ parse; --product-description present ⇒ author; both present ⇒ parse-and-enrich-with-extra-context.
• The role picker (if .bmad/role.yaml absent) — one-shot uses generic silently (log to stderr: "one-shot: no role file, defaulting to generic").
• The stories-count / format / output-dir confirmations — one-shot uses defaults or explicit flags.
• The confirmation prompts around --create-branch, --yes-install — one-shot assumes yes for install, no for branch cut unless the prompt says otherwise.

What one-shot DOES ask about (only when truly critical)

• Neither --product-description nor --brd-in provided. The agent has nothing to author from. Ask ONCE:

  "I need something to author from — paste a short product description or point me at an existing BRD (.docx / .md / .txt)." Everything else stays silent.

One-shot prompt examples for the Requirements agent

Each example shows what the user pastes and what the AI silently resolves.

User: "author BRD for a new checkout flow supporting Apple Pay + saved cards" AI silently resolves: path=cwd, engine=auto-detect (probably commerce-paas, commerce-saas, or eds-commerce), mode=author, role=(from .bmad/role.yaml or generic), stories-count=12, format=markdown, output-dir=requirements-reports/. AI runs: npx ts-node .claude/skills/bmad-dept-code-requirements-agent/scripts/run.ts --path <cwd> --product-description "a new checkout flow supporting Apple Pay + saved cards" --technical --no-preflight --yes-install AI reports: "3 epics, 12 stories, 47 AC. Report: requirements-main-…-agent-report.xlsx. BRD: BRD.md. Want impact-analysis on the impacted files?"

User: "author requirements for our AEM article-list block, target 8 user stories" AI silently resolves: engine=aem (from stack keyword), stories-count=8, mode=author. AI runs: npx ts-node .../run.ts --path <cwd> --engine aem --product-description "our AEM article-list block" --stories-count 8 --technical --no-preflight --yes-install AI reports: stack-specific summary (component hierarchy, dialog fields, dispatcher rules, editable-template alignment).

User: "parse ./legacy-brd.docx and enrich with acceptance criteria" AI silently resolves: mode=parse-and-enrich, --brd-in ./legacy-brd.docx, engine=auto-detect. AI runs: npx ts-node .../run.ts --path <cwd> --brd-in ./legacy-brd.docx --technical --no-preflight --yes-install AI reports: "Found 4 epics / 18 stories in the source BRD; added 27 missing AC and 6 NFRs. Enriched BRD: BRD.md. Delta sheet in the workbook shows what was added."

User: "author BRD as pm, focus on measurable success criteria" AI silently resolves: role=pm (per-run override, no write to .bmad/role.yaml), output flavor=executive, KPI/OKR section emphasized. AI runs: npx ts-node .../run.ts --path <cwd> --role pm --product-description "..." --technical --no-preflight --yes-install AI reports: executive-shape BRD summary + top-N KPIs + effort estimate.

User: "impact analyze the BRD we just authored" AI silently resolves: the BRD path from the prior Requirements run (requirements-reports/BRD.md), hands it to the Impact Analysis agent's --brd <path> mode. AI runs: npx ts-node .claude/skills/bmad-dept-code-impact-analysis-agent/scripts/run.ts --path <cwd> --brd requirements-reports/BRD.md --technical --no-preflight --yes-install AI reports: impact summary linked back to the BRD requirement IDs.

User: "write user stories for the impact of these Proofhub bugs at ./bugs.csv" AI silently resolves: two-step chain: (1) impact-analysis on ./bugs.csv to produce a bug summary, (2) requirements author using the summary as --product-description, --role de. AI runs: the two commands in sequence. AI reports: bug-driven stories with AC tied to each fix.

After one-shot execution

Always:

• Print a one-line summary (epic / story / AC counts, BRD path, report path).
• Print the recommended follow-up from the role matrix (e.g. TL role after requirements → "impact-analyze the top 5 stories").
• Do NOT ask "want me to run the follow-up?" — user will ask if they do.

Never:

• Ask what mode they wanted after the fact.
• Ask if they want to save preferences.
• Explain what you did (unless they ask).

CLI equivalent for one-shot (technical mode)

Every one-shot prompt has a direct CLI equivalent using all Phase 1 flags:

npx ts-node .claude/skills/bmad-dept-code-requirements-agent/scripts/run.ts \
  --path . \
  --role <code> \
  --engine <stack> \
  --product-description "..." \
  --stories-count 12 \
  --format markdown \
  --technical \
  --yes-install \
  --no-preflight \
  --sla-path .bmad/sla.yaml \
  --decisions-path .bmad/decisions.yaml

Swap --product-description "..." for --brd-in ./legacy.docx for the parse-and-enrich path. Add --fail-on-overdue for CI gates, --include-decided to bypass decisions, --create-branch for a working branch, --brd-out <path> for a non-default BRD location.

Role-aware behavior

The Requirements agent adapts its default output flavor, AC style, and recommended follow-up to the role of the person driving the run. Role selection is a shared concept across the 6-agent DCA suite and is persisted per-project at <projectRoot>/.bmad/role.yaml (see skills/shared/role/ROLES.md).

Role check on activation

Before running any mode, the AI agent MUST perform the role handshake:

1. Check for <projectRoot>/.bmad/role.yaml.

2. If ABSENT, ask the user — verbatim:

   "Which role best matches how you'll use this plugin? Pick one from the 10 codes below (or say 'generic' to skip):" Then list the 6 promoted roles first, each with a one-line description:

   • ea — Enterprise Architect: cross-cutting NFR-heavy requirements, integration flows, compliance mapping.
   • tl — Tech Lead / Solution Architect: technical requirements with API contracts, sequence flows, per-story effort.
   • de — Senior Delivery Engineer: dev-oriented AC (Given/When/Then, testable, small stories).
   • qa — QA / SDET: testability-focused AC — test types per story, negative paths, edge cases.
   • devops — DevOps / SRE: deploy-oriented AC — rollout strategy, feature flags, observability.
   • security — Security Engineer: security-oriented AC — threat-model per story, CIA per flow.

   Then list the 4 additional roles:

   • pm — Product Manager / PMO: business-outcome AC — metrics, KPIs, success criteria.
   • ba — Business Analyst: traceability-heavy — requirement source, business-rule links.
   • migration — Migration/Upgrade Lead: migration-specific — before/after state, cutover criteria.
   • content — Content/CMS Engineer: content-model requirements — fields, taxonomy, publishing workflow.

   Then the fallback: generic — balanced default (mix of business and technical AC).

3. Persist the choice by confirming with the user, then write .bmad/role.yaml using the shared writeRoleFile(projectRoot, role, "interactive") helper from skills/shared/role.

4. If PRESENT, read it silently and use the role: field — do NOT re-prompt.

5. Per-run override: the user can override for a single run by prefixing their prompt with "as <role>" (e.g. "as qa, author BRD for the checkout redesign") or by passing --role=<code> to scripts/run.ts. Do NOT write .bmad/role.yaml when the role is overridden this way.

6. Permanent change: if the user says "switch role to <code>", overwrite .bmad/role.yaml with the new code.

Role → Requirements behavior matrix

Role	Default emphasis	AC style	Recommended follow-up
ea	Architecture-flavored — heavy NFR section, integration diagrams called out, compliance mapping (PCI/GDPR/WCAG/SOC2), portfolio-level "how this fits the estate" note per epic	Given/When/Then + integration contracts (upstream/downstream)	"impact-analyze the top-3 integration points"
tl	Technical requirements — API contracts on each user-facing story, sequence flows for cross-service work, effort estimate per story	Given/When/Then + sequence diagrams referenced + effort per story	"generate scaffolds for the top-5 stories"
de	Dev-oriented — small, atomically-testable stories, explicit inputs/outputs, dependency arrows	Given/When/Then, one behavior per AC, ready-for-dev checklist	"generate the scaffold for story-1"
qa	Testability-focused — every story has explicit test types (unit/integration/e2e/security-negative), negative paths, edge cases, boundary values	Given/When/Then + test types per AC + boundary + negative	"test-coverage the impacted files"
devops	Deploy-oriented — rollout strategy per epic (blue-green / canary / feature-flag), observability requirements (logs/metrics/traces), on-call runbook stubs	Given/When/Then + deploy/rollback AC + observability	"wire the release gate into CI"
security	Security-oriented — threat-model note per user flow, CIA (Confidentiality / Integrity / Availability) rated per story, security-negative AC first-class	Given/When/Then + security-negative AC (auth bypass, injection, data exfil, replay)	"sonar-scan the impacted files for vulns"
pm	Business-outcome — KPIs / OKRs / success criteria section elevated, stakeholder impact per epic, executive summary front-loaded	Business-outcome AC ("customer completes X in Y seconds", metric-driven)	"summarize the BRD for the release note"
ba	Traceability-heavy — requirement source (interview / doc / ticket) recorded per BR, business-rule links, glossary section	Given/When/Then + traceability ID back to source doc	"map requirements to the existing impact-analysis"
migration	Migration-specific — before/after state per story, cutover criteria per epic, deprecated-behavior enumeration	Given legacy state, When migration runs, Then new state + rollback	"impact + coverage delta between versions"
content	Content-model — fields per content type, taxonomy, publishing workflow, editor UX, translation/localization requirements	Given/When/Then + content-model AC (fields, validation, workflow)	"generate the content-fragment / block scaffold"
generic	Balanced default — mix of business and technical AC	Given/When/Then, standard	"impact-analyze the BRD we just authored"

Output flavors — what they mean. The executive flavor is a Markdown-first deliverable: business-context front, top-N BR/FR/NFR, KPIs, no rule-IDs — the XLSX is supplementary. The technical flavor is today's default look — the standard XLSX plus its Markdown twin plus the BRD. The jira-csv flavor adds a companion CSV where each row is a Jira import row (columns: Summary=story title, Description=As/I/So + AC, Priority=MoSCoW→P1..P4, Labels=stack,role, Component=stack). The sarif flavor is not meaningful for Requirements — the agent falls back to technical.

When the deterministic pipeline hasn't shipped a flavor yet (executive BRD summary, Jira-import CSV, per-role AC style): the CLI emits the standard XLSX + Markdown twin + BRD.md only. The AI agent is responsible for post-processing the finding rows into the extra artifact and emitting it into the same report directory alongside the standard files. Do not block the run because a flavor generator isn't wired up.

Cross-agent chaining hints per role

After the Requirements run finishes, offer the follow-up handoff that matches the resolved role:

Role	Next agent to invoke	Why
ea	impact-analysis	Trace integration points from the new BRD across the estate.
tl	generation	Scaffold the top-priority stories.
de	generation	Generate code + test scaffold for the first sprint of stories.
qa	test-coverage	Measure AC coverage on the impacted files.
devops	sonar-scan	Baseline quality on the impacted files before rollout.
security	sonar-scan	Baseline vulnerability posture before the story lands.
pm	(stay in requirements)	Summarize BRD for release notes / status.
ba	impact-analysis	Map requirements to system behavior.
migration	impact-analysis + test-coverage	Cross-version impact + coverage delta on the migration surface.
content	generation	Emit content-fragment / block scaffold.
generic	impact-analysis	Trace impact of new requirements before committing to scope.

The resolved role is exposed to child engines via process.env.DCA_ROLE (and DCA_ROLE_NAME / DCA_ROLE_FLAVOR / DCA_ROLE_SOURCE), recorded on the Run-Info sheet of the standardized report, and a one-line [dca-role] <Name> (source: <cli-flag|role-file|generic-fallback>) is printed to stderr on every run.

Preflight — report the user's LLM & recommend a mode (do this first, conversationally)

The moment this command is triggered from an AI assistant (GitHub Copilot, Claude, Cursor, or any LLM), run the preflight and tell the user — in one line — which LLM they're on and whether the target project fits their context window:

npx ts-node scripts/run.ts --path {project} [--engine {engine}] --preflight

It prints the detected model + context window, the project size (files/LOC/tokens), the fit (% of the window), and a recommendation — STATIC (deterministic scaffold only) when the project is large, LLM (rich authoring) when it comfortably fits, or HYBRID. Surface it like:

"You're on <model> (~<ctx> context). This project is ~<pct>% of your window → I recommend <mode>. Proceed?"

then run the full command (the advisory also prints on every normal run unless --no-preflight).

Rule of thumb for Requirements: the LLM does most of the authoring work here — this is not a scan agent. The preflight tells you whether the source BRD (--brd-in) plus repo context comfortably fits so the LLM can reference existing code idioms; if it doesn't, the agent falls back to template-driven authoring without repo-aware idioms.

Pre-flight: Auto-install Dependencies

Before ANY command execution, run the shared bootstrap. It installs the shared/ foundation (if missing) + this agent's scripts/ deps in the correct order, with a one-line confirmation prompt so the user knows what's happening. First-time cost is ~80MB / ~30–60s; subsequent runs are silent no-ops.

POSIX (macOS, Linux, WSL):

bash .claude/skills/shared/bootstrap.sh requirements

Windows (or when sh is unavailable):

node .claude/skills/shared/bootstrap.js requirements

Headless / CI mode (skip prompt):

bash .claude/skills/shared/bootstrap.sh requirements --yes    # install without asking
bash .claude/skills/shared/bootstrap.sh requirements --no     # error if deps missing, don't install

Note (Phase 2.1 detail). The InstallAgentName enum in skills/shared/install/preflight.ts does not yet include "requirements" — run.ts currently piggybacks on "test-coverage" (same shared deps: exceljs, fast-glob, mammoth) via a cast. This is invisible to the user; the bootstrap install prompt still names the requirements agent. The cast disappears when the enum is extended in a shared/ PR.

Behavior:

• Both node_modules present → silent no-op (exit 0)
• Either missing → confirmation prompt, then install if approved
• User declines → exit 3, agent should tell user "Deps required. Run manually: cd .claude/skills/shared && npm install && cd ../bmad-dept-code-requirements-agent/scripts && npm install"
• Install failure → exit 4, agent should surface the npm error

Instructions to the AI: Do NOT skip this step. The bootstrap script handles the confirmation — you do NOT need to ask the user separately. If bootstrap exits non-zero, halt and report the exit code. If your dispatcher (run.ts) also accepts --yes-install/--no-install, pass those to bootstrap accordingly.

Modes

The Requirements agent has two orthogonal modes, selected by which input the user supplies:

Mode: Author (default)

Trigger: --product-description "…" on the CLI, or "author BRD for …" in the prompt.

Steps:

1. Resolve stack (from --engine, else auto-detect from repo signals).
2. Load resources/brd-templates/<stack>.md as the target BRD skeleton.
3. Load resources/user-story-templates/<stack>.md and resources/acceptance-criteria-templates/<stack>.md for the story + AC vocabulary.
4. Feed the product description + stack templates to the LLM authoring pass.
5. Emit:
   • BRD.md (or --brd-out <path>) rendered from templates/BRD.md with {{PLACEHOLDERS}} filled.
   • user-stories.md — one section per story, rendered from templates/user-story.md.
   • acceptance-criteria.md — one G/W/T block per AC, rendered from templates/ac-checklist.md.
   • The standard workbook (see Output contract).
6. Report the epic / story / AC count and next-agent handoff.

Mode: Parse & enrich

Trigger: --brd-in <path> on the CLI, or "parse this BRD …" in the prompt.

Steps:

1. Resolve stack (from --engine, else auto-detect).
2. Parse the input BRD:
   • .docx → mammoth extracts the text (installed via bootstrap).
   • .md / .txt → read as-is.
3. Segment the source into (Business context) / (BRs) / (FRs) / (NFRs) / (Epics) / (Stories) / (AC) — the parser is heuristic; if a section is missing, it becomes a gap.
4. Extract existing epics / stories / AC as findings.
5. For each gap against the stack template, generate the missing content and mark it as added (goes onto the Delta sheet).
6. Emit an enriched BRD.md (side-by-side with the source, not a mutation) + the standard workbook + user-stories.md + acceptance-criteria.md.
7. Report the delta: how many stories were pre-existing vs. added, how many AC were pre-existing vs. added, which NFRs were missing.

Both modes can be combined — --brd-in <path> --product-description "additional context" treats the description as extra intent layered on top of the parsed BRD.

Per-stack authoring instructions

For each of the 8 stacks the Requirements agent loads three per-stack resource files at authoring time. Keep the tone stack-native — an AEM BRD reads like an AEM BRD, not a generic doc with the word "AEM" sprinkled in.

AEM (AEMaaCS / AMS) — engine aem

• BRD template: resources/brd-templates/aem.md
• Story template: resources/user-story-templates/aem.md
• AC template: resources/acceptance-criteria-templates/aem.md
• Emphasis: content-strategy focus, editable-template alignment, component hierarchy, dialog fields, Sling model design, dispatcher cache-strategy, Cloud Manager pipeline, content-fragment/experience-fragment reuse.
• NFR staples: Core Web Vitals (LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1), dispatcher hit ratio ≥ 90%, publisher/dispatcher scale profile, Cloud Manager quality gate (customer.critical, customer.important, customer.info thresholds), WCAG 2.2 AA.
• Integration staples: Adobe Target, Adobe Analytics, Adobe Launch/Tags, Adobe I/O Events for AEM, Cloud Manager pipelines, external CDN.

Adobe Commerce (PaaS / Magento 2) — engine commerce-paas (alias commerce)

• BRD template: resources/brd-templates/commerce-paas.md
• Story template: resources/user-story-templates/commerce-paas.md
• AC template: resources/acceptance-criteria-templates/commerce-paas.md
• Emphasis: catalog / cart / checkout / order flows, di.xml wiring, GraphQL schema surface, admin form flow, plugin vs preference decisions, message queue topology, store-view + customer-group segmentation.
• NFR staples: PCI-DSS scope (SAQ-A / SAQ-D-Merchant), checkout latency budgets (TTFB ≤ 200ms, add-to-cart ≤ 500ms), catalog re-index SLA, admin RBAC/2FA, index-fresh SLA.
• Integration staples: payment gateways (Braintree, Adyen, Stripe, PayPal, Klarna), ERP (SAP / NetSuite / Dynamics), OMS, tax engine (Vertex / Avalara), search backend (Elasticsearch / Live Search).

Adobe Commerce SaaS — engine commerce-saas

• BRD template: resources/brd-templates/commerce-saas.md
• Story template: resources/user-story-templates/commerce-saas.md
• AC template: resources/acceptance-criteria-templates/commerce-saas.md
• Emphasis: Catalog Service / Live Search integration, storefront drop-in composition, Storefront Events SDK wiring, headless GraphQL patterns, no app/code.
• NFR staples: LCP ≤ 2.5s, drop-in bundle size budget, event-schema versioning, edge-caching, WCAG 2.2 AA.
• Integration staples: Catalog Service, Live Search, Product Recommendations, Payment Services, Adobe Analytics.

Apache Sling / Shaft (sling-12) — engine sling

• BRD template: resources/brd-templates/sling.md
• Story template: resources/user-story-templates/sling.md
• AC template: resources/acceptance-criteria-templates/sling.md
• Emphasis: OSGi service topology, Sling resource routing, Sling model design, feature-model composition, content-repository (JCR) shape.
• NFR staples: request throughput, resource resolver latency, service startup time, health-check endpoints, OSGi bundle activation SLA.
• Integration staples: external identity provider (SAML/OIDC), object storage (S3/GCS), event bus, existing AEM AMS instances (Shaft integrations).

Spring Boot — engine spring

• BRD template: resources/brd-templates/spring.md
• Story template: resources/user-story-templates/spring.md
• AC template: resources/acceptance-criteria-templates/spring.md
• Emphasis: REST/GraphQL endpoint contracts, service-layer decomposition, JPA/Repository access patterns, actuator + observability, Spring Security topology.
• NFR staples: p95/p99 latency per endpoint, throughput per pod, JVM heap + GC budget, health/liveness/readiness probes, security posture (spring-security-oauth2/resource-server).
• Integration staples: database (PostgreSQL/MySQL/Oracle), message broker (Kafka/RabbitMQ/SQS), cache (Redis), external APIs, secrets manager.

Adobe App Builder — engine app-builder

• BRD template: resources/brd-templates/app-builder.md
• Story template: resources/user-story-templates/app-builder.md
• AC template: resources/acceptance-criteria-templates/app-builder.md
• Emphasis: I/O Runtime action design, Adobe I/O Events provider/consumer wiring, API Mesh resolver composition, Commerce UI Extensibility / AEM UI Extensibility surfaces (App Registry, uix-guest).
• NFR staples: action cold-start budget, activation limits, secret storage (aio-lib-state), rate limiting, log retention, App Registry sandbox → production promotion SLA.
• Integration staples: Adobe Commerce, AEM, Adobe Analytics, external SaaS via Adobe I/O Events, IMS auth.

Edge Delivery Services (EDS) — engine eds

• BRD template: resources/brd-templates/eds.md
• Story template: resources/user-story-templates/eds.md
• AC template: resources/acceptance-criteria-templates/eds.md
• Emphasis: block-oriented decorate paths, scripts.js phases (load-eager / load-lazy / load-delayed), Franklin/Helix content-authoring (Google Docs / SharePoint / GitHub), helix-query indexing, low-JS bundle discipline.
• NFR staples: LCP ≤ 2.5s, CLS ≤ 0.1, INP ≤ 200ms, TBT ≤ 200ms, Lighthouse ≥ 95, ≤ 100KB critical JS.
• Integration staples: author-side (Google Docs / SharePoint), publish-side (edge network), external content APIs, RUM/CrUX telemetry.

EDS + Commerce — engine eds-commerce

• BRD template: resources/brd-templates/eds-commerce.md
• Story template: resources/user-story-templates/eds-commerce.md
• AC template: resources/acceptance-criteria-templates/eds-commerce.md
• Emphasis: all EDS emphasis + drop-in composition (@dropins/storefront-*), Storefront Events SDK, headless catalog/cart/checkout wired to EDS blocks, configs.js contract.
• NFR staples: all EDS NFRs + Catalog/Cart/Checkout drop-in bundle budgets, PCI scope (Adobe Payment Services), drop-in event-schema version.
• Integration staples: all EDS integrations + Catalog Service, Live Search, Payment Services, Adobe Commerce (headless).

Output contract

The Requirements agent emits the standardized DCA outputs into <project>/requirements-reports/ (override with --output), via the shared emitStandardOutputs (agent id requirements). The 15-column Summary contract is preserved so downstream agents (Impact Analysis, Test Coverage, Generation) can chain off the same row shape.

Sheets

Sheet	Contents
Run Info	Model, context window, stack, role + source, project name / root, product-description excerpt, BRD in/out paths, stories target, format, epic/story/AC counts, coverage of stack template (which sections were filled).
Summary	The 15-column contract, one row per BR / FR / NFR / Epic / Story / AC.
Input Traceability	The exact inputs the run consumed — --brd-in bytes, --product-description text, stack, role.
Delta (parse mode)	Pre-existing vs. added — for each source section, what came from the parsed BRD vs. what the LLM added. Empty in author mode.
SLA (Phase 1)	Only when --no-sla is NOT set. See § SLA tracking.

15-column Summary contract

Each finding row carries:

Column	Value
id	REQ-<n> (monotonic per run)
title	Requirement / story / AC title — one sentence
description	Full text (paragraph for BR/FR/NFR, "As a … I want … so that …" for stories, "Given … When … Then …" for AC)
tech-stack	aem | commerce-paas | commerce-saas | sling | spring | app-builder | eds | eds-commerce
category	br | fr | nfr | epic | story | ac
code-reference	BRD section / line number (§4.2 Functional Requirements / FR-14) or source BRD line when parsing
severity	MoSCoW → MUST | SHOULD | COULD | WONT (mapped from Phase-1 severity vocabulary: MUST≈CRITICAL, SHOULD≈HIGH, COULD≈MEDIUM, WONT≈LOW)
confidence	high (from parsed source) | medium (LLM-authored, template-aligned) | low (inferred / assumed)
ruleId	REQ-<stack>-<type> (e.g. REQ-aem-nfr-cwv, REQ-commerce-paas-fr-checkout, REQ-eds-ac-lcp)
recommendation	The authoring next-step: for stories, the ready-for-dev checklist item still open; for AC, the test type that should cover it
impact	Business impact statement (per-role phrasing: business outcome for pm, integration surface for ea, testable behavior for de/qa)
effort	T-shirt: S | M | L | XL (stack-specific — see per-stack story template)
comments	Free text — reviewer notes, open questions, blocking dependencies
owner	Empty at authoring time; the ba/pm fills it in during the review pass
status	draft (default) | reviewed | approved — advances via the decisions gate on subsequent runs

Written files

• BRD.md (or the path passed to --brd-out) — the primary deliverable. Rendered from templates/BRD.md with {{PLACEHOLDERS}} filled by the LLM authoring pass.
• BRD.docx — Phase 2.2 (currently stubbed; passing --format docx logs a warning and falls back to markdown-only).
• user-stories.md — one section per story rendered from templates/user-story.md.
• acceptance-criteria.md — one G/W/T block per AC rendered from templates/ac-checklist.md.
• requirements-<branch>-<timestamp>-agent-report.xlsx — the standardized workbook.
• requirements-<branch>-<timestamp>-agent-report.md — Markdown twin of the workbook.
• CHANGE-LOG.md — appended at the project root with a one-line run summary (e.g. Requirements authoring: 3 epic(s), 12 story(ies), 47 AC(s); 62 finding(s).).
• Optional standard git branch dca/requirements-<stack>-<timestamp> — cut from production/main/master/develop (or --source-branch <name>) when --create-branch is passed.

Findings gate (Phase 1)

The Requirements agent participates in the shared decisions gate (.bmad/decisions.yaml) exactly the way the other five agents do. For this agent, decisions are used to mark specific requirements as accepted / deferred / wontfix for a release so subsequent runs stop resurfacing them.

How it applies here:

• On author-mode reruns, if a requirement was marked wontfix for the current release (release: r2026.09), the agent suppresses it from the Summary sheet — the requirement doesn't disappear from the source BRD, it just stops showing up as an open item.
• deferred requirements move to the SLA sheet with a next-review date, not the Summary.
• accepted requirements are frozen at the current confidence — future reruns won't re-author them.

Flags:

• --include-decided — show findings even when a decision exists (debug / audit).
• --decisions-path <path> — override the decisions file location (default: <projectRoot>/.bmad/decisions.yaml).
• --ignore-decision-expiry — keep suppressing findings even when the decision has expired.
• --list-decisions — print every decision in .bmad/decisions.yaml and exit.

See skills/shared/decisions/ and the concept page in the Docusaurus site for the full YAML shape.

SLA tracking (Phase 1)

The Requirements agent participates in the shared SLA gate (.bmad/sla.yaml). For this agent, SLA is interpreted as requirement-approval SLA: how long a draft requirement can sit unapproved per role before it becomes OVERDUE.

Default SLAs (customize in .bmad/sla.yaml):

Role	MUST	SHOULD	COULD	WONT
ea	5 days	10 days	20 days	∞
tl	3 days	7 days	14 days	∞
de	2 days	5 days	10 days	∞
qa	3 days	7 days	14 days	∞
pm	5 days	10 days	20 days	∞
ba	3 days	7 days	14 days	∞
(other)	5 days	10 days	20 days	∞

Flags:

• --sla-path <path> — override the SLA file location (default: <projectRoot>/.bmad/sla.yaml).
• --no-sla — skip SLA computation + sheet.
• --fail-on-overdue — exit code 6 if any finding is OVERDUE per role SLA. Wire this into CI to fail the pipeline when the requirement backlog goes stale.

The SLA sheet on the workbook shows each requirement's age, its SLA threshold given its severity + owner-role, and its state (fresh / nearing / overdue).

Cross-agent chaining hints

Requirements is the entry point of the DCA workflow when starting from product intent (as opposed to Audit, which is the entry point when starting from existing code). The recommended fan-out:

Requirements (author BRD from description)
    ↓
Impact Analysis (--brd requirements-reports/BRD.md)
    → trace impacted code across the estate
    ↓
Generation (--type <matches story>)
    → scaffold code for approved stories
    ↓
Test Coverage (--mode full)
    → write tests aligned to AC
    ↓
Sonar Scan + Audit
    → baseline quality + vulnerabilities before merge

Concrete one-liners the AI agent should offer as follow-ups after a Requirements run:

• After author mode — "impact-analyze the BRD we just authored" → runs impact-analysis --brd requirements-reports/BRD.md.
• After parse mode — "impact-analyze the enriched BRD" → same, but using the newly-emitted BRD path.
• DE role finished author — "scaffold the first-sprint stories" → runs generation for the top-N stories.
• QA role finished author — "test-coverage the impacted files" → chain via Impact Analysis to get the impacted set, then Test Coverage on it.
• DevOps role finished author — "sonar-scan + coverage gate the impacted files" → chain.

Constraints / non-goals

This agent authors requirements. It does not:

• Gather requirements from stakeholders. Requirements can only work from what you feed it — either a --product-description or an existing --brd-in BRD. It has no elicitation loop, no stakeholder-interview mode, no discovery-workshop facilitation. You (the human PM/BA) provide the product intent; the agent formalizes it.
• Enforce an approval workflow. The status column on each Summary row (draft / reviewed / approved) is a marker, not a gate. There's no built-in reviewer assignment, no email/Slack notification, no locking. The decisions gate and SLA gate provide the closest thing to workflow — use them to freeze scope for a release and to flag overdue drafts, but the actual review handshake happens in your PM tool of choice (Jira, ProductBoard, Linear).
• Author against unsupported stacks. The Requirements agent is Adobe/JVM-focused (the same 8 stacks as the rest of the DCA suite). If you point it at a Ruby-on-Rails or Django repo, --engine auto-detection returns generic and the agent emits a single INFO finding pointing at --list-engines. Force a related stack with --engine spring (closest JVM analog) if you need generic backend structure.
• Write acceptance criteria without a story. AC live under stories; if you want isolated AC, use a placeholder story ("As the product team, we want the platform to enforce X, so that we meet compliance Y").
• Handle multi-BRD projects. The current dispatcher takes exactly one --brd-in. Chain runs manually if you need to merge multiple source BRDs.
• Author sequence diagrams, wireframes, or ER diagrams. Requirements references them (in the Integration Points and Technical Design sections of the BRD template) but doesn't generate them. Use Miro / Figma / Mermaid outside the agent.

What the agent does authoritatively:

• Turn a product description into a stack-native BRD, epics, stories, and AC that pass the INVEST checklist and align to the stack template.
• Enrich an existing BRD by filling gaps against the stack template (missing NFRs, missing AC on stated stories, missing integration points).
• Emit a traceability matrix (Epic → Story → AC → source BRD line) as the standardized DCA workbook so downstream agents can chain.
• Adapt output shape and AC style to the resolved role.
• Participate in the shared decisions + SLA gates so scope can be frozen and overdue drafts can gate CI.

Commands Reference

Trigger	Action
author requirements / author BRD / write requirements	Author mode; prompt for product description if missing
parse ./brd.docx / enrich this BRD	Parse mode with the given --brd-in
author BRD for X	Author mode with --product-description "X"
author BRD, N stories	Author mode with --stories-count N
author BRD as <role>	Author mode with --role <role> (per-run override)
author BRD and hand to impact-analysis	Author, then chain to Impact Analysis using the emitted BRD path
list requirements stacks	--list-engines
switch role to <code>	Rewrite .bmad/role.yaml
switch intake to interactive / technical	Rewrite .bmad/intake.yaml

CLI Options

Flag	Description
--path <dir>	Project root (default: .)
--engine <engine>	aem | commerce-paas (alias commerce) | commerce-saas | sling | spring | app-builder | eds | eds-commerce (auto-detect if omitted)
--output <dir>	Output directory (default <project>/requirements-reports)
--interactive	Interactive intake mode (prompts step-by-step)
--technical	Technical intake mode (silent error on missing required inputs)
--list-engines	List available engines
--role <code>	Role adaptation — persisted at <project>/.bmad/role.yaml; --role wins for a single run
--product-description <text>	Natural-language product intent — the primary input for author mode
--brd-in <path>	Path to existing BRD (.docx / .md / .txt) — the primary input for parse mode
--brd-out <path>	Where to write the generated BRD (default: <output>/BRD.md)
--stories-count <n>	Target user story count (default: 12; the LLM may drift ±2 based on natural boundaries)
--format <docx|markdown|both>	BRD output format (default: markdown; docx planned for Phase 2.2, currently falls back with a warning)
--create-branch	Cut standard branch dca/requirements-<stack>-<timestamp> before writing outputs
--source-branch <name>	Source branch for --create-branch (default candidates: production, main, master, develop)
--preflight	Print the model/context + STATIC/LLM/HYBRID advisory and exit
--no-preflight	Suppress the preflight advisory that otherwise prints on every run
--yes-install	Install missing dependencies without confirmation
--no-install	Error out if dependencies missing (do not install)
--include-decided	Show findings even when a decision exists in .bmad/decisions.yaml
--decisions-path <path>	Override decisions file location
--ignore-decision-expiry	Keep suppressing findings even when the decision has expired
--list-decisions	Print every decision in .bmad/decisions.yaml and exit
--sla-path <path>	Override SLA file location
--no-sla	Skip SLA computation + sheet
--fail-on-overdue	Exit code 6 if any finding is OVERDUE per role SLA
--help	Print usage and exit