@houseofwolvesllc/claude-scrum-skill 1.8.1 → 2.1.0

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
+}

package/lib/workflows/schemas/ReviewVerdictSchema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/ReviewVerdictSchema.json",
+  "title": "ReviewVerdictSchema",
+  "description": "Output of a single review pass (per-lens verdict in review_panel.js, or single-pass review in older skills).",
+  "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",
+          "items": { "$ref": "#/$defs/Finding" }
+        },
+        "warning": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Finding" }
+        },
+        "info": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Finding" }
+        }
+      }
+    },
+    "summary": {
+      "type": "string",
+      "description": "Reviewer's one-paragraph summary of the pass."
+    },
+    "lens": {
+      "type": "string",
+      "enum": ["correctness", "security", "style", "tests"],
+      "description": "Set by review_panel.js when running multi-lens; absent in single-pass review."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "Finding": {
+      "type": "object",
+      "required": ["title", "severity", "body"],
+      "properties": {
+        "title": { "type": "string" },
+        "location": {
+          "type": "string",
+          "description": "file:line or section reference; optional but recommended."
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["critical", "warning", "info"]
+        },
+        "body": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/lib/workflows/schemas/ScaffoldOutputSchema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/ScaffoldOutputSchema.json",
+  "title": "ScaffoldOutputSchema",
+  "description": "Output of /project-scaffold; consumed by /project-orchestrate Step 1 to scope the run.",
+  "type": "object",
+  "required": ["scope", "scopedEpics", "scopedStories"],
+  "properties": {
+    "scope": {
+      "type": "string",
+      "enum": ["prd", "all"],
+      "description": "Whether the run is PRD-scoped or covers all open epics."
+    },
+    "scopedEpics": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Epic slugs (local mode) or milestone numbers (remote mode) created/touched by this scaffold."
+    },
+    "scopedStories": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Story slugs or issue numbers created/touched by this scaffold."
+    },
+    "designSpikeEpic": {
+      "type": "string",
+      "description": "Slug of the auto-injected design-spike epic, if any."
+    },
+    "queueStateFilePath": {
+      "type": "string",
+      "description": "Path to orchestration-queue-state.md when multi-path mode is in effect."
+    }
+  },
+  "additionalProperties": false
+}

package/lib/workflows/schemas/SpecSchema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/SpecSchema.json",
+  "title": "SpecSchema",
+  "description": "Output shape of /project-spec, consumed by /project-scaffold. Inlined to avoid cross-file $ref resolution ambiguity.",
+  "type": "object",
+  "required": ["title", "overview", "objectives", "epics"],
+  "properties": {
+    "title": { "type": "string" },
+    "overview": { "type": "string" },
+    "objectives": {
+      "type": "object",
+      "required": ["primary"],
+      "properties": {
+        "primary": { "type": "array", "items": { "type": "string" } },
+        "secondary": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "epics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Epic" }
+    },
+    "dependencies": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "design_concerns": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "scaffold_mode": {
+      "type": "string",
+      "enum": ["single-pass", "two-pass"]
+    },
+    "design_spike": { "type": "boolean" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "Epic": {
+      "type": "object",
+      "required": ["name", "slug", "description"],
+      "properties": {
+        "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": {
+          "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" } }
+      }
+    },
+    "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/SprintStoryReturnSchema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/SprintStoryReturnSchema.json",
+  "title": "SprintStoryReturnSchema",
+  "description": "Per-story return value from sprint_pipeline.js. The calling skill persists results to state file and story frontmatter.",
+  "type": "object",
+  "required": ["storySlug", "status"],
+  "properties": {
+    "storySlug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["done", "blocked", "failed"]
+    },
+    "branch": {
+      "type": "string",
+      "description": "Story branch name created during implementation (e.g., story/12-auth-endpoint)."
+    },
+    "prUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "GitHub mode only. PR URL opened by the story branch."
+    },
+    "commits": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Commit SHAs produced by the story."
+    },
+    "blockers": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Free-text descriptions of why the story is blocked. Populated when status = blocked."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Free-text explanation when status = failed or blocked."
+    }
+  },
+  "additionalProperties": false
+}

package/lib/workflows/schemas/StorySchema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/houseofwolvesllc/claudescrumskill/schemas/StorySchema.json",
+  "title": "StorySchema",
+  "description": "Single story shape produced by Pass 2 elaboration; consumed by sprint planning and execution.",
+  "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",
+      "description": "Architecture notes, relevant files, approach guidance. May be empty if the story body is self-explanatory."
+    },
+    "points": {
+      "type": "integer",
+      "enum": [1, 2, 3, 5, 8, 13],
+      "description": "Fibonacci estimate per CONVENTIONS.md story point guidelines."
+    },
+    "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"],
+      "description": "Subagent posture preamble selection. Default is impl."
+    },
+    "blocked_by": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Slugs (or epic/slug references) of stories that must complete first."
+    },
+    "blocks": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "labels": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": false
+}

package/lib/workflows/sprint_pipeline.js

