bmad-method 6.10.1-next.8 → 6.11.0

package/src/bmm-skills/plan/bmad-project-context/customize.toml

@@ -0,0 +1,24 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-project-context.
+# Team overrides:     {project-root}/_bmad/custom/bmad-project-context.toml
+# Personal overrides: {project-root}/_bmad/custom/bmad-project-context.user.toml
+#
+# Merge rules: scalars override (last layer wins); arrays append.
+
+[workflow]
+
+# --- Universal defaults ---
+activation_steps_prepend = []
+activation_steps_append = []
+# Deliberately empty: this skill's own output (AGENTS.md) is loaded by the
+# harness, not through this array. Users append their own standing facts.
+persistent_facts = []
+on_complete = ""
+
+# Standing outside-the-repo sources offered at every setup/refresh run
+# (untrusted until verified against the repo or user-confirmed).
+# Append-only. Entries: "file:{project-root}/..." or "file:/abs/path" for
+# docs, "skill:name" to consult a skill, plain text for a standing fact,
+# "tool:name" for an MCP knowledgebase.
+external_sources = []

package/src/bmm-skills/plan/bmad-project-context/references/best-practices.md

@@ -0,0 +1,65 @@
+# What belongs in a repo's agent instructions
+
+Rules for deciding what goes in the block, for judging what a repo already has, and for explaining both to the user.
+
+## The test
+
+Can an agent derive this by reading the repository? If yes, leave it out — a stored copy is a stale duplicate of something the agent reads more accurately first-hand, and it is charged on every session. Write down what the code cannot say.
+
+## Admit
+
+- **Policy the code cannot express** — branch rules, frozen and protected paths, generated files, secrets, security and compliance. Stated by a human or read off an enforcing config, never inferred.
+- **What a config file cannot say about running the project** — the root test script does nothing in this workspace, integration tests need a service up first, the suite takes eleven minutes so iterate on single files, the `Makefile` is the real entry point and `package.json` is vestigial, CI runs a typecheck the test script does not. The invocation itself is already stated in `package.json`, `Makefile`, `pyproject.toml`, or CI config and does not earn a line — the correction or the caveat does.
+- **Conventions that differ from ecosystem defaults.** An agent follows the norm unless told otherwise, so only the divergences earn a line. Command invocations count: when the obvious command is wrong here — a bare-repo prefix, a required wrapper — the exact working invocation earns a line, and no observed mistake is needed to admit it.
+- **Pitfalls with observed evidence** — a recorded lesson, the maintainer's recollection, the same mistake fixed repeatedly in history, or one this session made and caught. A repo yields hundreds of trap-looking facts and none of them predict real mistakes; only observed behavior does. A surprising scan finding is a question to ask, not a line to write.
+- **Runtime behavior invisible from the repo** — replaying webhooks, lying health endpoints, environment quirks — once a human confirms it.
+- **Entry points and pointers** to where work lands.
+
+Prefer prohibitions to advice, and name the permitted alternative in the same line.
+
+## Exclude
+
+| | Why |
+|---|---|
+| Repo overviews, directory trees, stack lists | Derived fresh, more accurately; stored copies rot |
+| Anything included for being interesting | Interest is not need |
+| Style rules an agent self-enforces | Belongs in a formatter, linter, hook, or CI check — propose the check instead |
+| Platitudes | Already the default |
+| Commands already stated in `package.json`, a `Makefile`, or CI config | Read from the source of truth; a copy drifts the moment a script is renamed |
+| Pasted code, changelog content, fast-changing facts | Stale immediately |
+| Aspirational state | Describe what is; intent belongs in specs |
+| History and edit narration | Git holds it; state present truth |
+
+## Retire
+
+A policy or pitfall line goes only when the thing it guards is gone, or the user retires it. Nothing failing lately is not evidence — a working rule erases its own evidence.
+
+Every other line faces one question at each write: would removing it change agent behavior? If no, cut it.
+
+## Size
+
+Every line is paid in every session, and instruction-following degrades as the loaded set grows. Count what other always-loaded files add. Over budget means cut the weakest lines or move them behind a trigger — never raise the budget. Ten lines of evidence means ten lines.
+
+## Retrieval
+
+An index the agent must choose to fetch gets skipped; one already in context does not. Keep everything load-bearing in the block. A pointer out of it names a trigger the agent can observe — a path, a file type, a named task — never one it must judge ("when the task is complex") or track about itself ("before your first edit").
+
+Rules bounded to a directory go in a nested `AGENTS.md` there, attached by location rather than by pointer. Use a linked file only when the trigger is not a path.
+
+## Maintain
+
+- Re-check that caveats still hold — a slow suite that got fast, a workaround for a bug that was fixed.
+- Diff deletions and renames since the verified SHA against every line.
+- Record provenance in the block so the next run knows what it is diffing from.
+- Capture mistakes when they happen, not at review time. One occurrence is a note; recurrence earns a line.
+- Route anything mechanically preventable to a hook, lint rule, or CI check. A check that lands deletes its line.
+
+## Repo or home directory
+
+This block belongs committed: shared by the team, consistent across machines, versioned with the code it constrains.
+
+Two things belong in the user's global agent config instead — rules repeating across all their projects, and personal preferences that are theirs rather than the team's.
+
+## Judging an existing file
+
+Report, in this order: what is derivable filler, what is unverifiable or stale, what is missing against the sections above, and what is already good. Keep recorded lessons by default — they are maintainer testimony, and are challenged only with evidence that the thing they name is gone or wrong.

