@ikunin/sprintpilot 2.2.31 → 2.3.1

package/_Sprintpilot/scripts/state-shard.js

@@ -46,6 +46,16 @@ const CRITICAL_KEYS = new Set([
   'current_bmad_step',
   'in_worktree',
   'patch_commits',
+  // Pre-existing divergence with state-store.js — story_queue was added
+  // there for crash-resume of `--stories` / `--epic` queues but was
+  // never mirrored here. Added in v2.3.0 Round 4 for symmetry; without
+  // it, a process killed mid-queue would lose the queue head from the
+  // pending buffer that hadn't flushed yet.
+  'story_queue',
+  // v2.3.0 — verify-loop trackers must persist across crashes; see
+  // _Sprintpilot/lib/orchestrator/state-store.js for full rationale.
+  'last_verify_issues_signature',
+  'consecutive_identical_rejections',
 ]);
 
 const KIND_DIR = {
@@ -88,11 +98,9 @@ function validateKind(k) {
 }
 
 // Read BMad's `output_folder` config so a project that customized its
-// output location doesn't end up with shards split between
-// `_bmad-output/` (writer hardcoded) and `<output_folder>/` (reader
-// honoring config). Pre-2.0.8 this script ignored output_folder
-// entirely, contradicting sibling scripts (mark-done-stories-tasks.js)
-// that did read it.
+// output location keeps shards in the configured directory. Sibling
+// scripts (mark-done-stories-tasks.js) read the same config, so all
+// writers stay consistent.
 function readOutputFolder(projectRoot) {
   const cfg = path.join(projectRoot, '_bmad', 'bmm', 'config.yaml');
   if (!fs.existsSync(cfg)) return null;

package/_Sprintpilot/scripts/summarize-timings.js

@@ -139,9 +139,8 @@ function pairEvents(events) {
       // mark-API records arrive already paired. Anomalous records
       // (clock_skew / over_threshold) are tallied separately and never
       // contribute to p50/p95/max — otherwise a single backstep or
-      // stale marker poisons aggregates the way the v2.0.4 raw clamp
-      // did before the split. duration_ms must be a finite non-negative
-      // number; defensive against hand-edited shards.
+      // stale marker would poison the aggregates. duration_ms must be
+      // a finite non-negative number; defensive against hand-edited shards.
       //
       // Truthy comparison (not `=== true`) so a hand-edited shard with
       // `clock_skew: 1` or any other truthy value is still recognized

package/_Sprintpilot/skills/sprint-autopilot-on/SKILL.md

@@ -27,10 +27,38 @@ Follow **`./workflow.orchestrator.md`** verbatim. Flow control lives in
   is a HUMAN command. The autopilot's purpose is to drive without
   stopping until `session_story_limit`, a TRUE BLOCKER, retry-budget
   exhaustion, or `sprint_is_complete`. Heuristics like "PR opened,
-  time for review" / "natural breakpoint" / "let CI catch up" are NOT
-  valid reasons to pause — see `workflow.orchestrator.md` § "Pause is
+  time for review" / "natural breakpoint" / "let CI catch up" /
+  "context budget" / "clean checkpoint" / "merge cadence" / any
+  meta-reasoning about session length, story count, or your own
+  resource usage are NOT valid reasons to pause. Phrases like
+  "User-initiated checkpoint to control session length / context" in
+  a `details` string are LLM self-narration even when the wrapper
+  claims user intent — see `workflow.orchestrator.md` § "Pause is
   human-only."
 
+### Don't over-defend signals
+
+The verifier handles structural recovery for several common omission
+patterns — so you don't need to over-echo fields that the runner /
+git already prove:
+
+- `dev_red`: if you omit `test_files`, the verifier auto-detects test
+  files from `git diff` + untracked files (per-language regex). If you
+  provide them but with repo-relative paths, the verifier resolves
+  them against `projectRoot`.
+- `dev_green` / `patch_retest` / `nano_quick_dev`: if you omit
+  `tests_run`, the verifier accepts the runner's count.
+- `story_done`: if you omit `git_steps_completed: true`, the verifier
+  probes `git cat-file -e <commit_sha>` + `git ls-remote --heads
+  origin <branch>` and accepts the signal when both succeed.
+- `code_review`: findings recorded as a `### Review Findings` section
+  in the story file (the `bmad-code-review` convention) are accepted
+  alongside the legacy `_bmad-output/reviews/<key>.md` location.
+
+Provide the canonical fields when you have them — they're the audit
+trail. The recovery paths are for when the work is correct but the
+signal echo is incomplete.
+
 `workflow.orchestrator.md` is the **sole authority** for the rest of the
 session.
 

package/_Sprintpilot/skills/sprint-autopilot-on/workflow.orchestrator.md

@@ -6,8 +6,7 @@ state machine that enforces the BMad 7-step sequence. You own the
 *in-skill execution, diagnosis, triage, and small-judgment decisions* —
 not the flow.
 
-This file is the **≤150-line** authoritative workflow. It is the only
-workflow shipped — the v2.0.x prose `workflow.md` is gone.
+This file is the **≤150-line** authoritative workflow.
 
 ## The loop
 
@@ -83,7 +82,7 @@ Wrap everything in `{ "status": "...", ... }` and pass to
 | `failure`             | `reason`, `diagnosis` (first-class — fed back into next retry), `recoverable: boolean`           |
 | `blocked`             | `blocker_kind` (one of the 5 TRUE BLOCKERS or recoverable kinds), `details`, `user_input_needed`, `consecutive_count?` |
 | `propose_alternative` | `reason`, `alternative` (full Action object), `urgency_hint?` (raises impact only). Low impact → auto-accepted; medium / high → orchestrator stores the alternative in `state.pending_alternative` and emits `user_prompt`. The user accepts via `user_input` `{ kind: 'accept_alternative' }` or rejects via `force_continue` (both clear `pending_alternative`). |
-| `user_input`          | `commands: UserCommand[]` (validated server-side; see user-commands.js). Kinds: `skip_story`, `abort_sprint`, `force_continue`, `override_decision`, `change_profile`, `pause` (cleanly halts THIS session; next `/sprint-autopilot-on` resumes), `accept_alternative` (dispatches the stored `pending_alternative`), `trigger_retrospective` (v2.2.31+ — force-routes to RETROSPECTIVE for the current epic regardless of `remaining_stories_in_epic`; use when the user explicitly says "close out epic N with retro" while non-terminal stories remain). **NEVER send `pause` on your own initiative** — see "Pause is human-only" below. |
+| `user_input`          | `commands: UserCommand[]` (validated server-side; see user-commands.js). Kinds: `skip_story`, `abort_sprint`, `force_continue`, `override_decision`, `change_profile`, `pause` (cleanly halts THIS session; next `/sprint-autopilot-on` resumes), `accept_alternative` (dispatches the stored `pending_alternative`), `trigger_retrospective` (force-routes to RETROSPECTIVE for the current epic regardless of `remaining_stories_in_epic`; use when the user explicitly says "close out epic N with retro" while non-terminal stories remain). **NEVER send `pause` on your own initiative** — see "Pause is human-only" below. |
 | `verify_override`     | `evidence: { decision_log_ref?, explanation, expected_paths? }` — used when verify.js is wrong   |
 
 ## Pause is human-only
@@ -148,11 +147,11 @@ bookkeeping you'd otherwise be tempted to skip:
 | Phase | Bookkeeping that MUST be true before you signal `success` |
 |---|---|
 | `prepare_story_branch` | Every step in `action.steps` exited 0 — HEAD is on `action.branch` (verify with `git rev-parse --abbrev-ref HEAD`). Emitted only when `git.granularity ∈ {story, epic}` AND `git.reuse_user_branch=false`. Under `reuse_user_branch=true` this phase is skipped — the user-locked branch is detected at cmdStart instead. |
-| `create_story` | Story file has an Acceptance Criteria section (heading level 2-4: `##`/`###`/`####`; title `Acceptance Criteria` or `AC`) with at least one list entry (`-`, `*`, or numbered `1.` / `1)`) AND a `## Tasks` (or `## Tasks/Subtasks`) section with at least one `[ ]` or `[x]` checkbox. v2.2.25+ relaxed cosmetic variants. |
-| `dev_red` / `dev_green` | Test files exist on disk; runner exit codes match the phase contract; `tests_run` matches the runner's count. If `test_files` is omitted (v2.2.17+), the verifier auto-detects them from `git diff` + untracked files filtered by language convention. If `tests_run` is omitted (v2.2.21/22+), the runner's count is accepted. Relative paths are resolved against `projectRoot` (v2.2.18+). |
-| `code_review` | Findings recorded in any of: (a) `### Review Findings` section in the story file (what `bmad-code-review` actually writes), (b) `_bmad-output/reviews/<story_key>.md` (legacy), or (c) `_bmad-output/implementation-artifacts/code-review-<story_key>.md` (older repos). `findings[]` carries `{id, severity, category, action: 'block'\|'patch'\|'defer', rationale}` for every finding. v2.2.17+ accepts all three locations. |
+| `create_story` | Story file has an Acceptance Criteria section (heading level 2-4: `##`/`###`/`####`; title `Acceptance Criteria` or `AC`) with at least one list entry (`-`, `*`, or numbered `1.` / `1)`) AND a `## Tasks` (or `## Tasks/Subtasks`) section with at least one `[ ]` or `[x]` checkbox. |
+| `dev_red` / `dev_green` | Test files exist on disk; runner exit codes match the phase contract; `tests_run` matches the runner's count. Relative `test_files` paths resolve against `projectRoot`. The verifier auto-detects `test_files` from `git diff` + untracked files (language-shape filter) when the LLM omits the array, and accepts the runner's `tests_run` when the LLM omits the count — so signal echo of these two fields is optional when the underlying work is correct. |
+| `code_review` | Findings recorded in any of: (a) `### Review Findings` section in the story file (what `bmad-code-review` writes), (b) `_bmad-output/reviews/<story_key>.md`, or (c) `_bmad-output/implementation-artifacts/code-review-<story_key>.md`. `findings[]` carries `{id, severity, category, action: 'block'\|'patch'\|'defer', rationale}` for every finding. |
 | `patch_apply` | Every `patch_finding` id present in `state.patch_findings` is included in `applied_finding_ids`. |
-| `story_done` (and `nano_quick_dev`) | sprint-status.yaml shows this story as `done` (under `development_status.<story_key>` or inline). Story file has zero remaining `[ ]` task boxes — dev-story is responsible for flipping them to `[x]`. `commit_sha` and `branch` reported; `story_key` matches. **`git_steps_completed: true` in success output** — set this ONLY after every step in `action.steps` (the orchestrator's decorated git plan: `git add`, `git commit`, `git push -u origin <branch>`) has exited 0. If the flag is omitted, v2.2.17+ verifies the underlying git state directly: probes `git cat-file -e <commit_sha>` AND `git ls-remote --heads origin <branch>` — when both succeed and match, the signal is accepted. The flag remains the canonical signal; the probe is a recovery path. |
+| `story_done` (and `nano_quick_dev`) | sprint-status.yaml shows this story as `done` (under `development_status.<story_key>` or inline). Story file has zero remaining `[ ]` task boxes — dev-story is responsible for flipping them to `[x]`. `commit_sha` and `branch` reported; `story_key` matches. **`git_steps_completed: true` in success output** — set this ONLY after every step in `action.steps` (the orchestrator's decorated git plan: `git add`, `git commit`, `git push -u origin <branch>`) has exited 0. The flag is the canonical signal; when omitted, the verifier probes `git cat-file -e <commit_sha>` AND `git ls-remote --heads origin <branch>` and accepts the signal when both succeed and the remote sha matches. |
 | `retrospective` | `_bmad-output/retrospectives/<epic>.md` exists. |
 
 Skipping any of these — even when the code is "obviously done" — produces
@@ -194,9 +193,36 @@ land step from `state.land_pending`.
 On the next `autopilot start`, the orchestrator fingerprints
 `_bmad-output/`, sprint-status.yaml, and per-story branch HEADs against
 the fingerprint recorded at the last halt. Any divergence is emitted as
-`{ kind: 'resume_divergence', differences: ... }`. Forward the diff to
-the user; let them resolve via `user_input` (`force_continue` or
-`override_decision`).
+`{ kind: 'resume_divergence', differences: ... }`. Two escape paths
+proceed despite a divergent fingerprint:
+
+- **External-completion auto-acknowledge.** When the persisted
+  `current_story` is `done` in sprint-status (story merged outside the
+  autopilot — manual PR merge, hotfix, UI action), `autopilot start`
+  clears the stale story identity and proceeds. The next story is
+  picked from the queue or sprint-status as normal. Ledger records
+  `kind: resume, divergence: { kind: 'divergence_accepted', reason:
+  'external_completion', story: <key> }`.
+- **`--accept-divergence` flag** — catch-all for divergence patterns
+  the auto-acknowledge doesn't cover (multiple stories completed
+  externally, branch heads moved, etc.). Logged with
+  `reason: 'explicit_accept'`.
+
+For divergences that fit neither path (genuine corruption, unexpected
+state), forward the diff to the user and let them resolve via
+`user_input` (`force_continue` or `override_decision`).
+
+## Post-GREEN lint gate
+
+When `git.lint.enabled` is true, the verifier runs the composed
+lint pipeline (`scripts/post-green-gates.js`: lint-changed +
+lint-test-pitfalls + ci-parity scan) after the standard `dev_green`
+checks pass. `git.lint.blocking` governs whether a failed gate halts
+the autopilot for the LLM to fix-loop, or passes through with the
+failure logged for visibility. `git.lint.output_limit` truncates each
+gate's output; `git.lint.linters.<language>: [...]` overrides the
+default per-language linter priority (empty list disables a language;
+`javascript` + `typescript` keys merge into a single `js-ts` bucket).
 
 ## What you must NEVER do
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/architecture-mapper.md

@@ -6,18 +6,20 @@ You are analyzing a codebase to identify system design patterns, module boundari
 
 Scan the project at `{{project_root}}` and write your findings to `{{output_file}}`.
 
-## Quality Bar
+## Output standard
 
-- **Patterns matter more than lists.** Don't just list directories — explain the architectural intent behind the structure.
-- **Be prescriptive, not descriptive.** Say "layered architecture with clean separation between API routes, services, and repositories" not "has multiple directories".
-- **Every finding needs a file path.** No claims without evidence.
+- **Show structure, don't just enumerate it.** Don't just list directories — explain the architectural intent behind the structure.
+- **Commit to a definite finding.** Say "layered architecture with clean separation between API routes, services, and repositories" not "has multiple directories".
+- **Cite the file path for every claim.** No assertion without evidence.
 - **Focus on boundaries.** What talks to what? Where are the seams?
 
-## Forbidden Files — NEVER Read
+## Off-limits files
 
-- `.env`, `.env.*` (secrets)
-- `*.key`, `*.pem`, `*.p12` (private keys)
-- `credentials.json`, `service-account.json`
+Do not open these. Note their existence in the file inventory but never read or quote their contents:
+
+- environment files (`.env`, `.env.<variant>`)
+- private keys and certs (`*.key`, `*.pem`, `*.p12`)
+- credential blobs (`credentials.json`, `service-account.json`)
 
 ## Ignore-file Awareness
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/concerns-hunter.md

@@ -6,19 +6,21 @@ You are scanning a codebase for tech debt, security issues, deprecated patterns,
 
 Scan the project at `{{project_root}}` and write your findings to `{{output_file}}`.
 
-## Quality Bar
+## Output standard
 
-- **Patterns matter more than lists.** Don't just count TODOs — assess systemic debt patterns.
-- **Be prescriptive, not descriptive.** Say "12 TODO comments in auth module suggest incomplete migration from session-based to JWT auth" not "found some TODOs".
-- **Every finding needs a file path and line number.**
+- **Look for systemic patterns, not isolated counts.** Don't just count TODOs — assess systemic debt patterns.
+- **Commit to a definite finding.** Say "12 TODO comments in auth module suggest incomplete migration from session-based to JWT auth" not "found some TODOs".
+- **Cite a file path and line number for every claim.**
 - **Severity must be justified.** CRITICAL = blocks features or security risk. HIGH = degrades reliability. MEDIUM = maintenance burden. LOW = cleanup opportunity.
 
-## Forbidden Files — NEVER Read
+## Off-limits files
 
-- `.env`, `.env.*` (secrets)
-- `*.key`, `*.pem`, `*.p12` (private keys)
-- `credentials.json`, `service-account.json`
-- Files in `.git/` directory
+Do not open these. Note their existence in the file inventory but never read or quote their contents:
+
+- environment files (`.env`, `.env.<variant>`)
+- private keys and certs (`*.key`, `*.pem`, `*.p12`)
+- credential blobs (`credentials.json`, `service-account.json`)
+- anything under `.git/`
 
 ## Ignore-file Awareness
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/integration-mapper.md

@@ -6,20 +6,22 @@ You are mapping all external dependencies, APIs, services, and data stores that
 
 Scan the project at `{{project_root}}` and write your findings to `{{output_file}}`.
 
-## Quality Bar
+## Output standard
 
-- **Patterns matter more than lists.** Don't just list env vars — explain the integration topology.
-- **Be prescriptive, not descriptive.** Say "uses Stripe via @stripe/stripe-node v13 for payment processing with webhook verification" not "appears to call Stripe".
-- **Every finding needs a file path.** No claims without evidence.
+- **Describe the topology, not just the catalog.** Don't just list env vars — explain the integration topology.
+- **Commit to a definite finding.** Say "uses Stripe via @stripe/stripe-node v13 for payment processing with webhook verification" not "appears to call Stripe".
+- **Cite the file path for every claim.** No assertion without evidence.
 - **Redact actual secrets.** Show variable names and patterns only. NEVER output real tokens, keys, or passwords.
 
-## Forbidden Files — NEVER Read Contents Of
+## Off-limits files
 
-- `.env`, `.env.local`, `.env.production` (actual secrets)
-- `*.key`, `*.pem`, `*.p12` (private keys)
-- `credentials.json`, `service-account.json`
+Do not open these. Note their existence but never quote contents:
 
-**DO read**: `.env.example`, `.env.sample`, `.env.template` (safe — contain variable names only)
+- environment files holding real values (`.env`, `.env.local`, `.env.production`)
+- private keys and certs (`*.key`, `*.pem`, `*.p12`)
+- credential blobs (`credentials.json`, `service-account.json`)
+
+**OK to read**: `.env.example`, `.env.sample`, `.env.template` — these contain variable names only, no secrets.
 
 ## Ignore-file Awareness
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/quality-assessor.md

@@ -6,18 +6,20 @@ You are analyzing a codebase to assess code quality, test coverage, CI/CD maturi
 
 Scan the project at `{{project_root}}` and write your findings to `{{output_file}}`.
 
-## Quality Bar
+## Output standard
 
-- **Patterns matter more than lists.** Don't just count test files — assess whether the test strategy is sound.
-- **Be prescriptive, not descriptive.** Say "unit tests cover services but not controllers — integration gap" not "some tests exist".
-- **Every finding needs a file path.** No claims without evidence.
+- **Assess strategy, don't just tally artifacts.** Don't just count test files — assess whether the test strategy is sound.
+- **Commit to a definite finding.** Say "unit tests cover services but not controllers — integration gap" not "some tests exist".
+- **Cite the file path for every claim.** No assertion without evidence.
 - **Ratios tell the story.** Test:source ratio, coverage gaps, CI stage completeness.
 
-## Forbidden Files — NEVER Read
+## Off-limits files
 
-- `.env`, `.env.*` (secrets)
-- `*.key`, `*.pem`, `*.p12` (private keys)
-- `credentials.json`, `service-account.json`
+Do not open these. Note their existence in the file inventory but never read or quote their contents:
+
+- environment files (`.env`, `.env.<variant>`)
+- private keys and certs (`*.key`, `*.pem`, `*.p12`)
+- credential blobs (`credentials.json`, `service-account.json`)
 
 ## Ignore-file Awareness
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/stack-analyzer.md

@@ -6,19 +6,21 @@ You are analyzing a codebase to produce a complete technology inventory.
 
 Scan the project at `{{project_root}}` and write your findings to `{{output_file}}`.
 
-## Quality Bar
+## Output standard
 
-- **Patterns matter more than lists.** Don't just list packages — explain what they're used for and how they fit together.
-- **Be prescriptive, not descriptive.** Say "uses React 18 with Server Components" not "appears to use React".
-- **Every finding needs a file path.** No claims without evidence (e.g., `package.json:15`).
+- **Show how parts connect.** Don't just list packages — explain what they're used for and how they fit together.
+- **Commit to a definite finding.** Say "uses React 18 with Server Components" not "appears to use React".
+- **Cite the file path for every claim.** No assertion without evidence (e.g., `package.json:15`).
 - **Version numbers are critical.** Always include the exact version, not "latest" or "recent".
 
-## Forbidden Files — NEVER Read
+## Off-limits files
 
-- `.env`, `.env.*` (secrets)
-- `*.key`, `*.pem`, `*.p12` (private keys)
-- `credentials.json`, `service-account.json`
-- `*.secret`, `*password*`, `*token*` (in filenames)
+Do not open these. Note their existence in the file inventory but never read or quote their contents:
+
+- environment files (`.env`, `.env.<variant>`)
+- private keys and certs (`*.key`, `*.pem`, `*.p12`)
+- credential blobs (`credentials.json`, `service-account.json`)
+- anything whose filename contains `secret`, `password`, or `token`
 
 ## Ignore-file Awareness
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/workflow.md

@@ -1,6 +1,6 @@
 # Multi-Agent Codebase Map
 
-> Inspired by [GSD's map-codebase](https://github.com/gsd-build/get-shit-done). Adapted with distinct output format and enriched agent prompts.
+> Inspired by [GSD's map-codebase](https://github.com/gsd-build/get-shit-done) (MIT, Copyright (c) 2025 Lex Christopherson). Adapted with distinct output format and rewritten agent prompts. Full attribution: [NOTICES.md](../../../NOTICES.md).
 
 ## Purpose
 

package/_Sprintpilot/skills/sprintpilot-dependency-graph/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: sprintpilot-dependency-graph
+description: 'Render the sprint dependency graph from sprint-plan.yaml in a chosen format. Accepts mermaid (default), graphviz, text (topological tree), layers (parallel-eligible groups), or json (raw nodes + edges). Use when you want to visualize or programmatically inspect the DAG without manually calling resolve-dag.js. Optionally narrow to a single epic with an epic argument.'
+---
+
+## STOP — read this entire file before doing anything
+
+This skill is a **read-only renderer**. It does not modify `sprint-plan.yaml`,
+trigger LLM inference, or change autopilot state. The goal is to produce a
+visualization or structured dump of the existing dependency graph.
+
+Follow **`./workflow.md`** verbatim. The 4-step flow:
+
+1. Parse the user's invocation for a format + optional epic scope.
+2. Resolve format ambiguity by asking the user (only when no argument
+   was supplied).
+3. Shell out to `resolve-dag.js` with the resolved flags.
+4. Render the output inline (mermaid block) or report the written
+   file path (graphviz / mermaid-to-file).
+
+### Never improvise
+
+- **No file edits to `sprint-plan.yaml`.** If the plan is missing or
+  empty, point the user at `/sprintpilot-plan-sprint` — do NOT try to
+  build a plan from this skill.
+- **No re-inference.** Dependency inference lives in
+  `/sprintpilot-plan-sprint`. This skill renders what's already there.
+- **No format substitution.** If the user explicitly asks for graphviz
+  and `dot` isn't installed, the underlying script auto-falls-back to
+  mermaid with a stderr notice — surface that fallback clearly so the
+  user knows their requested format wasn't honored.
+
+### Invocation patterns
+
+| User input | Behavior |
+|---|---|
+| `/sprintpilot-dependency-graph` | Ask: mermaid / graphviz / text / layers / json |
+| `/sprintpilot-dependency-graph mermaid` | Render mermaid; inline the diagram in chat |
+| `/sprintpilot-dependency-graph graphviz` | Write .dot file; report path |
+| `/sprintpilot-dependency-graph text` | Topological-tree to chat, no file |
+| `/sprintpilot-dependency-graph layers` | JSON [[layer1], [layer2], ...] to chat |
+| `/sprintpilot-dependency-graph json` | JSON `{nodes, edges, epic}` to chat |
+| `/sprintpilot-dependency-graph mermaid epic 1` | Per-epic scope (cross-epic edges excluded) |
+| `/sprintpilot-dependency-graph mermaid --output dag.mmd` | Custom output path |
+
+Natural-language synonyms (parse loosely):
+- "show me the dependency graph" → ask for format
+- "render the dag as mermaid" → mermaid
+- "dot graph" / "graphviz output" → graphviz
+- "layers" / "parallel groups" → layers
+- "tree" / "text" / "plain" → text
+
+### When NOT to invoke
+
+- You want to BUILD or RE-INFER the graph → `/sprintpilot-plan-sprint`.
+- You want sprint progress / health → `/sprintpilot-sprint-progress`.
+- You want the BMad-native sprint-status report → `bmad-sprint-status`.
+- The plan file is absent → halt politely and point the user at the
+  planning skill instead of rendering an empty graph.
+
+---
+
+Follow the instructions in ./workflow.md.

package/_Sprintpilot/skills/sprintpilot-dependency-graph/workflow.md

@@ -0,0 +1,227 @@
+# Sprintpilot — Dependency Graph Renderer
+
+## Purpose
+
+Render the sprint dependency graph from `sprint-plan.yaml` in a
+user-chosen format without requiring shell commands. Wraps
+`resolve-dag.js` (`render` / `graph` / `layers` / `width`) so the user
+just types `/sprintpilot-dependency-graph mermaid` (or interactive
+prompt) and the visualization lands in chat.
+
+## Outputs
+
+- For **mermaid** + **text** + **layers** + **json** → rendered inline
+  in chat. Mermaid additionally writes a `.mmd` file (default
+  `_bmad-output/implementation-artifacts/sprint-plan-dag.mmd`) so the
+  user can preview in any markdown viewer.
+- For **graphviz** → writes a `.dot` file (default
+  `_bmad-output/implementation-artifacts/sprint-plan-dag.dot`); reports
+  the path. No inline render (chat doesn't render dot directly).
+
+No file mutations beyond the rendered output file.
+
+## Conventions
+
+- `<root>` = project root.
+- All formats accept an optional `--epic <id>` scope. When set,
+  cross-epic edges are filtered out; only intra-epic structure renders.
+- All formats accept an optional `--output <path>` for the file modes
+  (mermaid / graphviz).
+- Mermaid is the default when ambiguity needs to be resolved — it's
+  the most portable (GitHub-renderable, no system deps).
+
+---
+
+## Step 1 — Parse the User's Invocation
+
+<action>The user invoked this skill with optional arguments. Parse:
+
+1. **Format** (one of `mermaid` / `graphviz` / `text` / `layers` / `json`).
+   Accept synonyms:
+   - "mermaid" / "mmd" → mermaid
+   - "graphviz" / "dot" → graphviz
+   - "text" / "tree" / "plain" → text
+   - "layers" / "parallel" / "topo" → layers
+   - "json" / "raw" → json
+
+2. **Epic scope** (optional). Match `epic <id>` / `--epic <id>` / `for epic <id>`.
+
+3. **Output path** (optional). Match `--output <path>` / `to <path>`.
+
+If the user provided a format → skip Step 2.
+If they didn't → proceed to Step 2.</action>
+
+---
+
+## Step 2 — Ask for Format (When Ambiguous)
+
+<action>Only when the user invoked with no format argument, present a
+single multi-choice prompt:
+
+> Which format?
+>   [m] mermaid    — visual flowchart (default; GitHub-renderable, no deps)
+>   [g] graphviz   — .dot file for the dot toolchain (requires `dot` in PATH)
+>   [t] text       — topological tree rendered inline
+>   [l] layers     — JSON of parallel-eligible groups [[a], [b,c], ...]
+>   [j] json       — raw graph {nodes, edges, epic}
+
+Default to mermaid on empty input. If the user types something
+ambiguous, ask once more; don't default silently — they explicitly
+declined to pick a default.</action>
+
+---
+
+## Step 3 — Verify the Plan Exists
+
+<action>Check that `sprint-plan.yaml` exists and is readable:
+```
+node _Sprintpilot/scripts/sprint-plan.js read --project-root <root>
+```
+
+Three branches:
+
+- **`exists: false`** → halt politely:
+  > "No sprint plan found at `_bmad-output/implementation-artifacts/sprint-plan.yaml`.
+  > Run `/sprintpilot-plan-sprint` to build one, then re-invoke this
+  > skill to render the graph."
+  Do NOT attempt to render an empty graph.
+
+- **`exists: true, error: ...`** → corrupt plan file. Surface the
+  error message and halt:
+  > "sprint-plan.yaml exists but is unreadable: `<error message>`.
+  > Inspect manually, or run `/sprintpilot-plan-sprint` to rebuild
+  > from scratch."
+
+- **Valid plan** → proceed to Step 4.
+
+Also note: if `plan.stories` is `[]` (skill curation not yet done),
+the resolver still works — it falls back to sprint-status order. Mention
+that in the output so the user knows the graph isn't yet curation-aware.</action>
+
+---
+
+## Step 4 — Render
+
+<action>Pick the right `resolve-dag.js` subcommand based on the chosen
+format. All commands accept `--project-root <root>` and optionally
+`--epic <id>`.
+
+### Mermaid (default)
+
+```
+node _Sprintpilot/scripts/resolve-dag.js render --format mermaid \
+  [--epic <id>] [--output <path>] --project-root <root>
+```
+
+Returns JSON `{wrote, file, format, nodes, edges, fallback?}`. Then
+read the rendered file and inline its contents in a ```mermaid fenced
+code block so the chat client (Claude Code, etc.) renders the diagram
+inline. Also report the file path so the user can preview elsewhere:
+
+> Rendered to `<file>`. Below is the inline mermaid:
+> ```mermaid
+> flowchart LR
+>   subgraph epic_1 ["PROJ-100: Epic 1"]
+>     1-1-bootstrap["PROJ-101: 1-1-bootstrap"]:::done
+>     1-3-add-auth["1-3-add-auth"]:::pending   ← no issue_id set
+>   end
+>   ...
+> ```
+
+When `plan.stories[*].issue_id` or `plan.epics[*].issue_id` is set, the
+renderer prefixes the visual label with `<issue_id>: ` so the diagram
+cross-references back to the user's tracker (Jira / Linear / GitHub /
+GitLab). Stories/epics without an issue_id render with the bare key —
+silence communicates "not tracked" rather than spamming `[no issue]`.
+
+### Graphviz
+
+```
+node _Sprintpilot/scripts/resolve-dag.js render --format graphviz \
+  [--epic <id>] [--output <path>] --project-root <root>
+```
+
+If the result envelope has `fallback: 'graphviz-missing'`, the script
+silently rendered mermaid instead — surface that clearly to the user:
+
+> Graphviz toolchain (`dot`) not found in PATH; fell back to mermaid.
+> Output: `<mmd path>`. Install graphviz (e.g., `brew install graphviz`,
+> `apt install graphviz`) to get .dot output.
+
+Otherwise, report:
+
+> Rendered to `<dot path>`. Render to PNG with:
+>   `dot -Tpng <dot path> -o dag.png`
+
+### Text (topological tree)
+
+```
+node _Sprintpilot/scripts/resolve-dag.js layers \
+  [--epic <id>] --project-root <root>
+```
+
+Returns JSON `[[layer1], [layer2], ...]`. Render in chat as a tree:
+
+> Sprint DAG (topological layers — items in the same layer have no
+> mutual dependency and could run in parallel):
+>
+>   Layer 1: 1-1-bootstrap, 1-2-models
+>   Layer 2: 1-3-add-auth
+>   Layer 3: 2-1-foo
+>   ...
+>
+> Width: <N>  (max parallel-eligible stories at any single layer)
+
+### Layers (raw JSON)
+
+```
+node _Sprintpilot/scripts/resolve-dag.js layers \
+  [--epic <id>] --project-root <root>
+```
+
+Pretty-print the JSON array directly:
+
+> ```json
+> [
+>   ["1-1-bootstrap", "1-2-models"],
+>   ["1-3-add-auth"],
+>   ["2-1-foo"]
+> ]
+> ```
+
+### JSON (full graph)
+
+```
+node _Sprintpilot/scripts/resolve-dag.js graph \
+  [--epic <id>] --project-root <root>
+```
+
+Pretty-print the JSON `{nodes, edges, epic}`:
+
+> ```json
+> {
+>   "nodes": ["1-1-bootstrap", "1-2-models", "1-3-add-auth", "2-1-foo"],
+>   "edges": [
+>     ["1-1-bootstrap", "1-3-add-auth"],
+>     ["1-2-models", "1-3-add-auth"],
+>     ["1-3-add-auth", "2-1-foo"]
+>   ],
+>   "epic": null
+> }
+> ```
+
+In every mode, surface counts at the end: "N nodes, M edges,
+K cross-epic" (compute cross-epic by counting edges whose endpoints
+have different leading hyphen segments — leverage the JSON output).</action>
+
+---
+
+## Failure modes
+
+| Symptom | Recovery |
+|---|---|
+| Plan file missing | Halt with pointer to `/sprintpilot-plan-sprint`. Do NOT auto-build. |
+| Plan file corrupt | Surface the parse error from `sprint-plan.js read`; suggest re-running the planning skill. |
+| Cycle detected (`resolve-dag.js` exits 1 with "cycle detected") | Report the cycling node list verbatim. Suggest reviewing `plan.dependencies.stories` for the named keys, or re-running `/sprintpilot-plan-sprint` to re-infer. |
+| Graphviz binary missing | Note the fallback; tell the user how to install `dot`; do NOT silently retry with a different format. |
+| Output file write fails (permission, disk full) | Surface the error from the resolve-dag stderr; chat-render the JSON output as a fallback so the user still gets something usable. |