@houseofwolvesllc/claude-scrum-skill 2.0.0 → 2.1.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-scrum-skill",
   "description": "Complete scrum pipeline — PRD to production release with Claude as scrum master. Includes project scaffolding, sprint planning, status tracking, sprint releases, and full-project emulation testing.",
-  "version": "1.3.0",
+  "version": "2.1.1",
   "author": {
     "name": "House of Wolves LLC"
   },

package/README.md

@@ -4,6 +4,8 @@ An open-source npm package of Claude Code skills that give you a complete scrum
 
 Includes project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup.
 
+It is also an **opinionated spec-and-implementation process**: its engineering guidance is grounded in the principles of four foundational software texts — Robert C. Martin's *Clean Code*, Kent Beck's *Test-Driven Development: By Example*, Eric Evans's *Domain-Driven Design*, and the Gang of Four's *Design Patterns* — distilled into an always-on engineering baseline plus on-demand design-pattern and domain-modeling guidance. See [Acknowledgments](#acknowledgments).
+
 ```
 Manual mode — you invoke each skill:
 
@@ -54,6 +56,7 @@ PRD (optional)  -->  /project-orchestrate
 - [Autonomous Orchestration](#autonomous-orchestration)
 - [Customization](#customization)
 - [Tips](#tips)
+- [Acknowledgments](#acknowledgments)
 - [License](#license)
 
 ---
@@ -348,9 +351,13 @@ Create a fine-grained Personal Access Token:
 | **project-emulate** | `/project-emulate` | Integration seams, layer contracts, cross-service payloads, full lifecycle walkthrough |
 | **project-orchestrate** | `/project-orchestrate [prd] [repo]` | Autonomous lifecycle driver |
 | **project-cleanup** | `/project-cleanup [path] [--fix]` | Build, lint, dead code, and test coverage |
+| **design-patterns** | `/design-patterns` | Gang of Four pattern guidance, counterweight-first; composed by `spec` (design) and `project-orchestrate` (core-domain implementation) |
+| **domain-modeling** | `/domain-modeling` | Tactical Domain-Driven Design guidance; composed by `spec` and `project-orchestrate` for core-domain epics |
 
 The `[owner/repo]` argument is only needed in GitHub mode. Jira, Trello, and local modes read from config.
 
+`design-patterns` and `domain-modeling` are **situational guidance** layered on top of the always-on engineering baseline (`skills/shared/references/ENGINEERING_BASELINE.md`). They are pulled in automatically by `spec` and `project-orchestrate` for `core`-classified subdomains, and are also invocable directly. See [Acknowledgments](#acknowledgments) for their sources.
+
 ---
 
 ## Branch Strategy
@@ -565,6 +572,29 @@ skills/shared/
 
 ---
 
+## Acknowledgments
+
+The engineering guidance in this package — the always-on baseline plus the
+`design-patterns` and `domain-modeling` skills — is grounded in the principles of
+four foundational software texts. The guidance is expressed in this project's own
+words; these works are credited as its intellectual sources. Their authors are not
+affiliated with and do not endorse this project.
+
+- **Robert C. Martin**, *Clean Code: A Handbook of Agile Software Craftsmanship*
+  (Prentice Hall, 2008) — the engineering baseline's naming, function, comment, and
+  code-quality principles.
+- **Kent Beck**, *Test-Driven Development: By Example* (Addison-Wesley, 2002) — the
+  baseline's red/green/refactor discipline and simple-design rules.
+- **Eric Evans**, *Domain-Driven Design: Tackling Complexity in the Heart of
+  Software* (Addison-Wesley, 2003) — the `domain-modeling` skill's tactical
+  building blocks and ubiquitous-language guidance.
+- **Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides** ("the Gang of
+  Four"), *Design Patterns: Elements of Reusable Object-Oriented Software*
+  (Addison-Wesley, 1994) — the `design-patterns` skill's pattern catalog.
+
+If you find this guidance useful, read the originals — they go far deeper than any
+distillation can.
+
 ## License
 
 Apache 2.0 — See [LICENSE](LICENSE) for details.

package/lib/workflows/schemas/SpecSchema.json

@@ -43,6 +43,7 @@
         "name": { "type": "string" },
         "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
         "description": { "type": "string" },
+        "subdomain": { "type": "string", "enum": ["core", "supporting", "generic"] },
         "depends_on": { "type": "array", "items": { "type": "string" } },
         "shared_design_concerns": { "type": "array", "items": { "type": "string" } },
         "slice": {

package/lib/workflows/sprint_pipeline.js

@@ -1,8 +1,33 @@
-// sprint_pipeline.js — per-story sprint execution as a pipeline.
+// sprint_pipeline.js — per-story sprint execution.
 //
-// Invoked by /project-orchestrate Phase 1 Step 3. Replaces the v1.x
-// Task-spawning prose with per-stage barrier removal and concurrency up
-// to min(16, cpu_cores - 2) per the Workflow tool's cap.
+// Invoked by /project-orchestrate Phase 1 Step 3. Each story runs its own
+// independent chain — implement → review → verify → open PR — with no
+// per-stage barriers and concurrency up to min(16, cpu_cores - 2) per the
+// Workflow tool's cap.
+//
+// Concurrency safety. Stories run in parallel against one git repository, so
+// the model is built around a single invariant: the main working tree is
+// mutated only by the serialized local-mode merge step. Everything else stays
+// off it.
+//   - Implement and verify run in isolated worktrees (`isolation: 'worktree'`).
+//     They create/build the story branch in their own tree, so concurrent
+//     `git checkout -b` and commits never race in the shared tree. Branches and
+//     commits land in the shared object store and are visible afterward.
+//   - Review only diffs two refs (object-store comparison, no checkout), so it
+//     never touches the working tree.
+//   - Local-mode finalize merges each story branch into the shared release
+//     branch in the main tree; these merges are serialized behind a lock so
+//     concurrent fan-in merges cannot race. GitHub mode opens independent PRs
+//     and needs no lock.
+//
+// Dependency gating. A story does not start until every blocker that is also in
+// this batch has finished `done` (see `blocked_by`). Because a dependent only
+// branches after its in-batch blockers have merged into the release branch, it
+// builds on their work. Blockers outside this batch are the orchestrator's
+// concern — it passes only stories whose external blockers are already resolved
+// (SKILL.md "Independence check"). The in-batch graph is assumed acyclic; the
+// orchestrate skill validates the dependency DAG (cycle + missing-edge checks)
+// before any story reaches this workflow.
 //
 // args: {
 //   stories: Story[],              // StorySchema-shaped
@@ -12,7 +37,9 @@
 //   claudeMdPath?: string,         // project CLAUDE.md
 //   backendMode: "local" | "github" | "jira" | "trello",
 //   repoIdentifier?: string,       // "owner/repo" — github mode only
-//   personaPreambles: Record<string, string>  // persona name → preamble text
+//   personaPreambles: Record<string, string>, // persona name → preamble text
+//   baselinePath?: string,         // shared/references/ENGINEERING_BASELINE.md — injected into every story
+//   situationalGuidance?: string[] // SKILL.md paths (design-patterns, domain-modeling) — core-domain epics only
 // }
 //
 // returns: SprintStoryReturn[] (one per story; failed items filtered to null upstream)
@@ -106,6 +133,8 @@ const {
   backendMode,
   repoIdentifier,
   personaPreambles = {},
+  baselinePath,
+  situationalGuidance = [],
 } = args
 
 if (!stories || stories.length === 0) {
@@ -124,6 +153,12 @@ function buildImplementPrompt(story) {
   const contextLine = contextMdPath
     ? `Before writing any code, read ${contextMdPath} if it exists. Its Naming, File Layout, Shared Types, and Patterns sections are binding for this epic — they override generic CLAUDE.md conventions for this epic.`
     : ''
+  const baselineLine = baselinePath
+    ? `Before writing any code, read ${baselinePath} — the universal engineering baseline (Clean Code, Test-Driven Development, and the simple-design Arbitration Rule). Follow it for all code: write tests first (red-green-refactor), keep designs simple, and treat the Arbitration Rule as binding. On a direct conflict the project CLAUDE.md wins.`
+    : ''
+  const situationalLine = situationalGuidance.length
+    ? `This is a core-domain story. Also read and apply: ${situationalGuidance.join(', ')}. These are situational guidance and remain subordinate to the baseline's Arbitration Rule — model the domain's invariants first, and reach for a design pattern or domain layer only when a demonstrated axis of variation or an essential business rule warrants it, never speculatively.`
+    : ''
   return `${preamble}
 
 ---
@@ -131,6 +166,8 @@ function buildImplementPrompt(story) {
 You are implementing story ${story.slug} on release branch ${releaseBranch}.
 
 ${claudeMdLine}
+${baselineLine}
+${situationalLine}
 ${contextLine}
 
 **Story:** ${story.title}
@@ -139,7 +176,7 @@ ${(story.acceptance_criteria || []).map(c => `  - ${c}`).join('\n')}
 
 **Technical context:** ${story.technical_context || '(none provided)'}
 
-**Branch strategy:** Create branch \`story/${story.slug}\` from \`${releaseBranch}\`. Implement. Commit with a clear message. Return the branch name, the commit SHAs, and any notes.
+**Branch strategy:** You are in an isolated git worktree — work only here; do not touch other branches. Create branch \`story/${story.slug}\` from the latest \`${releaseBranch}\` (\`git checkout -b story/${story.slug} ${releaseBranch}\`); it already contains any in-sprint dependency this story builds on. Implement. Commit with a clear message. Return the branch name, the commit SHAs, and any notes.
 
 Do NOT open a PR yet. Do NOT merge. The next stage handles review.`
 }
@@ -147,12 +184,12 @@ Do NOT open a PR yet. Do NOT merge. The next stage handles review.`
 function buildReviewPrompt(impl, story) {
   return `You are reviewing the implementation of story ${story.slug} on branch ${impl.branch}.
 
-Read the diff between ${releaseBranch} and ${impl.branch}.
+Read the diff between ${releaseBranch} and ${impl.branch} with \`git diff ${releaseBranch}...${impl.branch}\` — do NOT check out either branch (other stories run concurrently in this repository; checking out would disturb the shared working tree).
 
 Story acceptance criteria:
 ${(story.acceptance_criteria || []).map(c => `  - ${c}`).join('\n')}
 
-Review for: correctness against acceptance criteria, project convention compliance (per CLAUDE.md), and obvious defects. Do NOT bikeshed style the project doesn't enforce.
+Review for: correctness against acceptance criteria, project convention compliance (per CLAUDE.md${baselinePath ? ` and the engineering baseline at ${baselinePath}` : ''}), and obvious defects. ${baselinePath ? 'Confirm the baseline was honored: tests accompany the code and the design is the simplest that satisfies the story (no unearned abstraction). ' : ''}Do NOT bikeshed style the project doesn't enforce.
 
 Return a ReviewVerdict: recommendation (accept | accept-with-followups | block), findings grouped by severity, and a one-paragraph summary.`
 }