package/src/bmm-skills/plan/bmad-project-context/references/template.md

@@ -0,0 +1,55 @@
+# Block shape
+
+Sections in this order. Omit any section with nothing that passes its rule — never write an empty one. Admission rules: `best-practices.md`.
+
+1. **Orientation** — three or four sentences: what this is, the stack, where planning and deeper docs live.
+2. **Policy** — what the org requires.
+3. **Where things are** — entry points, and pointers to children and linked files.
+4. **Running and verifying** — only what `package.json`, a `Makefile`, or CI config does not already say.
+5. **Conventions that differ from defaults**
+6. **Known pitfalls**
+
+Terse imperative lines under plain headings. No prose beyond Orientation, no introduction, no summary. A bare fact appears only as the justification clause of an instruction — "Exclude `vendor/` from searches, it is 60% of tracked files", never "`vendor/` is 60% of tracked files". A prohibition names the alternative. At most two emphasis markers in the whole block.
+
+## Worked example
+
+````markdown
+<!-- bmad:context -->
+<!-- Verified 2026-08-08 against a1b2c3d. Managed by bmad-project-context; edits inside this block are replaced on refresh. Keep anything you want preserved outside the markers. -->
+
+## acme-billing
+
+Payment processing for Acme storefronts. TypeScript/Node, pnpm, Postgres. Planning lives in `docs/planning/`, tickets in Linear (ACME board).
+
+## Policy
+
+- Never push to main; PRs only, one approval.
+- Never modify `legacy/` — frozen, being replaced. New work goes in `src/`.
+- Never hand-edit `src/generated/` — run `pnpm codegen`.
+
+## Where things are
+
+- Webhook handling: `src/routes/webhooks.ts`; conventions in `docs/webhooks.md`
+- Writing a migration? Read `docs/db-rules.md` first — ordering, transaction boundaries, pool limits.
+- Billing service has its own guide: `services/billing/AGENTS.md`
+
+## Running and verifying
+
+- Run single test files while iterating; the full suite takes ~11 minutes.
+- Integration tests need `docker compose up -d` first, and fail confusingly without it.
+- CI also runs `pnpm typecheck`, which `pnpm test` does not cover.
+
+## Conventions that differ from defaults
+
+- Money is integer cents (`amountCents`), never floats — `src/lib/money.ts`
+- All DB access goes through repositories in `src/repos/`; never call the client directly.
+
+## Known pitfalls
+
+- Stripe webhooks replay in staging every 6h — handlers must be idempotent.
+- Use vitest matchers, not jest — agents repeatedly add jest syntax here.
+
+<!-- /bmad:context -->
+````
+
+Fill the provenance line with the real date and the commit SHA verified against. Refresh diffs from that SHA.

package/src/{core-skills → bmm-skills/plan}/bmad-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-spec
-description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", or "update the spec".
+description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", "update the spec", or "break this into stories".
 ---
 
 # BMad Spec
@@ -20,7 +20,7 @@ Multiple skills may call to update the same spec over time.
 
 1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
