---
name: auto-requirements-pipeline
description: "Automated end-to-end requirements analysis pipeline: requirements analysis → architecture analysis → PRD creation → PRD validation → epic+story creation → architecture design → finalize. Use when the user says 'auto requirements', 'run requirements pipeline', or 'AR'"
---

# Auto Requirements Pipeline Workflow

**Goal:** Execute the complete automated requirements analysis lifecycle — from requirements document (req.md) through analysis, PRD creation, validation, epic/story breakdown, architecture design, and delivery readiness — as a single continuous pipeline with zero user intervention.

**Your Role:** Pipeline Orchestrator. You switch expert roles at each phase:

- **Analyst (xiaofen)** — Requirements analysis and deep research
- **Architect (xiaojia)** — Architecture analysis and design
- **PM (xiaochan)** — PRD creation, validation, and epic/story breakdown

- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
- Execute ALL steps in exact order; do NOT skip steps
- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the pipeline is COMPLETE or a HALT condition is triggered
- Each step file loads fresh to combat "lost in the middle" context degradation

---

## WORKFLOW ARCHITECTURE

This uses **step-file architecture** for focused execution across a long-running pipeline:

- Each step loads fresh to prevent context loss in long sessions
- State persists via variables passed between steps
- Sequential progression through pipeline phases with conditional branching
- Role switching at each phase boundary

### State Variables

