@houseofwolvesllc/claude-scrum-skill 1.8.1 → 2.1.0

package/skills/design-patterns/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: design-patterns
+description: >-
+  Faithful Gang of Four design-pattern catalog for complex core-domain design.
+  Used by project-spec (to name candidate patterns against real axes of
+  variation) and project-orchestrate (to refactor toward a named pattern while
+  implementing core-domain epics). Surfaces on a specific, demonstrated design
+  problem — conditional/switch logic on a type spreading across call sites, a
+  need for runtime-substitutable behavior, adding variants without modifying
+  existing classes, an object that must notify dependents, or a deliberate
+  extension point — or when a pattern is named explicitly. NOT for CRUD,
+  scripts, glue code, one-off transforms, or routine feature work; for those,
+  prefer the simplest thing that works.
+---
+
+# Design Patterns (Gang of Four)
+
+The classic catalog from *Design Patterns: Elements of Reusable Object-Oriented
+Software* (Gamma, Helm, Johnson, Vlissides). This skill is the **situational
+layer** — it composes on top of the Engineering Baseline and never overrides it.
+
+---
+
+## Read this before reaching for any pattern
+
+**You almost certainly do not need a pattern.** Patterns are a destination you
+**refactor toward** once a smell proves you need the flexibility — not a design
+you start from. This is the discipline of *Refactoring to Patterns* (Kerievsky),
+and it is the only safe way to use this catalog.
+
+Subordinate every entry below to the **Arbitration Rule** in
+`../shared/references/ENGINEERING_BASELINE.md`:
+
+> Simple design is the default. Abstractions and patterns are responses to
+> demonstrated complexity — never anticipatory architecture.
+
+Guardrails:
+
+- **Prefer the simplest thing that works.** Three similar lines beat a premature
+  abstraction. A function, a closure, a map, or a plain conditional usually wins.
+- **Apply the rule of three.** Don't introduce a pattern for one or two cases.
+  Wait until duplication or repeated change in the same place demands it.
+- **Patterns are a vocabulary, not a checklist.** Naming the pattern you arrived
+  at aids communication; hunting for a pattern to apply causes over-engineering.
+- **A named pattern can always collapse back.** If the variation it anticipated
+  never materializes, refactor it away.
+
+### Two modes (set by the calling skill)
+- **Design time (`project-spec`):** name a *candidate* pattern for an identified
+  axis of variation. Always in the form
+  `Pattern — because <real axis of variation>; revisit at build (may collapse to
+  a simpler form if the variation does not materialize)`. Candidate, justified,
+  revisitable — never binding.
+- **Implementation time (`project-orchestrate`, core epics only):** refactor
+  *toward* a candidate pattern only once the variation it anticipated has
+  actually appeared in the code. Otherwise implement the simplest sufficient
+  thing and leave the pattern unbuilt.
+
+---
+
+## The 23 patterns
+
+Each entry describes the pattern's intent in plain terms; the *reach for it* line
+is practical guidance for when a demonstrated smell justifies it. For the canonical
+treatment — motivation, structure, participants, and sample code — consult the book
+itself (cited under Acknowledgments).
+
+### Creational — how objects get made
+
+- **Abstract Factory** — create whole families of related or dependent objects
+  through one interface, without binding code to their concrete classes. Reach for
+  it when the system must stay independent of how a product *family* is produced.
+- **Builder** — separate the construction of a complex object from its
+  representation, so one construction process can yield different representations.
+  Reach for it for multi-step assembly or many optional parts.
+- **Factory Method** — define a creation interface but let subclasses choose which
+  class to instantiate, deferring instantiation to them.
+- **Prototype** — produce new objects by copying a prototypical instance rather
+  than instantiating classes directly. Reach for it when instantiation is costly or
+  types are chosen at runtime.
+- **Singleton** — guarantee a single instance with one global access point. Use
+  sparingly — global mutable state, often an anti-pattern; prefer dependency
+  injection.
+
+### Structural — how objects compose
+
+- **Adapter** — convert a class's interface into the one clients expect, letting
+  otherwise-incompatible interfaces work together. Typically at a boundary.
+- **Bridge** — decouple an abstraction from its implementation so the two can vary
+  independently. Reach for it to avoid a combinatorial subclass explosion.
+- **Composite** — arrange objects into tree structures for part-whole hierarchies,
+  letting clients treat individual objects and compositions uniformly.
+- **Decorator** — attach responsibilities to an object dynamically — a flexible
+  alternative to subclassing for extending behavior.
+- **Facade** — offer a single higher-level interface to a subsystem, making it
+  easier to use and decoupling clients from its internals.
+- **Flyweight** — share fine-grained objects to support large numbers of them
+  efficiently. Reach for it when many objects share intrinsic state.
+- **Proxy** — stand in for another object to control access to it (lazy loading,
+  access control, remoting, caching).
+
+### Behavioral — how objects interact and distribute responsibility
+
+- **Chain of Responsibility** — give several objects a chance to handle a request
+  by passing it along a chain until one handles it, decoupling sender from receiver.
+- **Command** — encapsulate a request as an object, enabling parameterization,
+  queuing, logging, and undo.
+- **Interpreter** — represent a grammar and an interpreter that evaluates sentences
+  in that language. Reach for it only for simple, well-understood grammars.
+- **Iterator** — traverse the elements of an aggregate sequentially without
+  exposing its underlying representation. Usually built into the language.
+- **Mediator** — encapsulate how a set of objects interact in a mediator object,
+  promoting loose coupling by removing their direct references to each other.
+- **Memento** — capture and externalize an object's internal state without breaking
+  encapsulation, so it can be restored later. Reach for it for undo/checkpoint.
+- **Observer** — establish a one-to-many dependency so that when one object changes
+  state, its dependents are notified and updated automatically.
+- **State** — let an object change its behavior when its internal state changes, as
+  if it changed class. Reach for it to replace sprawling state conditionals.
+- **Strategy** — encapsulate a family of interchangeable algorithms behind a common
+  interface so the algorithm can vary independently of the clients that use it.
+- **Template Method** — define the skeleton of an algorithm and defer some steps to
+  subclasses, which can redefine those steps without changing the structure.
+- **Visitor** — represent an operation to perform on the elements of an object
+  structure, letting you add new operations without modifying those elements.
+
+---
+
+These intents are paraphrased descriptions of the patterns from *Design Patterns:
+Elements of Reusable Object-Oriented Software* (Gamma, Helm, Johnson, Vlissides);
+the catalog is credited under Acknowledgments. Selecting among these patterns — and
+resisting them when the simplest thing suffices — is governed by the counterweight
+above and the Engineering Baseline's Arbitration Rule.