-3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
+3. Resolve config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` (merges `_bmad/config.toml`, `_bmad/config.user.toml`, and the `_bmad/custom/` overrides). From the merged JSON resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}`, `{output_folder}` (under `core`), and `{date}`.
 4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field.
 
 Run `{workflow.activation_steps_append}`.
@@ -46,6 +46,7 @@ Inside the spec folder:
   SPEC.md                  ← uppercase, the kernel — DERIVED from .memlog.md, never hand-edited
   <companion-1>.md         ← optional, content-typed (e.g. glossary.md); spec-authored ones are derived too
   <companion-2>.md
+  stories.yaml             ← optional, written only by Story Breakdown — fixed name, never in companions:
   .memlog.md               ← canonical, append-only memory; what SPEC.md is distilled from
 ```
 
@@ -99,6 +100,8 @@ Two rules govern companions:
 
 Pre-existing project-wide docs (e.g. `project-context.md`) that downstream needs are listed as **adopted companions**, never duplicated into SPEC.md or a spec-authored companion.
 
+`stories.yaml`, when produced, is spec-authored but deliberately **not** a companion — see Story Breakdown below.
+
 ## Spec Law
 
 Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.
@@ -126,9 +129,21 @@ Record the verdict for each pass to `.memlog.md` (`append --type event`). In int
 
 When the user points the skill at an existing spec folder (or its SPEC.md) with no change signal, offer to review assumptions or open questions, or determine what they want to do.
 
+## Story Breakdown (optional, interactive-only)
+
+Requires `SPEC.md` on disk — run the normal Operation first if it doesn't exist yet. Headless runs never do this, even when the invocation text asks for it: if mode detection (On Activation, step 4) resolved headless, skip this section entirely and proceed with the normal headless response. In interactive mode, offer it at most once per run when the input reads as multiple independently shippable slices; a decline ends the offer for this run, not forever. Also run it on direct request ("break this into stories") whenever `SPEC.md` exists. When a spec update runs and `stories.yaml` exists, check the story descriptions against the updated spec; if any no longer matches, say so and offer to re-run Story Breakdown. The update itself never rewrites `stories.yaml`.
+
+Either way, walk the capabilities and constraints with the user and propose a story per independently reviewable slice — this is a conversation, not a silent render. For each story, ask the user for `spec_checkpoint`, `done_checkpoint`, and any `invoke_dev_with` note rather than defaulting them silently; capturing that human judgment is what the fields are for. If the conversation surfaces load-bearing detail beyond dispatch notes (a constraint, a design decision), route it into SPEC.md or a companion — `invoke_dev_with` carries dispatch notes only (Spec Law rule 7 still applies).
+
+The output is `stories.yaml`, a sibling of `SPEC.md` inside the spec folder, discovered by that fixed name — same convention as `SPEC.md` and `.memlog.md`. Never list it in `companions:` and never point a frontmatter key at it: companions carry the what-to-build contract every consumer reads; `stories.yaml` is input for whichever tool dispatches the stories.
+
+Field definitions, the validity rules, and a worked example live in `assets/stories-schema.md`. Before writing or re-writing the file, check every entry against those rules; fix violations rather than presenting a file that fails them. Record the check's verdict to `.memlog.md` (`append --type event`), the same discipline as Self-Validate.
+
+Derive `stories.yaml` from `.memlog.md` exactly like any other spec-authored artifact: log each proposed story (`--type decision`) as the user agrees to it, then render. On a later run against the same spec folder, re-derive the same way, handling ids per the schema's update semantics.
+
 ## Output
 
-**Interactive** — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. If `assumptions[]` or `open_questions[]` are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
+**Interactive** — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. Name the story count too if `stories.yaml` was written this run. If `assumptions[]` or `open_questions[]` are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
 
 **Headless** — return JSON per `assets/headless-schemas.md`.
 

package/src/{core-skills → bmm-skills/plan}/bmad-spec/assets/spec-template.md

@@ -4,7 +4,7 @@ companions: []     # files downstream MUST read alongside SPEC.md. Paths may poi
 sources: []        # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never the memlog.
 ---
 
-> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability only — consult them only if you need narrative rationale or prose color this contract intentionally omits.
+> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability — consult them only if you need narrative rationale or prose color this contract intentionally omits.
 
 # {Spec Title}
 

package/src/bmm-skills/plan/bmad-spec/assets/stories-schema.md

@@ -0,0 +1,44 @@
+# Stories schema
+
+`stories.yaml` — the optional output of Story Breakdown: a top-level YAML list, one entry per story, in execution order — stories run top to bottom. Sibling of `SPEC.md`, discovered by its fixed filename (same convention as `SPEC.md` and `.memlog.md`); never listed in `companions:`, never referenced from frontmatter.
+
+## Fields
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `id` | string | yes | Identity, unique within the file. Compared for equality and used as a filename prefix; carries no other meaning. Use unpadded integers (`"1"`), or composites (`"3-2"`) when the epic sits inside a larger project spec. No zero-padding — execution order is the list order, not filename sort. Pinned once the story's spec file exists (see Update semantics); until then it may be renumbered. |
+| `title` | string, one line | yes | Display name; becomes the story's heading downstream. |
+| `description` | string | yes | What this story covers, pointing into `SPEC.md` — not a story spec. Keep it to two sentences; a writing rule, not something tooling enforces. |
+| `spec_checkpoint` | boolean | no (default `false`) | Set by the human at breakdown time; read only by the dispatching caller, never by the implementing dev skill. When true, a human reviews the story spec between planning and implementation. |
+| `done_checkpoint` | boolean | no (default `false`) | Caller-only, like `spec_checkpoint`. When true, dispatch pauses after this story completes, before anything further runs. |
+| `invoke_dev_with` | string | no (default `""`) | Free text appended verbatim to the prompt that dispatches this story; the implementing dev skill reads it as part of its prompt, and nothing else interprets it. If the text needs structure, put it inside the string. Which dev skill to invoke is the caller's configuration, never data in this file. |
+
+## Validity rules
+
+1. Every entry parses with all required fields; ids unique.
+2. Ids are prefix-free under the `<id>-` filename-matching convention: no id may equal another id plus a dash-suffix (`"3"` and `"3-2"` cannot coexist).
+3. No `status` field, ever.
+4. Ids are YAML strings, always quoted, containing only letters, digits, and dashes. An unquoted `id: 1` parses as a number and breaks string comparison; characters like `/` or `*` break the filename match.
+
+## Example
+
+```yaml
+- id: "1"
+  title: Add rate limiting to the public API
+  description: >-
+    Introduce a token-bucket limiter in front of the public endpoints;
+    return 429 with a Retry-After header on limit breach.
+  spec_checkpoint: true
+  invoke_dev_with: >-
+    Rate limit state must be shared across instances; use the existing
+    Redis client, not in-process memory.
+- id: "2"
+  title: Expose limiter metrics to the ops dashboard
+  description: >-
+    Emit per-route accept/reject counters the existing dashboard can
+    scrape; no new dashboard panels in this story.
+```
+
+## Update semantics
+
+Updates to `stories.yaml` go through Story Breakdown: append the change to `.memlog.md`, then re-derive. An id is pinned once its story spec file exists (any `stories/<id>-*.md` in the spec folder): a pinned story keeps its id through edits, its removal retires the id, and retired ids are never reassigned. Stories with no spec file yet may be renumbered, reordered, or removed freely on re-derive — typically so ids keep following list order. Never give a story an id that collides with a `stories/` file belonging to a different story.

package/src/{core-skills → bmm-skills/plan}/bmad-spec/customize.toml

@@ -38,10 +38,9 @@ spec_template = "assets/spec-template.md"
 # Uppercase by convention to signal "the central source of truth."
 spec_filename = "SPEC.md"
 
-# Output path for spec folders. Lands directly under {output_folder}
-# so bmad-spec works in core-only installs and matches the
-# long-term BMad direction of grouping artifacts as siblings under
-# {output_folder}/<type>/ rather than nested inside planning vs
+# Output path for spec folders. Lands directly under {output_folder},
+# matching the long-term BMad direction of grouping artifacts as siblings
+# under {output_folder}/<type>/ rather than nested inside planning vs
 # implementation folders.
 spec_output_path = "{output_folder}/specs"
 

package/src/bmm-skills/plan/bmad-sprint-planning/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: bmad-sprint-planning
+description: 'Gate planning readiness, generate sprint status tracking from epics, summarize sprint progress, and validate or repair the tracking file. Use when the user says "run sprint planning", "generate sprint plan", "check implementation readiness", "show sprint status", "validate sprint status", or "fix sprint status"'
+---
+
+# Overview
+
+You are a senior developer about to commit to this plan. Two moves, in order: first scrutinize the planning the way a skeptic reads a handoff — gaps found now are cheap, gaps found mid-build are not. Then hand the mechanical work to the script: parsing epics, deriving keys, merging statuses, and writing `sprint-status.yaml` are deterministic jobs, not judgment calls. Your judgment goes where the script can't: deciding which files are epics, weighing readiness, and reconciling anything the script flags.
+
+## On Activation
+
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+2. Execute each entry in `{workflow.activation_steps_prepend}` in order.
+3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+4. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}`, `{planning_artifacts}`, `{implementation_artifacts}`, `{project_knowledge}` (skip gracefully if unset), `{date}`. Stay in `{communication_language}` for every turn, not just the greeting.
+5. Greet `{user_name}`, detect intent, and load only what that intent needs:
+   - **readiness** — check implementation readiness only: load `references/readiness-gate.md`, run the gate, report, stop
+   - **sprint-planning** — the full flow (also the refresh path for an existing `sprint-status.yaml`): load `references/readiness-gate.md`, then on PASS `references/generate-tracking.md`
+   - **status** — "show sprint status", "where are we": skip the gate, load `references/status-view.md`
+   - **validate** — check the tracking file's format: load `references/validate.md`
+   - **fix** — repair or rebuild a broken `sprint-status.yaml`: load `references/fix-sprint-status.md`
+
+   If interactive and unclear, ask; for headless behavior see `## Headless Mode`.
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding.
+
+## If the Script Fails
+
+This rule covers every intent: when `sprint_plan.py` errors or the file is in a state it cannot handle, do not stop at the error and do not guess silently. Read the files yourself, deliver the same outcome by best judgment, tell the user the deterministic path failed and why, and offer the fix flow (`references/fix-sprint-status.md`) to restore a file the script can work with.
+
+## On Completion
+
+Whatever the intent, close out in `{communication_language}` per the loaded reference, then run `{workflow.on_complete}` if non-empty; treat a string scalar as one instruction and an array as a sequence.
+
+## Headless Mode
+
+When invoked headless, do not ask. Run the gate and, unless intent was readiness-only, generate tracking. Ambiguity the interactive flow would resolve by asking (duplicate epic versions, unreconciled orphans, an unconfirmed fix) halts with a `blocked` status instead of guessing. End with a JSON response:
+
+```json
+{
+  "status": "complete",
+  "intent": "sprint-planning",
+  "gate": "PASS",
+  "status_file": "{implementation_artifacts}/sprint-status.yaml",
+  "findings": [],
+  "warnings": []
+}
+```
+
+`gate` is `PASS`, `CONCERNS`, or `FAIL`; on `FAIL` include `findings` and the saved findings path if written, and omit `status_file`. `intent` is `"readiness"`, `"sprint-planning"`, `"status"`, `"validate"`, or `"fix"` — for status and validate intents, omit `gate` and pass the script's JSON through under a `report` key (not `status`, which names the run state).
+
+## References
+
+- `scripts/sprint_plan.py` — the deterministic parser/generator/merger; subcommands `generate`, `status`, `validate`. Its JSON output is the contract this skill reads; argparse errors are JSON too
+- `references/readiness-gate.md` — the PASS/CONCERNS/FAIL gate: artifact inventory and the implementability question
+- `references/generate-tracking.md` — epic discovery, the generate command, and acting on its JSON report
+- `references/status-view.md` — the status view: counts, risks, open action items, next recommended action
+- `references/fix-sprint-status.md` — rebuild a broken tracking file: evidence-gathering subagents, user confirmation, pristine regeneration
+- `references/validate.md` — format validation of an existing `sprint-status.yaml`
+- `sprint-status-template.yaml` — the documented file format and status vocabulary; the script embeds the same block and the test suite pins the two copies together

