@houseofwolvesllc/claude-scrum-skill 1.7.0 → 1.8.0

package/README.md

@@ -60,7 +60,23 @@ PRD (optional)  -->  /project-orchestrate
 
 ## Installation
 
-### Claude Code Plugin (recommended)
+### npm (recommended)
+
+```bash
+# Global install — available in all projects
+npm install -g @houseofwolvesllc/claude-scrum-skill
+
+# Local install — this project only
+npm install @houseofwolvesllc/claude-scrum-skill
+```
+
+Global install copies skills to `~/.claude/skills/`. Local install copies them to `<project>/.claude/skills/` and adds `.claude-scrum-skill` to your `.gitignore`.
+
+Skills surface in Claude Code with their plain names: `/project-scaffold`, `/project-orchestrate`, `/sprint-plan`, etc.
+
+> **Heads-up on re-installs:** the postinstall script overwrites every file under `<install-dir>/skills/` with the package's shipped version. If you've customized `<install-dir>/skills/shared/config.json` (e.g., changed `paths.specs` or `paths.adr`), back it up before re-running `npm install` and restore your values afterward. Skill files outside the shipped set are left alone — only files that exist in the package are overwritten.
+
+### Claude Code Plugin (alternative)
 
 ```
 /plugin marketplace add houseofwolvesllc/claudescrumskill
@@ -73,22 +89,14 @@ This installs all skills as a native Claude Code plugin with automatic updates.
 /plugin marketplace update
 ```
 
-### npm
-
-```bash
-# Global install — available in all projects
-npm install -g @houseofwolvesllc/claude-scrum-skill
-
-# Local install — this project only
-npm install @houseofwolvesllc/claude-scrum-skill
-```
-
-Global install copies skills to `~/.claude/skills/`. Local install copies them to `<project>/.claude/skills/` and adds `.claude-scrum-skill` to your `.gitignore`.
+> **Important difference from npm install:** Claude Code namespaces plugin-installed skills with the marketplace identifier to prevent collisions between plugins. Skills surface as `/@houseofwolvesllc/project-scaffold`, `/@houseofwolvesllc/project-orchestrate`, etc. — **not** as `/project-scaffold` and `/project-orchestrate`. If you prefer the plain names, use the npm install path above; if you prefer the marketplace UI for discovery and updates, use this path and live with the namespace.
 
 ### Manual
 
 Clone the repo and copy the `skills/` contents into `~/.claude/skills/` (global) or `<project>/.claude/skills/` (per-project). All skill directories must be siblings under the same parent, with `shared/` alongside them — skills reference `../shared/references/` via relative paths.
 
