@houseofwolvesllc/claude-scrum-skill 1.8.0 → 2.0.0

package/README.md

@@ -60,18 +60,24 @@ PRD (optional)  -->  /project-orchestrate
 
 ## Installation
 
+> **v2.0.0 runtime requirement:** v2.0.0 invokes Claude Code's [Workflow tool](https://docs.claude.com/claude-code) for internal fan-out. Your Claude Code must include the Workflow tool (latest CLI, desktop app, web app, and IDE extensions all do). If you're on a stale CLI install without auto-update, run `npm update -g @anthropic-ai/claude-code` first — or install the v1.8.x fallback: `npm install --save-dev @houseofwolvesllc/claude-scrum-skill@1.8.1`.
+
 ### 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
+# Local install — this project only (developer tooling → devDependencies)
+npm install --save-dev @houseofwolvesllc/claude-scrum-skill
+# or the shorthand:
+npm install -D @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`.
 
+> **Why `--save-dev`?** This package is developer tooling — the skills are consumed by Claude Code at planning/build/iteration time, never by your application's runtime. Saving to `devDependencies` (instead of `dependencies`) keeps it out of production installs (`npm ci --production`, `NODE_ENV=production`, Docker production layers), avoids running the postinstall script in environments where `~/.claude/skills/` doesn't exist, and accurately reflects that the package isn't a runtime requirement. Same category as `eslint`, `prettier`, `vitest`, etc.
+
 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.
@@ -478,6 +484,59 @@ Run `/project-scaffold` with a new PRD — it detects the existing project and o
 
 ---
 
+## Architecture (v2.0.0+)
+
+claudescrumskill ships in two cooperating layers. The split is documented in detail in [ADR-0003](docs/adrs/0003-workflow-backed-re-plumbing.md).
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Skills — markdown SKILL.md (the opinion + the surface)    │
+│  - Slash commands users type                                │
+│  - Phase / step structure                                   │
+│  - Durable repo artifacts (state files, ADRs, CONTEXT.md)   │
+│  - Installed at ~/.claude/skills/<skill>/SKILL.md           │
+└──────────────────────┬─────────────────────────────────────┘
+                       │  invokes via Workflow tool
+                       ▼
+┌────────────────────────────────────────────────────────────┐
+│  Workflows — JavaScript at lib/workflows/ (the substrate)  │
+│  - Fan-out (parallel, pipeline) up to 16 concurrent agents  │
+│  - Schema-validated structured returns                      │
+│  - Journal-based in-session resume                          │
+│  - Installed at ~/.claude/skills/_workflows/                │
+└──────────────────────┬─────────────────────────────────────┘
+                       │  spawns
+                       ▼
+┌────────────────────────────────────────────────────────────┐
+│  Agents — the workers that implement stories, review        │
+│  diffs, verify findings, etc.                               │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Workflow scripts shipped in v2.0.0
+
+| Script | Purpose | Used by |
+|--------|---------|---------|
+| `sprint_pipeline.js` | per-story pipeline: implement → review → verify → openPR | `/project-orchestrate` Phase 1 Step 3 |
+| `elaborate_epics.js` | Pass 2 of two-pass scaffolding, in parallel | `/project-scaffold` |
+| `adversarial_verify.js` | claimant/skeptic/judge per emulation finding | `/project-emulate` |
+| `review_panel.js` | multi-lens (correctness/security/style/tests) review | `/project-cleanup`, `/code-review` |
+
+### Schemas at `lib/workflows/schemas/`
+
+JSON Schema Draft 2020-12. The cross-skill type system: `SpecSchema`, `EpicSchema`, `StorySchema`, `EmulationFindingSchema`, `ReviewVerdictSchema`, `SprintStoryReturnSchema`, `ScaffoldOutputSchema`, `PRDFrontmatterSchema`. Schemas live alongside workflows and are referenced from `agent({ schema: ... })` calls.
+
+### Adding a workflow
+
+Contributors adding fan-out heavy skills (large parallel work, multi-stage pipelines, judge panels) should:
+
+1. Author the workflow at `lib/workflows/<name>.js` per the patterns in existing scripts.
+2. Add any new schemas to `lib/workflows/schemas/`.
+3. Reference the workflow from the skill markdown via the Path Resolution Algorithm documented in each affected SKILL.md (`<skills-root>/_workflows/<name>.js`).
+4. Bump the package version per SemVer (new workflow + new schema → minor; breaking schema change → major).
+
+---
+
 ## Shared References
 
 All skills reference shared configuration and standards from `skills/shared/`:

package/bin/install.js

@@ -5,6 +5,7 @@ const path = require('path');
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const SOURCE_DIR = path.join(__dirname, '..', 'skills');
+const WORKFLOWS_SOURCE_DIR = path.join(__dirname, '..', 'lib', 'workflows');
 const IS_GLOBAL = process.env.npm_config_global === 'true';
 
 // Global install → ~/.claude/skills/
@@ -76,6 +77,14 @@ for (const skill of skills) {
   }
 }
 
+// Copy lib/workflows/ → <skillsDir>/_workflows/ (v2.0.0+).
+// Underscore prefix prevents Claude Code from registering as a skill.
+if (fs.existsSync(WORKFLOWS_SOURCE_DIR)) {
+  const workflowsDest = path.join(skillsDir, '_workflows');
+  copyRecursive(WORKFLOWS_SOURCE_DIR, workflowsDest);
+  console.log('  ⚙️  _workflows (lib/workflows + schemas)');
+}
+
 // Add .claude-scrum-skill to .gitignore if not already present (local install only)
 if (!IS_GLOBAL) {
   const projectRoot = path.resolve(skillsDir, '..', '..');

package/lib/workflows/adversarial_verify.js

@@ -0,0 +1,148 @@
+// adversarial_verify.js — Claimant / skeptic / judge verification of
+// emulation findings. Replaces "trust the emulator" with structured verdicts.
+//
+// Invoked by /project-emulate after raw findings are produced.
+//
+// args: {
+//   findings: EmulationFinding[],     // EmulationFindingSchema-shaped
+//   codebaseContext?: { projectRoot: string, languages: string[] }
+// }
+//
+// returns: Array<{ finding, claim, skeptic, verdict }>
+
+export const meta = {
+  name: 'adversarial-verify',
+  description: 'Claimant / skeptic / judge verification of emulation findings.',
+  phases: [
+    { title: 'Argue' },
+    { title: 'Judge' },
+  ],
+}
+
+const EVIDENCE_SCHEMA = {
+  type: 'object',
+  required: ['summary', 'evidence'],
+  properties: {
+    summary: { type: 'string' },
+    evidence: { type: 'array', items: { type: 'string' }, minItems: 1 },
+    confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+  },
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['isReal', 'rationale'],
+  properties: {
+    isReal: { type: 'boolean' },
+    rationale: { type: 'string' },
+    confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+    severity_adjustment: {
+      type: 'string',
+      enum: ['raise', 'lower', 'unchanged'],
+      description: 'Whether to raise or lower severity vs original finding.',
+    },
+  },
+}
+
+const { findings, codebaseContext = {} } = args
+
+if (!findings || findings.length === 0) {
+  log('No findings to verify — exiting.')
+  return []
+}
+
+log(`Verifying ${findings.length} findings with claimant/skeptic/judge.`)
+
+phase('Argue')
+phase('Judge')
+
+function claimantPrompt(finding) {
+  return `You are arguing that the following emulation finding IS real and accurate.
+
+Finding (severity: ${finding.severity}):
+  Title: ${finding.title}
+  Category: ${finding.category}
+  Body: ${finding.body}
+  Affected files: ${(finding.affected_files || []).join(', ') || '(none)'}
+
+Argue the case. Read the affected files. Produce evidence supporting the finding. Cite specific lines / patterns. Default toward "real" unless evidence clearly contradicts.
+
+Return: summary, evidence (array of citations), confidence.`
+}
+
+function skepticPrompt(finding) {
+  return `You are arguing that the following emulation finding is a FALSE POSITIVE or overstated.
+
+Finding (severity: ${finding.severity}):
+  Title: ${finding.title}
+  Category: ${finding.category}
+  Body: ${finding.body}
+  Affected files: ${(finding.affected_files || []).join(', ') || '(none)'}
+
+Argue the case. Read the affected files. Look for: missing context the emulator didn't see, project-specific conventions that make this fine, downstream code that handles the concern, scope-narrowing facts that reduce severity, alternative interpretations.
+
+Return: summary, evidence (array of citations), confidence.`
+}
+
+function judgePrompt(finding, claim, skeptic) {
+  return `You are the third agent. Two prior agents argued opposing positions on this emulation finding.
+
+Finding:
+  Title: ${finding.title}
+  Body: ${finding.body}
+
+Claimant argued REAL:
+  Summary: ${claim.summary}
+  Evidence: ${(claim.evidence || []).join('\n  ')}
+  Confidence: ${claim.confidence || 'unspecified'}
+
+Skeptic argued FALSE POSITIVE:
+  Summary: ${skeptic.summary}
+  Evidence: ${(skeptic.evidence || []).join('\n  ')}
+  Confidence: ${skeptic.confidence || 'unspecified'}
+
+Judge: is this finding real or false-positive? Provide rationale. Optionally suggest a severity adjustment (raise / lower / unchanged).
+
+Return: isReal (bool), rationale, confidence, severity_adjustment.`
+}
+
+async function verifyOne(finding) {
+  const [claim, skeptic] = await parallel([
+    () =>
+      agent(claimantPrompt(finding), {
+        label: `claim:${finding.id}`,
+        phase: 'Argue',
+        schema: EVIDENCE_SCHEMA,
+      }),
+    () =>
+      agent(skepticPrompt(finding), {
+        label: `skeptic:${finding.id}`,
+        phase: 'Argue',
+        schema: EVIDENCE_SCHEMA,
+      }),
+  ])
+
+  if (!claim || !skeptic) {
+    log(`Skipping judge for finding ${finding.id} — claimant or skeptic agent failed.`)
+    return null
+  }
+
+  const verdict = await agent(judgePrompt(finding, claim, skeptic), {
+    label: `judge:${finding.id}`,
+    phase: 'Judge',
+    schema: VERDICT_SCHEMA,
+  })
+
+  if (!verdict) return null
+
+  return { finding, claim, skeptic, verdict }
+}
+
+const verified = await parallel(findings.map(f => () => verifyOne(f)))
+const successful = verified.filter(Boolean)
+
+const realCount = successful.filter(v => v.verdict.isReal).length
+const falsePositiveCount = successful.length - realCount
+log(`Verified ${successful.length}/${findings.length} findings: ${realCount} real, ${falsePositiveCount} false-positive.`)
+
+return verified

package/lib/workflows/elaborate_epics.js

@@ -0,0 +1,136 @@
+// elaborate_epics.js — Pass 2 of two-pass scaffolding.
+//
+// Invoked by /project-scaffold when two-pass mode is selected.
+// Replaces the v1.x Task-spawning prose with one parallel wave.
+//
+// args: {
+//   skeleton: {
+//     project: { name, description, global_preamble, non_functional_requirements: string[] },
+//     epics: Array<{
+//       name, slug, description,
+//       slice: { start_line: int, end_line: int },
+//       depends_on: string[],
+//       shared_design_concerns: string[]
+//     }>
+//   },
+//   prdPath: string,                       // for slicing
+//   conventionsPath?: string               // shared/references/CONVENTIONS.md
+// }
+//
+// returns: Epic[] with stories[] populated. Failed epics return null;
+//          the calling skill marks their stories needs-context.
+
+export const meta = {
+  name: 'elaborate-epics',
+  description: 'Pass 2 of two-pass scaffolding: per-epic elaboration in parallel.',
+  phases: [{ title: 'Elaborate Epics' }],
+}
+
+const EPIC_SCHEMA = {
+  type: 'object',
+  required: ['name', 'slug', 'description', 'stories'],
+  properties: {
+    name: { type: 'string' },
+    slug: { type: 'string', pattern: '^[a-z0-9]+(-[a-z0-9]+)*$' },
+    description: { type: 'string' },
+    depends_on: { type: 'array', items: { type: 'string' } },
+    shared_design_concerns: { type: 'array', items: { type: 'string' } },
+    stories: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title', 'slug', 'acceptance_criteria', 'points', 'executor'],
+        properties: {
+          title: { type: 'string' },
+          slug: { type: 'string', pattern: '^[a-z0-9]+(-[a-z0-9]+)*$' },
+          acceptance_criteria: { type: 'array', items: { type: 'string' }, minItems: 1 },
+          technical_context: { type: 'string' },
+          points: { type: 'integer', enum: [1, 2, 3, 5, 8, 13] },
+          executor: { type: 'string', enum: ['claude', 'human', 'cowork'] },
+          priority: { type: 'string', enum: ['P0-critical', 'P1-high', 'P2-medium', 'P3-low'] },
+          persona: { type: 'string', enum: ['impl', 'ops', 'research'] },
+          blocked_by: { type: 'array', items: { type: 'string' } },
+          blocks: { type: 'array', items: { type: 'string' } },
+          labels: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      minItems: 1,
+    },
+  },
+}
+
+const { skeleton, prdPath, conventionsPath } = args
+
+if (!skeleton || !skeleton.epics || skeleton.epics.length === 0) {
+  log('Empty skeleton — exiting.')
+  return []
+}
+
+log(`Pass 2: elaborating ${skeleton.epics.length} epics from ${prdPath}.`)
+
+phase('Elaborate Epics')
+
+function buildElaboratePrompt(epic) {
+  const siblings = skeleton.epics
+    .filter(e => e.slug !== epic.slug)
+    .map(e => `  - ${e.slug}: ${e.description}`)
+    .join('\n')
+
+  const sharedConcerns = (epic.shared_design_concerns || []).map(c => `  - ${c}`).join('\n')
+
+  return `You are elaborating epic "${epic.name}" (slug: ${epic.slug}) for project "${skeleton.project.name}".
+
+== Project global preamble ==
+${skeleton.project.global_preamble || ''}
+
+== Project NFRs ==
+${(skeleton.project.non_functional_requirements || []).map(n => `  - ${n}`).join('\n')}
+
+== This epic ==
+Description: ${epic.description}
+PRD slice: lines ${epic.slice.start_line}–${epic.slice.end_line} of ${prdPath}
+Depends on: ${(epic.depends_on || []).join(', ') || 'none'}
+Shared design concerns this epic introduces:
+${sharedConcerns || '  (none)'}
+
+== Sibling epics (for dependency awareness, NOT for elaboration) ==
+${siblings || '  (none)'}
+
+== Your task ==
+Read the PRD slice (lines ${epic.slice.start_line}–${epic.slice.end_line}). Produce the complete story list for THIS epic. Each story needs:
+  - title (concise imperative)
+  - slug (kebab-case)
+  - acceptance_criteria (at least one specific, testable item)
+  - technical_context (architecture notes, relevant files, approach)
+  - points (Fibonacci: 1, 2, 3, 5, 8, 13 per CONVENTIONS.md)
+  - executor (claude | human | cowork; per CONVENTIONS.md guidelines)
+  - persona (impl | ops | research; default impl)
+  - priority (P0/P1/P2/P3)
+  - blocked_by, blocks (within this epic or referencing other epics' slugs)
+  - labels (per CONVENTIONS.md taxonomy)
+
+${conventionsPath ? `Reference ${conventionsPath} for the label taxonomy and story point guidelines.` : ''}
+
+Return an Epic shape with name, slug, description, depends_on, shared_design_concerns, and stories[] populated.`
+}
+
+const elaborated = await parallel(
+  skeleton.epics.map(epic => () =>
+    agent(buildElaboratePrompt(epic), {
+      label: `elaborate:${epic.slug}`,
+      phase: 'Elaborate Epics',
+      schema: EPIC_SCHEMA,
+    })
+  )
+)
+
+const successes = elaborated.filter(Boolean)
+log(`Pass 2 complete: ${successes.length}/${skeleton.epics.length} epics elaborated successfully.`)
+if (successes.length < skeleton.epics.length) {
+  const failed = skeleton.epics
+    .filter((_, i) => !elaborated[i])
+    .map(e => e.slug)
+  log(`Failed epics (calling skill should mark stories needs-context): ${failed.join(', ')}`)
+}
+
+return elaborated

package/lib/workflows/review_panel.js

@@ -0,0 +1,166 @@
+// review_panel.js — Multi-lens parallel review with aggregated verdict.
+//
+// Invoked by /project-cleanup and /code-review for the review gate.
+//
+// args: {
+//   diff: string,
+//   files: Array<{ path: string, contents: string }>,
+//   lenses?: Array<"correctness" | "security" | "style" | "tests">,
+//   projectConventionsPath?: string    // CLAUDE.md
+// }
+//
+// returns: {
+//   panelVerdict: ReviewVerdict (aggregated),
+//   perLensVerdicts: Record<lens, ReviewVerdict>
+// }
+
+export const meta = {
+  name: 'review-panel',
+  description: 'Multi-lens parallel review with aggregated verdict.',
+  phases: [
+    { title: 'Per-Lens Review' },
+    { title: 'Aggregate' },
+  ],
+}
+
+const REVIEW_VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['recommendation', 'findings', 'summary'],
+  properties: {
+    recommendation: { type: 'string', enum: ['accept', 'accept-with-followups', 'block'] },
+    findings: {
+      type: 'object',
+      required: ['critical', 'warning', 'info'],
+      properties: {
+        critical: { type: 'array' },
+        warning: { type: 'array' },
+        info: { type: 'array' },
+      },
+    },
+    summary: { type: 'string' },
+    lens: { type: 'string' },
+  },
+}
+
+const DEFAULT_LENSES = ['correctness', 'security', 'style', 'tests']
+
+const { diff, files, lenses = DEFAULT_LENSES, projectConventionsPath } = args
+
+if (!diff && (!files || files.length === 0)) {
+  log('No diff and no files — nothing to review.')
+  return {
+    panelVerdict: {
+      recommendation: 'accept',
+      findings: { critical: [], warning: [], info: [] },
+      summary: 'Nothing to review.',
+    },
+    perLensVerdicts: {},
+  }
+}
+
+log(`Review panel: ${lenses.length} lenses (${lenses.join(', ')}).`)
+
+phase('Per-Lens Review')
+phase('Aggregate')
+
+const LENS_INSTRUCTIONS = {
+  correctness: `Focus on: does the code do what the acceptance criteria / change description requires? Are there logic errors, off-by-ones, missed branches, broken invariants? Are edge cases handled?`,
+  security: `Focus on: injection sinks (SQL, shell, HTML, path), missing authentication checks, broken authorization, secret exposure, unvalidated user input reaching dangerous APIs, permission expansion without justification.`,
+  style: `Focus on: project convention adherence (per CLAUDE.md), naming consistency, file organization, import ordering. Do NOT bikeshed style the project doesn't enforce.`,
+  tests: `Focus on: are new behaviors covered by tests? Are existing tests still meaningful? Are tests testing behavior or implementation? Coverage at integration seams?`,
+}
+
+function buildLensPrompt(lens) {
+  const conventions = projectConventionsPath
+    ? `Read ${projectConventionsPath} first — review against the project's actual conventions, not generic standards.`
+    : `Read the project CLAUDE.md if it exists — review against the project's actual conventions, not generic standards.`
+  return `You are reviewing a code change through the **${lens}** lens.
+
+${conventions}
+
+Lens focus: ${LENS_INSTRUCTIONS[lens] || '(no specific instructions for this lens)'}
+
+== Diff ==
+${diff || '(no diff provided; review the files below directly)'}
+
+== Changed files (full contents) ==
+${(files || []).map(f => `--- ${f.path} ---\n${f.contents}`).join('\n\n')}
+
+Return a ReviewVerdict for THIS LENS ONLY:
+  - recommendation (accept | accept-with-followups | block)
+  - findings grouped by severity (critical | warning | info)
+  - summary (one-paragraph)
+  - lens: "${lens}"
+
+Be specific. "This could be better" is not a finding. Cite file:line where applicable.`
+}
+
+const perLensResults = await parallel(
+  lenses.map(lens => () =>
+    agent(buildLensPrompt(lens), {
+      label: `review:${lens}`,
+      phase: 'Per-Lens Review',
+      schema: REVIEW_VERDICT_SCHEMA,
+    })
+  )
+)
+
+const perLensVerdicts = {}
+lenses.forEach((lens, i) => {
+  if (perLensResults[i]) {
+    perLensVerdicts[lens] = perLensResults[i]
+  }
+})
+
+const validVerdicts = Object.values(perLensVerdicts)
+
+if (validVerdicts.length === 0) {
+  log('All lens reviewers failed — returning a default block verdict.')
+  return {
+    panelVerdict: {
+      recommendation: 'block',
+      findings: {
+        critical: [{
+          title: 'Review panel failed to produce any verdict',
+          severity: 'critical',
+          body: 'All lens reviewers returned null.',
+        }],
+        warning: [],
+        info: [],
+      },
+      summary: 'Review panel non-functional.',
+    },
+    perLensVerdicts: {},
+  }
+}
+
+// Aggregation rule: any block → panel block; any accept-with-followups → panel accept-with-followups; else accept.
+let panelRecommendation = 'accept'
+if (validVerdicts.some(v => v.recommendation === 'block')) {
+  panelRecommendation = 'block'
+} else if (validVerdicts.some(v => v.recommendation === 'accept-with-followups')) {
+  panelRecommendation = 'accept-with-followups'
+}
+
+// Union findings across lenses, preserving lens attribution.
+const findings = { critical: [], warning: [], info: [] }
+for (const [lens, verdict] of Object.entries(perLensVerdicts)) {
+  for (const sev of ['critical', 'warning', 'info']) {
+    for (const f of verdict.findings[sev] || []) {
+      findings[sev].push({ ...f, lens })
+    }
+  }
+}
+
+const summary = `Panel verdict: ${panelRecommendation}. ${validVerdicts.length}/${lenses.length} lenses reported. ${findings.critical.length} critical, ${findings.warning.length} warning, ${findings.info.length} info findings (union across lenses).`
+
+log(summary)
+
+return {
+  panelVerdict: {
+    recommendation: panelRecommendation,
+    findings,
+    summary,
+  },
+  perLensVerdicts,
+}