package/skills/domain-modeling/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: domain-modeling
+description: >-
+  Tactical Domain-Driven Design for modeling complex core domains — deciding
+  where a business rule belongs, designing aggregate boundaries and their
+  consistency rules, choosing between an entity and a value object, introducing
+  domain events, and keeping code aligned with the domain's ubiquitous language.
+  Used by project-spec (advisory, shaping the spec and classifying subdomains)
+  and project-orchestrate (active, while implementing core-domain epics). Fires
+  only for behavior-rich core-domain logic. STAYS DORMANT for CRUD, generic and
+  supporting subdomains, technical plumbing, data pipelines, and simple
+  persistence — per Evans's own scoping: tactical DDD is for the core domain's
+  essential complexity, not generic subdomains.
+---
+
+# Domain Modeling (Tactical DDD)
+
+The tactical building blocks from *Domain-Driven Design* (Eric Evans). This skill
+is the **situational layer** — it composes on top of the Engineering Baseline and
+never overrides it.
+
+---
+
+## Read this before modeling
+
+**Apply this only to the complex core domain.** Evans's own thesis: tactical DDD
+earns its structure where essential business complexity lives — not in generic or
+supporting subdomains, and never in CRUD, plumbing, or simple persistence. For
+those, the Engineering Baseline's Arbitration Rule governs: write the simplest
+thing that works.
+
+The `subdomain` classification (`core` / `supporting` / `generic`) is set once,
+at design time, by `project-spec`. `project-orchestrate` reads it and applies
+this guidance **only to `core` epics**. Do not re-derive the classification
+downstream.
+
+Subordinate every decision below to the **Arbitration Rule** in
+`../shared/references/ENGINEERING_BASELINE.md`. Aggregates and domain services add
+layers; pay for them only where invariants demand it.
+
+---
+
+## Ubiquitous language
+
+Evans's idea: make the domain model the backbone of a shared language, and have
+the whole team use that language relentlessly — in speech, writing, diagrams, and
+the code itself.
+
+In practice: name classes, methods, and modules after the terms stakeholders
+actually use. When the code's language drifts from the conversation, the model is
+wrong — fix the names, and often the design follows.
+
+---
+
+## Building blocks (decision-oriented)
+
+### Entity vs. Value Object — choose deliberately
+- **Entity** (Evans) — an object distinguished by its identity and life-cycle
+  continuity rather than its attributes; keep its definition focused on identity
+  and continuity over time. Use when the thing has a lifecycle and must be tracked
+  (an `Order`, an `Account`).
+- **Value Object** (Evans) — an object you care about only for its attributes;
+  make it immutable, give it no identity, let it carry related behavior, and let
+  its attributes form a single conceptual whole (`Money`, `DateRange`, `Address`).
+  **Default to value objects** — they are simpler, safe to share, and push behavior
+  to where the data lives. Reach for an entity only when identity genuinely matters.
+
+### Where does a business rule live?
+- A rule about a single concept belongs **on that entity or value object** (rich
+  behavior, not an anemic data bag — this aligns with Clean Code's "objects
+  expose behavior").
+- A rule that spans several objects and belongs to none belongs in a **Domain
+  Service** (Evans) — a stateless operation offered as a standalone interface in
+  the model (unlike entities and value objects, it encapsulates no state). Name it
+  in the ubiquitous language. Use sparingly; most logic belongs on the model.
+- A rule that enforces consistency across a cluster belongs at the **aggregate
+  root** (below).
+
+### Aggregates
+- Evans's idea: cluster related entities and value objects into an **aggregate**
+  with a defined boundary, pick one entity as the **root**, and route all external
+  access through it — outside objects may hold a reference only to the root.
+- Because the root controls access, it can enforce every invariant of the aggregate
+  on any state change.
+- **Boundary heuristics:** keep aggregates small; one transaction modifies one
+  aggregate; reference other aggregates by identity, not by holding the object;
+  let cross-aggregate consistency be eventual.
+
+### Repositories
+- Evans's idea: for each type that needs global access, provide an object that acts
+  like an in-memory collection of all objects of that type — with methods to add,
+  remove, and select by criteria — while hiding the actual data store. One
+  repository per aggregate root.
+- Keep persistence concerns out of the domain; map rows to domain types behind
+  the repository interface (depend on the abstraction, per the baseline).
+
+### Factories
+- Evans's idea: move creation of complex objects and aggregates into a dedicated
+  object whose interface encapsulates the assembly and hides the concrete classes
+  from the client. Use a factory to enforce invariants at creation; don't add one
+  for simple construction — that's anticipatory abstraction.
+
+### Domain Events
+- **Note on provenance:** Domain Events are **not** a building block in Evans's
+  original 2003 *Domain-Driven Design*. They were added later (Evans's 2014
+  *Domain-Driven Design Reference*; popularized by Vernon's *Implementing DDD*).
+  Treat them as a widely-adopted extension, not original Evans canon.
+- A **Domain Event** captures something meaningful that happened in the domain,
+  named in past tense (`OrderPlaced`, `PaymentCaptured`).
+- Use to decouple aggregates and drive eventual consistency across boundaries —
+  not as a generic message bus for every state change.
+
+---
+
+## How this composes with design-patterns
+
+Tactical DDD answers *what the domain objects are and which invariants they hold*;
+`design-patterns` answers *how to structure code-level variation*. They can meet
+(a Factory appears in both vocabularies), but model the domain first — let the
+behavior and invariants drive the shape, and reach for a GoF pattern only if a
+demonstrated axis of variation then calls for one, per its own counterweight.

package/skills/project-cleanup/SKILL.md

@@ -303,6 +303,33 @@ After writing new tests, re-run the full suite to confirm all tests pass and cov
 
 ---
 
+## Phase 5.5: Multi-Lens Review Panel (v2.0.0+)
+
+After fixes are applied (or in `--report-only` mode after the catalog is built) and BEFORE Final Validation, invoke the **review_panel.js** workflow script to run a multi-lens review across the final diff or scoped change set.
+
+#### Path Resolution
+
+Workflow ships at `<skills-root>/_workflows/review_panel.js`.
+
+#### Invocation
+
+```yaml
+diff:                     <git diff against the pre-cleanup baseline>
+files:                    [{ path, contents }, ...]   # for files that lack a pre-baseline (new files)
+lenses:                   ["correctness", "security", "style", "tests"]   # default; override per project
+projectConventionsPath:   <project>/CLAUDE.md         # optional
+```
+
+The workflow returns `{ panelVerdict, perLensVerdicts }`. The panel verdict is aggregated per the workflow's rule (any lens blocks → panel blocks; any accept-with-followups → panel accept-with-followups; else accept).
+
+#### Apply the panel verdict
+
+- `panelVerdict.recommendation === "block"` → record the blocking findings in the cleanup report's Critical section; do NOT proceed to Final Validation; surface the per-lens verdicts to the user.
+- `panelVerdict.recommendation === "accept-with-followups"` → record follow-up findings in the cleanup report; proceed to Final Validation.
+- `panelVerdict.recommendation === "accept"` → proceed to Final Validation.
+
+Per-lens verdicts (with `lens` attribution preserved on each finding) are written verbatim to the cleanup report so users can see which lens raised each concern.
+
 ## Phase 6: Final Validation
 
 After all fixes (or after cataloging all issues in report-only mode), run a final validation pass.

package/skills/project-emulate/SKILL.md

@@ -505,6 +505,35 @@ Not every project will have all stages. Skip what doesn't apply. Add stages that
 
 ---
 
+## Phase 5.5: Adversarial Verification of Findings (v2.0.0+)
+
+After Phase 5 produces raw findings and BEFORE the Coverage Report is finalized, invoke the **adversarial_verify.js** workflow script to verify each finding via the claimant / skeptic / judge pattern. This lifts emulation from "trust the emulator" to structured verdicts.
+
+#### Path Resolution
+
+Workflow ships at `<skills-root>/_workflows/adversarial_verify.js` (parent of this SKILL.md's parent → `_workflows/`).
+
+#### Invocation
+
+Pass the finding list (per `EmulationFindingSchema`) and optional `codebaseContext`:
+
+```yaml
+findings:         [<EmulationFinding>, ...]   # collected during Phases 1-5
+codebaseContext:  { projectRoot: <path>, languages: ["typescript", ...] }
+```
+
+The workflow returns `[{ finding, claim, skeptic, verdict }, ...]` where `verdict.isReal` is a boolean and `verdict.severity_adjustment` may suggest raising/lowering severity.
+
+#### Apply the verdicts
+
+For each verified finding:
+- `verdict.isReal === false` → demote to Info OR drop entirely (your choice; if dropping, log the false-positive in a separate "Dismissed" section of ISSUES.md).
+- `verdict.isReal === true` AND `verdict.severity_adjustment === "raise"` → bump severity one level.
+- `verdict.isReal === true` AND `verdict.severity_adjustment === "lower"` → drop severity one level (Critical → Warning, Warning → Info).
+- Otherwise keep as-is.
+
+Findings that survive verification (and the survivors only) drive the Coverage Report and any hardening PRD downstream skills generate.
+
 ## Phase 6: Coverage Report
 
 After the walkthrough, produce a structured report:

package/skills/project-orchestrate/SKILL.md

@@ -11,10 +11,13 @@ Fully autonomous project lifecycle driver. Plans sprints, executes stories via p
 
 ## Before You Start
 
+0. **v2.0.0 runtime check.** Confirm the Claude Code **Workflow tool** is available in this session. v2.0.0 invokes workflow scripts at `<skills-root>/_workflows/*.js` for sprint execution, Pass 2 epic elaboration, multi-spec queueing, emulation finding verification, and the review gate. If the Workflow tool is absent, abort with: "v2.0.0 requires the Claude Code Workflow tool. Update Claude Code, or install the v1.8.x fallback (`npm install --save-dev @houseofwolvesllc/claude-scrum-skill@1.8.1`)." Do not proceed.
 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.
+3a. Read `../shared/references/ENGINEERING_BASELINE.md` — the universal engineering baseline (Clean Code, Test-Driven Development, and the simple-design Arbitration Rule). It applies to **all** work this orchestration drives, across every epic and story. Resolve its absolute path; you will pass it to the sprint pipeline as `baselinePath` so every implementation and review subagent follows it. Order of precedence: project `CLAUDE.md` > engineering baseline > situational guidance (`design-patterns`, `domain-modeling`).
+3b. **Subdomain classification gates situational guidance.** `/project-spec` classifies each epic as `core`, `supporting`, or `generic`, and `/project-scaffold` persists that classification into epic metadata: the `subdomain` field of each `_epic.md` frontmatter (local mode) or a `subdomain:<value>` label on the epic's issues (remote modes). Read the classification from that epic metadata — the single authoritative source — and do NOT re-derive it. At implementation time, only **`core`** epics receive the situational guidance skills (`design-patterns`, `domain-modeling`); `supporting`, `generic`, and unclassified epics get the baseline only. Resolve the absolute `SKILL.md` paths for the `design-patterns` and `domain-modeling` skills so you can pass them as `situationalGuidance` for core epics.
 4. Read `../shared/references/PERSONAS.md` for role preambles. When spawning
    subagents, select the persona matching each story's `persona:*` label (GitHub mode)
    or `persona` frontmatter field (local mode). If no persona exists, use `impl` (the default).
@@ -381,94 +384,57 @@ After planning completes, update the state file with the sprint stories and thei
 
 ### Step 3: Story Execution
 
-Execute all `executor:claude` stories in the current sprint. Skip `executor:human` and `executor:cowork` stories — they will roll over to the next sprint automatically.
+Execute all `executor:claude` stories in the current sprint by invoking the **sprint_pipeline.js** workflow script. Skip `executor:human` and `executor:cowork` stories — they roll over to the next sprint automatically.
 
-**Parallel execution via Task subagents:**
+#### Path Resolution
 
-For stories with no unresolved dependencies, spawn parallel Task subagents (using the `Task` tool with `subagent_type: "Bash"` or `subagent_type: "general-purpose"` as appropriate). Each subagent receives:
+The workflow script ships at `<skills-root>/_workflows/sprint_pipeline.js`, where `<skills-root>` is the parent directory of this SKILL.md's parent. For a SKILL.md at `~/.claude/skills/project-orchestrate/SKILL.md`, the workflow script absolute path is `~/.claude/skills/_workflows/sprint_pipeline.js`. The same algorithm works for global, local, and plugin install layouts.
 
-**Persona resolution:** Before spawning each subagent, resolve its persona:
+#### Pre-spawn checks
 
-1. **GitHub mode:** Check the story's labels for a `persona:*` label (e.g., `persona:ops`, `persona:research`).
-   **Local mode:** Read the `persona` field from the story file's frontmatter.
-2. If found, load the matching preamble from `../shared/references/PERSONAS.md`.
-3. If no persona exists, use the `impl` preamble.
-4. If the persona references a name not defined in `PERSONAS.md`, fall back
-   to `impl` and log a warning.
+Before invoking the workflow:
 
-**Subagent prompt structure:**
+1. **Independence check.** Exclude stories whose `blocked_by` references unresolved blockers. Only pass ready stories to the workflow.
+2. **Persona resolution.** For each story, resolve its persona (`impl`, `ops`, `research`) from labels (GitHub/Trello/Jira) or the `persona` frontmatter field (local mode). Default to `impl`. Build a `personaPreambles` map from the preambles in `../shared/references/PERSONAS.md` to pass to the workflow.
+3. **Skip human/cowork stories.** Log them as skipped in the state file before invoking.
 
-```
-<persona preamble from PERSONAS.md>
+#### Invocation
 
----
+Invoke the Workflow tool with `scriptPath` set to the resolved absolute path and `args` set to:
 
-You are executing story #<number> for repo <owner/repo>.
-
-**IMPORTANT:** First read the project's CLAUDE.md file if it exists, and
-follow all instructions in it. CLAUDE.md is authoritative for stack,
-patterns, and style — it overrides any general guidance in this preamble.
-
-**IMPORTANT:** Before writing any code, if `<paths.context>/<epic-slug>/CONTEXT.md`
-exists, read it in full. Treat its Naming Conventions, File Layout, Shared
-Types & Interfaces, Patterns to Follow, and Patterns to Avoid sections as
-binding for this epic — they override generic conventions in CLAUDE.md when
-in conflict, and you should follow them even when CLAUDE.md is silent. The
-`<paths.context>` and `<epic-slug>` values are substituted from the resolved
-config and the story's epic at spawn time.
-
-**Story:** <title>
-**Acceptance criteria:** <from issue body or story file>
-**Branch strategy:** Create branch `story/<number>-<slug>` from
-`release/<epic-slug>`, implement, commit, push, and open a PR targeting
-`release/<epic-slug>`.
-
-After implementation:
-
-GitHub mode:
-1. Open a PR with a clear description of changes
-2. Ensure CI passes
-3. The PR should target the release branch, NOT development or main
-4. Do NOT merge the PR — just open it and report back.
-
-Local mode:
-1. Commit all changes to the story branch
-2. Merge the story branch into release/<epic-slug>
-3. Push the release branch
-4. Report back what was implemented.
+```yaml
+stories:            <array of StorySchema-shaped story objects from the current sprint, filtered to executor:claude + ready>
+epicSlug:           <current epic slug>
+releaseBranch:      release/<epic-slug>
+contextMdPath:      <paths.context>/<epic-slug>/CONTEXT.md (or omit if no design-spike)
+claudeMdPath:       project CLAUDE.md absolute path (or omit if absent)
+backendMode:        local | github | jira | trello
+repoIdentifier:     <owner/repo> (github mode only)
+personaPreambles:   { impl: "...", ops: "...", research: "..." }
+baselinePath:       <absolute path to shared/references/ENGINEERING_BASELINE.md> (always set; applies to every story)
+situationalGuidance: <array of absolute SKILL.md paths for design-patterns and domain-modeling — set ONLY when the current epic's subdomain is `core`; omit or pass [] for supporting/generic/untagged epics>
 ```
 
-**Execution rules:**
-
-1. **Independence check:** Before spawning subagents, analyze story dependencies. Only spawn stories whose blockers are all resolved.
-2. **Concurrency limit:** Run up to 3 subagents in parallel to avoid rate limiting.
-3. **Progress tracking:** As each subagent completes, update the state file and check if any blocked stories are now unblocked. Spawn newly unblocked stories immediately.
-4. **Failure handling:** If a subagent fails, retry once with additional context about the failure. If it fails again, mark the story as blocked with a note and continue with remaining stories.
-5. **Story completion:**
-   - **GitHub mode:** After a story PR is opened and CI passes, merge it to the release branch:
-     ```bash
-     gh pr merge <pr-number> --repo <owner/repo> --squash --auto
-     ```
-   - **Local mode:** The subagent merges the story branch directly into the release branch. After completion, update the story file's frontmatter to `status: done`.
-6. **Skip human/cowork stories:** Log them as skipped in the state file. They roll over naturally during sprint release.
-7. **Persona routing:** When resolving personas:
-   - **GitHub mode:**
-     ```bash
-     persona=$(gh issue view <number> --repo <owner/repo> --json labels \
-       --jq '[.labels[].name | select(startswith("persona:"))] | first // empty' \
-       | sed 's/persona://')
-     persona=${persona:-impl}
-     ```
-   - **Local mode:** Read the `persona` field from the story file's frontmatter. Default to `impl` if not set.
-
-   Load the corresponding preamble section from `../shared/references/PERSONAS.md`
-   and prepend it to the subagent prompt. Log the persona assignment in the
-   state file.
-
-**Progress updates** — Print a concise progress line every 2-3 story completions:
+Wait for the workflow to return. The return is `SprintStoryReturn[]` — one entry per completed (or blocked / failed) story per `lib/workflows/schemas/SprintStoryReturnSchema.json`.
+
+#### Post-workflow persistence
+
+For each entry in the workflow's return:
+
+- `status: "done"` — Update the story file's frontmatter to `status: done`. Record `branch`, `prUrl` (github) or merge commit (local), and commit SHAs in the state file's "Current Sprint Stories" table.
+- `status: "blocked"` — Record `blockers[]` and `reason` in the state file. Add the `blocked` label to the story (or mark blocked locally). Continue.
+- `status: "failed"` — Same persistence as blocked, plus log the failure for sprint-release to roll over.
+
+#### Concurrency and barriers
+
+The workflow runs up to `min(16, cpu_cores - 2)` stories concurrently with no per-stage barriers — each story's pipeline is independent, so one slow review doesn't gate other stories' implementations. The barrier-removal benefit is unconditional; the concurrency lift is conditional on host cores (a 4-core host gets concurrency 2, an 8-core host gets 6, a 18+-core host gets the full 16). On all hosts this still beats v1.x's hardcoded 3 + barriers model on most sprint sizes.
+
+#### Progress updates
+
+The workflow surfaces structured progress via the Workflow tool's UI. Additionally, the executing agent SHOULD emit a concise summary line after the workflow returns:
 
 ```
-Sprint 2: 5/8 stories done (13/19 pts) — #21 auth middleware ✓, #22 rate limiting ✓
+Sprint 2: 5/8 stories done (13/19 pts) — 2 blocked, 1 needs review
 ```
 
 ### Step 4: Sprint Release
@@ -906,16 +872,20 @@ Applies when Mode Classification selected sequential multi-path mode (2+ tokens,
 
 ### Per-Spec Loop
 
+The per-spec loop is **executed by the skill markdown** (not a wrapping workflow), because the inner per-spec orchestration invokes individual workflows (`sprint_pipeline.js`, `elaborate_epics.js`, etc.) via the Workflow tool. The Workflow tool's nesting constraint ("one level of nesting only") prevents a multi-spec-queue workflow from invoking sub-workflows that themselves invoke workflows; the skill markdown is the right layer to orchestrate per-spec iteration.
+
 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.
+1. Update the queue state file: mark this spec's row as `in-progress`, record `Started` timestamp.
+2. Invoke the full single-spec orchestration against this spec — re-enter Phase 1 (Epic Completion Loop, including scaffolding via `/project-scaffold`), Phase 2 (Emulation Hardening Loop), Phase 3 (Project Cleanup), Step 16 (ADR Update). Each of these phases internally invokes workflows (`sprint_pipeline.js`, `elaborate_epics.js`, `adversarial_verify.js`, `review_panel.js`) as documented in their respective sections. Step 17 (state file cleanup) is **suppressed** in multi-path mode; archive instead with the slug-suffixed naming below.
 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.
+   - **Without `--skip-on-pause`** (default): 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. Remaining specs are NOT started. User resolves the gate and re-invokes; queue resumes from the paused 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.
 
+After all specs are processed, emit the Cumulative Summary per the subsection below.
+
 ### Spec Slug Derivation
 
 A spec's slug is derived from its filename: `basename(path, ".md")`.

package/skills/project-scaffold/SKILL.md

@@ -146,6 +146,7 @@ epics:
   - name: <string>
     slug: <kebab-case string>
     description: <one-paragraph string>
+    subdomain: <core | supporting | generic — from the spec's .spec.json epic entry (SpecSchema)>
     slice:
       start_line: <int>
       end_line: <int>
@@ -173,29 +174,27 @@ After Pass 1 completes, evaluate the epic count:
 
 ### Pass 2 — Per-Epic Elaboration
 
-Spawn one subagent per epic. Each subagent receives a focused context:
+Pass 2 is performed by the **elaborate_epics.js** workflow script. Replaces the v1.x Task-based fan-out (concurrency cap of 3) with one parallel wave (concurrency 16) and schema-validated returns.
 
-- The **global preamble** from Pass 1 (project overview, glossary, NFRs)
-- Its **assigned epic's PRD slice**, extracted using `slice.start_line`
-  and `slice.end_line` from the manifest
-- A **skeleton summary** of sibling epics (name, slug, one-paragraph
-  description, dependencies) — for cross-epic dependency awareness, NOT
-  for elaboration
+#### Path Resolution
 
-Each Pass 2 subagent produces the complete story list for its epic:
+Workflow script ships at `<skills-root>/_workflows/elaborate_epics.js`, where `<skills-root>` is the parent of this SKILL.md's parent directory. For `~/.claude/skills/project-scaffold/SKILL.md`, the absolute workflow path is `~/.claude/skills/_workflows/elaborate_epics.js`.
 
-- Story titles
-- Acceptance criteria
-- Technical context
-- Story points (per CONVENTIONS.md guidelines)
-- Executor assignment (per CONVENTIONS.md guidelines)
-- Persona designation (local mode: the `persona` frontmatter field; GitHub/Jira/Trello modes: a `persona:*` label — see CONVENTIONS.md "Persona Labels" and PERSONAS.md for the canonical set)
-- Dependency declarations (`blocked_by`, `blocks`)
-- All other required frontmatter fields
+#### Invocation
 
-**Concurrency cap:** Up to 3 Pass 2 subagents in parallel (matches
-`/project-orchestrate` Step 3 convention). Additional epics queue and
-start as earlier ones complete.
+Invoke the Workflow tool with `scriptPath` set to the resolved path and `args`:
+
+```yaml
+skeleton:          { project: { name, description, global_preamble, non_functional_requirements }, epics: [...] }   # the Pass 1 manifest
+prdPath:           <absolute path to the PRD>
+conventionsPath:   ../shared/references/CONVENTIONS.md   # optional but recommended
+```
+
+The workflow returns `Epic[]` per `lib/workflows/schemas/EpicSchema.json`, each with `stories[]` populated. Failed epics return `null` in the array.
+
+#### Per-epic context (encoded by the workflow)
+
+Each `elaborate:<epic-slug>` agent receives the global preamble, its epic's PRD slice (using `slice.start_line` / `slice.end_line` from the manifest), and a sibling-epic skeleton summary for cross-epic dependency awareness. The output story shape matches `lib/workflows/schemas/StorySchema.json`: title, slug, acceptance_criteria, technical_context, points (Fibonacci), executor, persona, priority, blocked_by, blocks, labels.
 
 ### Story Assembly
 
@@ -429,6 +428,7 @@ For each epic, create `<backlog-path>/<epic-slug>/`:
 title: <Epic Name>
 slug: <epic-slug>
 status: open
+subdomain: <core | supporting | generic>
 created: <ISO timestamp>
 ---
 
@@ -437,6 +437,14 @@ created: <ISO timestamp>
 <Epic description from PRD>
 ```
 
+**Carry the `subdomain` classification** from the spec's `.spec.json` epic entry
+(per `SpecSchema`) into epic metadata: the `_epic.md` frontmatter above in local
+mode, and a `subdomain:<value>` label on the epic's issues in remote modes. This
+is the single authoritative carrier `/project-orchestrate` reads to gate
+situational design guidance (`design-patterns`, `domain-modeling`) to `core`
+epics. If the spec carries no `subdomain` (e.g., not produced by the extended
+`/project-spec`), omit the field — orchestrate then treats the epic as generic.
+
 ### Local Step 5: Create Story Files
 
 For each story, create a numbered file in the epic directory. Use sequential