@houseofwolvesllc/claude-scrum-skill 1.2.4 → 1.4.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -1,8 +1,10 @@
 # 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, and full-project emulation testing. One PR per sprint. You stay in the executive seat.
+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, and autonomous orchestration. One PR per sprint, or let Claude drive the entire lifecycle hands-free.
 
 ```
+Manual mode — you invoke each skill:
+
 PRD → /project-scaffold → GitHub Project with sprints, stories, branches
                               ↓
                         /sprint-plan → populate the next sprint
@@ -16,6 +18,26 @@ PRD → /project-scaffold → GitHub Project with sprints, stories, branches
                      You review one PR → merge to development
                               ↓
                         /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
 ```
 
 ## Installation
@@ -29,7 +51,7 @@ Add the marketplace and install the plugin directly from GitHub:
 /plugin install claude-scrum-skill@houseofwolvesllc
 ```
 
-This installs all five skills as a native Claude Code plugin with automatic updates. To update later:
+This installs all six skills as a native Claude Code plugin with automatic updates. To update later:
 
 ```
 /plugin marketplace update
@@ -38,10 +60,14 @@ This installs all five skills as a native Claude Code plugin with automatic upda
 ### npm
 
 ```bash
+# Global — installs to ~/.claude/skills/ (all projects)
 npm install -g @houseofwolvesllc/claude-scrum-skill
+
+# Local — installs to <project>/.claude/skills/ (this project only)
+npm install @houseofwolvesllc/claude-scrum-skill
 ```
 
-This copies all skills into `~/.claude/skills/`. All five skills are installed as siblings so relative paths to shared conventions resolve correctly.
+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.
 
 ### Manual
 
@@ -177,13 +203,30 @@ Claude reads the entire codebase and runs a multi-phase validation:
 5. **Full lifecycle walkthrough** — emulates each role executing each action from deployment through teardown
 6. **Coverage report** — permission matrix, categorized issues, and missing coverage
 
-### 10. Repeat
+### 10. Orchestrate (Optional — Full Autonomy)
+
+```
+# Scaffold a PRD and orchestrate only its epics/stories
+/project-orchestrate path/to/prd.md
+
+# Orchestrate all open epics/stories on an existing project
+/project-orchestrate owner/repo
+
+# Both — scaffold PRD into a specific repo, then orchestrate
+/project-orchestrate path/to/prd.md owner/repo
+```
+
+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.
+
+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.
+
+### 11. Repeat (Manual Mode)
 
 ```
 /sprint-plan owner/repo
 ```
 
-Start the next sprint. The cycle continues until the project is complete.
+If you prefer manual control, start the next sprint. The cycle continues until the project is complete.
 
 ## How It Works
 