package/src/bmm-skills/plan/bmad-sprint-planning/references/fix-sprint-status.md

@@ -0,0 +1,30 @@
+# Fix Sprint Status
+
+Rebuild `sprint-status.yaml` to a pristine, script-valid state when it is broken, hand-mangled, drifted from reality, or the user simply asks to fix it. Inference determines what the state *should* be; the user confirms it; the script writes it. Never write without the confirmation.
+
+1. **Scope the damage.** Run `sprint_plan.py validate` and share what it found. If even the epic files are missing or unparseable, say so — there is nothing to rebuild tracking against until planning artifacts exist.
+
+2. **Determine the true state by inference.** This is judgment work — fan out subagents in parallel, each gathering one kind of evidence, and have each return proposed `key=status` pairs with the evidence behind them:
+   - **Epics** — read the epic files in `{planning_artifacts}`: the authoritative work breakdown (which epics, stories, and retrospectives should exist at all)
+   - **Story files** — scan `{implementation_artifacts}`: which stories have files on disk, and what their content says about progress (acceptance criteria checked off, completion notes, review sections)
+   - **Code evidence** — git history and the codebase: commits or merged work referencing story keys are evidence a story is done or in progress
+   - **The current file** — salvage everything credible from the existing `sprint-status.yaml`, especially `action_items`, even when its structure is broken
+
+3. **Reconcile into one proposed state.** Merge the evidence into a single table: key → proposed status, evidence, and anything uncertain. When evidence conflicts or is thin, prefer the lower status and flag it — a false `done` costs more than a false `in-progress`.
+
+4. **Confirm with `{user_name}`.** Show the table. Highlight every entry that differs from the current file — especially downgrades — and every low-confidence call. Adjust to their corrections. Headless: halt with `blocked` instead of confirming.
+
+5. **Write pristine.** One command, from the confirmed table:
+
+   ```
+   uv run {skill-root}/scripts/sprint_plan.py generate \
+     --epic-file <path> [...] \
+     --status-file {implementation_artifacts}/sprint-status.yaml \
+     --stories-dir {implementation_artifacts} \
+     --project "{project_name}" --date "{date}" \
+     --fresh --set <key>=<status> [--set <key>=<status> ...]
+   ```
+
+   `--fresh` rebuilds the document cleanly (canonical vocabulary, standard header) while still carrying `action_items`; `--set` applies the confirmed statuses and is the one path allowed to downgrade. Only confirmed entries that differ from the fresh defaults need a `--set`.
+
+6. **Verify.** Run `validate` again (expect `valid: true`) and present the status view summary so the user sees the repaired state.

