@zeyue0329/xiaoma-cli 1.0.49 → 1.0.66

package/src/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-03-bridge-sprint-planning.md

@@ -0,0 +1,143 @@
+---
+name: 'step-03-bridge-sprint-planning'
+description: 'Phase 2 bridge: auto-run sprint planning to generate sprint-status.yaml from epics, connecting epics output to per-story creation input'
+nextStepFile: './step-04-batch-create-stories.md'
+---
+
+# Step 3 of 5: Bridge — Sprint Planning
+
+**Goal:** Generate `sprint-status.yaml` from the epics produced in Phase 1. This bridges the epic breakdown to the per-story file generation in Phase 3. Without this step, Phase 3 cannot determine which stories to process.
+
+**Role:** SM (xiaomin) — Scrum Master generating sprint tracking
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Announce Phase Entry
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════
+  Phase 2 of 3 — Sprint Planning Bridge
+═══════════════════════════════════════════════════
+
+Switching role to SM (xiaomin)...
+Generating sprint-status.yaml from epics...
+This bridges epics → per-story file generation.
+───────────────────────────────────────────────────
+```
+
+### 2. Verify Epics Input
+
+Confirm `{planning_artifacts}/epics.md` exists and is readable (should always pass since Phase 1 verified this, but re-check for fresh context loading):
+
+- If missing: HALT — "epics.md not found. Phase 1 may have failed. Cannot generate sprint status."
+
+Also check for sharded epics format (safety net only — Phase 1 produces a single `epics.md` file, not a sharded format):
+
+- If `{planning_artifacts}/epics.md` not found, check for `{planning_artifacts}/epics/index.md`
+- If sharded version found, proceed — the sprint planning workflow handles both formats
+- If neither format found: HALT — "No epics found in any format. Phase 1 may have failed."
+
+### 3. Switch to SM Role
+
+Adopt the SM (xiaomin) persona:
+
+- You are xiaomin, the Technical Scrum Master + Story Preparation Specialist
+- Your purpose is to translate the epic breakdown into a sprint-status tracking file
+- Communication style: Crisp and checklist-driven
+
+### 4. Execute Sprint Planning Workflow
+
+Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+
+**Critical Pipeline Mode Instructions:**
+
+- **FULLY AUTOMATED:** Do NOT pause for user input
+- The sprint planning workflow is a **single-file workflow** (`workflow.md`) containing 5 inline `<step>` blocks (not separate step files):
+  1. Parse epic files and extract all work items
+  2. Build sprint status structure (epic-N, story keys, retrospective entries)
+  3. Apply intelligent status detection (check for existing story files)
+  4. Generate `{implementation_artifacts}/sprint-status.yaml`
+  5. Validate and report totals
+- Execute ALL 5 inline steps sequentially within the single workflow file
+- For fresh runs (no pre-existing story files), all stories should default to `backlog` status
+- For re-runs (pre-existing story files detected by step 3 of sprint-planning), stories with files on disk will be promoted to `ready-for-dev` — this is the intended idempotency behavior
+- When the workflow outputs "Next Steps" guidance at the end, **ignore it** — the next steps are handled by THIS pipeline automatically
+- **Complete ALL steps without stopping**
+
+### 5. Verify Sprint Status Output
+
+After sprint planning completes, verify:
+
+1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist
+   - If missing: HALT — "Sprint planning failed to generate sprint-status.yaml. Check epics format and retry."
+
+2. **Content Validation** — Read the generated file and verify:
+   - Contains `development_status:` section
+   - Contains at least one story entry (key matches `<digit>-<digit>-*` pattern, not just epic entries)
+   - Valid YAML syntax
+
+3. **Count Stories** — Parse and count:
+   - `{epic_count}` — Number of `epic-N` entries
+   - `{story_count}` — Total story keys matching `<digit>-<digit>-*`
+   - `{backlog_count}` — Stories with status `backlog`
+   - `{ready_count}` — Stories with status `ready-for-dev` (pre-existing files)
+
+If `{backlog_count}` == 0 AND `{ready_count}` == 0:
+
+- HALT — "No processable stories found in sprint-status.yaml. Both backlog and ready-for-dev queues are empty."
+
+### 6. Update Master Pipeline State
+
+- `{phase_2_status}` = "success"
+- `{prd_to_stories_status}` = "stories-phase"
+- `{steps_completed}` = 3
+
+### 7. Output Phase 2 Summary
+
+**Output:**
+
+```
+───────────────────────────────────────────────────
+  ✅ Phase 2 Complete — Sprint Planning Bridge
+───────────────────────────────────────────────────
+
+Sprint Status: {implementation_artifacts}/sprint-status.yaml
+  Total Epics: {epic_count}
+  Total Stories: {story_count}
+  Stories in Backlog: {backlog_count}
+  Stories already Ready-for-Dev (pre-existing files): {ready_count}
+
+Phase 2 Status: {phase_2_status}
+Master Step: 3/5
+
+Proceeding to Phase 3 — Batch Story File Generation...
+───────────────────────────────────────────────────
+```
+
+**Auto-Proceed:** YES — Do NOT wait for user input. Immediately proceed to step-04.
+
+---
+
+## NEXT STEP
+
+**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-04-batch-create-stories.md`
+
+---
+
+## SUCCESS METRICS
+
+- sprint-status.yaml generated with valid YAML
+- All epics and stories from epics.md represented
+- Story counts tallied for Phase 3 batch loop
+- Phase 2 status set to "success"
+
+## FAILURE MODES
+
+- Epics file missing or unreadable
+- Sprint planning workflow fails
+- Generated sprint-status.yaml is malformed or empty
+- No story entries found in sprint status

