@houseofwolvesllc/claude-scrum-skill 1.6.0 → 1.7.1

package/README.md

@@ -60,7 +60,23 @@ PRD (optional)  -->  /project-orchestrate
 
 ## Installation
 
-### Claude Code Plugin (recommended)
+### npm (recommended)
+
+```bash
+# Global install — available in all projects
+npm install -g @houseofwolvesllc/claude-scrum-skill
+
+# Local install — this project only
+npm install @houseofwolvesllc/claude-scrum-skill
+```
+
+Global install copies skills to `~/.claude/skills/`. Local install copies them to `<project>/.claude/skills/` and adds `.claude-scrum-skill` to your `.gitignore`.
+
+Skills surface in Claude Code with their plain names: `/project-scaffold`, `/project-orchestrate`, `/sprint-plan`, etc.
+
+> **Heads-up on re-installs:** the postinstall script overwrites every file under `<install-dir>/skills/` with the package's shipped version. If you've customized `<install-dir>/skills/shared/config.json` (e.g., changed `paths.specs` or `paths.adr`), back it up before re-running `npm install` and restore your values afterward. Skill files outside the shipped set are left alone — only files that exist in the package are overwritten.
+
+### Claude Code Plugin (alternative)
 
 ```
 /plugin marketplace add houseofwolvesllc/claudescrumskill
@@ -73,22 +89,14 @@ This installs all skills as a native Claude Code plugin with automatic updates.
 /plugin marketplace update
 ```
 
-### npm
-
-```bash
-# Global install — available in all projects
-npm install -g @houseofwolvesllc/claude-scrum-skill
-
-# Local install — this project only
-npm install @houseofwolvesllc/claude-scrum-skill
-```
-
-Global install copies skills to `~/.claude/skills/`. Local install copies them to `<project>/.claude/skills/` and adds `.claude-scrum-skill` to your `.gitignore`.
+> **Important difference from npm install:** Claude Code namespaces plugin-installed skills with the marketplace identifier to prevent collisions between plugins. Skills surface as `/@houseofwolvesllc/project-scaffold`, `/@houseofwolvesllc/project-orchestrate`, etc. — **not** as `/project-scaffold` and `/project-orchestrate`. If you prefer the plain names, use the npm install path above; if you prefer the marketplace UI for discovery and updates, use this path and live with the namespace.
 
 ### Manual
 
 Clone the repo and copy the `skills/` contents into `~/.claude/skills/` (global) or `<project>/.claude/skills/` (per-project). All skill directories must be siblings under the same parent, with `shared/` alongside them — skills reference `../shared/references/` via relative paths.
 
