---
name: auto-story-pipeline
description: "Automated end-to-end story development pipeline (single story): create → validate → develop → review → test → fix → done. Use when the user says 'run auto pipeline', 'automate story development', or 'auto story pipeline'. For batch processing of all stories, use xiaoma-auto-story-pipeline-batch (ASPB) instead."
---

# Auto Story Pipeline Workflow

**Goal:** Execute the complete automated story development lifecycle for a **single story** — from story creation through validation, development, code review, testing, bug fixing, and final delivery — as a single continuous pipeline.

**Your Role:** Pipeline Orchestrator. You switch expert roles at each phase:
- **Dev (xiaokai)** — Story creation and sprint coordination
- **PM (xiaochan)** — Story validation and quality gate
- **Dev (xiaokai)** — Code implementation and bug fixing
- **Reviewer** — Adversarial code review
- **Dev (xiaokai)** — Functional testing with real data

- 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

> **Note:** This workflow processes a **single story** (or resumes a specific story). For batch processing of all backlog stories, use the **Auto Story Pipeline Batch** skill (`ASPB` or `/xiaoma-auto-story-pipeline-batch`), which uses Agent subprocess isolation for each story.

---

## 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

- `{pipeline_mode}` — "single" (process next backlog story) or "resume" (resume a specific story by key)
- `{current_story_key}` — Key of story being processed (e.g., "1-2-user-auth")
- `{current_story_path}` — Full path to current story file (derived in step-01 after resolving `{current_story_key}`). Whenever re-reading the story file in subsequent steps (e.g., step-08 final validation, step-03 re-checks), always perform a FRESH read directly from disk using this path variable. Do NOT rely on cached/stale in-memory state from earlier steps, as intermediate steps (step-04, step-05, step-06, step-07) may have modified the file
- `{fix_iteration}` — Bug fix loop counter (max controlled by `{max_fix_iterations}`, default 5)
- `{max_fix_iterations}` — Maximum fix-and-retest cycles per story (configurable via `max_fix_iterations` in config.yaml; default 5 if not set)
- `{dev_retry}` — Dev-story retry counter used in step-04 section 3 when the delegated `xiaoma-dev-story` workflow HALTs with a fixable reason (max 2 retries; initialized lazily on first encounter, not in step-01). Bounds the dev-retry loop similarly to how `{fix_iteration}` bounds the fix loop — prevents indefinite retry on persistently unfixable HALT conditions.
- `{fix_source}` — Origin of failures being fixed in step-07: "code-review" (step-05 routed here with unresolvable issues), "qa-testing" (step-06 routed here with test failures), or "mixed" (both code review and QA issues); set in step-07 section 2; determines post-fix routing (code-review/mixed → inline targeted re-check before step-08; qa-testing → step-08 directly)
- `{pipeline_status}` — Current pipeline phase for tracking
- `{validation_attempt}` — Story validation attempt counter (used in step-03, max 3; re-initialized at start of step-03)
- `{stories_completed}` — Count of stories transitioned to "done" within this single-story pipeline run (initialized to 0 in step-01 section 3; incremented by 1 in step-08 section 5 after the story status flips to "done" in step-08 section 2; displayed in step-08's completion report). Always 0 or 1 in single-story mode; the variable exists so that a future "process-N-stories-in-a-loop" mode (currently delegated to the auto-story-pipeline-batch scheduler) can re-use the same accumulator semantics inside the inner pipeline. Note: not currently propagated to step-09 — step-09 reports `{steps_completed}` as `N / 9` and does not surface story-count, since single-story mode by definition processes at most one story.
- `{steps_completed}` — Count of distinct pipeline step files executed in this run (initialized to 0 in step-01). Incremented at most once per step file even if a step (e.g., step-07) is re-loaded in a self-loop. Use `{fix_iteration}` (or, for step-03, `{validation_attempt}`) to track loop iterations within a single step. Reported in step-09 as `N / 9` because resume-mode runs may legitimately have N < 9.
- `{epic_just_completed}` — Set by step-08 section 4 to the epic number when the last story in an epic transitions to "done"; otherwise null. Consumed by step-09 to recommend running epic-retrospective (ER).
- `{run_warnings}` — Ordered list of prefix-tagged warning strings accumulated across the run. Each emitting step (step-01, step-02, step-03, step-05, step-06, step-07, step-08, plus step-09's own sanity check — step-04 develop-story 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 `story-pipeline-status.json.warnings[]` by step-09 section 3. 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 (ASPB scheduler, auto-full-pipeline finalizer, dashboards, CI integrations) can filter and aggregate them uniformly. This convention is the **single source of truth** for the auto-story-pipeline family — `auto-story-pipeline-batch/workflow.md` section 2.3's "Warnings field semantics" block (an unnumbered block following part 6 "Return Format") and `auto-full-pipeline/step-05-finalize.md` (`[phase-3:{story_key}]` aggregation) both reference this table.

| Prefix tag | Emitting step | Trigger examples |
|---|---|---|
| `[step-01]` | step-01 init-and-validate | Stale `pipeline-status.json` (status != "complete"); incomplete story file at resume entry; story marked `in-progress` with zero completed tasks |
| `[step-02]` | step-02 create-story | Routing inconsistency (on-disk vs sprint-status); on-disk story status set but file incomplete (re-creation triggered); created story missing required sections |
| `[step-03]` | step-03 validate-story | Validation iteration N failed but max not yet reached (advisory only — terminal NO-GO still HALTs) |
| `[step-05]` | step-05 code-review | CRITICAL finding routed to step-07; HIGH/MEDIUM auto-fix produced new findings on re-review |
| `[step-06]` | step-06 test-story | Coverage threshold not enforced (`enforce_coverage_thresholds=false`) |
| `[step-07]` | step-07 fix-and-retest | Max fix iterations reached without convergence; escalation A/B/C/D dispatched |
| `[step-08]` | step-08 complete-story | Sprint-status write fallback used; epic-completion check skipped due to unparseable key; AC-test traceability orphan (an acceptance criterion has no corresponding passing test in the step-06 report); AC-test traceability check skipped (step-06 test report missing or AC identifiers cannot be extracted) |
| `[step-09]` | step-09 finalize | Sanity check: `{current_story_key}` not "done" in fresh sprint-status read |

**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-09 section 3 writes the full list as-is into the status JSON; ASPB scheduler later wraps each entry with `[phase-3:{story_key}]` 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.

**Batch-mode plumbing note:** When this pipeline is executed as an Agent subprocess launched by the `auto-story-pipeline-batch` (ASPB) scheduler, **step-09 does not execute** — the scheduler's prompt instructs the Agent to STOP after step-08 and return a STORY_RESULT block. In that mode, the only exit point for `{run_warnings}` is **step-08 section 7's STORY_RESULT block**, whose `warnings:` field MUST be set to the full `{run_warnings}` list as-is (prefix tags preserved, empty `[]` valid). The ASPB scheduler then plumbs the field into the per-story archive `story-pipeline-status.{story_key}.json` (see `auto-story-pipeline-batch/workflow.md` section 2.4b), where `auto-full-pipeline/step-05-finalize` aggregates it under `[phase-3:{story_key}]`. Failure to serialize `{run_warnings}` into STORY_RESULT.warnings silently drops every Phase-3 warning at the ASPB → auto-full boundary — see step-08 section 7's "FAILURE MODES" for the three concrete anti-patterns to avoid. The producer-side template lives in step-08 section 7; this dictionary is the canonical tag source for both single-story mode (consumed at step-09 section 3) and batch mode (consumed at step-08 section 7).

**Cross-pipeline style note:** The `[step-NN]` tags in this dictionary 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-story-pipeline has 8 distinct emitting steps (step-04 develop-story 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/09 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.

### Status Machine

Stories progress through these states:
- `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`

### Step Ordering Rationale

The pipeline runs: init → create → validate → develop → code-review → QA-test → fix (loop) → complete → finalize.

**Why code-review (step-05) comes before QA-test (step-06):** Code review is cheaper than QA testing — it catches logic, security, and AC-implementation defects from the code itself without spinning up databases, fixtures, or test environments. Routing review failures to step-07 BEFORE running QA avoids wasting expensive QA cycles on code that has obvious defects. QA-test then validates correctness against real data, the final functional gate.

**Why step-07 (fix-and-retest) is a self-looping step rather than a separate step file per iteration:** Bug-fix iteration counts vary widely per story. Keeping the loop in one step file with `{fix_iteration}` as the canonical counter (see step-07 LOOP CONTROL) avoids an N-fold explosion of step files and keeps the pipeline's "9 distinct steps" headline accurate regardless of iteration depth.

**Why step-08 (complete-story) is distinct from step-09 (finalize):** step-08 is per-story bookkeeping (story status → done, sprint-status sync, epic-completion check). step-09 is per-pipeline-run reporting (sprint snapshot, machine-readable status JSON, next-action recommendations). Separating them lets resume-mode runs reuse step-08 logic without duplicating finalization concerns.

---

## 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

- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
- `validation` = `{skill-root}/checklist.md`

### Related Workflows

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

- `create_story_workflow` = `skill:xiaoma-create-story`
- `dev_story_workflow` = `skill:xiaoma-dev-story`
- `code_review_workflow` = `skill:xiaoma-code-review`
- `qa_test_workflow` = `skill:xiaoma-qa-generate-e2e-tests`

### 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.