package/src/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-04-batch-create-stories.md

@@ -0,0 +1,309 @@
+---
+name: 'step-04-batch-create-stories'
+description: 'Phase 3 — Batch create detailed story files: for each backlog story, launch an Agent subprocess running xiaoma-create-story (and ONLY that — no dev/review/test)'
+nextStepFile: './step-05-finalize.md'
+---
+
+# Step 4 of 5: Batch Create Detailed Story Files
+
+**Goal:** For every backlog story in `sprint-status.yaml`, launch an independent Agent subprocess that runs `xiaoma-create-story` to produce a detailed `{story_key}.md` file. The Agent stops immediately after story creation — it does NOT enter development, code-review, or testing.
+
+**Role:** SM (xiaomin) — Pipeline Batch Scheduler
+
+---
+
+## Core Architecture: Agent-Isolated Story Creation (Narrowed)
+
+**Why this architecture:** Each story is delegated to an independent Agent subprocess so the main scheduler stays lightweight and isolated from per-story context bloat. This mirrors the proven `auto-story-pipeline-batch` (ASB) pattern.
+
+**KEY DIFFERENCE from ASB:** ASB's Agent runs steps 02→08 (create + validate + develop + review + test + fix + complete). **THIS pipeline's Agent runs ONLY xiaoma-create-story and exits.** It is a hard error for an Agent here to enter validate-story, develop-story, code-review, test-story, fix-and-retest, or complete-story.
+
+```
+Main conversation (scheduler, minimal context)
+  ├── Agent #1 → xiaoma-create-story for Story A → returns STORY_RESULT, exits
+  ├── Agent #2 → xiaoma-create-story for Story B → returns STORY_RESULT, exits
+  ├── Agent #3 → xiaoma-create-story for Story C → returns STORY_RESULT, exits
+  └── ...until backlog queue is empty
+```
+
+### Core Rules (Strictly Follow)
+
+1. **Each story processed by independent Agent** — Use the Agent tool to launch a general-purpose subprocess, pass complete story info + paths, have the Agent run `xiaoma-create-story` end-to-end, then return a structured summary
+2. **Agent must STOP after xiaoma-create-story** — Do NOT chain into any downstream step. This is enforced in the Agent prompt with explicit hard-boundary instructions
+3. **Main loop stays lightweight** — Main scheduler only: query sprint-status → launch Agent → read result → query remaining → continue or end
+4. **Serial processing** — Process one story at a time, wait for Agent completion before next, avoid concurrent modification conflicts on `sprint-status.yaml`
+5. **Failure tolerance** — A failed Agent does NOT halt the batch; the story key goes onto a blacklist and the loop continues
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Announce Phase Entry
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════
+  Phase 3 of 3 — Batch Create Detailed Story Files
+═══════════════════════════════════════════════════
+
+Switching role to SM (xiaomin) batch scheduler...
+Using Agent subprocess isolation — each story processed independently.
+
+For each story, an independent Agent will:
+  • Read and follow xiaoma-create-story workflow
+  • Produce {implementation_artifacts}/{story_key}.md
+  • Update sprint-status.yaml status to "ready-for-dev"
+  • Return STORY_RESULT summary and EXIT
+
+⚠️  Agent will NOT enter dev/review/test — this pipeline stops at story creation.
+───────────────────────────────────────────────────
+```
+
+### 2. Initial Sprint Status Load
+
+1. Load the FULL file: `{implementation_artifacts}/sprint-status.yaml`
+2. Read ALL lines from beginning to end — do not skip
+3. Parse the `development_status:` section completely
+4. Initial counts:
+   - `{backlog_count}` — Stories with status `backlog`
+   - `{ready_count}` — Stories with status `ready-for-dev` (pre-existing files; will be SKIPPED in this phase)
+5. If `{backlog_count}` == 0:
+   - If `{ready_count}` > 0: Output INFO — "{ready_count} stories already have files at ready-for-dev (from prior runs). Nothing to create. Proceeding to Step 4." → GOTO Step 4
+   - If `{ready_count}` == 0: HALT — "Sprint status has no backlog stories. Cannot proceed."
+
+### 3. Batch Loop
+
+Repeat the following until the backlog queue is empty:
+
+#### 3.1 Find Next Processable Story
+
+1. **Fresh read from disk:** Load the FULL `{implementation_artifacts}/sprint-status.yaml` again (do NOT rely on cached in-memory state — the previous iteration's Agent updated the file)
+2. Read ALL lines from beginning to end
+3. Parse `development_status:` completely
+4. Find the FIRST story (reading top to bottom) where:
+   - Key matches pattern `<digit>-<digit>-*` (e.g., `1-2-user-auth`)
+   - NOT an epic key (`epic-N`) or retrospective (`epic-N-retrospective`)
+   - Key is NOT in `{failed_story_keys}` (skip blacklisted stories)
+   - Status value equals `backlog`
+5. If no processable backlog story found → GOTO Step 4 (queue empty)
+
+Set `{current_story_key}` = the found story key.
+
+#### 3.2 Output Per-Story Progress Header
+
+```
+───────────────────────────────────────────────────
+Creating story: {current_story_key}
+Stories created so far: {stories_created} | Failed: {stories_failed}
+───────────────────────────────────────────────────
+```
+
+#### 3.3 Launch Independent Agent Subprocess
+
+<critical>
+
+Use the **Agent tool** to launch a **general-purpose subprocess** to create this story.
+
+The Agent's prompt MUST contain the following complete information for independent work:
+
+**1. Story Information:**
+
+- Story key: `{current_story_key}`
+- Current status: `backlog`
+- Expected output file: `{implementation_artifacts}/{current_story_key}.md`
+
+**2. Configuration (inline all resolved values):**
+
+- `project_name`: `{project_name}`
+- `user_name`: `{user_name}`
+- `communication_language`: `{communication_language}`
+- `document_output_language`: `{document_output_language}`
+- `user_skill_level`: `{user_skill_level}`
+- `planning_artifacts`: `{planning_artifacts}`
+- `implementation_artifacts`: `{implementation_artifacts}`
+- `sprint_status`: `{implementation_artifacts}/sprint-status.yaml`
+- `date`: current datetime
+- `architecture_absent`: `{architecture_absent}` (boolean from step-01; controls whether Data Model subsection must default to "TBD by architect")
+
+**3. Workflow Path (single workflow, narrow scope):**
+
+- `create_story_workflow`: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+
+**4. Project Context:**
+
+- Include the actual CONTENT of `project-context.md` if it exists (pass content inline, not just the path)
+
+**5. Processing Instructions (paste verbatim into the Agent prompt):**
+
+> You are an SM (xiaomin) story-creation specialist running in an isolated subprocess. Your one and only job is to create the detailed user-story file for `{current_story_key}` by reading and following the `xiaoma-create-story` workflow at `{create_story_workflow}`.
+>
+> **Steps:**
+>
+> 1. Read the workflow at `{create_story_workflow}` completely.
+> 2. Follow ALL its `<step>` blocks (step n=1 through step n=6) sequentially. The workflow auto-discovers the next backlog story from `sprint-status.yaml` — it will land on `{current_story_key}` because that's the first backlog story.
+> 3. Produce the story file at `{implementation_artifacts}/{current_story_key}.md`.
+> 4. **APPLY THE DETAILED DESIGN OUTPUT CONTRACT below before saving** — the create-story workflow's template is intentionally lean; this contract is mandatory and supersedes the template's defaults for the Dev Notes section.
+> 5. Update `sprint-status.yaml`: set `development_status[{current_story_key}] = "ready-for-dev"`.
+> 6. Return the STORY_RESULT summary (format below) and EXIT.
+>
+> **DETAILED DESIGN OUTPUT CONTRACT (mandatory) — applies to the story's `## Dev Notes` section:**
+>
+> The Dev Notes section MUST contain these three subsections (in this order). Do NOT omit, do NOT collapse, do NOT replace with a single paragraph.
+>
+> ```
+> ### Functional Requirements Addressed
+> - List EVERY FR/feature point from prd.md (or epics.md) that this story implements
+> - For each: FR reference (e.g., "FR-3", "PRD §4.2", or epic-story acceptance criteria number) → one-line restatement
+> - If a parent epic's FR list mentions FRs that this story is logically responsible for but you cannot find concrete acceptance criteria for them, list them anyway with the note "AC missing — needs PM review"
+>
+> ### Data Model & Database Design
+> - Tables / collections / entities touched by this story (give candidate names if not yet created in the codebase)
+> - Field list per entity: name, type, nullability, constraints, indexes, foreign keys
+> - Migration / schema-change notes if the story implies new tables or column changes
+> - **Source attribution:** every claim must end with `[Source: prd.md#<section>]` or `[Source: epics.md#<epic-story>]` or `[Source: architecture.md#<section>]`
+> - **TBD policy:**
+>   - If `architecture_absent == true` AND prd.md contains data-model clues (DDL snippets, ER hints, field lists): extract them and write the schema explicitly with `[Source: prd.md#<section>]`
+>   - If `architecture_absent == true` AND no data-model clues exist anywhere: write the literal line `TBD by architect — no data-model clues in prd.md or epics.md.` Do NOT silently omit this subsection.
+>   - If `architecture_absent == false`: extract data-model from architecture.md and cite it. If architecture.md does not cover this story's entities, write `TBD by architect — architecture.md does not cover <entity>.`
+>
+> ### Implementation Logic
+> - Key interface / function signatures (TypeScript-like or pseudocode form, even if the actual language differs)
+> - Core algorithm, state machine, or event flow — numbered steps or a small block diagram in ASCII
+> - Error-handling cases and boundary conditions (list the invariants and what should happen when they break)
+> - External-service / API integration points (endpoint, method, request/response shape)
+> - **Source attribution:** every claim must cite `[Source: prd.md#<section>]`, `[Source: epics.md#<epic-story>]`, or `[Source: architecture.md#<section>]`
+> - **TBD policy:** if no source covers the required logic, write `TBD by architect — <specific question>.` rather than fabricating logic. A specific TBD is better than a confident hallucination.
+> ```
+>
+> Standard create-story Dev Notes content (architecture patterns, source-tree components, testing standards) should still be produced — append them AFTER the three mandatory subsections above (e.g., as `### Architecture Patterns`, `### Source Tree Components`, `### Testing Standards`).
+>
+> **HARD BOUNDARY — DO NOT CROSS:**
+>
+> - After `xiaoma-create-story` workflow completes (and the contract above is applied), you are DONE.
+> - Do NOT read `auto-story-pipeline/steps/step-03-validate-story.md` or any subsequent step.
+> - Do NOT enter validate-story, develop-story, code-review, test-story, fix-and-retest, complete-story, or finalize.
+> - Do NOT read or follow ANY workflow under `5-full-pipeline/` (including auto-full-pipeline, auto-prd-to-stories itself, or any other pipeline workflow). The only workflow you may read is `{create_story_workflow}`.
+> - Do NOT read or follow `auto-story-pipeline-batch/workflow.md` or `auto-story-pipeline/workflow.md` — those are batch schedulers and downstream pipelines outside your scope.
+> - Do NOT write any code, run any tests, or modify any source files outside `{planning_artifacts}` and `{implementation_artifacts}`.
+> - Do NOT touch `sprint-status.yaml` beyond setting this one story's status to `ready-for-dev`.
+> - The main scheduler handles everything after you return.
+>
+> **Execution Rules:**
+>
+> - Execute the create-story workflow's steps in exact order; do NOT skip steps.
+> - When reading the story file or sprint-status in later substeps, always perform a FRESH read from disk.
+> - Do not stop because of "milestones" or "significant progress" — continue until the story file is created and sprint-status updated.
+> - If `xiaoma-create-story` asks for any user input (e.g., the "choose story" prompt in its step n=1), automatically pick option `{current_story_key}` (or let auto-discovery proceed — it will pick the first backlog story, which is this one).
+> - When the create-story workflow's step n=6 outputs guidance like "Next Steps: Run dev agents `dev-story`", IGNORE it. That guidance is for interactive single-story mode; in this batch pipeline, the main scheduler handles next steps.
+
+**6. Return Format (Agent must produce exactly this block at the end of its output):**
+
+```
+STORY_RESULT:
+- story_key: {story_key}
+- final_status: created | failed
+- file_path: {implementation_artifacts}/{story_key}.md
+- summary: {one-line description of what was created}
+- frs_addressed: [list of FR references / PRD section refs / acceptance-criteria ids that this story covers; empty list if none claimed]
+- db_design_status: present | tbd-flagged | missing
+- impl_logic_status: present | tbd-flagged | missing
+- error: {error message if failed, empty otherwise}
+```
+
+**Status-tag semantics (the Agent must self-assess and report honestly):**
+
+- `present` — the subsection contains concrete schema/logic content with source attributions
+- `tbd-flagged` — the subsection contains a clear "TBD by architect — <reason>" line as required by the contract
+- `missing` — the subsection is absent or empty (this should NEVER happen if the contract is followed; if reported, the main scheduler will flag the story for re-creation)
+
+</critical>
+
+#### 3.4 Read Agent Result and Handle Outcome
+
+Read the Agent's returned STORY_RESULT block.
+
+**IF the Agent succeeded (`final_status: created`):**
+
+1. Verify the file actually exists at `{implementation_artifacts}/{current_story_key}.md` (defense in depth — sometimes Agents claim success without writing the file)
+   - If file missing despite `final_status: created`: treat as failure (proceed to failure branch below)
+2. Increment `{stories_created}` by 1
+3. Append to `{story_results}`: `{ story_key, final_status: "created", file_path, summary, frs_addressed, db_design_status, impl_logic_status }` — preserve ALL fields from STORY_RESULT for step-05's report
+4. If `db_design_status == "missing"` OR `impl_logic_status == "missing"`: output WARNING — "Story {current_story_key} created but reported `missing` for a mandatory subsection. step-05 will surface this in Structural Warnings."
+
+**IF the Agent failed (`final_status: failed`, no STORY_RESULT block, or file-missing case above):**
+
+1. Increment `{stories_failed}` by 1
+2. Add `{current_story_key}` to `{failed_story_keys}` (prevents infinite re-selection)
+3. Append to `{story_results}`: `{ story_key, final_status: "failed", error }`
+4. Output: "⚠️ Story {current_story_key} failed. Reason: {error}. Skipping and continuing to next story."
+5. **Do NOT halt the batch.**
+
+#### 3.5 Refresh Sprint Status and Output Checkpoint
+
+1. Re-read `{implementation_artifacts}/sprint-status.yaml` from disk (fresh read)
+2. Recount: `{backlog_count}`, `{ready_count}`
+3. Output checkpoint:
+
+```
+[Checkpoint] Stories created: {stories_created} | Failed: {stories_failed} | Backlog remaining: {backlog_count}
+Last story: {current_story_key} ({final_status})
+```
+
+4. If `{backlog_count}` > 0 (and at least one backlog story is NOT in `{failed_story_keys}`): Continue loop — return to 3.1
+5. Otherwise: GOTO Step 4 (queue empty)
+
+### 4. Determine Phase 3 Status
+
+After loop exits:
+
+- If `{stories_created}` > 0 AND `{stories_failed}` == 0: `{phase_3_status}` = "success"
+- If `{stories_created}` > 0 AND `{stories_failed}` > 0: `{phase_3_status}` = "partial"
+- If `{stories_created}` == 0 AND `{stories_failed}` > 0: `{phase_3_status}` = "failed"
+- If `{stories_created}` == 0 AND `{stories_failed}` == 0: `{phase_3_status}` = "success" (nothing to do, but not an error — e.g., all stories pre-existing)
+
+### 5. Update Master Pipeline State
+
+- `{prd_to_stories_status}` = "complete"
+- `{steps_completed}` = 4
+
+### 6. Output Phase 3 Summary
+
+```
+───────────────────────────────────────────────────
+  Phase 3 Complete — Story File Generation
+───────────────────────────────────────────────────
+
+Stories Created: {stories_created}
+Stories Failed: {stories_failed}
+Failed Story Keys: {failed_story_keys joined by comma, or "none"}
+
+Phase 3 Status: {phase_3_status}
+Master Step: 4/5
+
+Proceeding to Finalization...
+───────────────────────────────────────────────────
+```
+
+**Auto-Proceed:** YES — Do NOT wait for user input. Immediately proceed to step-05.
+
+---
+
+## NEXT STEP
+
+**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md`
+
+---
+
+## SUCCESS METRICS
+
+- Every backlog story has either: (a) a corresponding `.md` file at `ready-for-dev`, OR (b) an entry in `{failed_story_keys}` with documented error
+- Main scheduler context stayed lightweight (no per-story bloat)
+- No Agent crossed the hard boundary into dev/review/test
+- `sprint-status.yaml` reflects all successful creations
+
+## FAILURE MODES
+
+- All Agent subprocesses failing (likely indicates a workflow-installation issue)
+- An Agent ignoring the hard-boundary instruction and entering downstream steps — if observed, the main scheduler should still record STORY_RESULT and continue, but the user should be warned in the final report
+- `sprint-status.yaml` corruption from concurrent modification — mitigated by strict serial processing