@ikunin/sprintpilot 2.2.31 → 2.3.1

package/_Sprintpilot/skills/sprintpilot-plan-sprint/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sprintpilot-plan-sprint
+description: 'Build (or refresh) the Sprintpilot sprint plan at _bmad-output/implementation-artifacts/sprint-plan.yaml. Infers per-epic + cross-epic dependencies from epics.md + architecture.md + sprint-status.yaml, presents the DAG, lets the user curate which stories belong in the active plan, and persists the result. Triggered by /sprintpilot-plan-sprint, by the autopilot when a stale plan is detected, or by `replan_sprint` mid-flight. Replaces the manual `infer-dependencies.js` workflow for end users.'
+---
+
+## STOP — read this entire file before doing anything
+
+This skill writes the authoritative sprint plan at
+`_bmad-output/implementation-artifacts/sprint-plan.yaml`. The plan
+controls which story Sprintpilot runs next and in what order, with
+dependency-aware priorities and optional external-tracker links.
+
+Follow **`./workflow.md`** verbatim. The 14 steps it lists are not
+suggestions — each one shells out to a primitive (`infer-dependencies.js`,
+`resolve-dag.js`, `sprint-plan.js`) that validates inputs and updates
+the plan atomically. Skipping a step or reordering them produces an
+inconsistent plan that downstream phases (autopilot queue resolver,
+reorder validator) will reject.
+
+### Never improvise
+
+- Never infer dependencies in chat — always pipe LLM JSON through
+  `node _Sprintpilot/scripts/infer-dependencies.js dry-run --epic <id>`
+  (or `--cross-epic`) first. The script enforces schema, unknown-key,
+  self-dep, cross-epic-isolation, missing-rationale, and cycle checks.
+  Hand-edited envelopes that bypass dry-run leave a plan that fails
+  validation on the next read.
+- Never write directly to `sprint-plan.yaml` — route every mutation
+  through `node _Sprintpilot/scripts/sprint-plan.js` so atomic write,
+  schema validation, and `generated`/`auto_inferred_at` stamping happen.
+- Never call an LLM "to plan the sprint" outside this skill. The skill
+  IS the LLM-driving layer; scripts never call models.
+
+### Invocation modes
+
+The skill responds to three callers:
+
+1. **User-direct:** `/sprintpilot-plan-sprint` with no arguments.
+   Build a plan from scratch (or refresh existing one).
+2. **Auto-derive:** the autopilot emits
+   `invoke_skill: sprintpilot-plan-sprint` with
+   `template_slots: { auto: true, reason, missing_keys?, removed_keys? }`
+   when a plan is missing/stale and the user opted in via
+   `autopilot.auto_plan_on_start: true`.
+3. **Replan:** the autopilot emits the same action with
+   `template_slots: { replan: true, reason }` after the user issued
+   `user_input { kind: 'replan_sprint' }` mid-flight.
+
+In every mode the skill follows the same 14-step workflow — only the
+"present results" tone differs (auto/replan modes assume the user wants
+a brief summary; user-direct mode is more conversational).
+
+### When NOT to invoke
+
+- BMad's `sprint-status.yaml` is missing → run `bmad-sprint-planning`
+  first; this skill has no work to do.
+- `epics.md` or `architecture.md` missing in
+  `_bmad-output/planning-artifacts/` → halt with a clear message
+  asking the user to run `bmad-create-epics-and-stories` and
+  `bmad-create-architecture` first.
+- The user only wants to see the existing DAG without editing →
+  use `node _Sprintpilot/scripts/resolve-dag.js render` directly;
+  no need to invoke this full skill.
+
+---
+
+Follow the instructions in ./workflow.md.

package/_Sprintpilot/skills/sprintpilot-plan-sprint/workflow.md