+The manual path produces the same plain-name UX as npm install (both bypass the plugin layer's namespacing), but you forfeit automatic updates.
+
 > **Note:** After installing, restart Claude Code for the skills to become available.
 
 ---
@@ -377,6 +385,36 @@ During sprint planning, personas are assigned automatically based on story label
 
 `/project-orchestrate` chains all skills into a fully autonomous pipeline.
 
+### Invocation Patterns
+
+| Form | Behavior |
+|------|----------|
+| `/project-orchestrate` | Orchestrates all open epics in the existing backlog. |
+| `/project-orchestrate spec.md` | Single-spec orchestration. Scaffolds the spec, runs the full lifecycle. |
+| `/project-orchestrate spec-1.md spec-2.md spec-3.md` | **Sequential multi-path mode.** Each spec receives its own complete orchestration (Phase 1 → Phase 2 → Phase 3 → ADR → state cleanup) end-to-end before the next begins. Each spec gets its own design-spike (if triggered), emulation pass, cleanup, and ADR. |
+| `/project-orchestrate owner/repo` | GitHub mode — orchestrates the named repo's open epics. |
+| `/project-orchestrate spec.md owner/repo` | GitHub mode — scaffolds the spec into the named repo, then orchestrates only that PRD's epics. |
+| `/project-orchestrate --merged spec-1.md spec-2.md` | Opt-in merged mode. Treats inputs as one combined project with best-effort legacy behavior. Emits a warning that formal merged semantics are deferred to a follow-up spec — prefer the sequential default unless you need merged. |
+
+#### Multi-Path Flags
+
+- **`--skip-on-pause`** (default off) — when a spec's orchestration pauses on a safety gate, mark it skipped and advance to the next spec instead of pausing the queue. Use with caution; safety gates exist for a reason.
+- **`--merged`** (default off) — see the table above; opts into the legacy unified-multi-spec behavior.
+
+#### Inter-Spec Dependencies
+
+PRD documents can declare optional `depends_on` frontmatter to override the default argument-order execution:
+
+```yaml
+---
+title: Spec B
+depends_on:
+  - spec-a.md   # ensure spec-a runs before this one
+---
+```
+
+`/project-orchestrate` resolves the dependency graph at run start (topological sort, ties broken by argument order) and aborts before any spec executes if a cycle or missing dependency is detected. See `CONVENTIONS.md` → Frontmatter Fields → PRD Document Frontmatter for the full convention.
+
 ### Phase 1 — Epic Completion Loop
 
 1. Scaffolds the PRD (if provided) or reads existing backlog. On large or multi-epic PRDs, scaffolding runs in [two-pass mode](#two-pass-mode) and auto-injects a [design-spike epic](#design-spike-epic) at position 0
@@ -464,6 +502,7 @@ skills/shared/
 - **Chunk large epics** into multiple sprints for natural review gates.
 - **Jira/Trello users:** If no project key or board ID is configured, `/project-scaffold` creates one automatically (Scrum template for Jira).
 - **Author large PRDs with explicit architectural intent.** Sections describing shared types, naming conventions, file layout boundaries, and cross-cutting patterns give the [design-spike epic](#design-spike-epic) concrete material to lift into the project's foundational ADR and per-epic `CONTEXT.md` files — the better your PRD spells these out, the more consistent your parallel implementation subagents will be.
+- **For related specs, declare `depends_on` in PRD frontmatter** rather than relying on argument order. `/project-orchestrate` will topologically sort the queue and abort on cycles or missing deps before any spec runs — catches ordering mistakes up front instead of mid-orchestration.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Claude Code skills for scrum project management — PRD to production release pipeline with project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup.",
   "bin": {},
   "publishConfig": {

package/skills/project-orchestrate/SKILL.md

@@ -11,7 +11,8 @@ Fully autonomous project lifecycle driver. Plans sprints, executes stories via p
 
 ## Before You Start
 
-1. Read `../shared/references/CONVENTIONS.md` for all project management standards. Follow these conventions exactly. Pay particular attention to **Epic Structure → Design-Spike Epic** — orchestration honors the design-spike epic's gating, so implementation work in a scoped run does not begin until the design-spike epic completes.
+1. Read `../shared/references/CONVENTIONS.md` for all project management standards. Follow these conventions exactly. Pay particular attention to **Epic Structure → Design-Spike Epic** — orchestration honors the design-spike epic's gating, so implementation work in a scoped run does not begin until the design-spike epic completes. Also note **Frontmatter Fields → PRD Document Frontmatter** — the `depends_on` field controls inter-spec execution order in sequential multi-path mode.
+1a. **Multi-path mode and new flags:** when invoked with 2+ existing-file paths, `/project-orchestrate` runs in sequential multi-path mode (each spec receives its own complete orchestration end-to-end). Two new flags are accepted: `--skip-on-pause` (default off; advance the queue when a spec hits a safety gate instead of pausing) and `--merged` (default off; treat multi-path inputs as one combined legacy multi-spec project with a deprecation warning). See **Input Parsing and Mode Detection** for the full classification and **Sequential Multi-Path Mode** for execution details.
 2. Read `../shared/config.json` to determine the scaffolding mode (`scaffolding` key: `"local"`, `"github"`, `"jira"`, or `"trello"`, default: `"local"`). If `"local"`, also read the `paths.backlog` and `paths.context` values (`paths.context` defaults to `.claude-scrum-skill/context` and is where Step 3 subagents look for per-epic CONTEXT.md files). Read `../shared/references/PROVIDERS.md` for provider-specific API commands when using a remote provider.
 3. Read the project's `CLAUDE.md` (if it exists) for project-specific rules. **All subagents you spawn must also read and follow `CLAUDE.md`** — include this instruction explicitly in every subagent prompt.
 4. Read `../shared/references/PERSONAS.md` for role preambles. When spawning
@@ -42,33 +43,19 @@ The following actions are NEVER authorized:
 
 ## Default Operating Mode
 
-`/project-orchestrate` defaults to **fully autonomous execution**. When invoked with a PRD path or repo identifier, run the full lifecycle — Phase 1 (Epic Completion) → Phase 2 (Emulation Hardening) → Phase 3 (Project Cleanup) → Step 16 (ADR Update) → Step 17 (State Cleanup) — end-to-end without pausing for routine confirmation.
+Run autonomously on invocation. Standing Authorizations cover the normal lifecycle — proceed under them without asking.
 
-### What autonomous means
+**No pre-flight audits.** Don't list concerns and present a menu of options before starting. Pick the spec's literal intent and go. Surface defects in execution output as you encounter them, not as pre-execution gates. Asking "which option do you want?" before executing is itself a violation of autonomous mode.
 
-- **No routine confirmation prompts.** Accept the skill's prescribed default at every decision point: sprint plans, story execution order, branch creation, merges to `development`, branch cleanup. The Standing Authorizations above cover the full set; do not re-ask for them.
-- **All phases run.** Phase 2 (Emulation Hardening) and Phase 3 (Project Cleanup) are **mandatory** quality gates — they execute even when Phase 1 produces a small or clean change set. Skipping them defeats the orchestration's quality model.
-- **State file handling is automatic — never prompt the user.**
-  - `Status: running` → resume from the recorded position.
-  - `Status: paused` → resume from the recorded position. The original pause cause should already be addressed before the user re-invokes; if it isn't, the run will pause again on the same issue and surface it fresh.
-  - `Status: completed` → rename the prior file to `orchestration-state.previous.md` and start a fresh run.
-  - No file → initialize a new state file.
-- **Scaffolding decisions fire per their own trigger logic.** Two-pass mode and design-spike epic injection are governed by `project-scaffold/SKILL.md` → Mode Detection and Design-Spike Epic. The orchestrator does NOT add a separate confirmation prompt on top of those triggers — if the scaffold spec says inject, the orchestrator lets it inject.
+**Phase 2 (Emulation) and Phase 3 (Cleanup) always run.** Mandatory on every orchestration regardless of how small or clean the Phase 1 change set looks. For projects with no traditional toolchain (e.g., a markdown-only repo), Phase 3 reports SKIP/PASS — that is the correct outcome, not a reason to omit the phase.
 
-### When pausing IS allowed
+**State file is automatic.** `Status: running` or `paused` → resume from the recorded position. `Status: completed` → rename to `orchestration-state.previous.md` and start a fresh run. Missing → initialize a new file. Never prompt.
 
-Only the four genuine safety gates pause the run. These exist because they require human judgment that no default can satisfy:
+**Scaffolding decisions fire per their own trigger logic.** Two-pass mode and design-spike epic injection live in `project-scaffold/SKILL.md` (Mode Detection, Design-Spike Epic). The orchestrator does NOT add a separate confirmation prompt on top of those triggers.
 
-1. **Unresolvable merge conflict.** Auto-rebase attempted first; if it fails, pause and surface the conflicting files (per Step 5c and Error Handling → Merge Conflicts).
-2. **Critical findings in the review gate.** The `review` persona's recommendation of `block` / `revert` pauses orchestration so the user can decide how to proceed (per Step 5b).
-3. **3rd consecutive hardening run still produces critical/warning findings.** The safety valve at Step 13 — three rounds of automated hardening without convergence suggests the remaining issues need human triage.
-4. **Rate-limit exhaustion.** After exponential-backoff retries fail (per Error Handling → Rate Limiting), pause rather than burn through quota.
+**Pause only on four real safety issues:** unresolvable merge conflict (Step 5c, Error Handling → Merge Conflicts); critical review/emulation finding (Step 5b, `block`/`revert` recommendation); 3rd consecutive hardening run still dirty (Step 13 safety valve); rate-limit exhaustion (Error Handling → Rate Limiting). Nothing else.
 
-All four are infrequent and indicate real problems. None can be defaulted away. Every other pause point in this document — sprint plan confirmation, state file resume confirmation, phase transition confirmation, completion confirmation — is removed by the autonomous default.
-
-### Overriding the default
-
-If the user explicitly requests interactive mode for the current run (e.g., "let me approve each sprint plan", "pause between phases", "stop after Phase 1"), honor that for the current invocation. The skill's default remains autonomous; the override is per-invocation and does not change the default.
+**Per-invocation overrides are honored** when the user explicitly asks for interactive mode for the current run ("pause between phases", "let me approve each sprint", etc.). The default remains autonomous.
 
 ---
 
@@ -80,8 +67,7 @@ If the user explicitly requests interactive mode for the current run (e.g., "let
 2. **A repo identifier** (e.g., `owner/repo`, GitHub mode only) — orchestrate **all open epics and stories** already on the project board. No scaffolding step.
 3. **A PRD file path + repo identifier** (e.g., `path/to/prd.md owner/repo`, GitHub mode only) — scaffold the PRD into the specified repo, then orchestrate only those epics/stories.
 4. **Nothing** — GitHub mode: detect the repo from the current git remote and orchestrate all open epics/stories. Local mode: orchestrate all open epics/stories in the configured backlog directory.
-
-**How to distinguish:** If an argument is a path to an existing file, treat it as a PRD. Otherwise treat it as a repo identifier (GitHub mode only).
+5. **Multiple PRD paths** (e.g., `spec-1.md spec-2.md spec-3.md`) — sequential per-spec orchestration. Each spec receives its own complete orchestration (Phase 1 → Phase 2 → Phase 3 → ADR → state cleanup) end-to-end before the next begins. See **Input Parsing and Mode Detection** below.
 
 ### Scope Rules
 
@@ -90,6 +76,157 @@ If the user explicitly requests interactive mode for the current run (e.g., "let
 
 ---
 
+## Input Parsing and Mode Detection
+
+Before any orchestration work begins, classify the invocation into one of the modes below and announce the decision. The classification depends on how many tokens are in `$ARGUMENTS` and how many of them resolve to existing files on disk.
+
+### Mode Classification
+
+**Pre-classification step:** Before applying the table below, separate **flag tokens** (those starting with `--`, e.g., `--skip-on-pause`, `--merged`) from **argument tokens**. Count and classify only the argument tokens. Flags are validated and consumed separately by the Flag Parsing subsection below; they do not contribute to the token count or the file/non-file determination.
+
+Apply these rules in order; the first match wins.
+
+| Argument token count | All resolve to files? | Mixed? | Mode |
+|----------------------|----------------------|--------|------|
+| 0 | — | — | **No-arg mode** (existing v1.7.1) — orchestrate open epics in the backlog. |
+| 1 | yes | — | **Single-spec mode** (existing v1.7.1) — scaffold + orchestrate this one PRD. |
+| 1 | no | — | **Repo-identifier mode** (existing v1.7.1, GitHub only) — orchestrate the repo's open epics. |
+| Exactly 2 | exactly one is a file, the other is not | — | **Single-spec + repo mode** (existing v1.7.1, GitHub only) — scaffold the PRD into the named repo, orchestrate only that PRD's epics. |
+| 2+ | yes (all tokens are paths to existing files) | — | **Sequential multi-path mode** (new) — see "Sequential Multi-Path Mode" section. |
+| 2+ | no (all tokens are non-files) | — | **ERROR.** Multi-repo invocation is unsupported. Abort with a message listing the repo identifiers offered and noting that exactly one repo identifier is permitted per invocation. |
+| 2+ | mixed (some files, some non-files, AND not the exactly-2 single-spec+repo case above) | yes | **ERROR.** Abort with a clear message listing which tokens are paths and which are not. Mixed argument lists outside the single-spec+repo shape are unsupported. |
+
+### Flag Parsing
+
+`/project-orchestrate` accepts the following flags. They may appear in any position within `$ARGUMENTS`:
+
+- **`--skip-on-pause`** (default off) — in sequential multi-path mode, a spec whose orchestration pauses on a safety gate is marked `skipped`, its in-progress state file is archived with `.skipped.md` suffix, and the queue advances to the next spec. Without this flag (the default), the queue pauses and waits for the user to resolve the gate before re-invocation.
+- **`--merged`** (default off) — when set with 2+ PRD paths, treat the inputs as one combined multi-spec project using legacy best-effort behavior. Emits a deprecation warning that formal merged semantics are not yet specified. Prefer the sequential default unless merged behavior is explicitly required.
+
+The flags are orthogonal: pass either, both, or neither.
+
+Unknown flags or invalid flag values MUST cause the skill to abort with an error BEFORE starting any orchestration work. Example: `--mode=fast` is unknown; abort and list the supported flags.
+
+### Glob Expansion
+
+Modern shells expand globs (e.g., `docs/specs/*.md`) before passing to Claude Code, so the skill typically sees pre-expanded paths. If `$ARGUMENTS` arrives with literal glob characters (`*`, `?`, `[...]`) still present, the skill MUST expand the glob itself BEFORE applying mode classification.
+
+### Announcement (Mandatory)
+
+Before any orchestration work begins, announce the chosen mode and the count of specs (for multi-path) so the user understands what's about to happen:
+
+```
+Multi-path orchestration mode: 3 specs detected.
+
+Dependency graph: no depends_on declarations — using argument order.
+Execution order:
+  1. spec-1.md
+  2. spec-2.md
+  3. spec-3.md
+
+Flags: none.
+
+Starting Spec 1/3 — spec-1.md
+```
+
+For single-spec, repo-identifier, or no-arg modes, the announcement is the existing v1.7.1 startup summary; no new format required.
+
+### Routing
+
+- **Sequential multi-path mode** → run Dependency Resolution (next subsection), then invoke the per-spec wrapper documented in **Sequential Multi-Path Mode**.
+- **Merged mode** (with `--merged`) → see **Sequential Multi-Path Mode → Merged Mode (Opt-In)**.
+- **All other modes** → continue with the existing State Management and Phase 1 sections unchanged.
+
+### Dependency Resolution
+
+Applies only to sequential multi-path mode (and merged mode if dependencies need to inform internal ordering). Runs after Mode Classification but BEFORE any spec executes.
+
+#### `depends_on` Frontmatter
+
+Each PRD/spec MAY declare an optional `depends_on` field in its YAML frontmatter. The value is a YAML list of paths or basenames. See `CONVENTIONS.md` → Frontmatter Fields → PRD Document Frontmatter for the full convention.
+
+```yaml
+---
+title: My Spec
+depends_on:
+  - other-spec.md            # basename match against other args
+  - subdir/another-spec.md   # path match relative to this spec's directory
+---
+```
+
+#### Path Resolution
+
+For each entry in a spec's `depends_on` list:
+
+1. Try interpreting the entry as a path relative to the declaring spec's own directory. If it canonicalizes to one of the specs in the current invocation's argument list (compared by canonical absolute path), the dependency resolves.
+2. If step 1 fails, try interpreting the entry as a basename match against the basenames (filename without directory) of the argument-list specs. If exactly one spec in the list has a matching basename, the dependency resolves.
+3. If neither step 1 nor step 2 resolves to a spec in the current invocation's argument list, ABORT the run with a clear error message naming the unresolved entry. Do NOT start any spec. Silent ignoring of unresolved dependencies would lead to subtle wrong-order execution.
+
+#### Dependency Graph Construction
+
+After resolving every spec's `depends_on` entries, build a directed acyclic graph (DAG):
+
+- Nodes: each spec in the argument list.
+- Edges: from depended-upon spec → dependent spec. (If spec-B has `depends_on: [spec-A.md]`, the edge is `spec-A → spec-B`, meaning A must complete before B.)
+
+#### Cycle Detection
+
+Detect cycles using the standard algorithm (e.g., DFS with a visiting-set). A cycle includes:
+
+- Two-node cycles: `A → B → A`.
+- Longer cycles: `A → B → C → A`.
+- Self-loops: a spec declaring `depends_on: [itself.md]`.
+
+If any cycle is detected, ABORT with the following error format BEFORE starting any spec:
+
+```
+ERROR: Dependency cycle detected. No specs were started.
+
+Cycle members:
+  spec-a.md → depends_on: spec-b.md
+  spec-b.md → depends_on: spec-a.md
+
+Resolve the cycle (remove one of the declarations) and re-run.
+```
+
+#### Missing-Dependency Detection
+
+If any `depends_on` entry references a path that does not appear in the current invocation's argument list (after path resolution per the rules above), ABORT with the following error format BEFORE starting any spec:
+
+```
+ERROR: Dependency not in argument list. No specs were started.
+
+Missing dependency:
+  spec-b.md declares depends_on: [spec-a.md]
+  spec-a.md is not present in this invocation.
+
+Either add spec-a.md to the invocation, or remove the depends_on declaration in spec-b.md.
+```
+
+#### Topological Sort with Stable Tie-Break
+
+Once the graph passes cycle and missing-dependency checks, topologically sort the specs. Tie-break: when two specs have no dependency relationship between them, the one appearing earlier in the original `$ARGUMENTS` order executes first. The sort MUST be stable.
+
+#### No-`depends_on` Fallback
+
+If NO spec declares `depends_on`, execution order is simply the order tokens appear in `$ARGUMENTS`. No graph construction or topological sort is performed (or, equivalently, an empty graph topo-sorts to the input order).
+
+#### Pre-Execution Validation Order
+
+All validation runs BEFORE any spec's orchestration begins (NFR-3):
+
+1. Mixed-argument detection (per Mode Classification).
+2. Flag validation (unknown flags abort).
+3. Glob expansion (if needed).
+4. `depends_on` parsing and path resolution.
+5. Cycle detection.
+6. Missing-dependency detection.
+7. Topological sort.
+
+Only after all of these pass does the per-spec wrapper start invoking the per-spec orchestration.
+
+---
+
 ## State Management
 
 Orchestration state is persisted to `.claude-scrum-skill/orchestration-state.md` so progress survives context compaction, usage caps, and session restarts. This file is human-readable markdown.
@@ -759,6 +896,217 @@ run starts with a clean slate:
 rm -f .claude-scrum-skill/orchestration-state.md
 ```
 
+**In multi-path mode, Step 17 is suppressed.** The multi-path wrapper handles per-spec state file archival with a slug-suffixed name instead — see Sequential Multi-Path Mode → Per-Spec State File Lifecycle.
+
+---
+
+## Sequential Multi-Path Mode
+
+Applies when Mode Classification selected sequential multi-path mode (2+ tokens, all paths to existing files, `--merged` not set). This section is the wrapper that invokes the existing single-spec orchestration (Phases 1-3 + Step 16 + Step 17, as documented above) once per spec, in the order determined by Dependency Resolution.
+
+### Per-Spec Loop
+
+For each spec in the topologically-sorted execution order:
+
+1. Update the queue state file (see below): mark this spec's row as `in-progress`, record `Started` timestamp.
+2. Invoke the full single-spec orchestration against this spec. This is the existing v1.7.1 flow — Phase 1 (Epic Completion Loop, including scaffolding via `/project-scaffold`), Phase 2 (Emulation Hardening Loop), Phase 3 (Project Cleanup), Step 16 (ADR Update). Step 17 (state file cleanup) is **suppressed** in multi-path mode; the wrapper handles archival instead.
+3. On the spec's natural completion: archive `.claude-scrum-skill/orchestration-state.md` to `.claude-scrum-skill/orchestration-state-<spec-slug>.previous.md` BEFORE the next spec begins. Update the queue state file: mark this spec's row as `completed`, record `Completed` timestamp, update aggregate stats.
+4. On the spec's safety-gate pause:
+   - **Without `--skip-on-pause`** (default): the per-spec state file remains at `.claude-scrum-skill/orchestration-state.md` with `Status: paused`. Update the queue state file: mark this spec's row as `paused`, set queue `Status: paused`. Exit the wrapper. The remaining specs in the queue are NOT started. The user resolves the gate, re-invokes `/project-orchestrate` with the same arguments, and the queue resumes from this spec.
+   - **With `--skip-on-pause`**: archive `.claude-scrum-skill/orchestration-state.md` to `.claude-scrum-skill/orchestration-state-<spec-slug>.skipped.md`. Update the queue state file: mark this spec's row as `skipped`, record the pause reason. Continue to the next spec.
+5. Per-spec orchestration runs to completion (or pause) before the next spec begins — no interleaving of sprints, no concurrent execution.
+
+### Spec Slug Derivation
+
+A spec's slug is derived from its filename: `basename(path, ".md")`.
+
+- `docs/specs/20260527_215752_multi_spec_sequential_orchestration.md` → `20260527_215752_multi_spec_sequential_orchestration`
+- `spec-a.md` → `spec-a`
+
+If two specs in the same invocation produce the same slug (e.g., one is `foo/spec.md`, another is `bar/spec.md`), ABORT before starting any spec — slug collisions would clobber each other's archived state files. Error format:
+
+```
+ERROR: Spec slug collision. No specs were started.
+
+Colliding specs:
+  foo/spec.md → slug "spec"
+  bar/spec.md → slug "spec"
+
+Rename one of the specs so basenames differ, then re-run.
+```
+
+### Per-Spec State File Lifecycle
+
+| Event | State file action |
+|-------|-------------------|
+| Spec starts | Per-spec orchestration creates `.claude-scrum-skill/orchestration-state.md` (existing v1.7.1 behavior). |
+| Spec completes naturally | Wrapper renames to `.claude-scrum-skill/orchestration-state-<slug>.previous.md`. |
+| Spec pauses, no `--skip-on-pause` | File remains at canonical location with `Status: paused`. Queue exits. |
+| Spec pauses, with `--skip-on-pause` | Wrapper renames to `.claude-scrum-skill/orchestration-state-<slug>.skipped.md`. Queue advances. |
+| Resume from paused state | Per-spec orchestration reads `.claude-scrum-skill/orchestration-state.md` and resumes (existing v1.7.1 behavior). The wrapper resumes the queue from this spec's position based on the queue state file. |
+
+Single-spec mode state file lifecycle is unchanged from v1.7.1 — no slug suffix, no queue file. Step 17's `rm -f` runs as it always did. Only multi-path mode uses the slug-suffix archival and suppresses Step 17.
+
+### Queue State File
+
+Multi-path mode maintains a queue state file at `.claude-scrum-skill/orchestration-queue-state.md` tracking the entire run. The file is human-readable markdown.
+
+**Structure:**
+
+```markdown
+# Orchestration Queue State
+
+## Meta
+- **Mode:** sequential | merged
+- **Status:** running | paused | completed
+- **Started:** <ISO timestamp>
+- **Last Updated:** <ISO timestamp>
+- **Flags:** --skip-on-pause=<true|false>, --merged=<true|false>
+
+## Specs (resolved execution order)
+| # | Spec Path | Slug | Status | Started | Completed | State File Archive |
+|---|-----------|------|--------|---------|-----------|--------------------|
+| 1 | docs/specs/spec-a.md | spec-a | completed | <ts> | <ts> | orchestration-state-spec-a.previous.md |
+| 2 | docs/specs/spec-b.md | spec-b | in-progress | <ts> | — | orchestration-state.md (live) |
+| 3 | docs/specs/spec-c.md | spec-c | pending | — | — | — |
+
+## Dependency Graph
+- spec-c depends_on spec-a
+- spec-b depends_on spec-a
+(or "no dependencies declared" if empty)
+
+## Aggregate (updated as specs complete)
+- **Total specs:** N
+- **Completed:** N
+- **Paused:** N (current: <spec-slug>, if any)
+- **Skipped:** N
+- **Pending:** N
+- **Total stories delivered (across completed specs):** N
+- **Total sprints executed:** N
+- **Total ADRs created:** N
+
+## Log
+- [<ts>] Multi-path run started — 3 specs in scope
+- [<ts>] Dependency graph resolved — execution order: spec-a, spec-b, spec-c
+- [<ts>] Spec 1/3 (spec-a) started
+- [<ts>] Spec 1/3 (spec-a) completed — 12 stories, 3 sprints
+- [<ts>] Spec 2/3 (spec-b) started
+```
+
+**Lifecycle:**
+
+- Created at multi-path mode start (after Mode Classification, Flag Parsing, Glob Expansion, and Dependency Resolution all pass).
+- Updated after every spec status transition: pending → in-progress → completed | paused | skipped.
+- On clean completion (all specs `completed` or `skipped`, none `paused`): renamed to `orchestration-queue-state.previous.md`. The wrapper emits the Cumulative Summary.
+- On paused run: remains in place with `Status: paused` and the paused spec identified. Resume continues from the paused spec.
+
+**On startup**, check for an existing `.claude-scrum-skill/orchestration-queue-state.md`:
+
+- `Status: running` → resume from the recorded position (autonomous default).
+- `Status: paused` → resume from the recorded position. The paused spec's per-spec state file is read by its own resume logic.
+- `Status: completed` → rename to `orchestration-queue-state.previous.md` and start a fresh run.
+- No file → initialize a new queue state file.
+
+Never prompt. Same autonomous-default discipline as the single-spec state file (see Default Operating Mode).
+
+### Safety-Gate Pause Announcements
+
+**Default (without `--skip-on-pause`):**
+
+```
+[Spec 2/3] spec-b.md — paused on safety gate.
+
+Pause reason: 3rd consecutive hardening run produced 2 critical findings
+(see .claude-scrum-skill/reports/emulation-report/ISSUES.md).
+
+Remaining specs (1) are not started. Queue state preserved at
+.claude-scrum-skill/orchestration-queue-state.md.
+
+Resolve the findings and re-invoke /project-orchestrate with the same
+arguments to resume. The queue picks up at spec-b.md.
+```
+
+**With `--skip-on-pause`:**
+
+```
+[Spec 2/3] spec-b.md — paused on safety gate. --skip-on-pause set; marking skipped.
+
+Skipped reason: 3rd consecutive hardening run produced 2 critical findings.
+State archived to .claude-scrum-skill/orchestration-state-spec-b.skipped.md.
+
+Continuing to Spec 3/3 — spec-c.md
+```
+
+### Resume Semantics
+
+A multi-path run paused on a safety gate is resumed by re-invoking `/project-orchestrate` with the same argument list. The queue state file's recorded execution order takes precedence — even if a spec's `depends_on` frontmatter changed between attempts, the resumed run uses the order recorded at the original run's start. This prevents subtle ordering shifts mid-run.
+
+Completed specs are NOT re-executed on resume. The wrapper skips entries marked `completed` and `skipped`, resumes the entry marked `paused` (handing off to the per-spec orchestration's own resume logic), and continues with `pending` entries afterward.
+
+### Cumulative Summary
+
+At the end of a multi-path run (all specs `completed` or `skipped`, none `paused`), emit a cumulative summary mirroring the existing single-spec completion summary structure, with a per-spec section plus an aggregate header.
+
+Format:
+
+```
+## Multi-Spec Orchestration Complete
+
+### Aggregate
+- Specs in queue: 3
+- Completed: 2 (spec-a, spec-c)
+- Skipped: 1 (spec-b, paused on 3rd hardening run; archived)
+- Total stories delivered: 27 (44 story points)
+- Total sprints: 7
+- Total ADRs created: 3
+- Total duration: 4h 12m
+
+### Per-Spec
+
+#### spec-a.md  ✅ Completed
+- 3 sprints, 12 stories, 18 points
+- Design-spike: yes (ADR-0007, 2 CONTEXT.md files)
+- Emulation runs: 1 (clean)
+- Cleanup: PASS
+- State archive: orchestration-state-spec-a.previous.md
+- ADR: docs/adrs/0007-spec-a-architecture.md
+
+#### spec-b.md  ⚠️ Skipped (paused, --skip-on-pause)
+- 2 sprints, 8 stories, 13 points completed before pause
+- Pause reason: 3rd hardening run produced 2 critical findings
+- State archive: orchestration-state-spec-b.skipped.md
+- Report: .claude-scrum-skill/reports/emulation-report/ISSUES.md
+
+#### spec-c.md  ✅ Completed
+- 4 sprints, 15 stories, 26 points
+- Design-spike: no (single epic)
+- Emulation runs: 2 (clean after hardening)
+- Cleanup: PASS
+- State archive: orchestration-state-spec-c.previous.md
+- ADR: docs/adrs/0008-spec-c-architecture.md
+```
+
+After emitting the summary, mark the queue `Status: completed` and rename `orchestration-queue-state.md` → `orchestration-queue-state.previous.md`.
+
+### Merged Mode (Opt-In)
+
+When `--merged` is set alongside 2+ PRD paths, the skill treats the inputs as one combined multi-spec project using legacy best-effort behavior — the pre-v1.8.0 path where the agent improvises merge policy at runtime (one combined scaffold call, one merged design-spike, one combined sprint cycle, one emulation, one cleanup, one ADR pass).
+
+Emit the following deprecation-style warning BEFORE proceeding:
+
+```
+WARNING: --merged is set. Multi-path inputs will be treated as one combined
+project with best-effort merge semantics. Formal merged behavior is not
+yet specified (deferred to a follow-up spec); results may be inconsistent
+run-to-run.
+
+If you want predictable per-spec isolation, drop --merged and re-run.
+
+Proceeding with merged mode...
+```
+
+Then run the legacy unified-multi-spec flow. The queue state file is still created (with `Mode: merged` in Meta) but tracks the merged invocation as a single combined orchestration rather than per-spec entries. Formal merged semantics — shared design-spike strategy, cross-spec dependency resolution, unified state file vs queue file — are deferred to a follow-up spec.
+
 ---
 
 ## Communication Pattern

package/skills/shared/references/CONVENTIONS.md

@@ -241,6 +241,29 @@ In local-mode backlogs (`scaffolding: "local"`), epic and story files use YAML f
 
 Absence of `epic_type` means a standard implementation epic — this preserves backward compatibility with existing `_epic.md` files.
 
+### PRD Document Frontmatter
+
+PRD/spec documents (passed to `/project-scaffold` or `/project-orchestrate`) may declare an optional `depends_on` field at the top of the document. The field is consumed by `/project-orchestrate` when running in sequential multi-path mode to determine inter-spec execution order — see `project-orchestrate/SKILL.md` → Input Parsing and Mode Detection → Dependency Resolution for the full algorithm.
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `depends_on` | list of strings | Other specs in the same multi-path invocation that must complete before this one. Each entry is either a path (relative to this spec's directory) or a basename matching another spec in the argument list. Absence of the field means no inter-spec constraint — execution falls back to argument order. |
+
+Example:
+
+```yaml
+---
+title: My Spec
+depends_on:
+  - other-spec.md            # basename match against other args
+  - subdir/another-spec.md   # path match relative to this spec's directory
+---
+```
+
+`depends_on` is parallel in spirit to the story-level `blocked_by` field, but operates at the spec level. `/project-orchestrate` resolves the dependency graph at run start (topological sort, stable tie-break on argument order) and aborts the run BEFORE any spec executes if a cycle or missing dependency is detected. Cycles include self-references (`depends_on: [this-spec.md]`).
+
+The field is ignored in single-path orchestrate invocations and in `/project-scaffold` invocations — it only takes effect when 2+ existing-file paths are passed to `/project-orchestrate`.
+
 ## Sprint Cadence
 
 - Default sprint length: **2 weeks** (configurable per project)