+The manual path produces the same plain-name UX as npm install (both bypass the plugin layer's namespacing), but you forfeit automatic updates.
+
 > **Note:** After installing, restart Claude Code for the skills to become available.
 
 ---
@@ -103,7 +111,12 @@ All configuration lives in `skills/shared/config.json`:
   "paths": {
     "specs": ".claude-scrum-skill/specs",
     "adr": ".claude-scrum-skill/adr",
-    "backlog": ".claude-scrum-skill/backlog"
+    "backlog": ".claude-scrum-skill/backlog",
+    "context": ".claude-scrum-skill/context"
+  },
+  "scaffold": {
+    "two_pass_threshold_words": 5000,
+    "design_spike_enabled": true
   },
   "jira": {
     "project_key": ""
@@ -123,6 +136,40 @@ All configuration lives in `skills/shared/config.json`:
 | `jira` | Jira Cloud issues, epics, and sprints | Env vars |
 | `trello` | Trello boards, lists, and cards | Env vars |
 
+### Two-Pass Mode
+
+For large PRDs, `/project-scaffold` automatically switches from single-pass to **two-pass** scaffolding. Pass 1 extracts only the epic skeleton (one agent reads the whole PRD); Pass 2 spawns one focused subagent per epic to elaborate that epic's stories. Per-epic context stays tight regardless of PRD size, so the last epic's stories are as well-specified as the first.
+
+**Triggers** (first match wins):
+
+1. PRD frontmatter `scaffold_mode: single-pass | two-pass` (explicit override)
+2. CLI flag `--mode single-pass | two-pass`
+3. PRD word count exceeds `scaffold.two_pass_threshold_words` (default `5000`)
+
+If Pass 1 finds ≤ 2 epics, scaffolding auto-downgrades to single-pass elaboration since the two-pass overhead isn't justified at that scale. Failures retry once and degrade gracefully — Pass 1 falls back to single-pass; Pass 2 marks the affected epic's stories `needs-context` and lets sibling subagents continue.
+
+The chosen mode and reasoning are announced before scaffolding begins, so you always know why a given path was taken.
+
+### Design-Spike Epic
+
+When `/project-scaffold` runs two-pass on a multi-epic PRD, it auto-injects a research-driven **design-spike epic** at the head of the project. This epic's stories (all `persona: research`) produce:
+
+- One foundational **ADR** at `<paths.adr>/NNNN-<slug>.md`
+- One per-implementation-epic **CONTEXT.md** at `<paths.context>/<epic-slug>/CONTEXT.md`
+
+Implementation epics are gated on the design-spike epic via the existing `blocked_by` mechanism, so no implementation story enters a sprint until its CONTEXT.md exists. During execution, `/project-orchestrate` subagents read `CONTEXT.md` in addition to `CLAUDE.md` before writing code — its naming, file layout, types, and patterns sections override generic CLAUDE.md conventions for that epic. This gives every parallel subagent a shared anchor, eliminating the cross-story drift that otherwise compounds before the sprint review gate.
+
+**Triggers** (first match wins):
+
+1. PRD frontmatter `design_spike: true | false`
+2. CLI flag `--design-spike | --no-design-spike`
+3. `scaffold.design_spike_enabled` config (default `true`)
+4. Auto-trigger: two-pass mode + > 1 implementation epic
+
+Artifacts are committed to the `development` branch via the filesystem in **all** backends — git is the universal substrate. Remote backends may surface links via milestone/epic descriptions but the committed files are the single source of truth.
+
+Detection signal is the `type:design-spike` label (GitHub/Trello/Jira) or `epic_type: design-spike` frontmatter field (local). The default epic title is "Architecture & Design" but the title is not load-bearing.
+
 ### Configurable Paths
 
 | Path | Default | Purpose |
@@ -130,9 +177,17 @@ All configuration lives in `skills/shared/config.json`:
 | `paths.specs` | `.claude-scrum-skill/specs` | Spec documents from `/spec` |
 | `paths.adr` | `.claude-scrum-skill/adr` | Architecture Decision Records |
 | `paths.backlog` | `.claude-scrum-skill/backlog` | Local backlog files (local mode only) |
+| `paths.context` | `.claude-scrum-skill/context` | Per-epic CONTEXT.md files produced by the design-spike epic |
 
 To check these files into version control (e.g., `docs/adr`), change the path and it won't be covered by the `.gitignore` entry for `.claude-scrum-skill`.
 
+### Scaffolding Behavior
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `scaffold.two_pass_threshold_words` | `5000` | PRD word count above which two-pass scaffolding auto-triggers |
+| `scaffold.design_spike_enabled` | `true` | Global enable switch for the design-spike pre-epic |
+
 ---
 
 ## Quick Start
@@ -141,6 +196,18 @@ To check these files into version control (e.g., `docs/adr`), change the path an
 
 1. **Write a PRD** — Create a markdown file describing your project, epics, and stories.
 
+   Optionally include YAML frontmatter to override the auto-detected scaffolding behavior:
+
+   ```yaml
+   ---
+   title: My Project
+   scaffold_mode: two-pass     # force two-pass even for a small PRD
+   design_spike: false         # suppress the design-spike epic even when triggered
+   ---
+   ```
+
+   Both fields are optional — omit them to use the word-count heuristic and the auto-injection rules described in [Two-Pass Mode](#two-pass-mode) and [Design-Spike Epic](#design-spike-epic).
+
 2. **Scaffold the project:**
    ```
    /project-scaffold path/to/prd.md
@@ -320,9 +387,9 @@ During sprint planning, personas are assigned automatically based on story label
 
 ### Phase 1 — Epic Completion Loop
 
-1. Scaffolds the PRD (if provided) or reads existing backlog
-2. Plans sprints via `/sprint-plan`
-3. Executes `executor:claude` stories in parallel via subagents with persona routing
+1. Scaffolds the PRD (if provided) or reads existing backlog. On large or multi-epic PRDs, scaffolding runs in [two-pass mode](#two-pass-mode) and auto-injects a [design-spike epic](#design-spike-epic) at position 0
+2. Plans sprints via `/sprint-plan` — the design-spike epic (when present) executes first, producing the ADR and per-epic `CONTEXT.md` files that seed the implementation epics
+3. Executes `executor:claude` stories in parallel via subagents with persona routing — implementation subagents read their epic's `CONTEXT.md` in addition to `CLAUDE.md` before writing code
 4. Releases via `/sprint-release`
 5. Runs automated review gate (using the `review` persona)
 6. Merges to `development` and cleans up branches
@@ -404,6 +471,7 @@ skills/shared/
 - **Run `/project-cleanup --fix` after major changes** to enforce build/lint cleanliness and test coverage.
 - **Chunk large epics** into multiple sprints for natural review gates.
 - **Jira/Trello users:** If no project key or board ID is configured, `/project-scaffold` creates one automatically (Scrum template for Jira).
+- **Author large PRDs with explicit architectural intent.** Sections describing shared types, naming conventions, file layout boundaries, and cross-cutting patterns give the [design-spike epic](#design-spike-epic) concrete material to lift into the project's foundational ADR and per-epic `CONTEXT.md` files — the better your PRD spells these out, the more consistent your parallel implementation subagents will be.
 
 ---
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "1.6.0",
+  "version": "1.7.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": {
+    "access": "public"
+  },
   "scripts": {
     "postinstall": "node bin/install.js"
   },

package/skills/project-orchestrate/SKILL.md

@@ -11,8 +11,8 @@ Fully autonomous project lifecycle driver. Plans sprints, executes stories via p
 
 ## Before You Start
 
-1. Read `../shared/references/CONVENTIONS.md` for all project management standards. Follow these conventions exactly.
-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` value. Read `../shared/references/PROVIDERS.md` for provider-specific API commands when using a remote provider.
+1. Read `../shared/references/CONVENTIONS.md` for all project management standards. Follow these conventions exactly. Pay particular attention to **Epic Structure → Design-Spike Epic** — orchestration honors the design-spike epic's gating, so implementation work in a scoped run does not begin until the design-spike epic completes.
+2. Read `../shared/config.json` to determine the scaffolding mode (`scaffolding` key: `"local"`, `"github"`, `"jira"`, or `"trello"`, default: `"local"`). If `"local"`, also read the `paths.backlog` and `paths.context` values (`paths.context` defaults to `.claude-scrum-skill/context` and is where Step 3 subagents look for per-epic CONTEXT.md files). Read `../shared/references/PROVIDERS.md` for provider-specific API commands when using a remote provider.
 3. Read the project's `CLAUDE.md` (if it exists) for project-specific rules. **All subagents you spawn must also read and follow `CLAUDE.md`** — include this instruction explicitly in every subagent prompt.
 4. Read `../shared/references/PERSONAS.md` for role preambles. When spawning
    subagents, select the persona matching each story's `persona:*` label (GitHub mode)
@@ -40,6 +40,24 @@ The following actions are NEVER authorized:
 
 ---
 
+## Default Operating Mode
+
+Run autonomously on invocation. Standing Authorizations cover the normal lifecycle — proceed under them without asking.
+
+**No pre-flight audits.** Don't list concerns and present a menu of options before starting. Pick the spec's literal intent and go. Surface defects in execution output as you encounter them, not as pre-execution gates. Asking "which option do you want?" before executing is itself a violation of autonomous mode.
+
+**Phase 2 (Emulation) and Phase 3 (Cleanup) always run.** Mandatory on every orchestration regardless of how small or clean the Phase 1 change set looks. For projects with no traditional toolchain (e.g., a markdown-only repo), Phase 3 reports SKIP/PASS — that is the correct outcome, not a reason to omit the phase.
+
+**State file is automatic.** `Status: running` or `paused` → resume from the recorded position. `Status: completed` → rename to `orchestration-state.previous.md` and start a fresh run. Missing → initialize a new file. Never prompt.
+
+**Scaffolding decisions fire per their own trigger logic.** Two-pass mode and design-spike epic injection live in `project-scaffold/SKILL.md` (Mode Detection, Design-Spike Epic). The orchestrator does NOT add a separate confirmation prompt on top of those triggers.
+
+**Pause only on four real safety issues:** unresolvable merge conflict (Step 5c, Error Handling → Merge Conflicts); critical review/emulation finding (Step 5b, `block`/`revert` recommendation); 3rd consecutive hardening run still dirty (Step 13 safety valve); rate-limit exhaustion (Error Handling → Rate Limiting). Nothing else.
+
+**Per-invocation overrides are honored** when the user explicitly asks for interactive mode for the current run ("pause between phases", "let me approve each sprint", etc.). The default remains autonomous.
+
+---
+
 ## Input
 
 `$ARGUMENTS` can be:
@@ -112,11 +130,12 @@ Orchestration state is persisted to `.claude-scrum-skill/orchestration-state.md`
 
 ### State Operations
 
-**On startup**, check for an existing `.claude-scrum-skill/orchestration-state.md`:
-- If found and `Status: running` → resume from the recorded position
-- If found and `Status: paused` → ask the user whether to resume or restart
-- If found and `Status: completed` → ask the user whether to start a fresh run
-- If not found → initialize a new state file
+**On startup**, check for an existing `.claude-scrum-skill/orchestration-state.md`. The autonomous default handles all four cases without prompting the user — see Default Operating Mode → State file handling for the full decision table. Briefly:
+
+- `Status: running` → resume from the recorded position.
+- `Status: paused` → resume from the recorded position (the pause cause should already be addressed; if not, the run will pause again on the same issue).
+- `Status: completed` → rename to `orchestration-state.previous.md` and start fresh.
+- No file → initialize a new state file.
 
 **During execution**, update the state file:
 - After every sprint plan, story completion, release, and phase transition
@@ -197,6 +216,14 @@ Invoke the `/sprint-plan` skill:
 
 **If PRD-scoped:** Ensure the sprint plan only pulls from the scoped stories (recorded in the state file). If `/sprint-plan` proposes stories outside the scope, exclude them — they belong to other work and should not be mixed into this orchestration run.
 
+**Blocked-by gate:** Before selecting stories for the sprint, exclude any
+story whose `blocked_by` list contains an open (not yet `done`) story. This
+naturally gates implementation epics on the design-spike epic when one
+exists: implementation stories list the design-spike CONTEXT.md story as a
+blocker, so they cannot enter a sprint until that story completes. The
+existing dependency mechanism in `/sprint-plan` already honors this; this
+note is an explicit affirmation, not a new requirement.
+
 Since this is autonomous mode, accept the default sprint plan without waiting for user confirmation — the skill's proposed sprint based on priority ordering and velocity target is the plan.
 
 After planning completes, update the state file with the sprint stories and their dependency map.
@@ -231,6 +258,14 @@ You are executing story #<number> for repo <owner/repo>.
 follow all instructions in it. CLAUDE.md is authoritative for stack,
 patterns, and style — it overrides any general guidance in this preamble.
 
+**IMPORTANT:** Before writing any code, if `<paths.context>/<epic-slug>/CONTEXT.md`
+exists, read it in full. Treat its Naming Conventions, File Layout, Shared
+Types & Interfaces, Patterns to Follow, and Patterns to Avoid sections as
+binding for this epic — they override generic conventions in CLAUDE.md when
+in conflict, and you should follow them even when CLAUDE.md is silent. The
+`<paths.context>` and `<epic-slug>` values are substituted from the resolved
+config and the story's epic at spawn time.
+
 **Story:** <title>
 **Acceptance criteria:** <from issue body or story file>
 **Branch strategy:** Create branch `story/<number>-<slug>` from
@@ -477,6 +512,8 @@ Transitioning to Phase 2 — Emulation Hardening.
 
 Validate the **entire codebase** through emulation, fix discovered issues, and repeat until clean. This phase always covers the full project regardless of whether Phase 1 was PRD-scoped — new code must integrate cleanly with the existing codebase.
 
+**Phase 2 is mandatory.** Do not skip it under any circumstance, even when Phase 1 produced a small or clean change set. The emulation pass is the quality gate that catches integration drift, layer contract mismatches, and cross-story inconsistency that per-story review cannot. Skipping it defeats the orchestration's quality model. See Default Operating Mode.
+
 ### Step 8: Run Emulation
 
 Invoke the project emulation skill:
@@ -588,6 +625,8 @@ Options:
 
 After emulation hardening is clean (or accepted), run a final mechanical hygiene pass to ensure the codebase builds, lints, and tests cleanly.
 
+**Phase 3 is mandatory.** Like Phase 2, it always runs at the tail of every orchestration even when the codebase appears clean. For projects with no traditional toolchain (e.g., a markdown skill suite), `project-cleanup` reports SKIP for the non-applicable phases — that is the correct outcome, not a reason to omit the phase. See Default Operating Mode.
+
 ### Step 14: Run Project Cleanup
 
 Invoke the cleanup skill in fix mode:
@@ -671,15 +710,20 @@ Read the ADR output path from `../shared/config.json` (key: `paths.adr`,
 default: `.claude-scrum-skill/adr`).
 
 1. Read all existing ADRs in the configured ADR directory to understand what's
-   already documented and the numbering/format convention in use.
+   already documented and the numbering/format convention in use. Compute
+   the next sequential ADR number as `max(existing_numbers) + 1`. This
+   shared numbering pool applies regardless of whether prior ADRs were
+   created by a design-spike epic in this run, by a previous orchestration
+   run, or hand-authored — they all share one sequence.
 2. Review the epics completed, hardening fixes applied, and any significant
    technical choices made during orchestration (e.g., new libraries adopted,
    patterns introduced, infrastructure changes, security model decisions).
 3. For each decision that is **non-obvious, hard to reverse, or would
    surprise a future contributor**, create a new ADR following the existing
    format and numbering sequence.
-4. Skip decisions that are already covered by an existing ADR or that are
-   trivial/self-evident from the code.
+4. Skip decisions that are already covered by an existing ADR (including
+   any ADR produced by a design-spike epic earlier in this run) or that
+   are trivial/self-evident from the code.
 
 Print a summary:
 

package/skills/project-scaffold/SKILL.md

@@ -10,7 +10,10 @@ Scaffold a complete GitHub Project from one or more PRD or spec documents, or ad
 ## Before You Start
 
 1. Read `../shared/references/CONVENTIONS.md` for all project management standards including label taxonomy, branch strategy, issue templates, custom fields, and executor assignment guidelines. Follow these conventions exactly.
-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` value (default: `.claude-scrum-skill/backlog`).
+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` value (default: `.claude-scrum-skill/backlog`). Also read these scaffolding-control keys (fall back to defaults silently if missing):
+   - `scaffold.two_pass_threshold_words` (default `5000`) — PRD word count above which two-pass mode auto-triggers. See Mode Detection.
+   - `scaffold.design_spike_enabled` (default `true`) — global enable switch for the design-spike pre-epic. See Design-Spike Epic.
+   - `paths.context` (default `.claude-scrum-skill/context`) — where per-epic CONTEXT.md files written by the design-spike epic live.
 3. Read `../shared/references/PROVIDERS.md` for provider-specific API commands when operating in remote mode (GitHub, Jira, or Trello).
 4. **Terminology:** Always refer to milestones as **"epics"** in all user-facing text, summaries, and conversational output. The word "milestone" should only appear in API commands and code — never in communication with the user.
 5. **If `scaffolding: "github"`:** Confirm the `gh` CLI is authenticated by running `gh auth status`. Identify the target repository. If the user doesn't specify, ask which repo to use.
@@ -24,6 +27,333 @@ The user provides `$ARGUMENTS` which should be one or more file paths to PRD or
 
 Read all provided documents thoroughly before proceeding.
 
+### PRD Frontmatter Overrides
+
+PRD authors can preempt the auto-detected scaffolding behavior via YAML
+frontmatter at the top of the PRD document:
+
+```yaml
+---
+title: My Project
+scaffold_mode: two-pass     # force two-pass even for a small PRD
+design_spike: false         # suppress the design-spike epic even when triggered
+---
+```
+
+Allowed values:
+
+- `scaffold_mode`: `single-pass` | `two-pass` (omit to use the word-count
+  heuristic in Mode Detection)
+- `design_spike`: `true` | `false` (omit to use the auto-injection rules
+  in Design-Spike Epic)
+
+### CLI Flags
+
+Equivalent flags can be passed alongside the PRD path:
+
+- `--mode single-pass` / `--mode two-pass` — overrides any frontmatter or
+  word-count heuristic for the scaffolding mode.
+- `--design-spike` / `--no-design-spike` — overrides any frontmatter or
+  auto-injection rule for the design-spike epic.
+
+There is no formal CLI argument parser — Claude Code skills receive a
+single free-text `$ARGUMENTS` string. The executing agent scans
+`$ARGUMENTS` for these flag strings (exact match) and treats each
+recognized flag as a trigger source at the precedence noted below.
+Invalid or empty flag values (e.g., `--mode` with no value, or
+`--mode three-pass`) are ignored, and the next trigger source in
+precedence applies.
+
+Trigger precedence (highest first): CLI flag → PRD frontmatter → config /
+heuristic. Whatever wins is announced before scaffolding begins so the
+user understands why a given path was taken.
+
+## Mode Detection
+
+Before invoking any per-backend procedure, decide whether to run scaffolding
+in **single-pass** mode (the original behavior — one agent reads the whole
+PRD and produces all epics + stories) or **two-pass** mode (skeleton
+extraction followed by per-epic elaboration subagents). Two-pass mode keeps
+per-epic context tight on large PRDs, so the last epic's stories are as
+well-specified as the first.
+
+### Trigger Evaluation (in order, first match wins)
+
+1. **CLI flag:**
+   - `--mode single-pass` → force single-pass
+   - `--mode two-pass` → force two-pass
+2. **PRD frontmatter override:**
+   - `scaffold_mode: single-pass` → force single-pass
+   - `scaffold_mode: two-pass` → force two-pass
+3. **Word count heuristic:**
+   - Count words in the PRD body (whitespace-delimited; exclude frontmatter).
+   - Read `scaffold.two_pass_threshold_words` from `../shared/config.json`
+     (default `5000`; if the key is missing, use the default silently).
+   - If word count exceeds the threshold → two-pass.
+   - Otherwise → single-pass.
+
+### Announce the Decision
+
+Before proceeding to any procedure, announce the mode and the trigger
+reason so the user understands why the heuristic chose what it chose:
+
+```
+PRD analysis:
+  Word count: 8,420 (threshold: 5000) → triggering two-pass mode
+
+Pass 1: extracting epic skeleton...
+```
+
+If an override forced the decision, mention that explicitly:
+
+```
+PRD analysis:
+  Frontmatter override: scaffold_mode: single-pass → forcing single-pass
+```
+
+### Routing
+
+- **Single-pass** → continue to the per-backend procedure (Local / Jira /
+  Trello / GitHub) and run its existing Parse the PRD step against the
+  whole PRD.
+- **Two-pass** → run the Two-Pass Procedure (below) first, then continue
+  to the per-backend procedure with the assembled story list.
+
+## Two-Pass Procedure
+
+When Mode Detection selects two-pass, run this procedure before the
+per-backend creation steps. The output is the same shape as a single-pass
+parse would produce: an assembled list of epics + their stories, ready for
+the backend to create issues/files. Backends consume the same shape, so the
+per-backend creation logic does not change.
+
+### Pass 1 — Skeleton Extraction
+
+A single agent reads the whole PRD and produces a structured manifest. The
+manifest is held in orchestrator context — it is NOT persisted to disk.
+
+**Manifest shape (YAML):**
+
+```yaml
+project:
+  name: <string>
+  description: <string>
+  global_preamble: |
+    <multi-line markdown excerpt — project overview, glossary,
+    cross-cutting non-functional requirements that every epic should know>
+  non_functional_requirements: [<string>]
+epics:
+  - name: <string>
+    slug: <kebab-case string>
+    description: <one-paragraph string>
+    slice:
+      start_line: <int>
+      end_line: <int>
+    depends_on: [<epic-slug>]
+    shared_design_concerns:
+      - <string describing naming/layout/type/pattern this epic introduces
+        that other epics may consume>
+```
+
+Pass 1 produces NO story-level detail. Its job is structural — identify
+epic boundaries, capture inter-epic dependencies, and extract the shared
+global context that every Pass 2 subagent will need. The
+`shared_design_concerns` list feeds the Design-Spike Epic procedure when
+that is triggered.
+
+### Auto-Downgrade
+
+After Pass 1 completes, evaluate the epic count:
+
+- **≤ 2 epics** → downgrade to single-pass elaboration: spawn one Pass 2
+  subagent that handles all epics together. The two-pass overhead is not
+  justified at this scale, and inter-epic coordination is easier in a
+  single context. Announce the downgrade.
+- **> 2 epics** → proceed to per-epic Pass 2 spawning.
+
+### Pass 2 — Per-Epic Elaboration
+
+Spawn one subagent per epic. Each subagent receives a focused context:
+
+- The **global preamble** from Pass 1 (project overview, glossary, NFRs)
+- Its **assigned epic's PRD slice**, extracted using `slice.start_line`
+  and `slice.end_line` from the manifest
+- A **skeleton summary** of sibling epics (name, slug, one-paragraph
+  description, dependencies) — for cross-epic dependency awareness, NOT
+  for elaboration
+
+Each Pass 2 subagent produces the complete story list for its epic:
+
+- Story titles
+- Acceptance criteria
+- Technical context
+- Story points (per CONVENTIONS.md guidelines)
+- Executor assignment (per CONVENTIONS.md guidelines)
+- Persona designation (local mode: the `persona` frontmatter field; GitHub/Jira/Trello modes: a `persona:*` label — see CONVENTIONS.md "Persona Labels" and PERSONAS.md for the canonical set)
+- Dependency declarations (`blocked_by`, `blocks`)
+- All other required frontmatter fields
+
+**Concurrency cap:** Up to 3 Pass 2 subagents in parallel (matches
+`/project-orchestrate` Step 3 convention). Additional epics queue and
+start as earlier ones complete.
+
+### Story Assembly
+
+After all Pass 2 subagents return, assemble their outputs into a single
+backlog before handing off to the per-backend creation logic:
+
+1. **Collect** every story from every Pass 2 output, preserving each
+   story's epic association.
+2. **Detect slug collisions** by exact string match across all stories.
+   If two or more stories share a slug, rename all-but-the-first by
+   prepending the epic slug: `<epic-slug>-<original-slug>`. Log every
+   rename so the user sees the resolution.
+3. **Resolve cross-epic dependencies** declared in story `blocked_by`
+   and `blocks` fields. If a dependency references a slug that was
+   renamed in step 2, update the reference.
+4. **Emit the assembled list** in the same shape a single-pass parse
+   would have produced. The per-backend creation logic consumes this
+   shape unchanged.
+
+### Failure Handling
+
+Scaffolding must degrade gracefully — it must never abort on a Pass 1 or
+Pass 2 failure.
+
+**Pass 1 failure:**
+
+1. Retry once with identical input.
+2. If the second attempt fails, log the failure and fall back to
+   single-pass scaffolding: run the per-backend procedure's Parse the PRD
+   step against the whole PRD as if two-pass had never been triggered.
+3. Announce the fallback clearly:
+
+   ```
+   Pass 1 failed twice; falling back to single-pass scaffolding for this PRD.
+   ```
+
+**Pass 2 subagent failure:**
+
+1. Retry the failed subagent once with the original prompt plus the failure
+   context appended.
+2. If the second attempt fails, do NOT abort the whole scaffold:
+   - Write the affected epic's epic-level metadata (`_epic.md` in local
+     mode, milestone in remote modes) using the Pass 1 skeleton data.
+   - Generate placeholder stories for the affected epic with
+     `status: needs-context` and a note explaining the Pass 2 failure.
+     Use the existing `needs-context` status signal label from
+     CONVENTIONS.md.
+   - Sibling Pass 2 subagents continue unaffected.
+3. Surface every retry attempt and final outcome (success / fallback /
+   needs-context) in the skill's user-facing output so the user knows what
+   landed cleanly versus what needs hand-completion.
+
+## Design-Spike Epic
+
+A **design-spike epic** is a research-driven pre-epic that produces written
+design artifacts (an ADR + per-implementation-epic CONTEXT.md files) before
+any implementation work begins. It auto-injects at position 0 of the
+scaffold when triggered, giving every subsequent implementation subagent a
+shared anchor for naming, file layout, types, and patterns. See
+CONVENTIONS.md → Epic Structure → Design-Spike Epic for the broader rationale.
+
+### Trigger Evaluation (in order, first match wins)
+
+1. **CLI flag:**
+   - `--no-design-spike` → suppress.
+   - `--design-spike` → force.
+2. **PRD frontmatter override:**
+   - `design_spike: false` → suppress the design-spike epic.
+   - `design_spike: true` → force it.
+3. **Global enable switch:**
+   - Read `scaffold.design_spike_enabled` from `../shared/config.json`
+     (default `true`; missing key falls back to default silently).
+   - If `false` globally, skip the design-spike regardless of remaining
+     signals (the CLI flag and frontmatter overrides above already won
+     before reaching this rule if either was set).
+4. **Auto-trigger:**
+   - Two-pass mode was selected AND Pass 1 produced more than one
+     implementation epic → auto-inject.
+
+If none of the above fire, skip the design-spike epic.
+
+### Idempotency Check
+
+Before injecting, check whether a design-spike epic already exists in the
+target project. Detection is by canonical signal (label/field), not by
+title — the title is configurable but the signal is fixed.
+
+- **Local mode:** Scan `<paths.backlog>/*/[_]epic.md` frontmatter for
+  `epic_type: design-spike`.
+- **GitHub mode:** Query open milestones whose issues carry the
+  `type:design-spike` label.
+- **Jira mode:** Query Epic-type issues labeled `type:design-spike`.
+- **Trello mode:** Query lists whose cards carry the `type:design-spike`
+  label.
+
+If an existing design-spike epic is found, skip injection and reuse it
+for `blocked_by` references on the new implementation stories.
+
+### Skeleton Augmentation
+
+When the design-spike epic is to be injected, modify the skeleton produced
+by Pass 1 (or, in single-pass mode, the parsed epic list) before per-epic
+elaboration runs:
+
+1. **Prepend a new epic at position 0** with:
+   - Default title: `Architecture & Design` (overridable; not load-bearing).
+   - Detection signal: label `type:design-spike` (remote backends) and
+     `epic_type: design-spike` in `_epic.md` frontmatter (local mode).
+   - Description sourced from the project description + the union of all
+     implementation epics' `shared_design_concerns` (from the Pass 1
+     manifest).
+2. **Generate the design-spike stories** to be elaborated by a Pass 2
+   subagent with `persona: research`:
+   - One **ADR-authoring story** producing the project's foundational ADR
+     at `<paths.adr>/NNNN-<slug>.md`. The ADR number is the next available
+     in the existing ADR sequence (see `/project-orchestrate` Step 16 for
+     the shared numbering pool).
+   - One **CONTEXT.md-authoring story per implementation epic**, each
+     producing `<paths.context>/<epic-slug>/CONTEXT.md` from the template
+     at `shared/templates/CONTEXT-template.md`. The story body lists the
+     `shared_design_concerns` for that epic so the research subagent has
+     concrete inputs.
+3. **Wire `blocked_by` references** on every implementation story:
+   - Each implementation story gets `blocked_by` references to the
+     design-spike story that produces its epic's CONTEXT.md.
+   - Sprint planning then naturally excludes implementation stories until
+     their CONTEXT.md exists — no additional gate logic required.
+
+### Artifact Storage
+
+ADR and CONTEXT.md files are committed to the `development` branch via
+the filesystem in ALL four backends. Git is the universal substrate; this
+keeps the artifact location uniform regardless of which backend the
+backlog lives in.
+
+- ADR location: `<paths.adr>/NNNN-<slug>.md`
+- CONTEXT.md location: `<paths.context>/<epic-slug>/CONTEXT.md`
+
+Remote backends (GitHub, Jira, Trello) MAY additionally surface links to
+these files via milestone/epic descriptions for discoverability — but the
+committed files are the single source of truth. If the description link
+becomes stale (e.g., file renamed), the filesystem path wins.
+
+### Auto-Injection of References
+
+When the design-spike epic is part of the scaffold, every implementation
+story's Technical Context section receives an appended line referencing
+the artifacts that will be produced:
+
+```
+See [<paths.context>/<epic-slug>/CONTEXT.md] and [<paths.adr>/NNNN-<slug>.md] for shared architectural decisions.
+```
+
+The paths use the resolved `paths.context` and `paths.adr` config values
+(not hardcoded strings) and the ADR number assigned during skeleton
+augmentation. Auto-injection happens during Story Assembly, after Pass 2
+produces stories but before per-backend creation runs.
+
 ## Scaffold Procedure
 
 Read `../shared/config.json` to determine mode. If `scaffolding` is `"local"`,
@@ -39,8 +369,13 @@ instead of GitHub issues, milestones, and project boards.
 
 ### Local Step 1: Parse the PRD
 
-Same as GitHub Step 1 — extract project name, epics, stories, dependencies,
-and technical context. Present the summary and ask the user to confirm.
+**If two-pass mode was selected** (see Mode Detection), the Two-Pass
+Procedure has already produced the assembled epic + story list. Skip this
+step's parsing work and proceed to Step 2 with the assembled list as input.
+
+**If single-pass mode was selected**, do this step as before: extract
+project name, epics, stories, dependencies, and technical context. Present
+the summary and ask the user to confirm.
 
 ### Local Step 2: Detect Existing Backlog
 
@@ -187,7 +522,10 @@ and sprints. Refer to `../shared/references/PROVIDERS.md` for all API calls.
 
 ### Jira Step 1: Parse the PRD
 
-Same as Local Step 1 / GitHub Step 1.
+Same routing as Local Step 1: if two-pass mode was selected, the Two-Pass
+Procedure has already produced the assembled list — proceed to Step 2 with
+that list. If single-pass mode, parse the PRD inline as in Local Step 1 /
+GitHub Step 1.
 
 ### Jira Step 2: Ensure Project Exists
 
@@ -290,7 +628,10 @@ all API calls.
 
 ### Trello Step 1: Parse the PRD
 
-Same as Local Step 1 / GitHub Step 1.
+Same routing as Local Step 1: if two-pass mode was selected, the Two-Pass
+Procedure has already produced the assembled list — proceed to Step 2 with
+that list. If single-pass mode, parse the PRD inline as in Local Step 1 /
+GitHub Step 1.
 
 ### Trello Step 2: Ensure Board Exists
 
@@ -418,7 +759,12 @@ Ask the user to choose and, if option 2 or 3, which epic(s) to target.
 
 ### Step 1: Parse the PRD
 
-Extract the following from the PRD document(s):
+**If two-pass mode was selected** (see Mode Detection), the Two-Pass
+Procedure has already produced the assembled epic + story list. Skip the
+inline parsing below and proceed to Step 2 with that list as input.
+
+**If single-pass mode was selected**, extract the following from the PRD
+document(s):
 
 - **Project name** — used for the GitHub Project title (if creating new)
 - **Epics** — major bodies of work; each becomes a milestone (unless mapped to an existing one)

package/skills/shared/config.json

@@ -3,7 +3,12 @@
   "paths": {
     "specs": ".claude-scrum-skill/specs",
     "adr": ".claude-scrum-skill/adr",
-    "backlog": ".claude-scrum-skill/backlog"
+    "backlog": ".claude-scrum-skill/backlog",
+    "context": ".claude-scrum-skill/context"
+  },
+  "scaffold": {
+    "two_pass_threshold_words": 5000,
+    "design_spike_enabled": true
   },
   "jira": {
     "project_key": ""

package/skills/shared/references/CONVENTIONS.md

@@ -58,6 +58,7 @@ Create these views on every project board:
 - `type:spike` — Research/exploration task with defined timebox
 - `type:infra` — Infrastructure, CI/CD, tooling, DevOps
 - `type:chore` — Maintenance, cleanup, refactoring, documentation
+- `type:design-spike` — Research-driven epic that produces design artifacts (ADR + per-implementation-epic CONTEXT.md files) consumed by implementation epics. Auto-injected by `/project-scaffold` for large/multi-epic PRDs; see Epic Structure → Design-Spike Epic.
 
 ### Priority Labels
 
@@ -197,6 +198,49 @@ Both are set at issue creation time. The label is what scrum teams see day-to-da
 
 **Backward compatibility:** Existing milestones named `Phase N: <Name>` are treated as epics without renaming. If an existing project has no `epic:*` labels, the skills create them when adding new stories.
 
+### Design-Spike Epic
+
+A **design-spike epic** is a research-driven pre-epic that produces written design artifacts before any implementation work begins. It auto-injects at the head of the project when triggered, giving every subsequent implementation subagent a shared anchor for naming, file layout, types, and patterns.
+
+**When it auto-injects:**
+
+- Two-pass scaffolding was triggered AND the resulting skeleton has more than one implementation epic, OR
+- PRD frontmatter contains `design_spike: true`, OR
+- User explicitly passes `--design-spike` to `/project-scaffold`.
+
+`design_spike: false` in PRD frontmatter suppresses the epic even when other triggers fire. The global enable switch is `scaffold.design_spike_enabled` in `config.json` (default `true`).
+
+**What it contains:**
+
+- One ADR-authoring story (`persona: research`, `executor: claude`) producing the project's foundational ADR at `<paths.adr>/NNNN-<slug>.md`.
+- One CONTEXT.md-authoring story per implementation epic (`persona: research`, `executor: claude`) producing `<paths.context>/<epic-slug>/CONTEXT.md` from the shared template at `skills/shared/templates/CONTEXT-template.md`.
+
+**How it gates implementation:**
+
+Every implementation story receives a `blocked_by` reference to the design-spike story that produces its epic's CONTEXT.md. Sprint planning then naturally excludes implementation stories until the design-spike epic completes — no special gate logic required, the existing dependency mechanism handles it.
+
+**Where artifacts live:**
+
+ADR and CONTEXT.md files are committed to the `development` branch via the filesystem in ALL four backends (local, GitHub, Jira, Trello). Git is the universal substrate; remote backends additionally surface links via milestone/epic descriptions but the committed files are the single source of truth.
+
+**Detection signal:**
+
+The canonical signal that an epic is a design-spike is the `type:design-spike` label (GitHub/Trello) or `epic_type: design-spike` frontmatter field (local). The default epic title is "Architecture & Design" but the title is not load-bearing — detection always uses the label/field, never the title.
+
+## Frontmatter Fields (Local Mode)
+
+In local-mode backlogs (`scaffolding: "local"`), epic and story files use YAML frontmatter for metadata. Beyond the per-file fields documented in their respective templates, these fields apply to the epic-level `_epic.md`:
+
+| Field | Type | Allowed Values | Purpose |
+|-------|------|----------------|---------|
+| `title` | string | any | Display name of the epic |
+| `slug` | string | kebab-case | Directory name and ID |
+| `status` | string | `open`, `closed` | Epic completion state |
+| `created` | string | ISO timestamp | Creation time |
+| `epic_type` | string | `design-spike` (omit for implementation epics) | Marks the epic as the design-spike pre-epic for detection by orchestration |
+
+Absence of `epic_type` means a standard implementation epic — this preserves backward compatibility with existing `_epic.md` files.
+
 ## Sprint Cadence
 
 - Default sprint length: **2 weeks** (configurable per project)

package/skills/shared/templates/ADR-template.md

@@ -0,0 +1,36 @@
+# ADR-NNNN: <Short Title of the Decision>
+
+- **Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNNN
+- **Date:** YYYY-MM-DD
+- **Deciders:** <names or roles>
+
+## Context
+
+<What is the issue motivating this decision? What forces are at play? What constraints apply?>
+
+## Decision
+
+<What did we decide to do, in active voice and present tense.>
+
+## Consequences
+
+### Positive
+- <Good thing that follows from this decision>
+
+### Negative
+- <Trade-off or cost being accepted>
+
+### Neutral
+- <Side-effect that is neither clearly good nor bad>
+
+## Alternatives Considered
+
+### <Alternative 1>
+<What it was and why it was rejected>
+
+### <Alternative 2>
+<What it was and why it was rejected>
+
+## References
+
+- <Links to related ADRs, specs, issues, docs>

package/skills/shared/templates/CONTEXT-template.md

@@ -0,0 +1,96 @@
+# <Epic Name> — Shared Context
+
+> Authored once per implementation epic by a `persona: research` subagent during the design-spike epic. Every implementation subagent for this epic reads this file in full before writing code. Sections below are required — keep them present even if briefly populated.
+
+## Overview
+
+<1–2 sentence summary of what this epic builds and how its stories fit together.>
+
+Example: "Implements the authentication subsystem. Each story adds one piece — credential storage, session issuance, middleware, refresh flow — and they compose into a single auth pipeline consumed by every protected route."
+
+## Naming Conventions
+
+<Domain terms, prefixes, suffixes, casing rules specific to this epic. These override generic conventions in CLAUDE.md when in conflict.>
+
+Example:
+- All endpoint handler functions prefix with `handle_` (e.g., `handle_login`, `handle_refresh`)
+- Event names use past tense (`UserCreated`, `SessionExpired` — never `CreateUser`, `ExpireSession`)
+- Database column names use `snake_case`; corresponding TypeScript fields use `camelCase`
+- Repository methods that return one row use singular nouns (`findUser`); those that return many use plural (`findUsers`)
+
+## File Layout
+
+<Where new files for this epic's stories live. Include full paths.>
+
+Example:
+- Repository implementations: `src/data/<entity>/postgres_<entity>_repository.ts`
+- API controllers: `src/api/<entity>/<entity>_controller.ts`
+- Domain types: `src/core/<entity>/types.ts`
+- Tests colocated with source: `<file>.test.ts` next to `<file>.ts`
+- Migrations: `migrations/NNNN_<description>.sql` (numbered sequentially)
+
+## Shared Types & Interfaces
+
+<Code blocks with type/interface/struct definitions stories must IMPORT rather than redefine. If two stories need the same type, define it here and reference the location.>
+
+Example:
+
+```typescript
+// src/core/auth/types.ts
+export type SessionId = string & { readonly __brand: "SessionId" };
+
+export interface Credentials {
+  email: string;
+  password: string;
+}
+
+export interface Session {
+  id: SessionId;
+  userId: UserId;
+  expiresAt: Date;
+}
+```
+
+Stories MUST import these from the canonical location, not re-declare structurally identical types.
+
+## Patterns to Follow
+
+<Code-level patterns with concrete examples. Cover error handling, logging, pagination, validation, transaction boundaries, etc. Each pattern should include a one-line "why" so reviewers can judge edge cases.>
+
+Example:
+
+**Error handling at controller boundaries:**
+
+```typescript
+try {
+  const result = await service.doThing(input);
+  return ok(result);
+} catch (e) {
+  if (e instanceof DomainError) return badRequest(e.message);
+  logger.error("unexpected", { e });
+  return internalServerError();
+}
+```
+
+Why: Domain errors are caller-visible; unknown errors must not leak internals.
+
+**Pagination:** Cursor-based, never offset. Use `{ cursor, limit }` query params; return `{ items, nextCursor }`. Why: stable ordering across concurrent writes.
+
+## Patterns to Avoid
+
+<Anti-patterns specific to this epic with rationale. These are NOT a generic "best practices" list — they are concrete things that have caused problems or that violate the epic's design.>
+
+Example:
+
+- **Don't share a database client between modules.** Each repository constructs its own. Why: makes mocking and per-test isolation trivial.
+- **Don't catch generic `Error` in middleware.** Catch specific subtypes only. Why: a broad catch swallows programmer errors that should crash loudly in dev.
+- **Don't add new auth-related env vars without updating `src/config/env_schema.ts`.** Why: the schema is the validation layer — env vars not in it are silently undefined.
+
+## External References
+
+<Links to upstream docs, related ADRs, CLAUDE.md sections this epic depends on.>
+
+- ADR: `<paths.adr>/NNNN-<slug>.md`
+- CLAUDE.md sections: `Architecture`, `Code Quality`, `Testing`
+- Upstream docs: `<url to library/framework docs if any>`
+- Related epics: `<epic-slug>` (consumes the types defined here)