package/lib/workflows/schemas/EmulationFindingSchema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/EmulationFindingSchema.json",
+  "title": "EmulationFindingSchema",
+  "description": "Single finding produced by /project-emulate; consumed by adversarial_verify.js.",
+  "type": "object",
+  "required": ["id", "severity", "category", "title", "body"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique finding identifier (e.g., C1, W3, I7)."
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["critical", "warning", "info"]
+    },
+    "category": {
+      "type": "string",
+      "description": "Free-form classification (e.g., 'Integration/Dockerfile/COPY', 'Layer/ResponseFormat', 'Documentation/Consistency')."
+    },
+    "title": {
+      "type": "string",
+      "description": "One-line finding summary."
+    },
+    "body": {
+      "type": "string",
+      "description": "Detailed finding description including reproduction or evidence."
+    },
+    "affected_files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo-relative paths of files implicated by the finding."
+    }
+  },
+  "additionalProperties": false
+}

package/lib/workflows/schemas/EpicSchema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/EpicSchema.json",
+  "title": "EpicSchema",
+  "description": "Single epic shape with stories inlined to avoid cross-file $ref resolution ambiguity.",
+  "type": "object",
+  "required": ["name", "slug", "description"],
+  "properties": {
+    "name": { "type": "string" },
+    "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "description": { "type": "string" },
+    "depends_on": { "type": "array", "items": { "type": "string" } },
+    "shared_design_concerns": { "type": "array", "items": { "type": "string" } },
+    "slice": {
+      "type": "object",
+      "properties": {
+        "start_line": { "type": "integer", "minimum": 1 },
+        "end_line": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "epic_type": { "type": "string", "enum": ["design-spike"] },
+    "stories": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Story" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "Story": {
+      "type": "object",
+      "required": ["title", "slug", "acceptance_criteria", "points", "executor"],
+      "properties": {
+        "title": { "type": "string" },
+        "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+        "acceptance_criteria": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "technical_context": { "type": "string" },
+        "points": { "type": "integer", "enum": [1, 2, 3, 5, 8, 13] },
+        "executor": { "type": "string", "enum": ["claude", "human", "cowork"] },
+        "priority": { "type": "string", "enum": ["P0-critical", "P1-high", "P2-medium", "P3-low"] },
+        "persona": { "type": "string", "enum": ["impl", "ops", "research"] },
+        "blocked_by": { "type": "array", "items": { "type": "string" } },
+        "blocks": { "type": "array", "items": { "type": "string" } },
+        "labels": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/lib/workflows/schemas/PRDFrontmatterSchema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/PRDFrontmatterSchema.json",
+  "title": "PRDFrontmatterSchema",
+  "description": "YAML frontmatter parsed from PRD documents. All fields optional.",
+  "type": "object",
+  "properties": {
+    "title": { "type": "string" },
+    "scaffold_mode": {
+      "type": "string",
+      "enum": ["single-pass", "two-pass"]
+    },
+    "design_spike": { "type": "boolean" },
+    "depends_on": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Other PRD specs (path or basename) that must complete before this one in sequential multi-path mode."
+    }
+  },
+  "additionalProperties": false
+}