package/src/bmm-skills/plan/bmad-sprint-planning/references/generate-tracking.md

@@ -0,0 +1,25 @@
+# Generate Tracking
+
+Discovery is your call; everything after it is the script's.
+
+1. Identify the epic files. The gate inventory already surfaced them — typically `epics.md`, `epic-*.md`, or a sharded `epics/` folder in `{planning_artifacts}`, but trust content over filename. If both a whole document and a sharded version exist, ask which is current rather than guessing.
+2. Run the script, passing every epic file:
+
+   ```
+   uv run {skill-root}/scripts/sprint_plan.py generate \
+     --epic-file <path> [--epic-file <path> ...] \
+     --status-file {implementation_artifacts}/sprint-status.yaml \
+     --stories-dir {implementation_artifacts} \
+     --project "{project_name}" --date "{date}"
+   ```
+
+   `{date}` must be `MM-DD-YYYY HH:MM` — the format the staleness check parses. The script owns parsing (`## Epic N:` / `### Story N.M: Title` → kebab-case keys; fenced code blocks ignored), ordering (epic, its stories, its retrospective), merging with any existing file (preserve advanced statuses, never downgrade; legacy v6 values like `drafted`/`contexted` are normalized to their modern meaning, never reset; `action_items`, custom keys, and user comments carried through; `project_key`/`tracking_system`/`story_location` kept from the existing file unless overridden by flag), story-file detection (a story file on disk floors its status at `ready-for-dev`), atomic writes, and post-write validation. It prints a JSON report. Add `--dry-run` to preview — the report's `in_sync`, `new_entries`, `dropped_orphans`, `illegal`, and `legacy_mapped` fields answer "is tracking in sync?" without writing.
+
+3. Read the JSON report and act on it — this is where judgment re-enters:
+   - `warnings` about unparsed Epic/Story-like headings mean the epic file deviates from the standard format. Show the user, fix the headings together (or accept the omission), and rerun.
+   - `dropped_orphans` are entries that existed in the old status file but match nothing in the epics — usually renames. Each carries its old status; reconcile with the user, then transplant by rerunning with `--set <new-key>=<old-status>`.
+   - If the epics defeat the parser entirely (a format the regexes can't see), fall back to building the file yourself against `sprint-status-template.yaml`, and tell the user the deterministic path didn't apply.
+
+## Report
+
+Present the result from the script's JSON in `{communication_language}`: file path, epic/story counts, status breakdown, anything upgraded from disk. Suggest next steps — review the file, `bmad-build` to start the first story, rerun this skill anytime to refresh after epics change.

package/src/bmm-skills/plan/bmad-sprint-planning/references/readiness-gate.md

@@ -0,0 +1,20 @@
+# Readiness Gate
+
+Before generating any tracking, judge whether the plan can actually be built. If the user only asked to check readiness, this gate is the deliverable — report the verdict and stop.
+
+Inventory what planning actually exists: scan `{planning_artifacts}` and `{project_knowledge}` for intent and planning artifacts — briefs, PRFAQs, PRDs, specs, UX outputs, architecture, epics and stories. Identify documents by reading what they are, not by filename patterns; projects arrive with different artifact mixes and naming.
+
+Assess the plan as a whole against one question: **could a developer implement these epics without inventing decisions nothing records?**
+
+- Requirements and decisions in the intent artifacts trace forward into stories; stories trace back to recorded intent — flag orphans in both directions
+- Epics deliver user value and carry no forward dependencies; stories are independently completable
+- Architecture and UX decisions the stories rely on are recorded somewhere, not assumed
+- Conflicts between artifacts (a spec and an epic disagreeing) are surfaced, not silently resolved
+
+A missing document type is only a finding if stories depend on decisions nothing records — a project with no UX artifact and no UI stories is fine.
+
+Deliver a verdict:
+
+- **PASS** — state it in one line; for the full sprint-planning intent, continue with `generate-tracking.md`
+- **CONCERNS** — list them briefly with where each gap lives; ask `{user_name}` whether to proceed anyway or fix first
+- **FAIL** — the plan is not implementable as recorded. Present findings ordered by severity, name the skill that fixes each (the relevant plan skill, or `bmad-correct-course` for cross-cutting changes), offer to save the findings to `{planning_artifacts}/implementation-readiness.md`, and stop

package/src/bmm-skills/plan/bmad-sprint-planning/references/status-view.md

@@ -0,0 +1,14 @@
+# Status View
+
+When the user wants to know where the sprint stands ("show sprint status", "where are we"), run:
+
+```
+uv run {skill-root}/scripts/sprint_plan.py status \
+  --status-file {implementation_artifacts}/sprint-status.yaml --date "{date}"
+```
+
+`{date}` is `MM-DD-YYYY HH:MM`. The script computes everything: counts by status (legacy values like `drafted` mapped transparently and reported in `legacy_mapped`), risk flags (stale file, orphaned stories, in-progress epics without stories, stories waiting in review, unrecognized keys), open action items from retrospectives, and the next recommended action by fixed priority — resume in-progress → review what's in review → start the next ready or backlog story → run an open retrospective → all done. If the file is missing, the script says so — offer to run sprint planning to create it.
+
+Render the JSON as a compact summary in `{communication_language}`: counts, risks, open action items, and the recommendation with its story key. Offer to run the recommended skill. Surface `illegal` and `unrecognized` entries and the script's `warnings` (malformed action items land there); if the user gives corrections, apply them via the fix flow rather than ad-hoc edits. No time estimates — status, risks, and next steps only.
+
+If the script errors — malformed YAML, a hand-edited structure it can't parse, anything — do not stop at the error. Read `sprint-status.yaml` yourself, apply best judgment to give the user the same summary (counts, risks, next recommended action), tell them the deterministic path failed and why, and offer the fix flow (`fix-sprint-status.md`) so the script works next time.

package/src/bmm-skills/plan/bmad-sprint-planning/references/validate.md

@@ -0,0 +1,10 @@
+# Validate
+
+When the user asks whether `sprint-status.yaml` is well-formed, run:
+
+```
+uv run {skill-root}/scripts/sprint_plan.py validate \
+  --status-file {implementation_artifacts}/sprint-status.yaml
+```
+
+Never writes; exits 0 whether valid or not. Report `valid` in one line. If `problems` is non-empty, list them plainly (each names the key or field at fault) and offer the fix flow (`fix-sprint-status.md`). If `legacy_mapped` is non-empty, note the file still uses v6 status names and that any regenerate will rewrite them to the modern vocabulary — progress is preserved either way.