@@ -0,0 +1,264 @@
+// sprint_pipeline.js — per-story sprint execution as a pipeline.
+//
+// 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.
+//
+// args: {
+//   stories: Story[],              // StorySchema-shaped
+//   epicSlug: string,
+//   releaseBranch: string,         // "release/<epic-slug>"
+//   contextMdPath?: string,        // <paths.context>/<epicSlug>/CONTEXT.md
+//   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
+//   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)
+
+export const meta = {
+  name: 'sprint-pipeline',
+  description: 'Per-story sprint execution: implement → review → verify → open PR',
+  phases: [
+    { title: 'Implement' },
+    { title: 'Review' },
+    { title: 'Verify' },
+    { title: 'Open PR' },
+  ],
+}
+
+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' },
+  },
+}
+
+const IMPL_RETURN_SCHEMA = {
+  type: 'object',
+  required: ['storySlug', 'branch', 'commits'],
+  properties: {
+    storySlug: { type: 'string' },
+    branch: { type: 'string' },
+    commits: { type: 'array', items: { type: 'string' } },
+    notes: { type: 'string' },
+  },
+}
+
+const VERIFY_RETURN_SCHEMA = {
+  type: 'object',
+  required: ['storySlug', 'verifyStatus'],
+  properties: {
+    storySlug: { type: 'string' },
+    verifyStatus: { type: 'string', enum: ['pass', 'warn', 'fail'] },
+    notes: { type: 'string' },
+  },
+}
+
+const SPRINT_STORY_RETURN_SCHEMA = {
+  type: 'object',
+  required: ['storySlug', 'status'],
+  properties: {
+    storySlug: { type: 'string' },
+    status: { type: 'string', enum: ['done', 'blocked', 'failed'] },
+    branch: { type: 'string' },
+    prUrl: { type: 'string' },
+    commits: { type: 'array', items: { type: 'string' } },
+    blockers: { type: 'array', items: { type: 'string' } },
+    reason: { type: 'string' },
+  },
+}
+
+/**
+ * Build a SprintStoryReturn-shaped object for short-circuit paths
+ * (review-block, verify-fail). The shape conforms to
+ * SPRINT_STORY_RETURN_SCHEMA above; keeping the helper alongside ensures
+ * any future schema change requires updating both at once.
+ */
+function makeSprintStoryReturn({ storySlug, status, branch, commits, prUrl, blockers, reason }) {
+  const out = { storySlug, status }
+  if (branch !== undefined) out.branch = branch
+  if (commits !== undefined) out.commits = commits
+  if (prUrl !== undefined) out.prUrl = prUrl
+  if (blockers !== undefined) out.blockers = blockers
+  if (reason !== undefined) out.reason = reason
+  return out
+}
+
+const {
+  stories,
+  epicSlug,
+  releaseBranch,
+  contextMdPath,
+  claudeMdPath,
+  backendMode,
+  repoIdentifier,
+  personaPreambles = {},
+  baselinePath,
+  situationalGuidance = [],
+} = args
+
+if (!stories || stories.length === 0) {
+  log('No stories in sprint — exiting.')
+  return []
+}
+
+log(`Sprint pipeline: ${stories.length} stories on release branch ${releaseBranch} (backend=${backendMode}).`)
+
+function buildImplementPrompt(story) {
+  const persona = story.persona || 'impl'
+  const preamble = personaPreambles[persona] || ''
+  const claudeMdLine = claudeMdPath
+    ? `Before writing any code, read ${claudeMdPath} and follow every convention.`
+    : 'Read the project CLAUDE.md (if present) and follow every convention.'
+  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}
+
+---
+
+You are implementing story ${story.slug} on release branch ${releaseBranch}.
+
+${claudeMdLine}
+${baselineLine}
+${situationalLine}
+${contextLine}
+
+**Story:** ${story.title}
+**Acceptance criteria:**
+${(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.
+
+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}.
+
+Story acceptance criteria:
+${(story.acceptance_criteria || []).map(c => `  - ${c}`).join('\n')}
+
+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.`
+}
+
+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).
+
+Return verifyStatus (pass | warn | fail) and brief notes.`
+}
+
+function buildOpenPRPrompt(verify, story, impl) {
+  const ghOrLocal =
+    backendMode === 'github'
+      ? `Open a PR via gh CLI targeting ${releaseBranch}. Capture the PR URL.`
+      : `Merge story/${story.slug} into ${releaseBranch} locally. Capture the merge commit SHA.`
+  return `You are finalizing story ${story.slug}.
+
+Verify status: ${verify.verifyStatus}. Review recommendation: (from prior stage).
+
+${ghOrLocal}
+
+Return SprintStoryReturn: storySlug, status (done | blocked | failed), branch, prUrl (github mode) or merge commit (local mode), commits[], blockers[] (if blocked), reason (if failed).`
+}
+
+phase('Implement')
+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.',
+      })
+    }
+    return agent(buildOpenPRPrompt(verify, story, impl), {
+      label: `pr:${story.slug}`,
+      phase: 'Open PR',
+      schema: SPRINT_STORY_RETURN_SCHEMA,
+    })
+  }
+)
+
+return results.filter(Boolean)

package/package.json

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