@@ -160,7 +197,7 @@ Return a ReviewVerdict: recommendation (accept | accept-with-followups | block),
 function buildVerifyPrompt(review, story) {
   return `You are running a lightweight verification on story ${story.slug}.
 
-If the project has a build/lint/test command, run it on the story branch. If not, perform a smoke read of the changed files to confirm no obvious runtime defects (broken imports, syntax errors, dangling references).
+You are in an isolated git worktree — check out \`story/${story.slug}\` here (\`git checkout story/${story.slug}\`) so any build artifacts stay off the shared working tree. If the project has a build/lint/test command, run it on the story branch. If not, perform a smoke read of the changed files to confirm no obvious runtime defects (broken imports, syntax errors, dangling references).
 
 Return verifyStatus (pass | warn | fail) and brief notes.`
 }
@@ -184,69 +221,140 @@ phase('Review')
 phase('Verify')
 phase('Open PR')
 
-const results = await pipeline(
-  stories,
-  // Stage 1: Implement
-  story =>
-    agent(buildImplementPrompt(story), {
-      label: `impl:${story.slug}`,
-      phase: 'Implement',
-      schema: IMPL_RETURN_SCHEMA,
-    }),
-  // Stage 2: Review
-  (impl, story) =>
-    impl
-      ? agent(buildReviewPrompt(impl, story), {
-          label: `review:${story.slug}`,
-          phase: 'Review',
-          schema: REVIEW_VERDICT_SCHEMA,
-        }).then(review => ({ impl, review }))
-      : null,
-  // Stage 3: Verify
-  (prev, story) =>
-    prev
-      ? agent(buildVerifyPrompt(prev.review, story), {
-          label: `verify:${story.slug}`,
-          phase: 'Verify',
-          schema: VERIFY_RETURN_SCHEMA,
-        }).then(verify => ({ ...prev, verify }))
-      : null,
-  // Stage 4: Open PR (or local merge)
-  (prev, story) => {
-    if (!prev) return null
-    const { impl, review, verify } = prev
-    // If the reviewer said block, short-circuit to blocked status without an openPR call.
-    if (review.recommendation === 'block') {
-      const blockers = [
-        ...review.findings.critical.map(f => f.title),
-        ...review.findings.warning.map(f => f.title),
-      ]
-      return makeSprintStoryReturn({
-        storySlug: story.slug,
-        status: 'blocked',
-        branch: impl.branch,
-        commits: impl.commits,
-        blockers,
-        reason: 'Review recommended block.',
-      })
-    }
-    // If verify failed, also short-circuit.
-    if (verify.verifyStatus === 'fail') {
-      return makeSprintStoryReturn({
-        storySlug: story.slug,
-        status: 'blocked',
-        branch: impl.branch,
-        commits: impl.commits,
-        blockers: [verify.notes || 'verification failed'],
-        reason: 'Verification failed.',
-      })
+const batchSlugs = new Set(stories.map(story => story.slug))
+
+/**
+ * Blockers of `story` that are also in this batch, by trailing slug.
+ * blocked_by entries may be bare slugs or "<epic>/<slug>" references. A story
+ * cannot block itself, and blockers outside the batch are the orchestrator's
+ * concern (it only passes stories whose external blockers are resolved).
+ */
+function inBatchBlockers(story) {
+  return (story.blocked_by || [])
+    .map(reference => reference.split('/').pop())
+    .filter(slug => slug !== story.slug && batchSlugs.has(slug))
+}
+
+// Serializes local-mode merges onto the shared release branch: each merge runs
+// only after the previous one settles, success or failure, so a failed merge
+// never stalls the rest. GitHub mode opens independent PRs and does not use it.
+let mergeChain = Promise.resolve()
+function serializeMerge(runMerge) {
+  const merged = mergeChain.then(runMerge, runMerge)
+  mergeChain = merged.then(() => {}, () => {})
+  return merged
+}
+
+function reviewBlocked(story, impl, review) {
+  return makeSprintStoryReturn({
+    storySlug: story.slug,
+    status: 'blocked',
+    branch: impl.branch,
+    commits: impl.commits,
+    blockers: [
+      ...review.findings.critical.map(finding => finding.title),
+      ...review.findings.warning.map(finding => finding.title),
+    ],
+    reason: 'Review recommended block.',
+  })
+}
+
+function verifyBlocked(story, impl, verify) {
+  return makeSprintStoryReturn({
+    storySlug: story.slug,
+    status: 'blocked',
+    branch: impl.branch,
+    commits: impl.commits,
+    blockers: [verify.notes || 'verification failed'],
+    reason: 'Verification failed.',
+  })
+}
+
+function dependencyBlocked(story, unmet) {
+  return makeSprintStoryReturn({
+    storySlug: story.slug,
+    status: 'blocked',
+    blockers: unmet.map(slug => `upstream story ${slug} did not complete`),
+    reason: 'Upstream in-sprint dependency did not complete.',
+  })
+}
+
+// Each story's terminal promise, registered before any chain runs so a
+// dependent can always await its blocker regardless of array order.
+const terminal = new Map()
+
+async function runStory(story) {
+  const blockers = inBatchBlockers(story)
+  if (blockers.length) {
+    const outcomes = await Promise.all(blockers.map(slug => terminal.get(slug)))
+    const unmet = blockers.filter((_, index) => outcomes[index]?.status !== 'done')
+    if (unmet.length) {
+      log(`Skipping ${story.slug}: upstream ${unmet.join(', ')} did not complete.`)
+      return dependencyBlocked(story, unmet)
     }
-    return agent(buildOpenPRPrompt(verify, story, impl), {
+  }
+
+  const impl = await agent(buildImplementPrompt(story), {
+    label: `impl:${story.slug}`,
+    phase: 'Implement',
+    schema: IMPL_RETURN_SCHEMA,
+    isolation: 'worktree',
+  })
+  if (!impl) return null
+
+  const review = await agent(buildReviewPrompt(impl, story), {
+    label: `review:${story.slug}`,
+    phase: 'Review',
+    schema: REVIEW_VERDICT_SCHEMA,
+  })
+  if (!review) return null
+  if (review.recommendation === 'block') return reviewBlocked(story, impl, review)
+
+  const verify = await agent(buildVerifyPrompt(review, story), {
+    label: `verify:${story.slug}`,
+    phase: 'Verify',
+    schema: VERIFY_RETURN_SCHEMA,
+    isolation: 'worktree',
+  })
+  if (!verify) return null
+  if (verify.verifyStatus === 'fail') return verifyBlocked(story, impl, verify)
+
+  const finalize = () =>
+    agent(buildOpenPRPrompt(verify, story, impl), {
       label: `pr:${story.slug}`,
       phase: 'Open PR',
       schema: SPRINT_STORY_RETURN_SCHEMA,
     })
-  }
-)
 
+  // Local mode mutates the shared release branch — serialize. GitHub mode opens
+  // an independent PR and can run concurrently.
+  return backendMode === 'github' ? finalize() : serializeMerge(finalize)
+}
+
+// Open the gate only after every terminal promise is registered, so a
+// dependent's blocker lookup never races an unregistered entry.
+let openGate
+const gate = new Promise(resolve => {
+  openGate = resolve
+})
+for (const story of stories) {
+  terminal.set(
+    story.slug,
+    // Isolate each chain: a thrown agent or stage becomes a 'failed' result
+    // rather than rejecting Promise.all and tearing down the whole batch. A
+    // failed (not 'done') outcome also correctly blocks any dependent.
+    gate.then(() => runStory(story)).catch(error => {
+      const detail = error?.message || String(error)
+      log(`Story ${story.slug} errored: ${detail}`)
+      return makeSprintStoryReturn({
+        storySlug: story.slug,
+        status: 'failed',
+        reason: `Unhandled error: ${detail}`,
+      })
+    })
+  )
+}
+openGate()
+
+const results = await Promise.all(stories.map(story => terminal.get(story.slug)))
 return results.filter(Boolean)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "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/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-orchestrate/SKILL.md

@@ -16,6 +16,8 @@ Fully autonomous project lifecycle driver. Plans sprints, executes stories via p
 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).
@@ -409,6 +411,8 @@ 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>
 ```
 
 Wait for the workflow to return. The return is `SprintStoryReturn[]` — one entry per completed (or blocked / failed) story per `lib/workflows/schemas/SprintStoryReturnSchema.json`.
@@ -421,9 +425,11 @@ For each entry in the workflow's return:
 - `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
+#### Concurrency, isolation, 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.
+The workflow runs up to `min(16, cpu_cores - 2)` stories concurrently with no per-stage barriers — each story's chain 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.
+
+Concurrent stories share one git repository, so the workflow keeps them off each other's toes with a single invariant: **the main working tree is mutated only by the serialized local-mode merge step.** Implement and verify run in isolated git worktrees (each story branches, commits, and builds in its own tree); review only diffs refs without checking out; and in local mode the per-story merges into the shared release branch are serialized behind a lock. This is why the **Independence check** (above) need not be perfect: even if two file-overlapping stories run together, they cannot corrupt each other's branch or commits. The workflow also re-enforces dependencies internally — a story whose `blocked_by` names another story *in the same batch* waits for that story to finish `done` before it starts, and branches from the release branch only after the blocker has merged.
 
 #### Progress updates
 

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>
@@ -427,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>
 ---
 
@@ -435,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

package/skills/project-spec/SKILL.md

@@ -40,6 +40,43 @@ As Claude Code, your task is to transform the user's rough prompt into a compreh
    - Add code examples if they help illustrate requirements
    - Structure the document with clear headings and subheadings
 
+## Design Passes (Baseline, Domain & Patterns)
+
+Before finalizing, run these passes so the spec is grounded in the project's
+engineering standards. They shape the spec at **design time**; implementation-time
+enforcement is `/project-orchestrate`'s job.
+
+6. **Engineering baseline.** Read `../shared/references/ENGINEERING_BASELINE.md`
+   (Clean Code, Test-Driven Development, the simple-design Arbitration Rule). The
+   spec must assume this baseline: acceptance criteria assume tests-first
+   (red-green-refactor), and every proposed design assumes the Arbitration Rule
+   — the simplest thing that works, no anticipatory abstraction.
+
+7. **Strategic domain pass (DDD).** For each epic, capture the domain's
+   **ubiquitous language** and **classify its subdomain** as one of `core`,
+   `supporting`, or `generic`:
+   - `core` — the complex business heart with real invariants; warrants tactical
+     domain modeling.
+   - `supporting` — necessary but not differentiating.
+   - `generic` — CRUD, plumbing, off-the-shelf concerns.
+
+   Record the classification on each epic (see the JSON sibling below). It is the
+   single authoritative source `/project-orchestrate` reads to decide which epics
+   receive situational guidance — so classify carefully and do **not** expect
+   downstream skills to re-derive it. For `core` epics, sketch candidate
+   aggregates, entities vs. value objects, and where key business rules live,
+   consistent with the `domain-modeling` skill.
+
+8. **Pattern-naming pass (GoF), candidate only.** Identify axes of *expected
+   variation* and, where one is real, name a **candidate** Gang of Four pattern.
+   Every named pattern MUST follow this form and stay non-binding:
+
+   > `Pattern — because <real axis of variation>; revisit at build (may collapse
+   > to a function or simpler form if the variation does not materialize)`.
+
+   Do not name patterns speculatively or for CRUD/generic work. A spec is not a
+   pattern shopping list — naming records a justified hypothesis, not a mandate.
+
 ## Filename Convention
 
 Read the specs output path from `../shared/config.json` (key: `paths.specs`,
@@ -64,6 +101,7 @@ In addition to the markdown spec document, write a sibling JSON file at `<specs-
       "name": "<epic name>",
       "slug": "<kebab-case>",
       "description": "<one-paragraph>",
+      "subdomain": "core | supporting | generic",
       "depends_on": [],
       "shared_design_concerns": [],
       "slice": { "start_line": 0, "end_line": 0 }

package/skills/shared/references/ENGINEERING_BASELINE.md

@@ -0,0 +1,154 @@
+# Engineering Baseline
+
+> The universal engineering standard for all work this skill suite drives.
+> `project-spec` reads it at design time; `project-orchestrate` reads it and
+> **injects it into every subagent it spawns** at implementation time. It
+> applies across the board, to every story and every file, regardless of domain.
+>
+> This is the **baseline layer**. The **situational layer** — Gang of Four
+> design patterns (`design-patterns`) and tactical Domain-Driven Design
+> (`domain-modeling`) — sits on top of it and is composed in only when the work
+> warrants it (see each skill). When the situational layer fires, it remains
+> **subordinate to the Arbitration Rule below**.
+
+---
+
+## The Arbitration Rule (read this first)
+
+**Simple design is the default. Abstractions, design patterns, and domain layers
+are responses to demonstrated complexity — duplication, repeated change in one
+place, or essential domain rules — never anticipatory architecture. Arrive at
+patterns by refactoring toward them, not by designing to them.**
+
+Every pattern, every layer, every abstraction must justify itself against this
+rule. Three similar lines beat a premature abstraction. When in doubt, write the
+simplest thing that works and let duplication or change-pressure tell you when to
+extract.
+
+---
+
+## Clean Code
+
+### Naming
+> Martin's standard: a good name answers the big questions — why the thing exists,
+> what it does, and how it's used. If a name needs a comment to explain it, the
+> name has failed.
+
+- Names reveal intent. If a name needs a comment, the name is wrong.
+- Class names are nouns; method names are verbs.
+- One word per concept, used consistently across the codebase.
+- Name length matches scope. Short names for short scopes; full descriptive
+  names for wide ones.
+- Don't encode type or scope into names (no Hungarian notation, no `m_`).
+- Names describe side effects. A function that creates-if-absent is not a getter.
+
+### Functions
+> Martin's rules: functions should be small — and then smaller. Each should do one
+> thing, do it well, and do it only.
+
+- Small. One thing. One level of abstraction per function body.
+- Stepdown rule: high-level functions first, helpers below — readable top to
+  bottom like a newspaper.
+- Minimize arguments. Zero–two normal, three suspect, more → pass an object.
+- No flag (boolean) arguments — split into two functions.
+- No hidden side effects. Command-query separation: change state or return a
+  value, not both.
+- Don't return null and don't pass null. Return an empty collection, an Optional,
+  or throw.
+
+### Comments
+> Martin's view: a comment is a way of compensating for failing to express the
+> intent in code. Prefer rewriting the code over explaining it with a comment.
+
+- The best comment is the one made unnecessary by clear code.
+- Delete commented-out code; version control remembers.
+- A necessary comment explains **why**, not **what**.
+- TODOs carry a ticket number or removal date.
+
+### Formatting
+- Related code stays vertically close; declare variables near first use.
+- Keep lines readable without horizontal scrolling (~100 chars).
+- Blank lines separate concepts; none between tightly coupled statements.
+- Team/project formatting rules override personal preference.
+
+### Objects and Data
+- Objects hide data and expose behavior; data structures expose data and have no
+  behavior. Don't make hybrids.
+- Law of Demeter: don't reach through chains (`a.getB().getC().do()`).
+- Prefer polymorphism over `switch`/`if-else` chains on type.
+
+### Error Handling
+> Martin's guidance: prefer exceptions over return codes for error signaling.
+
+- Exceptions, not return codes. Write try-catch-finally first for fallible code.
+- Provide context: what operation failed and what state was expected.
+- Define exception types by how the caller handles them.
+
+### Boundaries
+- Wrap third-party APIs behind your own interfaces; don't let library types leak
+  across module boundaries.
+
+### Classes
+- Single Responsibility: one reason to change.
+- High cohesion: most methods use most fields.
+- Open-Closed: extend without modifying working code.
+- Dependency Inversion: depend on abstractions, not concretions.
+
+### Smells — fix on sight
+Dead code; commented-out code; functions with >3 arguments; magic
+numbers/strings; base classes referencing derivatives; feature envy; inconsistent
+conventions; hidden temporal coupling; artificial coupling; negative conditionals
+(`!isNotReady()` → `isReady()`).
+
+### The Boy Scout Rule
+> The Boy Scout Rule (Martin, adapting the scouting maxim): always leave the code
+> a little cleaner than you found it.
+
+Leave every file cleaner than you found it. Every commit. No exceptions.
+
+---
+
+## Test-Driven Development
+
+TDD is universal here — it governs how code comes into being, not just whether
+tests exist.
+
+### The discipline
+- **Red → Green → Refactor** — Beck's rhythm. *Red:* write a small test that fails
+  (it may not even compile yet). *Green:* make it pass as quickly as possible.
+  *Refactor:* remove the duplication you created getting there. Always in that
+  order — make it work, then make it clean.
+- **Three laws** (Robert C. Martin's formulation of the same discipline): (1)
+  write a failing test before production code; (2) write only enough test to fail;
+  (3) write only enough production code to pass.
+- **Small steps** — Beck's techniques. When a step is hard, take a smaller one:
+  *Fake It* (return a constant) to get to green, then *Triangulate* to the real
+  implementation.
+
+### What good tests look like
+- Tests describe behavior, not implementation. Test names are assertions
+  ("computes pace when duration is edited"), not "test case 1".
+- One concept per test (not necessarily one assert — one idea).
+- **F.I.R.S.T.**: Fast, Independent, Repeatable, Self-validating, Timely.
+- Test boundary conditions and cluster tests near known bugs.
+- Tests are first-class code: clean, readable, well-named, colocated with source.
+
+### Emergence (simple design, in priority order)
+1. All tests pass. Untested code is unfinished code.
+2. No duplication. Every piece of knowledge has one authoritative representation.
+3. Code is expressive. The reader understands intent without asking the author.
+4. Minimal classes and methods. Don't create abstractions you don't need yet.
+
+---
+
+## How this baseline is applied
+
+- **`project-spec` (design time):** specs are written to satisfy this baseline.
+  Acceptance criteria assume tests-first; designs assume the Arbitration Rule.
+- **`project-orchestrate` (implementation time):** this document is injected,
+  verbatim or by reference, into every implementation, review, and hardening
+  subagent prompt. Subagents follow it in addition to the project's own
+  `CLAUDE.md` (project rules win on direct conflict).
+- **Order of precedence:** project `CLAUDE.md` > this baseline > situational
+  guidance (`design-patterns`, `domain-modeling`). The situational layer never
+  overrides the Arbitration Rule.