npm package: @houseofwolvesllc/claude-scrum-skill
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.
Author: House of Wolves LLC
Latest version: 1.5.1

# 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.

```
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

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

### 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:

```
/plugin marketplace update
```

### 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
```

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

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.

**Note:** After installing, restart Claude Code for the skills to become available.

## Quick Start

### 1. Create a Fine-Grained GitHub Personal Access Token

These skills use `gh` for all GitHub operations. You need a fine-grained PAT scoped to the repos you want to manage.

**Step 1:** Go to [github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens) and click **Generate new token**.

**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

**Step 3:** Under **Permissions → Repository permissions**, grant:

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

**Step 4:** Under **Permissions → Account permissions**, grant:

| Permission | Access | Why |
|---|---|---|
| Projects | Read & Write | Create project boards, custom fields, and views |

**Step 5:** Click **Generate token** and copy it immediately — you won't see it again.

**Step 6:** Authenticate the GitHub CLI with your new token:

```bash
echo "YOUR_TOKEN" | gh auth login --with-token
```

Verify it worked:

```bash
gh auth status
```

**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.

### 2. Write a PRD

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

### 3. Scaffold the Project

Open Claude Code in your repo and run:

```
/project-scaffold path/to/your-prd.md
```

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.

### 4. Plan a Sprint

```
/sprint-plan owner/repo
```

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.

### 5. Assign an Executor

Three executor labels control who works each story:

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

### 6. Hand Off to Claude Code

In Claude Code, tell it to work 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."

Claude works autonomously — branching, committing, opening PRs with auto-merge to the release branch.

### 7. Check Progress

```
/sprint-status owner/repo
```

Get a progress report: stories completed vs. remaining, burndown, blockers, and what Claude is working on.

### 8. Release the Sprint

```
/sprint-release owner/repo
```

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`.

### 9. Emulate the Project

```
/project-emulate
```

Claude reads the entire codebase and runs a multi-phase validation:

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

### 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. Clean Up the Codebase

```
# Report issues without fixing
/project-cleanup

# Scope to a specific directory
/project-cleanup src/

# Auto-fix everything
/project-cleanup --fix

# Report only, no fixes even if --fix is present
/project-cleanup --report-only
```

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.

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.

Reads your project's `CLAUDE.md` for overrides — project rules always win over default best practices.

### 12. Repeat (Manual Mode)

```
/sprint-plan owner/repo
```

If you prefer manual control, start the next sprint. The cycle continues until the project is complete.

## How It Works

### 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 ✓
```

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.

### GitHub Project Board

The scaffold creates a GitHub Project (the newer Projects experience, not classic project boards) with these custom fields:

| Field | Type | Purpose |
|---|---|---|
| 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) |

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.

**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

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.

### Shared Conventions

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.

Located at: `project-scaffold/references/CONVENTIONS.md`

## Skills Reference

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

## Customization

### Sprint Length
Edit `CONVENTIONS.md` → "Sprint Cadence" section. Default is 2 weeks.

### Velocity Target
The `sprint-plan` skill asks for velocity or defaults to 20 story points. Adjust as you calibrate.

### Label Colors
All label hex colors are defined in the `project-scaffold` skill. Modify to match your preferences.

### Executor Criteria
Edit `CONVENTIONS.md` → "Executor Assignment Guidelines" to tune what gets assigned to Claude vs. you vs. Cowork.

### 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.
- **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%.

## License

Apache 2.0 — See [LICENSE](LICENSE) for details.