- `{req_file_path}` — Path to the requirements document (default: `{planning_artifacts}/req.md`)
- `{pipeline_status}` — Current pipeline phase for tracking
- `{steps_completed}` — Count of steps completed in this pipeline run
- `{validation_iteration}` — PRD validation loop counter (used in step-05, max 3)
- `{max_validation_iterations}` — PRD validation retry limit (set in step-05, default 3; higher than analysis/architecture limits because PRD validation delegates to the full 14-step validate-prd workflow)
- `{analysis_iteration}` — Requirements analysis quality-retry counter (used in step-02, max 2 retries)
- `{architecture_iteration}` — Architecture analysis quality-retry counter (used in step-03, max 2 retries)
- `{readiness_status}` — Implementation-readiness verdict produced by step-08 section 2.5 (advisory). One of: `ready`, `gaps`, `blocked`, `not_checked`. Serialized into `pipeline-status.json.readiness_status` by step-08 section 4.
- `{run_warnings}` — Ordered list of prefix-tagged warning strings accumulated across the run (initialized to `[]` in step-01 section 4). Each emitting step (step-01, step-02, step-03, step-05, step-06, step-07, plus step-08's own readiness/validation gates — step-04 create-prd is a pure-delegate orchestrator with no emitter; see prefix-tag table and cross-pipeline style note below) appends to this list using the canonical prefix tags defined in the "Warning Prefix-Tag Convention" section below. Serialized into `pipeline-status.json.warnings[]` by step-08 section 4. Empty list `[]` is a valid value.

### Warning Prefix-Tag Convention

All warnings emitted during a pipeline run are tagged with a `[step-NN]` prefix so downstream consumers (the auto-story-pipeline step-01 status reader, `auto-full-pipeline/step-05-finalize`'s `[phase-1]` aggregation, dashboards, CI integrations) can filter and aggregate them uniformly. This convention is the **single source of truth** for the auto-requirements-pipeline — `auto-full-pipeline/step-05-finalize.md` (`[phase-1]` aggregation) and the auto-story-pipeline's gating read of `pipeline-status.json` both reference this table.

| Prefix tag | Emitting step | Trigger examples |
|---|---|---|
| `[step-01]` | step-01 init-and-validate | `src/` directory missing (limited architecture analysis); optional `xiaoma-check-implementation-readiness` workflow not installed (readiness gate will be skipped in step-08) |
| `[step-02]` | step-02 requirements-analysis | Quality self-check exceeded `{analysis_iteration}` > 2; proceeded with remaining gaps logged under "Known Limitations" in `requirements-analysis.md` |
| `[step-03]` | step-03 architecture-analysis | Quality self-check exceeded `{architecture_iteration}` > 2; proceeded with remaining gaps logged under "Key Observations and Constraints" in `current-architecture-analysis.md` |
| `[step-05]` | step-05 validate-prd | Validation iteration N failed but max not yet reached (advisory only — terminal HALT at iteration > 3 is a hard stop); escalation A/B/C/D dispatched after 3 iterations |
| `[step-06]` | step-06 create-epics | Epic coverage incomplete relative to PRD features (advisory — step continues after best-effort completion); epic(s) with zero stories (advisory — Phase 3 will skip those epics); story/stories missing acceptance criteria (advisory — downstream auto-story-pipeline step-03 validation will likely flag these) |
| `[step-07]` | step-07 create-architecture | Architecture missing coverage for one or more epics (advisory — step continues after best-effort completion); stale `architecture.md` found and overwritten |
| `[step-08]` | step-08 finalize | Missing non-critical artifact; readiness verdict `BLOCKED` or `GAPS` (the "readiness skill not installed → verdict downgraded to `not_checked`" branch is owned by `[step-01]` above and is intentionally NOT re-emitted here — see step-08 section 2.5 "If the skill is not installed" branch for the `do NOT double-append here` directive); traceability orphan detected (requirement/PRD-feature/epic/story with no downstream coverage — see step-08 section 2.4); traceability verification skipped due to missing identifier conventions in source documents |

**Rules:**

1. Each warning string starts with exactly one prefix tag enclosed in square brackets, followed by a single space, followed by a short human-readable description.
2. Warnings are append-only within a run — no step retracts a warning emitted by an earlier step.
3. step-08 section 4 writes the full list as-is into `pipeline-status.json.warnings[]`; `auto-full-pipeline/step-05-finalize` later wraps each entry with `[phase-1]` when aggregating into `full-pipeline-status.json` (no double-prefixing — the wrap is added, the original tag preserved).
4. Free-form WARNING output to the user terminal is unchanged; the prefix tag is added when the warning is **also** appended to `{run_warnings}`. Steps may emit user-visible WARNINGs without appending to `{run_warnings}` for purely conversational hints.
5. Hard HALTs (e.g., missing delegated workflow in step-01; PRD validation exceeded `{max_validation_iterations}` in step-05) MAY append a `[step-NN]` entry BEFORE halting so that any future partial-status snapshot writer can capture the cause; in the current pipeline these append entries are not consumed because step-08 never executes when a hard HALT fires earlier, but the appends remain for forward compatibility (mirrors the auto-story-pipeline convention).

**Cross-pipeline style note:** The `[step-NN]` tags above are **emitting-step** tags (axis: *which step produced the warning*). The sibling pipeline `auto-prd-to-stories` (`5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md` §7) uses **semantic-category** tags instead (`[fr-coverage]` / `[tier-c]` / `[self-reported]` / `[fr-coverage-map]` / `[checklist]` / `[bridge-failure]` / `[warnings-truncated]`) — axis: *what kind of issue is reported*. Both styles are sanctioned; the choice is driven by pipeline shape. auto-requirements-pipeline has 7 distinct emitting steps (step-04 create-prd is a pure-delegate orchestrator with no emitter — see the prefix-tag table above which lists rows for step-01/02/03/05/06/07/08 only) so emitting-step tags carry useful filtering signal; auto-prd-to-stories has effectively 2 emitting steps so semantic tags carry more signal. A future dashboard layer that aggregates across all pipelines should treat both vocabularies as first-class and document the mapping at the dashboard side, not require either pipeline to switch styles. Mirrors the same note in `auto-story-pipeline/workflow.md`.

### Output Artifacts

All outputs are written to `{planning_artifacts}/`:

- `requirements-analysis.md` — Deep requirements analysis report
- `current-architecture-analysis.md` — Existing codebase architecture analysis
- `prd.md` — Product Requirements Document
- `epics.md` — Epic and story breakdown
- `architecture.md` — Technical architecture design
- `pipeline-status.json` — Machine-readable pipeline completion status

### Step Ordering Rationale

The pipeline orders steps as: requirements analysis → existing-architecture analysis → PRD → validate PRD → epics & stories → new architecture → finalize.

**Why epics (step-06) come before new architecture (step-07):** Epics and stories provide concrete feature decomposition that informs architectural decisions (e.g., service boundaries, data flow, transactional units). The architecture in step-07 is the *solution* design and benefits from knowing the full set of stories it must support. The *existing* architecture analysis in step-03 is intentionally placed before PRD creation so that PRD constraints reflect what is already in place.

If your project is genuinely greenfield with no existing code, step-03's output will be sparse — that is expected and acceptable; step-07 will design from scratch using the PRD and epics.

### Architecture Document Types (Important Distinction)

This pipeline produces TWO different architecture documents:

1. **current-architecture-analysis.md** (Step 3 output)
   - Analysis of the EXISTING codebase
   - Generated by Architect (xiaojia) analyzing current system patterns
   - Used as context for designing new features that integrate cleanly
   - Describes what IS

2. **architecture.md** (Step 7 output)
   - Technical design for NEW features/requirements
   - Generated by Architect (xiaojia) designing the solution
   - References current architecture analysis as context
   - Describes what SHOULD BE

When step-07 runs, it may find a stale `architecture.md` from a prior pipeline run — in that case, the step explicitly overwrites it (see step-07 section 4).

---

## INITIALIZATION

### Configuration Loading

Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:

- `project_name`, `user_name`
- `communication_language`, `document_output_language`
- `user_skill_level`
- `planning_artifacts`, `implementation_artifacts`
- `date` as system-generated current datetime

### Paths

- `validation` = `{skill-root}/checklist.md`

### Related Workflows

These existing workflows contain the detailed logic that pipeline steps delegate to:

- `create_prd_workflow` = `skill:xiaoma-prd` *(invoked with **create** intent — `xiaoma-prd` is the consolidated PRD skill: create / update / validate)*
- `validate_prd_workflow` = `skill:xiaoma-prd` *(invoked with **validate** intent — same skill, validate mode)*
- `create_epics_workflow` = `skill:xiaoma-create-epics-and-stories`
- `create_architecture_workflow` = `skill:xiaoma-create-architecture`

### Context

- `project_context` = `**/project-context.md` (load if exists)

---

## EXECUTION

Read fully and follow: `./steps/step-01-init-and-validate.md` to begin the pipeline.