@@ -0,0 +1,435 @@
+# Sprintpilot — Sprint Plan Generation
+
+## Purpose
+
+Build (or refresh) `_bmad-output/implementation-artifacts/sprint-plan.yaml`
+— the authoritative sprint plan that drives autopilot story selection,
+DAG-aware reordering, and external-tracker integration. Infers per-epic
++ cross-epic dependencies via piped LLM envelopes (validated server-side
+by `infer-dependencies.js`), lets the user curate which stories belong
+in the active plan, and persists everything atomically.
+
+## Prerequisites
+
+| Artifact | Path | Required |
+|---|---|---|
+| BMad sprint-status | `_bmad-output/implementation-artifacts/sprint-status.yaml` | yes |
+| BMad epics | `_bmad-output/planning-artifacts/epics.md` | yes |
+| BMad architecture | `_bmad-output/planning-artifacts/architecture.md` | yes |
+
+If any required prerequisite is missing, halt with a `user_prompt`
+naming the missing file and the BMad skill that produces it
+(`bmad-sprint-planning`, `bmad-create-epics-and-stories`,
+`bmad-create-architecture`). Do NOT attempt the workflow without them.
+
+## Outputs
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `sprint-plan.yaml` | `_bmad-output/implementation-artifacts/` | Authoritative plan (read by autopilot + resolve-dag) |
+| `sprint-plan-dag.mmd` | `_bmad-output/implementation-artifacts/` | Rendered mermaid DAG (refreshed on every plan write) |
+| Archived legacy | `.archive/dependencies.yaml.migrated` | If a pre-v2.3.0 `_Sprintpilot/sprints/dependencies.yaml` existed |
+
+## Conventions used below
+
+- `<root>` = the project root passed via `--project-root` (or `cwd`).
+- All scripts live under `_Sprintpilot/scripts/` — invoke via `node <path>`.
+- LLM envelopes are JSON; you produce them, the script validates them.
+- On any 3-iteration validation failure (per-epic OR cross-epic), the
+  skill writes `_bmad-output/implementation-artifacts/sprint-plan.yaml.partial`
+  with the last attempted envelope + errors header, writes the sentinel
+  `.sprint-plan-validation-failed`, and halts with a `user_prompt`
+  asking the user to inspect the partial.
+
+---
+
+## Step 1 — Load Inputs
+
+<action>Verify the three required artifacts exist:
+- `_bmad-output/implementation-artifacts/sprint-status.yaml`
+- `_bmad-output/planning-artifacts/epics.md`
+- `_bmad-output/planning-artifacts/architecture.md`
+
+If any is missing, halt with a `user_prompt` naming what's missing.</action>
+
+<action>Read each into memory. Parse epics.md for the list of epic IDs.
+Parse sprint-status.yaml for the list of story keys under
+`development_status:` (or `stories:` for the alternate shape).</action>
+
+<action>Read the existing plan if present:
+```
+node _Sprintpilot/scripts/sprint-plan.js read --project-root <root>
+```
+Note: `exists: true/false` + the full plan body when present. Used by
+Step 3 to compute staleness and decide which epics need re-inference.</action>
+
+---
+
+## Step 2 — Migrate Legacy Dependencies (One-Shot)
+
+<action>Check whether a pre-v2.3.0 sidecar exists at
+`_Sprintpilot/sprints/dependencies.yaml`. If it does AND `sprint-plan.yaml`
+is absent OR has an empty `dependencies.stories` block, run the
+one-shot migration:
+```
+node _Sprintpilot/scripts/infer-dependencies.js migrate --project-root <root>
+```
+The migrate command imports the legacy `stories:` + `overrides:` blocks
+into the new plan, drops the legacy `epics:` block with a warning,
+and moves the old file to `.archive/dependencies.yaml.migrated`.
+
+If `migrated: false` and `reason: 'no_legacy_file'` — proceed silently.
+If `migrated: false` for any other reason — surface the message in a
+`user_prompt` and ask whether to continue with a fresh plan.</action>
+
+---
+
+## Step 3 — Staleness Check
+
+<action>Compute which epics need re-inference. The cheap way is to
+ask the orchestrator helper:
+```
+node -e "
+const m = require('./_Sprintpilot/lib/orchestrator/sprint-plan.js');
+console.log(JSON.stringify(m.planStaleness({projectRoot: process.cwd()})));
+"
+```
+Returns `{ stale: bool, reason, missing_keys?, removed_keys? }`.
+
+Decision matrix:
+
+| stale | reason | action |
+|---|---|---|
+| false | — | Skip Step 4 entirely (plan is fresh). Go to Step 5 unless invoked via /sprintpilot-plan-sprint with a "rebuild from scratch" intent. |
+| true | `missing` | Run Step 4 for EVERY epic in epics.md. |
+| true | `migration_needed` | Step 2 should have handled this — re-check; if still missing, run Step 4 for every epic. |
+| true | `added_stories` | Run Step 4 only for the epics whose stories appear in `missing_keys`. |
+| true | `removed_stories` | Run Step 4 for the epics affected (a missing story means the per-epic graph for that epic is stale). |
+| true | `corrupt` | Halt with a `user_prompt` showing the corruption error + offering archive+regenerate. |
+
+For hand-authored plans (no AUTO-INFERRED marker AND user-direct invocation
+of /sprintpilot-plan-sprint without explicit "rebuild" intent), confirm
+with a `user_prompt` before regenerating: "An existing plan has hand
+edits in the `dependencies` block. Proceed with regeneration (loses the
+edits) or skip per-epic inference and just refresh DAG render?"</action>
+
+---
+
+## Step 4 — Per-Epic Inference
+
+<action>For each epic that needs (re-)inference, run a tight loop:
+
+1. Generate the prompt:
+   ```
+   node _Sprintpilot/scripts/infer-dependencies.js scaffold-prompt --epic <id> --project-root <root>
+   ```
+   Stdout is the literal prompt — feed it back to yourself in chat as
+   the "next user message" to infer the dependencies. Read the four
+   files the prompt names; do not improvise based on memory.
+
+2. Produce a JSON envelope of the EXACT shape:
+   ```json
+   {
+     "version": 1,
+     "epic": "<id>",
+     "dependencies": { "<story-key>": ["<dep-key>", ...] },
+     "rationale":   { "<story-key>": "1 sentence quoting the AC/file/architecture line" }
+   }
+   ```
+   Stories with NO inbound deps are omitted from `dependencies`. Every
+   listed key needs a non-empty rationale. Cross-epic edges go through
+   Step 5 — don't put them here.
+
+3. Validate via dry-run:
+   ```
+   echo '<envelope>' | node _Sprintpilot/scripts/infer-dependencies.js dry-run --epic <id> --project-root <root>
+   ```
+   On `valid: true`, proceed. On `valid: false`, the response carries
+   an `errors[]` array — fix the envelope and retry. Max 3 iterations
+   per epic. On 3rd failure, save the partial + sentinel and halt
+   (see "Conventions" above).
+
+4. Commit the envelope:
+   ```
+   echo '<envelope>' | node _Sprintpilot/scripts/infer-dependencies.js write --epic <id> --project-root <root>
+   ```
+   `wrote: true, edges_inferred, edges_added, edges_removed` confirms
+   success. The script writes into `plan.dependencies.stories.*` while
+   preserving entries for other epics and the `overrides:` block.</action>
+
+---
+
+## Step 5 — Cross-Epic Detection
+
+<action>Now that per-epic edges are in place, ask the LLM whether
+any edges cross epic boundaries:
+
+1. Generate the cross-epic prompt:
+   ```
+   node _Sprintpilot/scripts/infer-dependencies.js scaffold-prompt --cross-epic --project-root <root>
+   ```
+
+2. Produce a JSON envelope:
+   ```json
+   {
+     "version": 1,
+     "cross_epic_deps": [
+       { "from_story": "<key>", "to_story": "<key>", "rationale": "<≤200 chars>" }
+     ]
+   }
+   ```
+   `from_story` depends on `to_story`. Both keys must belong to
+   DIFFERENT epics. If no cross-epic deps detected, send
+   `cross_epic_deps: []`.
+
+3. Validate via dry-run:
+   ```
+   echo '<envelope>' | node _Sprintpilot/scripts/infer-dependencies.js dry-run --cross-epic --project-root <root>
+   ```
+   Validator checks: keys exist in sprint-status, from/to epics differ,
+   rationale present (≤200 chars), no duplicate of per-epic edges,
+   no cycle in the combined graph. Max 3 iterations.
+
+4. Present each surviving edge to the user with its rationale:
+   ```
+   Cross-epic edge detected:
+     2-1-foo depends on 1-3-add-auth
+     Rationale: needs auth context from 1-3 before integration
+     [a] accept  [r] reject  [s] skip remaining edges
+   ```
+   Accept-all, reject-all, or per-edge. Rejected edges drop out;
+   accepted edges go through to write.
+
+5. Commit accepted edges:
+   ```
+   echo '<accepted envelope>' | node _Sprintpilot/scripts/infer-dependencies.js write-cross-epic --project-root <root>
+   ```</action>
+
+---
+
+## Step 6 — Issue Tracker Setup (Optional)
+
+<action>Ask the user (single user_prompt):
+> "Do you want to link stories to an external issue tracker
+> (Jira / Linear / GitHub / GitLab)? [y/N]"
+
+On `n` or skip — proceed to Step 7 without writing the `issue_tracker:`
+block.
+
+On `y` — collect:
+- `provider`: one of `jira`, `linear`, `github`, `gitlab`
+- `base_url`: full URL prefix (e.g., `https://co.atlassian.net`)
+- `project_key`: the tracker's project key (e.g., `PROJ` for Jira)
+
+Then call the sprint-plan primitive. Currently the simplest path is
+to read the plan, set `plan.issue_tracker = { provider, base_url, project_key }`,
+and write the whole plan back via `node _Sprintpilot/scripts/sprint-plan.js write`
+(piping the modified plan to stdin). The script validates schema and writes
+atomically.</action>
+
+---
+
+## Step 7 — Issue ID Capture (Optional)
+
+<action>Ask the user (single user_prompt):
+> "Capture external issue IDs for each epic/story? [Y]es / [n]o
+>  / [s]kip remaining for this epic / [p]attern (sequential IDs)"
+
+On `n` — proceed to Step 8 without setting any `issue_id` fields.
+
+On `Y` — loop through epics and stories. For each entity:
+> "Issue ID for epic 1 (or skip)?"
+> "Issue ID for story 1-3-add-auth (or skip)?"
+
+`p` mode prompts once for a prefix (e.g., `PROJ-`) + starting number;
+the skill assigns sequential IDs (`PROJ-100`, `PROJ-101`, …).
+
+**Validation rules** — `setIssueId` rejects these inputs (re-prompt if
+they appear; don't retry the same value):
+- Any of: `[ ] < > | ; & \n \r` or ASCII control characters
+- Any Unicode RTL/LTR override marks (`‪`–`‮`, `⁦`–`⁩`)
+- Length > 200 chars
+
+Legitimate tracker IDs from Jira (`PROJ-101`), Linear (`LIN-42`),
+GitHub (`org/repo#123`), and GitLab don't contain any of these. If a
+user enters something like `PROJ;101` or pastes a URL with embedded
+brackets, the validator throws — show the error and ask for a clean
+ID. Don't loop on the same broken input.
+
+For each captured ID, update the plan via read → mutate → write. The
+relevant primitive is `setIssueId(entity_key, issue_id, { projectRoot })`
+in `sprint-plan.js`; from this skill the simplest path is to bulk-edit
+the plan in memory and write it once at the end of the loop.
+
+Bulk skip options ensure this step doesn't become tedious on sprints
+with many stories.</action>
+
+---
+
+## Step 8 — Finalize Dependencies in Plan
+
+<action>By this point Steps 4 + 5 have written `plan.dependencies.stories`
+and `plan.cross_epic_deps`. Step 6/7 may have edited `issue_tracker`
+and per-entity `issue_id`. Re-read the plan once to confirm:
+```
+node _Sprintpilot/scripts/sprint-plan.js read --project-root <root>
+```
+The plan should validate cleanly. If `exists: true, error: ...` →
+something went wrong; halt with the error.</action>
+
+---
+
+## Step 9 — Build the Sprint-Wide DAG
+
+<action>Compute the topological layering for presentation:
+```
+node _Sprintpilot/scripts/resolve-dag.js graph --project-root <root>
+```
+Returns `{ nodes, edges, layers, width, cycle }`. If `cycle.length > 0`,
+the combined intra + cross-epic graph has a cycle (validator should
+have caught this earlier; if reached, halt with the offending nodes
+and ask the user to remove the bad edge).</action>
+
+---
+
+## Step 10 — Present the DAG
+
+<action>Render a text-mode topological tree to the user:
+```
+Layer 1 (parallel-eligible width: <N>):
+  - 1-1-bootstrap
+  - 2-1-foo                          ← cross-epic upstream of 1-3
+Layer 2:
+  - 1-2-models
+Layer 3:
+  - 1-3-add-auth  (depends on: 1-1, 1-2, 2-1)
+...
+```
+
+Highlight cross-epic edges with `←` or `cross-epic →` annotations.
+Show summary stats: total stories, total epics, max layer width
+(indicates parallel potential for v2.4.0), count of missing issue IDs.</action>
+
+<action>Also write the mermaid DAG file for visual review:
+```
+node _Sprintpilot/scripts/resolve-dag.js render --format mermaid --project-root <root>
+```
+Report the path to the user:
+> "DAG rendered to `_bmad-output/implementation-artifacts/sprint-plan-dag.mmd`
+> — preview in any markdown viewer (GitHub, VS Code with Mermaid Preview, etc.)."</action>
+
+---
+
+## Step 11 — Curation
+
+<action>Ask the user which stories belong in this sprint plan:
+> "Which stories do you want to run in this sprint?
+>  Default: ALL non-done stories.
+>  [Enter] accept default  [e] edit selection  [a:KEY] add  [r:KEY] remove"
+
+`Default: ALL non-done` means every story in sprint-status whose
+status is not `done`. Excluded stories carry `plan_status: excluded`
+in the plan — they remain visible in the file for context (e.g., as
+upstreams of included stories) but are NOT picked by the queue resolver.</action>
+
+<action>On `e` (edit), present a numbered list with `[x]` for included
+and `[ ]` for excluded; the user toggles entries by number.</action>
+
+---
+
+## Step 12 — Validate Selection
+
+<action>For each story marked included, every transitive upstream
+(intra-epic AND cross-epic) must be either ALSO included OR already
+done in sprint-status. Compute via the orchestrator helper:
+```
+node -e "
+const m = require('./_Sprintpilot/lib/orchestrator/sprint-plan.js');
+const plan = require('./_Sprintpilot/scripts/sprint-plan.js').read({projectRoot: process.cwd()});
+const proposed = [/* user-selected keys */];
+console.log(JSON.stringify(m.validateOrdering(proposed, plan, {projectRoot: process.cwd()})));
+"
+```
+Returns `{ valid, violations: [{story, upstream, suggestion}] }`.
+
+On `valid: false`, present each violation:
+> "Story `1-3-add-auth` (included) depends on `1-1-bootstrap` which is
+>  not in the plan and not done. Options:
+>  [a] add `1-1-bootstrap` to the plan
+>  [r] remove `1-3-add-auth` from the plan
+>  [x] exclude `1-3-add-auth` (keeps it visible but won't run)"
+
+Loop until `valid: true`. Excluded stories carry `plan_status: excluded`
+and the validator treats them as terminal.</action>
+
+---
+
+## Step 13 — Write Plan
+
+<action>Build the final plan object in memory:
+- `schema_version: 1`
+- `source: 'skill' | 'auto' | 'cli'` (use `auto` when invoked via
+  `template_slots.auto: true`, `skill` otherwise)
+- `plan_id`: keep existing if re-running; generate fresh on first
+  curation
+- `epics: []` — per-epic metadata captured in Step 1 (id, title)
+- `stories: []` — per-story entries with `key`, `epic`, `title`,
+  `plan_status` (`pending` for included, `excluded` for excluded),
+  `issue_id` (from Step 7), `priority` (1-indexed in topological order),
+  `upstream` (denormalized from `plan.dependencies.stories.<key>.depends_on`),
+  `cross_epic_upstream` (denormalized from `plan.cross_epic_deps`),
+  `added_by: 'skill'`, `added_at`
+- `dependencies`, `cross_epic_deps`, `overrides`, `notes` — preserved
+  from Steps 4-7
+- `status.last_run_outcome: 'success'`, `status.last_run_at: <now>`,
+  `status.last_error: null`
+
+Pipe to write:
+```
+echo '<plan-json>' | node _Sprintpilot/scripts/sprint-plan.js write --project-root <root>
+```
+The script validates schema, stamps `generated`, and atomically writes
+via tmp+rename.</action>
+
+<action>Re-render the DAG to reflect any curation changes:
+```
+node _Sprintpilot/scripts/resolve-dag.js render --format mermaid --project-root <root>
+```</action>
+
+---
+
+## Step 14 — Report
+
+<action>Summarize what was written:
+> "Sprint plan written to
+> `_bmad-output/implementation-artifacts/sprint-plan.yaml`.
+>
+> - **N** stories planned (M epics)
+> - **X** cross-epic edges
+> - **Y** stories excluded (kept for context)
+> - **Z** stories without issue IDs
+>
+> First 5 in execution order:
+>   1. 1-1-bootstrap
+>   2. 1-2-models
+>   3. ...
+>
+> Run `/sprint-autopilot-on` to begin execution, or
+> `/sprintpilot-plan-sprint` again to refine."</action>
+
+<action>If invoked via `template_slots.auto: true` or `replan: true`,
+keep the summary shorter (1-2 sentences) and return cleanly so the
+autopilot session resumes; do not block on confirmation.</action>
+
+---
+
+## Failure modes
+
+| Symptom | Recovery |
+|---|---|
+| Prerequisite artifact missing | Halt with `user_prompt` naming the missing file + the BMad skill that produces it. |
+| 3 consecutive validation failures (per-epic OR cross-epic) | Save `sprint-plan.yaml.partial` + `.sprint-plan-validation-failed` sentinel; halt asking the user to inspect. |
+| Cycle in combined intra+cross graph | Halt with the offending nodes; ask the user to remove or re-rationalize the bad edge. |
+| Plan write fails (disk full, permission) | The atomic tmp+rename is all-or-nothing — no torn state. Halt with the error message. |
+| `sprint-plan.yaml` corrupt on entry to Step 3 | Offer archive+regenerate via `user_prompt`. |
+| Skill invoked but `sprint-status.yaml` is empty | No stories to plan; halt and ask the user to run `bmad-sprint-planning` first. |

package/_Sprintpilot/skills/sprintpilot-sprint-progress/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: sprintpilot-sprint-progress
+description: 'Synthesize current sprint execution progress with LLM-layered judgment. Reads sprint-plan.yaml, sprint-status.yaml, and the autopilot ledger via `autopilot progress`; highlights stalls, repeated verify failures, retry loops, and stuck phases; suggests the next action (continue, narrow to a specific story, reorder, replan, abort). Use when you want a quick health check between autopilot sessions without scrolling through the raw ledger.'
+---
+
+## STOP — read this entire file before doing anything
+
+This skill is a **read-only diagnostic**. It does not change sprint-plan.yaml,
+sprint-status.yaml, or any persisted autopilot state. The goal is to produce
+a concise human-readable summary of where execution stands and what (if
+anything) the user should do about it.
+
+Follow **`./workflow.md`** verbatim. The three steps it lists are:
+
+1. Collect the structured snapshot via `autopilot progress --json`.
+2. Pull recent ledger entries for halt / verify / step context.
+3. Synthesize a brief progress report with LLM judgment + one
+   recommended next action.
+
+### Never improvise
+
+- **No file writes.** This skill is observational. If the user wants to
+  reorder, add stories, mark something skipped, or replan — point them
+  at the appropriate user_input command or `/sprintpilot-plan-sprint`.
+  Don't try to fix things from this skill.
+- **No state interpretation beyond what's in the ledger.** Don't
+  speculate about why a verify failed — just report what the ledger
+  says and recommend the user look at the relevant file.
+- **No long-form output by default.** Default mode is ≤15 lines. If
+  the user asks for more detail, narrow to a story and read its
+  recent step events.
+
+### When to invoke
+
+- Between autopilot sessions to check whether anything halted that
+  needs intervention.
+- When you (the LLM) just finished a long batch of stories and want
+  to know if anything's stuck before suggesting next moves.
+- When the user asks "how's the sprint going?" / "where are we?" /
+  "is autopilot stuck?".
+
+### When NOT to invoke
+
+- For machine-readable output: call
+  `node _Sprintpilot/bin/autopilot.js progress --json` directly. This
+  skill adds LLM synthesis on top — pure JSON consumers don't need it.
+- For full sprint reports: that's `bmad-sprint-status` (BMad-native,
+  reads sprint-status.yaml only).
+- For build / deploy / CI status: not this skill's domain.
+
+---
+
+Follow the instructions in ./workflow.md.