@@ -239,6 +282,7 @@ Located at: `project-scaffold/references/CONVENTIONS.md`
 | `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 |
 
 ## Customization
 
@@ -257,6 +301,40 @@ Edit `CONVENTIONS.md` → "Executor Assignment Guidelines" to tune what gets ass
 ### 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.
 
+## Autonomous Orchestration
+
+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
+
+**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
+
+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.
+
+### Safety Boundaries
+
+- 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.

package/bin/install.js

@@ -4,15 +4,35 @@ const fs = require('fs');
 const path = require('path');
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
-const SKILLS_DIR = path.join(HOME, '.claude', 'skills');
 const SOURCE_DIR = path.join(__dirname, '..', 'skills');
+const IS_GLOBAL = process.env.npm_config_global === 'true';
+
+// Global install → ~/.claude/skills/
+// Local install  → <project>/.claude/skills/
+let skillsDir;
+if (IS_GLOBAL) {
+  skillsDir = path.join(HOME, '.claude', 'skills');
+} else {
+  // Walk up from node_modules to find the project root
+  let projectRoot = path.resolve(__dirname, '..');
+  while (projectRoot !== path.dirname(projectRoot)) {
+    if (path.basename(projectRoot) === 'node_modules') {
+      projectRoot = path.dirname(projectRoot);
+      break;
+    }
+    projectRoot = path.dirname(projectRoot);
+  }
+  skillsDir = path.join(projectRoot, '.claude', 'skills');
+}
 
 const skills = [
   'project-scaffold',
   'sprint-plan',
   'sprint-status',
   'sprint-release',
-  'project-emulate'
+  'project-emulate',
+  'project-orchestrate',
+  'project-cleanup'
 ];
 
 function copyRecursive(src, dest) {
@@ -28,15 +48,15 @@ function copyRecursive(src, dest) {
   }
 }
 
-console.log('\n📋 Installing claude-scrum-skill...\n');
+const location = IS_GLOBAL ? 'global (~/.claude/skills/)' : `project (${skillsDir})`;
+console.log(`\n📋 Installing claude-scrum-skill (${location})...\n`);
 
-// Ensure ~/.claude/skills exists
-fs.mkdirSync(SKILLS_DIR, { recursive: true });
+fs.mkdirSync(skillsDir, { recursive: true });
 
 let installed = 0;
 for (const skill of skills) {
   const src = path.join(SOURCE_DIR, skill);
-  const dest = path.join(SKILLS_DIR, skill);
+  const dest = path.join(skillsDir, skill);
 
   if (fs.existsSync(src)) {
     copyRecursive(src, dest);
@@ -47,6 +67,6 @@ for (const skill of skills) {
   }
 }
 
-console.log(`\n✨ Installed ${installed} skills to ${SKILLS_DIR}`);
-console.log('   Skills are available in Claude Code immediately.\n');
+console.log(`\n✨ Installed ${installed} skills to ${skillsDir}`);
+console.log('   Restart Claude Code for the skills to become available.\n');
 console.log('   Run /project-scaffold <prd-path> to get started.\n');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "1.2.4",
-  "description": "Claude Code skills for scrum project management — PRD to production release pipeline with project scaffolding, sprint planning, status tracking, sprint releases, and full-project emulation testing.",
+  "version": "1.4.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": {},
   "scripts": {
     "postinstall": "node bin/install.js"

package/skills/project-cleanup/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: project-cleanup
+description: Systematically verify and enforce codebase hygiene — zero build errors, zero lint warnings, HATEOAS compliance, no dead or duplicated code, all tests passing with at least 50% coverage. Reads the project's CLAUDE.md for overrides and treats best practices as defaults that yield to project-specific rules.
+---
+
+# Project Cleanup
+
+Ensure the codebase is production-clean: builds without errors or warnings, passes lint with zero issues, adheres to HATEOAS and project conventions, contains no dead or duplicated code, and has comprehensive test coverage.
+
+---
+
+## Before You Start
+
+1. Read the project's `CLAUDE.md` (if it exists) for project-specific rules. **CLAUDE.md overrides are authoritative** — if a project rule conflicts with a best practice listed here, the project rule wins. Record any overrides you find so you can reference them when making decisions.
+2. Read `../project-scaffold/references/CONVENTIONS.md` for project management standards (if applicable).
+3. **Terminology:** Always refer to milestones as **"epics"** in all user-facing text, summaries, and conversational output. The word "milestone" should only appear in GitHub API commands and code — never in communication with the user.
+4. Identify the project's language(s), framework(s), build system, linter, test runner, and coverage tool by reading `package.json`, `tsconfig.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, or equivalent config files.
+5. Confirm all required tooling is installed and runnable (`npm`, `npx`, `tsc`, `eslint`, `jest`/`vitest`/`pytest`/`go test`, etc.).
+
+---
+
+## Input
+
+`$ARGUMENTS` can be:
+
+1. **Nothing** — clean up the entire project in the current working directory.
+2. **A path** (e.g., `src/` or `packages/api/`) — scope cleanup to a specific directory or package.
+3. **A flag** `--fix` — automatically fix all issues found. Without this flag, the skill reports issues but does not modify code.
+4. **A flag** `--report-only` — produce the report without any fixes, even if `--fix` is also present.
+
+Flags can be combined: `/project-cleanup src/ --fix`
+
+---
+
+## Phase 1: Build Verification
+
+Verify the project compiles and builds with zero errors and zero warnings.
+
+### Step 1: Identify Build Commands
+
+Detect the build toolchain from project config files:
+
+- **Node.js/TypeScript:** `tsc --noEmit` for type checking, `npm run build` or equivalent for full build
+- **Go:** `go build ./...`
+- **Rust:** `cargo build 2>&1`
+- **Python:** `python -m py_compile` or `mypy` for type checking
+- **Multi-package (monorepo):** Run build for each workspace/package
+
+If the project has a `build` script in `package.json`, use it. Otherwise infer from the toolchain.
+
+### Step 2: Run Build
+
+Execute the build command and capture all output. Parse output into:
+
+- **Errors** — compilation failures, type errors, missing imports
+- **Warnings** — unused variables, implicit any, deprecation notices
+
+**Target: zero errors, zero warnings.**
+
+### Step 3: Catalog Build Issues
+
+For each issue found, record:
+
+| File | Line | Severity | Code | Message |
+|------|------|----------|------|---------|
+| `src/api/handler.ts` | 42 | error | TS2345 | Argument of type 'string' is not assignable... |
+
+If `--fix` is active, fix each issue in order of severity (errors first, then warnings). After fixing, re-run the build to confirm the fix didn't introduce new issues.
+
+---
+
+## Phase 2: Lint Verification
+
+Verify the project passes lint with zero errors and zero warnings.
+
+### Step 1: Identify Lint Configuration
+
+Detect the linter(s) from project config:
+
+- **ESLint:** `.eslintrc.*`, `eslint.config.*`, `eslint` field in `package.json`
+- **Prettier:** `.prettierrc.*`, `prettier` field in `package.json`
+- **Biome:** `biome.json`
+- **golangci-lint:** `.golangci.yml`
+- **Ruff/flake8:** `pyproject.toml [tool.ruff]`, `.flake8`
+- **clippy:** `cargo clippy`
+
+### Step 2: Run Linter
+
+Execute the linter with all warnings enabled:
+
+```bash
+# Example for ESLint
+npx eslint . --max-warnings 0 --format json
+```
+
+Use `--max-warnings 0` (or equivalent) to treat warnings as failures.
+
+### Step 3: Catalog Lint Issues
+
+For each issue found, record:
+
+| File | Line | Rule | Severity | Message | Fixable |
+|------|------|------|----------|---------|---------|
+| `src/utils.ts` | 15 | `no-unused-vars` | warning | 'helper' is defined but never used | no |
+
+### Step 4: Apply Fixes (if `--fix` active)
+
+1. Run the linter's auto-fix first: `npx eslint . --fix`
+2. Re-run the linter to identify remaining issues that need manual fixes
+3. Fix remaining issues manually, following these rules:
+   - **Unused imports/variables:** Remove them
+   - **Formatting issues:** Apply the project's formatter (Prettier, Biome, etc.)
+   - **Rule violations:** Fix the code to comply with the rule; do NOT add `eslint-disable` comments unless `CLAUDE.md` explicitly allows it
+   - **Deprecation warnings:** Update to the recommended replacement
+4. Re-run the linter to confirm zero remaining issues
+
+---
+
+## Phase 3: HATEOAS and Project Principles Compliance
+
+Verify the codebase adheres to HATEOAS (Hypermedia as the Engine of Application State) principles and any project-specific architectural standards.
+
+**Important:** Only apply HATEOAS checks to projects that expose REST APIs. Skip this phase entirely for CLI tools, libraries, static sites, or other non-API projects.
+
+### Step 1: Identify API Layer
+
+Scan for API route definitions, controllers, and response construction:
+
+- Express/Fastify/Koa route handlers
+- NestJS/Spring/Django/Rails controllers
+- Serverless function handlers (Lambda, Cloud Functions)
+- GraphQL resolvers (HATEOAS doesn't apply to GraphQL — skip these)
+
+### Step 2: HATEOAS Link Audit
+
+For each API endpoint that returns resource representations, verify:
+
+**Self links** — Every resource response MUST include a `self` link:
+```json
+{
+  "id": "123",
+  "name": "Example",
+  "_links": {
+    "self": { "href": "/resources/123" }
+  }
+}
+```
+
+**Relational links** — Resources with relationships SHOULD include navigational links:
+- Parent resource link (e.g., `collection` → `/resources`)
+- Related resource links (e.g., `author` → `/users/456`)
+- Action links where applicable (e.g., `approve` → `/resources/123/approve`)
+
+**Collection links** — Collection endpoints SHOULD include:
+- `self` link with current query parameters
+- Pagination links (`next`, `prev`, `first`, `last`) when paginated
+- Item links or embedded items with their own `self` links
+
+**Consistency checks:**
+- All link `href` values MUST correspond to actual routes that exist in the codebase
+- Link relations MUST be consistent across all endpoints (don't use `_links` in some responses and `links` in others)
+- Media type SHOULD be consistent (if using HAL, use HAL everywhere; if using JSON:API, use JSON:API everywhere)
+
+### Step 3: Project-Specific Principles
+
+Read `CLAUDE.md` and any architecture documentation (ADRs, `docs/architecture.md`, etc.) for project-specific principles. Common things to check:
+
+- **Layered architecture compliance** — are controllers calling repositories directly instead of going through services?
+- **Dependency direction** — do inner layers depend on outer layers?
+- **Naming conventions** — do file names, function names, and variable names follow the project's conventions?
+- **Error handling patterns** — does the project use a specific error handling strategy consistently?
+- **Response envelope** — does the project wrap responses in a specific envelope format?
+
+### Step 4: Catalog HATEOAS/Architecture Issues
+
+For each violation found, record:
+
+| File | Line | Category | Issue | Recommendation |
+|------|------|----------|-------|----------------|
+| `src/controllers/users.ts` | 78 | HATEOAS | Response missing `_links.self` | Add self link to user response |
+| `src/routes/orders.ts` | 45 | Architecture | Controller directly queries DB | Route through OrderService |
+
+If `--fix` is active:
+- Add missing `_links` to response objects
+- Add missing pagination links to collection responses
+- Refactor architectural violations (move logic to correct layer)
+- Verify fixes don't break existing tests
+
+---
+
+## Phase 4: Dead and Duplicated Code Detection
+
+Find and remove code that is unused, unreachable, or unnecessarily duplicated.
+
+### Step 1: Dead Code Detection
+
+**Unused exports** — Identify exports that are never imported anywhere:
+```bash
+# Use the project's tooling if available (e.g., ts-prune, knip, unimported)
+# Otherwise, for each exported symbol, grep for its import across the codebase
+```
+
+Tools to check for (use if present in devDependencies):
+- `knip` — comprehensive unused file/export/dependency detector
+- `ts-prune` — TypeScript-specific unused export finder
+- `unimported` — unused file detector
+- `depcheck` — unused dependency detector
+
+If no specialized tool is available, perform manual analysis:
+
+1. **Unused files** — files that are never imported or referenced
+2. **Unused exports** — exported functions, classes, types, or constants that are never imported
+3. **Unused dependencies** — packages in `dependencies`/`devDependencies` that are never imported
+4. **Dead branches** — code paths that can never execute (e.g., `if (false)`, unreachable code after `return`)
+5. **Commented-out code** — blocks of commented code (not documentation comments)
+6. **Vestigial patterns** — unused interfaces/types kept "for backwards compatibility" with no consumers, re-exports that point to nothing, empty files, placeholder implementations
+
+**Exclusions — do NOT flag as dead code:**
+- Entry points referenced in `package.json` (`main`, `bin`, `exports`)
+- Files referenced in build config (`webpack.config`, `vite.config`, etc.)
+- Test files and test utilities
+- Type declaration files (`.d.ts`) that are part of the public API
+- Anything that `CLAUDE.md` explicitly says to keep
+
+### Step 2: Duplicated Code Detection
+
+Identify substantially duplicated code blocks:
+
+1. **Exact duplicates** — identical code blocks (3+ lines) appearing in multiple locations
+2. **Near duplicates** — code blocks that differ only in variable names, literal values, or minor structural variations
+3. **Pattern duplication** — repeated patterns that should be abstracted (e.g., the same error handling try/catch block copied across 5 handlers)
+
+**Judgment calls (follow CLAUDE.md if it has guidance):**
+- Two similar 3-line blocks are fine — don't create a premature abstraction
+- The same 10+ line pattern in 4+ places should be extracted
+- If extracting would require complex parameterization, the duplication may be preferable — note it but don't force an abstraction
+
+### Step 3: Catalog Dead/Duplicated Code
+
+| File | Line(s) | Category | Description |
+|------|---------|----------|-------------|
+| `src/old-handler.ts` | 1-120 | Dead file | Never imported anywhere |
+| `src/utils.ts` | 45-67 | Dead export | `formatDate` exported but never imported |
+| `src/controllers/` | various | Duplication | Error handling block repeated in 6 controllers |
+
+If `--fix` is active:
+- **Dead code:** Remove it. Delete unused files, remove unused exports, remove unused dependencies from `package.json`.
+- **Duplicated code:** Extract shared logic into utility functions or base classes. Follow the project's existing abstraction patterns.
+- After each batch of removals, re-run the build and linter to confirm nothing broke.
+
+---
+
+## Phase 5: Test Verification and Coverage
+
+Verify all tests pass and coverage meets the 50% minimum threshold.
+
+### Step 1: Identify Test Framework
+
+Detect from project config:
+
+- **Jest:** `jest.config.*`, `jest` field in `package.json`
+- **Vitest:** `vitest.config.*`, `vite.config.*` with test config
+- **Mocha/Chai:** `.mocharc.*`, `mocha` field in `package.json`
+- **pytest:** `pyproject.toml [tool.pytest]`, `pytest.ini`, `conftest.py`
+- **Go:** Built-in `go test`
+- **Rust:** Built-in `cargo test`
+
+### Step 2: Run Tests
+
+Execute the full test suite:
+
+```bash
+# Example for Jest/Vitest
+npx jest --ci --coverage --coverageReporters=json-summary --coverageReporters=text
+```
+
+Capture:
+- Pass/fail status for every test
+- Coverage summary (statements, branches, functions, lines)
+
+### Step 3: Analyze Test Results
+
+**Failing tests** — For each failure, record:
+
+| Test File | Test Name | Error | Category |
+|-----------|-----------|-------|----------|
+| `src/__tests__/auth.test.ts` | `should reject expired token` | `TypeError: jwt.verify is not a function` | Broken import |
+
+Categorize failures:
+- **Environment issues** — missing env vars, database not available, network dependency
+- **Broken imports** — module not found, wrong path
+- **Logic errors** — assertion failures indicating actual bugs
+- **Stale tests** — tests for code that was refactored but tests weren't updated
+
+**Coverage analysis:**
+
+| Metric | Current | Target | Status |
+|--------|---------|--------|--------|
+| Statements | 62% | 50% | PASS |
+| Branches | 38% | 50% | FAIL |
+| Functions | 71% | 50% | PASS |
+| Lines | 60% | 50% | PASS |
+
+**Target: all four metrics at or above 50%.**
+
+### Step 4: Identify Coverage Gaps
+
+If any metric is below 50%, identify the files and functions most responsible for the gap:
+
+1. List uncovered files (0% coverage) that contain substantive logic (not config, not types)
+2. List partially covered files where key functions lack tests
+3. Prioritize by impact — covering a 200-line untested service file moves the needle more than adding edge case tests to an already-covered utility
+
+### Step 5: Fix Tests and Improve Coverage (if `--fix` active)
+
+**Fix failing tests first** (in this order):
+1. Broken imports — update paths, fix module resolution
+2. Stale tests — update tests to match refactored code
+3. Logic errors — determine if the test or the code is wrong; fix the one that's wrong
+4. Environment issues — add proper mocking or skip with a clear annotation
+
+**Then improve coverage** (if below 50%):
+1. Write tests for completely uncovered files with substantive logic
+2. Add tests for uncovered branches in partially covered files
+3. Focus on testing public API / exported functions
+4. Follow existing test patterns and conventions in the project
+5. Do NOT write trivial tests just to hit the number (e.g., testing that a constant equals itself)
+
+After writing new tests, re-run the full suite to confirm all tests pass and coverage meets the target.
+
+---
+
+## Phase 6: Final Validation
+
+After all fixes (or after cataloging all issues in report-only mode), run a final validation pass.
+
+### Step 1: Full Verification Run
+
+Run all checks in sequence and confirm clean results:
+
+1. **Build:** `tsc --noEmit` / `npm run build` — zero errors, zero warnings
+2. **Lint:** `npx eslint . --max-warnings 0` — zero issues
+3. **Tests:** `npx jest --ci --coverage` — all pass, coverage >= 50%
+
+### Step 2: Regression Check
+
+If `--fix` was active, verify that fixes didn't introduce new problems:
+
+- Run a `git diff --stat` to summarize all changes
+- Verify no test that previously passed is now failing
+- Verify coverage didn't decrease in any file that wasn't touched
+- Verify no new lint or build warnings were introduced
+
+---
+
+## Output
+
+Save the cleanup report to `.claude/reports/cleanup-report/`. Create the directory if it doesn't exist.
+
+### Report Structure
+
+```
+cleanup-report/
+├── SUMMARY.md              # High-level findings, pass/fail status for each phase
+├── BUILD.md                # Build errors and warnings
+├── LINT.md                 # Lint violations by rule and file
+├── HATEOAS.md              # HATEOAS and architecture compliance findings
+├── DEAD-CODE.md            # Dead and duplicated code inventory
+├── TESTS.md                # Test results and coverage analysis
+└── FIXES.md                # (if --fix was used) Summary of all changes made
+```
+
+### SUMMARY.md Format
+
+```markdown
+# Project Cleanup Report
+
+**Date:** <ISO date>
+**Scope:** <full project | scoped to path>
+**Mode:** <report-only | fix>
+**CLAUDE.md Overrides:** <list any project rules that overrode default behavior>
+
+## Results
+
+| Phase | Status | Issues Found | Issues Fixed |
+|-------|--------|--------------|--------------|
+| Build | PASS/FAIL | <count> errors, <count> warnings | <count> (if --fix) |
+| Lint | PASS/FAIL | <count> errors, <count> warnings | <count> (if --fix) |
+| HATEOAS/Architecture | PASS/FAIL/SKIP | <count> violations | <count> (if --fix) |
+| Dead/Duplicated Code | PASS/FAIL | <count> dead, <count> duplicated | <count> (if --fix) |
+| Tests | PASS/FAIL | <count> failing, coverage: <pct>% | <count> (if --fix) |
+| **Overall** | **PASS/FAIL** | **<total>** | **<total>** |
+
+## Coverage Summary
+
+| Metric | Before | After | Target | Status |
+|--------|--------|-------|--------|--------|
+| Statements | <pct>% | <pct>% | 50% | PASS/FAIL |
+| Branches | <pct>% | <pct>% | 50% | PASS/FAIL |
+| Functions | <pct>% | <pct>% | 50% | PASS/FAIL |
+| Lines | <pct>% | <pct>% | 50% | PASS/FAIL |
+
+## Critical Issues
+
+<List any issues that block production readiness>
+
+## Recommendations
+
+<Prioritized list of remaining work if not all issues were fixed>
+```
+
+---
+
+## Execution Notes
+
+**CLAUDE.md is king.** If the project says "we use `eslint-disable` for generated files" or "skip HATEOAS for internal microservice endpoints" or "we intentionally keep the old API types for backwards compat" — follow those rules. Best practices are defaults, not mandates.
+
+**Fix in dependency order.** Build errors can cause false-positive lint failures. Dead code removal can cause build errors. Fix in this order: dead code removal, build errors, lint issues, HATEOAS compliance, test fixes, coverage improvement.
+
+**Don't over-abstract.** When removing duplicated code, only extract when it genuinely simplifies the codebase. Three similar 5-line blocks are not necessarily worth a shared utility with 3 parameters.
+
+**Don't write bad tests.** When improving coverage, write meaningful tests that verify actual behavior. A test that just calls a function without asserting anything useful doesn't count. Focus on public API surface, error paths, and boundary conditions.
+
+**Report, don't surprise.** In `--fix` mode, the FIXES.md file should clearly document every change made and why. The user should be able to review all changes before committing.
+
+**Preserve project style.** When writing new tests or refactoring code, match the existing patterns in the codebase. Don't introduce a new testing pattern, assertion library, or file structure convention.

package/skills/project-orchestrate/SKILL.md

@@ -0,0 +1,518 @@
+---
+name: project-orchestrate
+description: Autonomous project lifecycle driver that ties together all skills into a continuous loop — plan sprints, execute stories in parallel, release, merge, clean up, and repeat until all epics are done, then run emulation hardening loops until the codebase is clean. Use when you want Claude to drive the entire project from backlog to production-ready without manual skill invocation at each step.
+---
+
+# Project Orchestrate
+
+Fully autonomous project lifecycle driver. Plans sprints, executes stories via parallel subagents, releases, merges to development, cleans up branches, and repeats until every epic is complete — then hardens the codebase through emulation-driven fix cycles until no issues remain.
+
+---
+
+## Before You Start
+
+1. Read `../project-scaffold/references/CONVENTIONS.md` for all project management standards. Follow these conventions exactly.
+2. 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.
+3. **Terminology:** Always refer to milestones as **"epics"** in all user-facing text, summaries, and conversational output. The word "milestone" should only appear in GitHub API commands and code — never in communication with the user.
+4. Confirm the `gh` CLI is authenticated by running `gh auth status`.
+5. Identify the target repository. If the user doesn't specify, detect from the current git remote or ask.
+
+### Standing Authorizations
+
+The following actions are pre-authorized and do NOT require user confirmation during orchestration:
+
+- **Merge release PRs to `development`** — after the release PR is created and CI passes
+- **Delete merged story and release branches** — standard cleanup after merge
+- **Create and switch between feature/release branches** — normal git workflow
+
+The following actions are NEVER authorized:
+
+- **Merge anything to `main`** — always requires explicit human review
+- **Force push or destructive git operations** — never permitted
+- **Close or delete issues without completing them** — incomplete work rolls over
+
+---
+
+## Input
+
+`$ARGUMENTS` can be:
+
+1. **A PRD file path** (e.g., `path/to/prd.md`) — scaffold the PRD first via `/project-scaffold`, then orchestrate **only the epics and stories created from that PRD**. The repo is detected from the current git remote (or ask the user).
+2. **A repo identifier** (e.g., `owner/repo`) — orchestrate **all open epics and stories** already on the project board. No scaffolding step.
+3. **A PRD file path + repo identifier** (e.g., `path/to/prd.md owner/repo`) — scaffold the PRD into the specified repo, then orchestrate only those epics/stories.
+4. **Nothing** — detect the repo from the current git remote and orchestrate all open epics/stories.
+
+**How to distinguish:** If an argument is a path to an existing file, treat it as a PRD. Otherwise treat it as a repo identifier.
+
+### Scope Rules
+
+- **Phase 1 (Epic Completion Loop):** When a PRD is provided, only execute epics/stories that were created from that PRD. Record the milestone numbers and issue numbers created during scaffolding and limit the sprint loop to those. When no PRD is provided, execute all open epics/stories on the project board.
+- **Phase 2 (Emulation Hardening Loop):** Always applies to the **entire codebase** regardless of whether a PRD was provided. Emulation validates the whole project, not just the new work.
+
+---
+
+## State Management
+
+Orchestration state is persisted to `.claude/orchestration-state.md` so progress survives context compaction, usage caps, and session restarts. This file is human-readable markdown.
+
+### State File Structure
+
+```markdown
+# Orchestration State
+
+## Meta
+- **Repo:** owner/repo
+- **Project:** #<number>
+- **Phase:** epic-completion | emulation-hardening
+- **Status:** running | paused | completed
+- **Scope:** prd | all
+- **PRD Source:** path/to/prd.md (if scope=prd, otherwise "—")
+- **Scoped Milestones:** #1, #3 (if scope=prd — only these epics are orchestrated in Phase 1)
+- **Scoped Issues:** #10, #11, #12, ... (if scope=prd — only these stories are orchestrated in Phase 1)
+- **Started:** <ISO timestamp>
+- **Last Updated:** <ISO timestamp>
+
+## Current Position
+- **Current Epic:** <epic name> (milestone #<number>)
+- **Current Sprint:** <N>
+- **Hardening Run:** <N> (Phase 2 only)
+
+## Epic Progress
+| Epic | Status | Open | Closed | Total |
+|------|--------|------|--------|-------|
+| Core API | in-progress | 4 | 12 | 16 |
+| Dashboard | pending | 8 | 0 | 8 |
+
+## Current Sprint Stories
+| # | Title | Executor | Status | Subagent |
+|---|-------|----------|--------|----------|
+| 12 | Auth endpoint | claude | done | — |
+| 13 | Login UI | claude | in-progress | agent-3 |
+| 14 | API keys | human | skipped | — |
+
+## Dependency Map
+- #15 blocked-by #12 → unblocked (completed)
+- #18 blocked-by #15 → waiting
+
+## Log
+- [<timestamp>] Phase 1 started — 3 open epics detected
+- [<timestamp>] Sprint 1 planned — 8 stories, 19 points
+- [<timestamp>] Story #12 completed by subagent
+- [<timestamp>] Sprint 1 released — PR #25
+```
+
+### State Operations
+
+**On startup**, check for an existing `.claude/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
+
+**During execution**, update the state file:
+- After every sprint plan, story completion, release, and phase transition
+- On any error that pauses execution
+- Keep the log section as an append-only journal (trim entries older than the current phase to prevent unbounded growth)
+
+**On completion**, set `Status: completed` and write a final summary to the log.
+
+---
+
+## Phase 1 — Epic Completion Loop
+
+Drive all open epics to completion through iterative sprint cycles.
+
+### Step 1: Initialize
+
+**If a PRD was provided** — scaffold it first, then scope the run:
+
+```
+/project-scaffold <prd-path>
+```
+
+After scaffolding completes, capture the milestone numbers and issue numbers that were created. These define the **orchestration scope** — Phase 1 will only plan and execute sprints for these specific epics and stories. Record them in the state file under `Scoped Milestones` and `Scoped Issues`.
+
+**If no PRD was provided** — detect and assess the existing project state:
+
+```bash
+# Get open epics (milestones)
+gh api repos/<owner/repo>/milestones --jq '.[] | select(.state=="open") | {number, title, open_issues, closed_issues}'
+
+# Get backlog overview
+gh issue list --repo <owner/repo> --state open --label "type:story" --json number,title,labels,milestone
+
+# Get current sprint iteration info via GraphQL
+# Check for any in-progress work
+```
+
+All open epics and stories are in scope for Phase 1.
+
+**In both cases**, present a brief overview to the user:
+
+```
+## Orchestration Overview
+
+**Repo:** owner/repo
+**Scope:** PRD-scoped (path/to/prd.md) | All open epics
+**Epics in scope:** 3
+  - Core API: 16 stories (4 remaining)
+  - Dashboard: 8 stories (all pending)
+  - Notifications: 5 stories (all pending)
+
+**Total stories remaining:** 17
+**Estimated sprints:** 2-3 (at 20 pts/sprint)
+
+Starting Phase 1 — Epic Completion Loop.
+```
+
+Initialize the state file and proceed.
+
+### Step 2: Sprint Planning
+
+Invoke the `/sprint-plan` skill for the current epic:
+
+```
+/sprint-plan <owner/repo>
+```
+
+**If PRD-scoped:** Ensure the sprint plan only pulls from the scoped issues (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.
+
+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.
+
+### Step 3: Story Execution
+
+Execute all `executor:claude` stories in the current sprint. Skip `executor:human` and `executor:cowork` stories — they will roll over to the next sprint automatically.
+
+**Parallel execution via Task subagents:**
+
+For stories with no unresolved dependencies, spawn parallel Task subagents (using the `Task` tool with `subagent_type: "Bash"` or `subagent_type: "general-purpose"` as appropriate). Each subagent receives:
+
+```
+You are executing story #<number> for repo <owner/repo>.
+
+**IMPORTANT:** First read the project's CLAUDE.md file if it exists, and follow all instructions in it.
+
+**Story:** <title>
+**Acceptance criteria:** <from issue body>
+**Branch strategy:** Create branch `story/<number>-<slug>` from `release/<epic-slug>`, implement, commit, push, and open a PR targeting `release/<epic-slug>`.
+
+After implementation:
+1. Open a PR with a clear description of changes
+2. Ensure CI passes
+3. The PR should target the release branch, NOT development or main
+
+Do NOT merge the PR — just open it and report back.
+```
+
+**Execution rules:**
+
+1. **Independence check:** Before spawning subagents, analyze story dependencies. Only spawn stories whose blockers are all resolved.
+2. **Concurrency limit:** Run up to 3 subagents in parallel to avoid rate limiting.
+3. **Progress tracking:** As each subagent completes, update the state file and check if any blocked stories are now unblocked. Spawn newly unblocked stories immediately.
+4. **Failure handling:** If a subagent fails, retry once with additional context about the failure. If it fails again, mark the story as blocked with a note and continue with remaining stories.
+5. **PR merging:** After a story PR is opened and CI passes, merge it to the release branch:
+   ```bash
+   gh pr merge <pr-number> --repo <owner/repo> --squash --auto
+   ```
+6. **Skip human/cowork stories:** Log them as skipped in the state file. They roll over naturally during sprint release.
+
+**Progress updates** — Print a concise progress line every 2-3 story completions:
+
+```
+Sprint 2: 5/8 stories done (13/19 pts) — #21 auth middleware ✓, #22 rate limiting ✓
+```
+
+### Step 4: Sprint Release
+
+Once all `executor:claude` stories in the sprint are complete (or retried and marked blocked), invoke the sprint release skill:
+
+```
+/sprint-release <owner/repo>
+```
+
+This closes the sprint, handles rolled-over stories, and opens the release PR to `development`.
+
+### Step 5: Merge Release PR to Development
+
+After `/sprint-release` creates the release PR, merge it to `development` (standing authorization — no user confirmation needed):
+
+```bash
+# Wait for CI to pass on the release PR
+gh pr checks <pr-number> --repo <owner/repo> --watch
+
+# Merge the release PR to development
+gh pr merge <pr-number> --repo <owner/repo> --squash
+```
+
+If merge conflicts exist:
+1. Attempt automatic resolution by rebasing the release branch onto `development`
+2. If auto-resolution fails, **pause orchestration** and escalate to the user:
+   ```
+   ⚠️ Merge conflict on release/<epic-slug> → development
+   Conflicting files: <list>
+
+   Orchestration paused. Please resolve conflicts and resume.
+   ```
+3. Update the state file with `Status: paused` and the conflict details.
+
+### Step 6: Branch Cleanup
+
+After successful merge, clean up merged branches (standing authorization):
+
+```bash
+# Delete merged story branches
+git fetch origin
+git branch -r --merged origin/development | grep -E 'origin/story/' | sed 's|origin/||' | while read branch; do
+  git push origin --delete "$branch"
+done
+
+# If the release branch is fully merged and the epic is complete, delete it too
+git push origin --delete release/<epic-slug>
+
+# Prune local references
+git remote prune origin
+```
+
+Never delete `main` or `development`.
+
+### Step 7: Epic Completion Check
+
+After each sprint cycle, check if the current epic is complete:
+
+```bash
+# Check remaining open issues for this epic
+gh api repos/<owner/repo>/milestones/<milestone-number> --jq '{open_issues, closed_issues}'
+```
+
+**If open issues remain** (excluding `executor:human`/`executor:cowork` stories that were skipped):
+- Check if remaining stories are all human/cowork → if yes, the epic's claude-executable work is done, move to next epic
+- Otherwise → loop back to Step 2 for another sprint
+
+**If all issues are closed:**
+```bash
+# Close the epic
+gh api repos/<owner/repo>/milestones/<milestone-number> -X PATCH -f state="closed"
+```
+
+**If more in-scope epics remain** → move to the next epic (by priority) and loop back to Step 2. When PRD-scoped, only consider epics listed in `Scoped Milestones`.
+
+**If all in-scope epics are complete** → transition to Phase 2.
+
+Print a phase transition summary:
+
+```
+## Phase 1 Complete — All Epics Done
+
+**Sprints completed:** 4
+**Stories delivered:** 32
+**Stories skipped (human/cowork):** 6
+**Total points delivered:** 89
+
+Transitioning to Phase 2 — Emulation Hardening.
+```
+
+---
+
+## Phase 2 — Emulation Hardening Loop
+
+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.
+
+### Step 8: Run Emulation
+
+Invoke the project emulation skill:
+
+```
+/project-emulate
+```
+
+This produces the full emulation report in `.claude/reports/emulation-report/`, including `ISSUES.md` with categorized findings.
+
+### Step 9: Parse Findings
+
+Read and parse `.claude/reports/emulation-report/ISSUES.md`. Extract findings by severity:
+
+- **Critical** — must fix (blocks production readiness)
+- **Warning** — should fix (degrades quality or reliability)
+- **Info** — may fix (cleanup, minor improvements)
+
+If no critical or warning findings exist → orchestration is complete, skip to Step 14.
+
+Count and categorize:
+
+```
+## Emulation Results (Run <N>)
+
+**Critical:** 3 findings
+**Warning:** 7 findings
+**Info:** 4 findings
+
+Generating hardening PRD for 10 actionable findings.
+```
+
+### Step 10: Generate Hardening PRD
+
+Create a PRD document at `.claude/hardening-prd-run-<N>.md` from the emulation findings. This PRD becomes the input for scaffolding a hardening epic.
+
+Structure the PRD as:
+
+```markdown
+# Hardening PRD — Run <N>
+
+## Overview
+Automated hardening pass based on emulation findings from run <N>.
+Addresses <count> critical and <count> warning issues discovered during
+full-project emulation.
+
+## Epic: Hardening (Run <N>)
+
+### Stories
+
+#### Fix: <Issue title from ISSUES.md>
+**Priority:** <P0 for critical, P1 for warning>
+**Executor:** claude
+**Story Points:** <estimate based on scope>
+**Acceptance Criteria:**
+- <derived from the issue description>
+- Verify fix by re-checking the specific integration seam / layer contract / workflow
+
+#### Fix: <next issue>
+...
+```
+
+Only include critical and warning findings. Info-level findings are logged but not scaffolded.
+
+### Step 11: Scaffold Hardening Epic
+
+Invoke project scaffold with the hardening PRD to create a single "Hardening (Run N)" epic:
+
+```
+/project-scaffold .claude/hardening-prd-run-<N>.md
+```
+
+This creates the milestone, issues, labels, and branches for the hardening work.
+
+### Step 12: Execute Hardening Sprints
+
+Run the same sprint loop as Phase 1 (Steps 2-7) for the hardening epic. Since hardening stories are typically all `executor:claude`, this should proceed fully autonomously.
+
+### Step 13: Re-validate
+
+After the hardening epic is complete, run emulation again:
+
+```
+/project-emulate
+```
+
+Parse the new findings:
+
+- **If new critical or warning findings exist** → increment the run counter and loop back to Step 10
+- **If clean (no critical or warning findings)** → proceed to Step 14
+
+Safety valve: If this is the 3rd consecutive hardening run, pause and escalate to the user:
+
+```
+⚠️ Hardening loop has run 3 times without reaching a clean state.
+Remaining findings may require human judgment.
+
+<summary of remaining findings>
+
+Options:
+1. Continue for another hardening run
+2. Accept current state and finish
+3. Review findings manually
+```
+
+### Step 14: Completion Summary
+
+Print a comprehensive summary of the entire orchestration run:
+
+```
+## Orchestration Complete
+
+### Phase 1 — Epic Completion
+- **Epics completed:** <N>
+- **Sprints executed:** <N>
+- **Stories delivered:** <N> (<points> story points)
+- **Stories skipped (human/cowork):** <N>
+- **Average velocity:** <points>/sprint
+
+### Phase 2 — Emulation Hardening
+- **Hardening runs:** <N>
+- **Issues fixed:** <N> critical, <N> warning
+- **Final emulation status:** ✅ Clean / ⚠️ Accepted with <N> remaining
+
+### Timeline
+- Started: <timestamp>
+- Phase 1 completed: <timestamp>
+- Phase 2 completed: <timestamp>
+
+### Remaining Work
+- <N> human/cowork stories still open across <N> epics
+- <list any deferred or unresolved items>
+```
+
+Update the state file with `Status: completed`.
+
+---
+
+## Communication Pattern
+
+Keep the user informed without being noisy:
+
+| Event | Output |
+|-------|--------|
+| Orchestration start | Full overview (Step 1) |
+| Sprint planned | Sprint number, story count, point total — 2 lines |
+| Every 2-3 stories | Progress line with counts and latest completions |
+| Story failure | Immediate single-line alert with story number and error |
+| Sprint released | Sprint scorecard — 3-4 lines |
+| Merge to development | Single confirmation line |
+| Epic completed | Epic summary — 3-4 lines |
+| Phase transition | Full phase summary |
+| Hardening run start | Run number and finding counts |
+| Orchestration complete | Full completion summary (Step 14) |
+| Error/pause | Immediate alert with context and options |
+
+---
+
+## Error Handling
+
+### Subagent Failures
+- Retry once with additional context about the failure
+- If second attempt fails, mark story as blocked, log the error, and continue
+- Do not let a single story failure halt the entire sprint
+
+### Merge Conflicts
+- Attempt automatic rebase resolution first
+- If auto-resolution fails, pause orchestration and escalate to the user
+- Update state file with conflict details for resume
+
+### State File Corruption
+- If `.claude/orchestration-state.md` is unreadable or malformed, reconstruct state from GitHub:
+  ```bash
+  # Get sprint and story status from the project board
+  # Get branch state from git
+  # Get PR state from gh
+  ```
+- Log the reconstruction and continue
+
+### Rate Limiting
+- If GitHub API returns 429 or secondary rate limit errors, back off exponentially:
+  - First: wait 30 seconds
+  - Second: wait 60 seconds
+  - Third: wait 2 minutes
+  - Fourth: pause orchestration and notify the user
+
+### CI Failures on Release Branch
+- If CI fails on the release PR, do not merge
+- Report the failure with links to the failing checks
+- Attempt to identify the failing test or build step
+- If the fix is straightforward, create a fix commit on the release branch and retry
+- If not, pause and escalate
+
+### Usage Cap / Context Compaction
+- The state file ensures progress is not lost
+- On resume, read the state file and continue from the last recorded position
+- The log section provides context about what happened before compaction

package/skills/project-scaffold/references/CONVENTIONS.md

@@ -96,6 +96,16 @@ main (human-only — gh token has NO write access)
 - Release PR to development includes a sprint summary (auto-generated by sprint-release skill).
 - Production PRs from development → main are opened manually when ready to ship.
 
+### Branch Lifecycle & Cleanup
+
+The skill that creates branches is NOT necessarily the skill that cleans them up. `project-scaffold` and `sprint-plan` create release and story branches. `sprint-release` is responsible for cleaning up any that are fully merged into `development` by the time it runs. This prevents branch sprawl regardless of which execution pattern was used during the sprint.
+
+**Cleanup rules:**
+- Never delete `main` or `development`
+- Only delete branches fully merged into `development`
+- Do not delete unmerged release branches (they have pending work)
+- Report all deletions in the release summary
+
 ### Approval Layers
 
 | Merge | Reviewer | Trigger |

package/skills/sprint-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sprint-release
-description: Wrap up a sprint by generating a release summary, opening the release PR to main for human review, handling incomplete stories, and preparing for the next sprint. Use when a sprint is complete or at the sprint boundary deadline.
+description: Wrap up a sprint by generating a release summary, opening release PRs for human review, handling incomplete stories, cleaning up merged branches, and preparing for the next sprint. Use when a sprint is complete or at the sprint boundary deadline.
 ---
 
 # Sprint Release
@@ -114,19 +114,38 @@ for the reviewer to be aware of.>
 - [ ] Reviewed release summary above
 ```
 
-### Step 4: Open the Release PR
+### Step 4: Detect Branch State
 
-The release PR targets `development`, NOT `main`. The development → main promotion is a separate, human-initiated production release.
+Before creating any PR, determine the current branch state:
 
 ```bash
-# Ensure release branch is up to date
-git checkout release/<epic-slug> && git pull
+git fetch origin
+
+# Find all release and story branches
+RELEASE_BRANCHES=$(git branch -r | grep 'origin/release/' | sed 's|origin/||' | xargs)
+STORY_BRANCHES=$(git branch -r | grep 'origin/story/' | sed 's|origin/||' | xargs)
+
+# Check which release branches have unmerged commits relative to development
+UNMERGED=""
+for branch in $RELEASE_BRANCHES; do
+  AHEAD=$(git rev-list --count origin/development..origin/$branch 2>/dev/null || echo "0")
+  if [ "$AHEAD" -gt 0 ]; then
+    UNMERGED="$UNMERGED $branch"
+  fi
+done
+```
+
+Based on the result, follow the matching scenario:
+
+**Scenario A — Unmerged release branches exist:**
+
+Release branches have commits not yet in `development`. This is the "accumulate and release" pattern.
 
-# Check for conflicts with development
-git fetch origin development
-git merge-tree $(git merge-base HEAD origin/development) HEAD origin/development
+1. Create one PR per unmerged release branch targeting `development`
+2. Do NOT create a `development` → `main` PR (that's a separate human-initiated production release)
+3. Clean up only the story branches that are fully merged into their release branch
 
-# Open the PR targeting development
+```bash
 gh pr create \
   --repo <owner/repo> \
   --base development \
@@ -142,9 +161,68 @@ If there are merge conflicts with development:
 - Offer to resolve them or flag for manual resolution
 - Do NOT open the PR until conflicts are resolved
 
-### Step 5: Close the Epic (if all stories are complete)
+**Scenario B — All release branches already merged to development:**
+
+All epic work was merged into `development` during sprint execution. Nothing to PR into `development`.
 
-If all stories in the epic (milestone) are complete (no open issues remaining):
+1. Check for an existing `development` → `main` PR
+   - If one exists, update its body with the release notes
+   - If none exists, create it
+2. Clean up all merged story and release branches (both local and remote)
+
+```bash
+# Check for existing development → main PR
+gh pr list --repo <owner/repo> --base main --head development --json number,state
+
+# If no PR exists, create the production release PR
+gh pr create \
+  --repo <owner/repo> \
+  --base main \
+  --head development \
+  --title "Release: Sprint <N> — <summary>" \
+  --body "<release PR body from Step 3>" \
+  --reviewer <owner> \
+  --label "type:release"
+
+# If a PR already exists, update its body with the release notes
+gh api repos/<owner/repo>/pulls/<pr-number> -X PATCH -f body="<release PR body>"
+```
+
+**Scenario C — Mixed (some merged, some not):**
+
+Some release branches were merged during sprint execution, others are still pending.
+
+1. Create PRs for unmerged release branches → `development` (Scenario A behavior)
+2. Do NOT create the `development` → `main` PR yet (pending work still needs to land)
+3. Clean up only fully-merged branches
+
+### Step 5: Clean Up Merged Branches
+
+After handling the release PR(s), clean up branches that are fully merged into `development`. The skill that creates branches is NOT necessarily the skill that cleans them up — `project-scaffold` and `sprint-plan` create release/story branches, but `sprint-release` is responsible for cleaning up any that are fully merged by the time it runs.
+
+```bash
+# Identify merged branches (excluding main and development)
+git branch -r --merged origin/development | grep -E 'origin/(story|release)/' | sed 's|origin/||'
+
+# Delete remote branches
+for branch in <merged-branches>; do
+  git push origin --delete "$branch"
+done
+
+# Delete local tracking branches and prune
+git branch -d <local-merged-branches>
+git remote prune origin
+```
+
+**Cleanup rules:**
+- Never delete `main` or `development`
+- Only delete branches fully merged into `development`
+- In Scenario A/C, only delete story branches merged into their release branch — do not delete unmerged release branches
+- Report all deletions in the release summary
+
+### Step 6: Close Epics (if all stories are complete)
+
+If all stories in an epic (milestone) are complete (no open issues remaining):
 
 ```bash
 gh api repos/<owner/repo>/milestones/<milestone-number> -f state="closed"
@@ -152,13 +230,13 @@ gh api repos/<owner/repo>/milestones/<milestone-number> -f state="closed"
 
 If stories remain, keep the epic open for the next sprint.
 
-### Step 6: Generate Release Report
+### Step 7: Generate Release Report
 
 ```
 ## Sprint <N> Release Complete
 
 **Release PR:** #<pr-number> — awaiting your review
-**Branch:** release/<slug> → development
+**Branch:** <branch flow description, e.g. "development → main" or "release/<slug> → development">
 
 ### Sprint Scorecard
 - **Velocity:** <points_completed> points (target was <planned_points>)
@@ -170,12 +248,20 @@ If stories remain, keep the epic open for the next sprint.
 - **<Epic Name>:** <closed_issues>/<total_issues> stories complete (<percentage>%)
 - **Epic status:** <open/closed>
 
+### Cleanup
+- **Branches deleted:** <list of deleted branches, or "none">
+- **Remaining branches:** main, development
+
 ### Next Steps
+<If Scenario A (release → development):>
 1. **Review the release PR:** <link to PR>
 2. **Merge to development** when satisfied
 3. Run `/sprint-plan` to plan Sprint <N+1>
-<If epic complete:>
-4. Epic "<Epic Name>" is complete! Consider promoting development → main for a production release.
+
+<If Scenario B (development → main):>
+1. **Review the production release PR:** <link to PR>
+2. **Merge to main** when satisfied
+3. Run `/sprint-plan` to plan the next phase
 ```
 
 ## Error Handling