@houseofwolvesllc/claude-scrum-skill 1.5.1 → 1.7.0

package/README.md

@@ -1,57 +1,73 @@
 # Claude Scrum Skill
 
-An open-source npm package of Claude Code skills that give you a complete scrum pipeline — from PRD to production release — with Claude as your scrum master. Includes project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup. One PR per sprint, or let Claude drive the entire lifecycle hands-free.
+An open-source npm package of Claude Code skills that give you a complete scrum pipeline — from PRD to production release — with Claude as your scrum master. Works with **local file-based backlogs**, **GitHub Projects**, **Jira**, or **Trello**.
+
+Includes project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup.
 
 ```
 Manual mode — you invoke each skill:
 
-PRD → /project-scaffold → GitHub Project with sprints, stories, branches
-                              ↓
-                        /sprint-plan → populate the next sprint
-                              ↓
-                     Claude works stories → auto-merge to release branch
-                              ↓
-                       /sprint-status → check progress anytime
-                              ↓
-                      /sprint-release → wrap up sprint, open release PR
-                              ↓
-                     You review one PR → merge to development
-                              ↓
-                        /sprint-plan → next cycle
+PRD  -->  /project-scaffold  -->  backlog (local, GitHub, Jira, or Trello)
+                                      |
+                                /sprint-plan --> populate the next sprint
+                                      |
+                               Claude works stories --> commits to release branch
+                                      |
+                                /sprint-status --> check progress anytime
+                                      |
+                               /sprint-release --> wrap up sprint, merge to development
+                                      |
+                                 You review   --> merge to main when ready
+                                      |
+                                /sprint-plan  --> next cycle
 
 Autonomous mode — one command drives the full lifecycle:
 
-PRD (optional) → /project-orchestrate (scaffolds PRD if given, else uses existing board)
-                              ↓
-              ┌──────── Epic Completion Loop ────────┐
-              │  /sprint-plan → execute stories      │
-              │  → /sprint-release → merge to dev    │
-              │  → branch cleanup → next sprint      │
-              │  (repeat until all epics done)        │
-              └──────────────┬───────────────────────┘
-                              ↓
-              ┌──── Emulation Hardening Loop ────────┐
-              │  /project-emulate → parse findings   │
-              │  → generate PRD → /project-scaffold  │
-              │  → fix sprints → re-emulate          │
-              │  (repeat until clean)                 │
-              └──────────────┬───────────────────────┘
-                              ↓
-                     Production-ready codebase
+PRD (optional)  -->  /project-orchestrate
+                           |
+            +----- Epic Completion Loop ------+
+            |  /sprint-plan --> execute stories |
+            |  --> /sprint-release --> merge    |
+            |  --> branch cleanup --> repeat    |
+            +----------------+-----------------+
+                             |
+            +--- Emulation Hardening Loop ----+
+            |  /project-emulate --> findings   |
+            |  --> generate PRD --> scaffold   |
+            |  --> fix sprints --> re-emulate  |
+            +----------------+-----------------+
+                             |
+                    Production-ready codebase
 ```
 
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick Start](#quick-start)
+- [Provider Setup](#provider-setup)
+- [Skills Reference](#skills-reference)
+- [Branch Strategy](#branch-strategy)
+- [Personas](#personas)
+- [Autonomous Orchestration](#autonomous-orchestration)
+- [Customization](#customization)
+- [Tips](#tips)
+- [License](#license)
+
+---
+
 ## Installation
 
 ### Claude Code Plugin (recommended)
 
-Add the marketplace and install the plugin directly from GitHub:
-
 ```
 /plugin marketplace add houseofwolvesllc/claudescrumskill
 /plugin install claude-scrum-skill@houseofwolvesllc
 ```
 
-This installs all seven skills as a native Claude Code plugin with automatic updates. To update later:
+This installs all skills as a native Claude Code plugin with automatic updates. To update later:
 
 ```
 /plugin marketplace update
@@ -60,311 +76,396 @@ This installs all seven skills as a native Claude Code plugin with automatic upd
 ### npm
 
 ```bash
-# Global — installs to ~/.claude/skills/ (all projects)
+# Global install — available in all projects
 npm install -g @houseofwolvesllc/claude-scrum-skill
 
-# Local — installs to <project>/.claude/skills/ (this project only)
+# Local install — this project only
 npm install @houseofwolvesllc/claude-scrum-skill
 ```
 
-Global install copies skills to `~/.claude/skills/` so they're available everywhere. Local install copies them to your project's `.claude/skills/` directory — useful for dev containers and CI where the home directory is ephemeral.
+Global install copies skills to `~/.claude/skills/`. Local install copies them to `<project>/.claude/skills/` and adds `.claude-scrum-skill` to your `.gitignore`.
 
 ### Manual
 
-Clone the repo and copy the `skills/` contents into `~/.claude/skills/` (global) or `your-repo/.claude/skills/` (per-project). All skill directories must be siblings — `sprint-plan`, `sprint-status`, and `sprint-release` reference `../project-scaffold/references/CONVENTIONS.md` via relative path.
+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.
+
+> **Note:** After installing, restart Claude Code for the skills to become available.
+
+---
+
+## Configuration
+
+All configuration lives in `skills/shared/config.json`:
+
+```json
+{
+  "scaffolding": "local",
+  "paths": {
+    "specs": ".claude-scrum-skill/specs",
+    "adr": ".claude-scrum-skill/adr",
+    "backlog": ".claude-scrum-skill/backlog",
+    "context": ".claude-scrum-skill/context"
+  },
+  "scaffold": {
+    "two_pass_threshold_words": 5000,
+    "design_spike_enabled": true
+  },
+  "jira": {
+    "project_key": ""
+  },
+  "trello": {
+    "board_id": ""
+  }
+}
+```
 
-**Note:** After installing, restart Claude Code for the skills to become available.
+### Scaffolding Modes
 
-## Quick Start
+| Mode | Description | Auth Required |
+|------|-------------|---------------|
+| `local` | File-based backlog in your project directory (default) | None |
+| `github` | GitHub Issues, Milestones, and Projects | `gh` CLI |
+| `jira` | Jira Cloud issues, epics, and sprints | Env vars |
+| `trello` | Trello boards, lists, and cards | Env vars |
 
-### 1. Create a Fine-Grained GitHub Personal Access Token
+### Two-Pass Mode
 
-These skills use `gh` for all GitHub operations. You need a fine-grained PAT scoped to the repos you want to manage.
+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.
 
-**Step 1:** Go to [github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens) and click **Generate new token**.
+**Triggers** (first match wins):
 
-**Step 2:** Fill in the token details:
-- **Token name** — Something descriptive like `claude-code-pm`
-- **Expiration** — Set a reasonable window (90 days is a good default)
-- **Resource owner** — Your account (or your org if the repos live there)
-- **Repository access** — Select **Only select repositories**, then pick the repos these skills will manage
+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`)
 
-**Step 3:** Under **Permissions → Repository permissions**, grant:
+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.
 
-| Permission | Access | Why |
-|---|---|---|
-| Contents | Read & Write | Create branches, push commits |
-| Issues | Read & Write | Create and update stories on the project board |
-| Metadata | Read | Required by GitHub for all fine-grained PATs |
-| Pull requests | Read & Write | Open PRs for story branches and releases |
+The chosen mode and reasoning are announced before scaffolding begins, so you always know why a given path was taken.
 
-**Step 4:** Under **Permissions → Account permissions**, grant:
+### Design-Spike Epic
 
-| Permission | Access | Why |
-|---|---|---|
-| Projects | Read & Write | Create project boards, custom fields, and views |
+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:
 
-**Step 5:** Click **Generate token** and copy it immediately — you won't see it again.
+- One foundational **ADR** at `<paths.adr>/NNNN-<slug>.md`
+- One per-implementation-epic **CONTEXT.md** at `<paths.context>/<epic-slug>/CONTEXT.md`
 
-**Step 6:** Authenticate the GitHub CLI with your new token:
+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.
 
-```bash
-echo "YOUR_TOKEN" | gh auth login --with-token
-```
+**Triggers** (first match wins):
 
-Verify it worked:
+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
 
-```bash
-gh auth status
-```
+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.
 
-**Security tip:** Do not grant write access to your `main` branch via the token. Set up branch protection rules so merges to `main` always require your manual review. This is the gate that keeps you in control.
+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.
 
-### 2. Write a PRD
+### Configurable Paths
 
-Create a markdown file with your project requirements. The more structured, the better the scaffold. At minimum, include:
-- Project name and description
-- Epics or major bodies of work with clear boundaries
-- User stories or features per epic
-- Acceptance criteria for each story
+| Path | Default | Purpose |
+|------|---------|---------|
+| `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 |
 
-### 3. Scaffold the Project
+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`.
 
-Open Claude Code in your repo and run:
+### Scaffolding Behavior
 
-```
-/project-scaffold path/to/your-prd.md
-```
+| 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 |
 
-This creates:
-- A GitHub Project board with custom fields (Status, Sprint, Priority, Executor, Story Points)
-- Board views: Current Sprint, Claude Queue, My Tasks, Backlog, Epic Overview
-- Issues for every story, labeled with type, priority, executor, and `epic:<slug>`
-- Epics tracked two ways: `epic:*` labels for visibility + milestones for progress tracking
-- Release branches for each epic
-- Branch protection on main
+---
 
-Already have an existing project? The skill detects it and offers to add stories to existing epics or create new ones — no need to scaffold from scratch every time.
+## Quick Start
 
-### 4. Plan a Sprint
+### Local Mode (default — no setup required)
 
-```
-/sprint-plan owner/repo
-```
+1. **Write a PRD** — Create a markdown file describing your project, epics, and stories.
 
-The skill pulls stories from the backlog, assigns them to the next sprint iteration, and sets up the release branch. It respects your velocity target (default: 20 story points) and prioritizes by the Priority field.
+   Optionally include YAML frontmatter to override the auto-detected scaffolding behavior:
 
-### 5. Assign an Executor
+   ```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
+   ---
+   ```
 
-Three executor labels control who works each story:
+   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).
 
-| Label | Who | When |
-|---|---|---|
-| `executor:claude` | Claude Code | Clear implementation path, no human judgment needed |
-| `executor:human` | You | Business decisions, credentials, external approvals |
-| `executor:cowork` | Cowork agent | Research, drafting, web-based tasks |
+2. **Scaffold the project:**
+   ```
+   /project-scaffold path/to/prd.md
+   ```
+   This creates a local backlog with epic directories and story files in `.claude-scrum-skill/backlog/`.
 
-### 6. Hand Off to Claude Code
+3. **Plan a sprint:**
+   ```
+   /sprint-plan
+   ```
 
-In Claude Code, tell it to work the sprint:
+4. **Work stories** — Tell Claude to pick up `executor:claude` stories from the sprint.
 
-> "Pick up the current sprint. Work through all stories labeled executor:claude in priority order. For each story, create a feature branch off the release branch, implement, open a PR back to the release branch, and move the issue to Done."
+5. **Check progress:**
+   ```
+   /sprint-status
+   ```
 
-Claude works autonomously — branching, committing, opening PRs with auto-merge to the release branch.
+6. **Release the sprint:**
+   ```
+   /sprint-release
+   ```
 
-### 7. Check Progress
+7. **Or go fully autonomous:**
+   ```
+   /project-orchestrate path/to/prd.md
+   ```
 
-```
-/sprint-status owner/repo
-```
+### Remote Mode (GitHub, Jira, or Trello)
 
-Get a progress report: stories completed vs. remaining, burndown, blockers, and what Claude is working on.
+1. Set `"scaffolding"` in `config.json` to `"github"`, `"jira"`, or `"trello"`.
+2. Complete the [provider setup](#provider-setup) for your chosen provider.
+3. Follow the same workflow above — the skills automatically use the configured provider's API.
 
-### 8. Release the Sprint
+---
 
-```
-/sprint-release owner/repo
-```
+## Provider Setup
 
-This closes the sprint, opens a release PR from the release branch into `development`, and summarizes everything that shipped. You review one PR, merge it, and the sprint is done. When you're ready for production, promote `development` into `main`.
+### GitHub
 
-### 9. Emulate the Project
+Create a fine-grained Personal Access Token:
 
-```
-/project-emulate
-```
+1. Go to [github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens) and generate a new token.
 
-Claude reads the entire codebase and runs a multi-phase validation:
+2. Grant these **repository permissions**:
 
-1. **Discovery** — finds every role, action, and permission boundary
-2. **Integration seam validation** — checks that Docker, build tools, transpilers, IoC containers, config files, and service contracts are mutually consistent
-3. **Layer contract validation** — traces data through response helpers, middleware chains, IoC resolution, config stores, and error handlers to verify every layer agrees on data shapes
-4. **Cross-service payload validation** — verifies that request/response bodies, query parameters, headers, shared types, pagination contracts, and error shapes match across service boundaries
-5. **Full lifecycle walkthrough** — emulates each role executing each action from deployment through teardown
-6. **Coverage report** — permission matrix, categorized issues, and missing coverage
+   | Permission | Access | Why |
+   |---|---|---|
+   | Contents | Read & Write | Create branches, push commits |
+   | Issues | Read & Write | Create and update stories |
+   | Metadata | Read | Required by GitHub for all PATs |
+   | Pull requests | Read & Write | Open PRs for releases |
 
-### 10. Orchestrate (Optional — Full Autonomy)
+3. Grant this **account permission**:
 
-```
-# Scaffold a PRD and orchestrate only its epics/stories
-/project-orchestrate path/to/prd.md
+   | Permission | Access | Why |
+   |---|---|---|
+   | Projects | Read & Write | Create project boards and fields |
 
-# Orchestrate all open epics/stories on an existing project
-/project-orchestrate owner/repo
+4. Authenticate the CLI:
+   ```bash
+   echo "YOUR_TOKEN" | gh auth login --with-token
+   gh auth status
+   ```
 
-# Both — scaffold PRD into a specific repo, then orchestrate
-/project-orchestrate path/to/prd.md owner/repo
-```
+> **Security tip:** Do not grant write access to `main`. Set up branch protection so merges to `main` always require your review.
 
-Instead of manually invoking each skill at every step, let Claude drive the entire lifecycle autonomously. Pass a PRD to scaffold and execute just that work, or pass a repo to execute everything on the board. The orchestrator loops through sprint planning, story execution (parallel subagents for `executor:claude` stories), sprint release, merge to development, and branch cleanup — repeating until all in-scope epics are complete. Then it runs emulation hardening loops against the **entire codebase** (not just the new work): emulate, generate a findings PRD, scaffold a hardening epic, fix everything, and re-emulate until the codebase is clean.
+### Jira
 
-Human/cowork stories are skipped (they roll over). Merges to `development` happen automatically. Merges to `main` still require your review. State is persisted to `.claude/orchestration-state.md` so progress survives session restarts.
+1. Generate an API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
 
-### 11. Clean Up the Codebase
+2. Set environment variables:
+   ```bash
+   export JIRA_SITE="https://yourcompany.atlassian.net"
+   export JIRA_EMAIL="you@example.com"
+   export JIRA_API_TOKEN="your-api-token"
+   ```
 
-```
-# Report issues without fixing
-/project-cleanup
+3. Optionally set the project key in `config.json`:
+   ```json
+   {
+     "scaffolding": "jira",
+     "jira": {
+       "project_key": "MYPROJ"
+     }
+   }
+   ```
 
-# Scope to a specific directory
-/project-cleanup src/
+4. If `project_key` is empty, `/project-scaffold` creates a new Scrum project automatically and saves the key back to config.json. If set, it uses the existing project.
 
-# Auto-fix everything
-/project-cleanup --fix
+### Trello
 
-# Report only, no fixes even if --fix is present
-/project-cleanup --report-only
-```
+1. Get your API key from [trello.com/power-ups/admin](https://trello.com/power-ups/admin).
 
-Verify codebase hygiene across five dimensions: zero build errors/warnings, zero lint errors/warnings, project principles compliance (driven by your `CLAUDE.md`), no dead or duplicated code, and all tests passing with at least 50% coverage. The skill detects your toolchain (TypeScript, Go, Rust, Python, etc.) automatically.
+2. Generate a token by visiting:
+   ```
+   https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=YOUR_API_KEY
+   ```
 
-In `--fix` mode, it resolves issues in dependency order — dead code removal first, then build errors, lint violations, architecture fixes, and finally test fixes and coverage improvement. All changes are documented in a `FIXES.md` report. Without `--fix`, it produces a full report to `.claude/reports/cleanup-report/` without modifying code.
+3. Set environment variables:
+   ```bash
+   export TRELLO_API_KEY="your-api-key"
+   export TRELLO_TOKEN="your-token"
+   ```
 
-Reads your project's `CLAUDE.md` for overrides — project rules always win over default best practices.
+4. Optionally set the board ID in `config.json`:
+   ```json
+   {
+     "scaffolding": "trello",
+     "trello": {
+       "board_id": "your-board-id"
+     }
+   }
+   ```
+   Find your board ID by opening the board in Trello, adding `.json` to the URL, and looking for the `"id"` field.
 
-### 12. Repeat (Manual Mode)
+5. If `board_id` is empty, `/project-scaffold` creates a new board automatically and saves the ID back to config.json. If set, it uses the existing board.
 
-```
-/sprint-plan owner/repo
-```
+> **Note:** Trello has no native sprint, dependency, or story point support. Sprints are modeled as lists, points are stored in custom fields (or card title prefixes), and dependencies are tracked in card descriptions.
+
+---
+
+## Skills Reference
+
+| Skill | Command | What It Does |
+|---|---|---|
+| **project-scaffold** | `/project-scaffold <prd-path>` | Full project setup from PRD |
+| **spec** | `/spec <prompt>` | Transform a rough idea into a structured spec document |
+| **sprint-plan** | `/sprint-plan [owner/repo]` | Plan and populate the next sprint |
+| **sprint-status** | `/sprint-status [owner/repo]` | Progress report and burndown |
+| **sprint-release** | `/sprint-release [owner/repo]` | Close sprint, merge to development |
+| **project-emulate** | `/project-emulate` | Integration seams, layer contracts, cross-service payloads, full lifecycle walkthrough |
+| **project-orchestrate** | `/project-orchestrate [prd] [repo]` | Autonomous lifecycle driver |
+| **project-cleanup** | `/project-cleanup [path] [--fix]` | Build, lint, dead code, and test coverage |
+
+The `[owner/repo]` argument is only needed in GitHub mode. Jira, Trello, and local modes read from config.
 
-If you prefer manual control, start the next sprint. The cycle continues until the project is complete.
+---
 
-## How It Works
+## Branch Strategy
 
-### Branch Strategy
+All modes share the same git branch strategy:
 
 ```
 main (human-only — requires your review)
- └── development (sprint approval gate)
-      └── release/core-api
-           ├── story/1-init-project → auto-merge ✓
-           ├── story/2-database-schema → auto-merge ✓
-           └── story/3-auth-endpoints → auto-merge ✓
+ +-- development (sprint approval gate)
+      +-- release/core-api
+           +-- story/1-init-project     --> auto-merge
+           +-- story/2-database-schema  --> auto-merge
+           +-- story/3-auth-endpoints   --> auto-merge
 ```
 
-Story branches auto-merge into the release branch when CI passes. At sprint end, the release branch merges into `development` after your review. When you're ready to ship, `development` merges into `main`. Two approval gates: one per sprint, one for production.
+- **Story --> Release branch:** Auto-merge when CI passes (or direct merge in local mode)
+- **Release --> development:** PR review in GitHub mode, direct merge in local/Jira/Trello mode
+- **development --> main:** Always human-initiated
 
-### GitHub Project Board
+---
 
-The scaffold creates a GitHub Project (the newer Projects experience, not classic project boards) with these custom fields:
+## Personas
 
-| Field | Type | Purpose |
+Stories can be assigned a **persona** that controls the posture of the subagent executing them during orchestration. Personas are defined in `skills/shared/references/PERSONAS.md`.
+
+| Persona | Assigned via | Behavior |
 |---|---|---|
-| Status | Single select | Workflow state: Backlog → Ready → In Progress → In Review → Done |
-| Sprint | Iteration (2-week) | Time-boxed sprint assignment |
-| Priority | Single select | P0-Critical through P3-Low |
-| Executor | Single select | Who works this: `claude`, `human`, or `cowork` |
-| Story Points | Number | Fibonacci estimation (1, 2, 3, 5, 8, 13) |
+| `impl` (default) | No label needed | Standard implementation — write code, tests, open PR |
+| `ops` | `persona:ops` label or frontmatter | Ops/infra posture — idempotency, rollback, least privilege |
+| `research` | `persona:research` label or frontmatter | Research posture — output is a document (ADR/RFC), not code |
+| `review` | Automatic (release gate) | Reviews the release diff, reports findings by severity |
 
-Epics are tracked two ways: `epic:*` labels give scrum teams the vocabulary they expect right on every issue, while native GitHub Milestones power the progress tracking (open/closed counts, % complete) behind the scenes. Both are set at issue creation time. You can filter by either on any project view.
+During sprint planning, personas are assigned automatically based on story labels (e.g., `scope:infra` gets `persona:ops`). Override by manually setting the label or frontmatter before orchestration.
 
-**Board views** use GitHub's view system:
+---
 
-- **Current Sprint** — Board layout, filtered to the active sprint, columns by Status
-- **Claude Queue** — Table layout, filtered to `Executor = claude` and `Status = Ready`, sorted by Priority
-- **My Tasks** — Table layout, filtered to `Executor = human`, grouped by Sprint
-- **Backlog** — Table layout, filtered to `Status = Backlog`, sorted by Priority
-- **Epic Overview** — Table layout, grouped by Milestone, with field sums on Story Points
+## Autonomous Orchestration
 
-You can also use **Slice by** on any field to quickly filter the current view from a side panel — useful for slicing a sprint view by Executor or Priority.
+`/project-orchestrate` chains all skills into a fully autonomous pipeline.
 
-### Shared Conventions
+### Phase 1 — Epic Completion Loop
 
-All skills reference a single `CONVENTIONS.md` file that defines labels, branch naming, custom fields, executor guidelines, and story point standards. Edit it once and every skill inherits the changes.
+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
+7. Repeats until all epics are complete
 
-Located at: `project-scaffold/references/CONVENTIONS.md`
+### Phase 2 — Emulation Hardening Loop
 
-## Skills Reference
+1. Runs `/project-emulate` to discover issues
+2. Generates a hardening PRD from critical/warning findings
+3. Scaffolds and executes a hardening epic
+4. Re-emulates until clean (safety valve at 3 runs)
 
-| Skill | Command | What It Does |
-|---|---|---|
-| `project-scaffold` | `/project-scaffold <prd-path>` | Full project setup from PRD, or add stories to an existing project |
-| `sprint-plan` | `/sprint-plan [owner/repo]` | Plan and populate the next sprint |
-| `sprint-status` | `/sprint-status [owner/repo]` | Progress report and burndown |
-| `sprint-release` | `/sprint-release [owner/repo]` | Close sprint, open release PR to development |
-| `project-emulate` | `/project-emulate` | Integration seams, layer contracts, cross-service payloads, and full lifecycle walkthrough |
-| `project-orchestrate` | `/project-orchestrate [prd-path] [owner/repo]` | Autonomous lifecycle driver — sprint loop + emulation hardening until done |
-| `project-cleanup` | `/project-cleanup [path] [--fix] [--report-only]` | Build, lint, project principles, dead code, and test coverage verification/enforcement |
+### Phase 3 — Project Cleanup
+
+1. Runs `/project-cleanup --fix` across the entire codebase
+2. Reviews and updates ADRs based on decisions made during orchestration
+3. Cleans up the orchestration state file
+
+### State Persistence
+
+Orchestration state is saved to `.claude-scrum-skill/orchestration-state.md`. If Claude hits a usage cap or the session restarts, it picks up exactly where it left off.
+
+### Safety Boundaries
+
+- Merges to `development` are pre-authorized
+- Merges to `main` are **never** automatic
+- Failed stories are retried once, then marked blocked
+- Merge conflicts pause orchestration and escalate to you
+- After 3 hardening runs, Claude pauses and asks for guidance
+- Review gate can be skipped with `ORCHESTRATE_SKIP_REVIEW=1`
+
+---
 
 ## Customization
 
 ### Sprint Length
-Edit `CONVENTIONS.md` → "Sprint Cadence" section. Default is 2 weeks.
+Edit `shared/references/CONVENTIONS.md` > "Sprint Cadence". Default: 2 weeks.
 
 ### Velocity Target
-The `sprint-plan` skill asks for velocity or defaults to 20 story points. Adjust as you calibrate.
+`/sprint-plan` asks for velocity or defaults to 20 story points.
 
 ### Label Colors
-All label hex colors are defined in the `project-scaffold` skill. Modify to match your preferences.
+Defined in `project-scaffold/SKILL.md`. Modify to match your preferences.
 
 ### Executor Criteria
-Edit `CONVENTIONS.md` → "Executor Assignment Guidelines" to tune what gets assigned to Claude vs. you vs. Cowork.
+Edit `shared/references/CONVENTIONS.md` > "Executor Assignment Guidelines".
 
-### Adding Epics
-Epics map to your PRD structure. To add new epics later, run `/project-scaffold` with the new PRD — it detects the existing project and lets you add stories to existing epics or create new ones.
+### Personas
+Edit `shared/references/PERSONAS.md` to add or modify persona preambles.
 
-## Autonomous Orchestration
+### Output Paths
+Edit `shared/config.json` to change where specs, ADRs, and backlog files are written. Point them to a non-dotfile path (e.g., `docs/adr`) to include them in version control.
 
-The `/project-orchestrate` skill is a meta-orchestrator that chains all other skills into a fully autonomous pipeline. After scaffolding your project, run it once and Claude handles everything else.
-
-### What It Does
-
-**Phase 1 — Epic Completion Loop:**
-1. Detects open epics and presents an overview
-2. Plans sprints via `/sprint-plan`
-3. Executes `executor:claude` stories in parallel via subagents (skips human/cowork — they roll over)
-4. Releases via `/sprint-release`
-5. Merges the release PR to `development` (pre-authorized, no confirmation needed)
-6. Cleans up merged branches
-7. Repeats until all epics are complete
+### Adding Epics
+Run `/project-scaffold` with a new PRD — it detects the existing project and offers to add stories to existing epics or create new ones.
 
-**Phase 2 — Emulation Hardening Loop:**
-1. Runs `/project-emulate` to discover issues
-2. Generates a hardening PRD from critical/warning findings
-3. Scaffolds a "Hardening (Run N)" epic via `/project-scaffold`
-4. Executes the hardening sprint (same loop as Phase 1)
-5. Re-emulates — if new issues found, repeats; if clean, done
+---
 
-### State Persistence
+## Shared References
 
-Orchestration state is saved to `.claude/orchestration-state.md` (human-readable markdown). If Claude hits a usage cap or the session restarts, it picks up exactly where it left off. The state file tracks the current phase, epic, sprint, story status, and a running log.
+All skills reference shared configuration and standards from `skills/shared/`:
 
-### Safety Boundaries
+```
+skills/shared/
+  +-- config.json                 # mode, paths, provider settings
+  +-- references/
+       +-- CONVENTIONS.md         # labels, branches, fields, estimation
+       +-- PERSONAS.md            # subagent role preambles
+       +-- PROVIDERS.md           # GitHub/Jira/Trello API reference
+```
 
-- Merges to `development` are pre-authorized (standing auth)
-- Merges to `main` are **never** automatic — always requires your review
-- Failed stories are retried once, then marked blocked — they don't halt the pipeline
-- Merge conflicts pause orchestration and escalate to you
-- After 3 hardening runs without a clean emulation, Claude pauses and asks for guidance
+---
 
 ## Tips
 
-- **Chunk large epics** into multiple sprints for natural review gates. If an epic has 30 stories, split it into 2-3 sprints rather than one massive batch.
-- **Start small.** Scaffold a real but small project first to calibrate your conventions before relying on it for bigger work.
-- **Branch protection is your safety net.** The PAT should not have write access to main. Merges to main always go through your review.
-- **Run `/project-emulate` before releases** to catch integration seam failures, layer contract mismatches, cross-service payload drift, permission gaps, and dead code before shipping.
-- **Run `/project-cleanup --fix` after major changes** to enforce build/lint cleanliness, remove dead code, and ensure test coverage stays above 50%.
+- **Start with local mode.** No setup required — scaffold a PRD and start working immediately.
+- **Branch protection is your safety net.** The PAT should not have write access to `main`.
+- **Run `/project-emulate` before releases** to catch integration seam failures, layer contract mismatches, and permission gaps.
+- **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.
+
+---
 
 ## License