@houseofwolvesllc/claude-scrum-skill 1.4.0 → 1.5.1

package/README.md

@@ -1,6 +1,6 @@
 # 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, and autonomous orchestration. 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. 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:
@@ -51,7 +51,7 @@ Add the marketplace and install the plugin directly from GitHub:
 /plugin install claude-scrum-skill@houseofwolvesllc
 ```
 
-This installs all six skills as a native Claude Code plugin with automatic updates. To update later:
+This installs all seven skills as a native Claude Code plugin with automatic updates. To update later:
 
 ```
 /plugin marketplace update
@@ -220,7 +220,29 @@ Instead of manually invoking each skill at every step, let Claude drive the enti
 
 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)
+### 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
@@ -283,6 +305,7 @@ Located at: `project-scaffold/references/CONVENTIONS.md`
 | `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
 
@@ -341,6 +364,7 @@ Orchestration state is saved to `.claude/orchestration-state.md` (human-readable
 - **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Claude Code skills for scrum project management — PRD to production release pipeline with project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup.",
   "bin": {},
   "scripts": {

package/skills/project-cleanup/SKILL.md

@@ -116,75 +116,48 @@ For each issue found, record:
 
 ---
 
-## Phase 3: HATEOAS and Project Principles Compliance
+## Phase 3: Project Principles Compliance
 
-Verify the codebase adheres to HATEOAS (Hypermedia as the Engine of Application State) principles and any project-specific architectural standards.
+Verify the codebase adheres to the architectural and design principles defined in the project's `CLAUDE.md`. This phase is entirely driven by what the project specifies — there are no default architectural checks.
 
-**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.
+**If `CLAUDE.md` does not exist or contains no architectural principles, skip this phase entirely.**
 
-### Step 1: Identify API Layer
+### Step 1: Extract Principles from CLAUDE.md
 
-Scan for API route definitions, controllers, and response construction:
+Read the project's `CLAUDE.md` and identify every architectural or design principle it specifies. These may include (but are not limited to):
 
-- 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)
+- **API design patterns** — HATEOAS, REST conventions, GraphQL schema standards, response envelope formats
+- **Layered architecture rules** — e.g., "controllers must not call repositories directly"
+- **Dependency direction** — e.g., "inner layers must not depend on outer layers"
+- **Naming conventions** — file names, function names, variable naming patterns
+- **Error handling patterns** — e.g., "all errors must extend AppError"
+- **Response formats** — e.g., "all responses must include `_links`" or "use HAL format"
+- **Testing requirements** — e.g., "every service must have integration tests"
+- **Any other explicit rule** — whatever the project declares, enforce it
 
-### Step 2: HATEOAS Link Audit
+Record each principle found so violations can reference the specific rule.
 
-For each API endpoint that returns resource representations, verify:
+### Step 2: Audit Compliance
 
-**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:
+For each principle extracted in Step 1, scan the codebase for violations:
 
-- **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?
+1. Identify all files and code paths where the principle applies
+2. Check each instance for compliance
+3. Flag every violation with the specific principle it breaks
 
-### Step 4: Catalog HATEOAS/Architecture Issues
+### Step 3: Catalog Violations
 
 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 |
+| File | Line | Principle | Issue | Recommendation |
+|------|------|-----------|-------|----------------|
+| `src/routes/orders.ts` | 45 | Layered architecture | Controller directly queries DB | Route through OrderService |
+| `src/controllers/users.ts` | 78 | HATEOAS (per CLAUDE.md) | Response missing `_links.self` | Add self link to user response |
 
 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)
+- Fix violations in order of severity (principles the project marks as critical first)
 - Verify fixes don't break existing tests
+- Re-scan to confirm compliance
 
 ---
 
@@ -364,7 +337,7 @@ 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
+├── PRINCIPLES.md           # Project principles compliance findings (from CLAUDE.md)
 ├── 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
@@ -386,7 +359,7 @@ cleanup-report/
 |-------|--------|--------------|--------------|
 | 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) |
+| Project Principles | 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>** |
@@ -413,9 +386,9 @@ cleanup-report/
 
 ## 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.
+**CLAUDE.md is king.** If the project says "we use `eslint-disable` for generated files" or "we intentionally keep the old API types for backwards compat" — follow those rules. Best practices are defaults, not mandates. Phase 3 (Project Principles) only enforces what `CLAUDE.md` explicitly declares — no assumptions about HATEOAS, REST conventions, or any other architectural pattern unless the project specifies them.
 
-**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.
+**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, project principles 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.
 

package/skills/project-orchestrate/SKILL.md

@@ -63,7 +63,7 @@ Orchestration state is persisted to `.claude/orchestration-state.md` so progress
 ## Meta
 - **Repo:** owner/repo
 - **Project:** #<number>
-- **Phase:** epic-completion | emulation-hardening
+- **Phase:** epic-completion | emulation-hardening | project-cleanup
 - **Status:** running | paused | completed
 - **Scope:** prd | all
 - **PRD Source:** path/to/prd.md (if scope=prd, otherwise "—")
@@ -337,7 +337,7 @@ Read and parse `.claude/reports/emulation-report/ISSUES.md`. Extract findings by
 - **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.
+If no critical or warning findings exist → skip to Step 14 (Project Cleanup).
 
 Count and categorize:
 
@@ -408,7 +408,7 @@ After the hardening epic is complete, run emulation again:
 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
+- **If clean (no critical or warning findings)** → proceed to Step 14 (Project Cleanup)
 
 Safety valve: If this is the 3rd consecutive hardening run, pause and escalate to the user:
 
@@ -424,7 +424,47 @@ Options:
 3. Review findings manually
 ```
 
-### Step 14: Completion Summary
+---
+
+## Phase 3 — Project Cleanup
+
+After emulation hardening is clean (or accepted), run a final mechanical hygiene pass to ensure the codebase builds, lints, and tests cleanly.
+
+### Step 14: Run Project Cleanup
+
+Invoke the cleanup skill in fix mode:
+
+```
+/project-cleanup --fix
+```
+
+This runs across the **entire codebase** and automatically fixes:
+- Build errors and warnings (type errors, unused variables, deprecations)
+- Lint violations (ESLint/Biome/etc. with `--max-warnings 0`)
+- HATEOAS compliance gaps (missing `_links`, pagination links, consistency)
+- Dead and duplicated code (unused exports, files, dependencies, commented-out code)
+- Failing tests and coverage gaps (targets 50% minimum across all metrics)
+
+After cleanup completes, read the report at `.claude/reports/cleanup-report/SUMMARY.md`:
+
+- **If all phases PASS** → proceed to Step 15 (Completion Summary)
+- **If any phase FAIL** → review the report, attempt a second cleanup pass. If issues persist after two passes, log remaining issues and proceed to Step 15 with a note
+
+Print a phase transition summary:
+
+```
+## Phase 3 Complete — Project Cleanup
+
+**Build:** ✅ zero errors, zero warnings
+**Lint:** ✅ zero violations
+**Project Principles:** ✅ compliant (or SKIP if no principles in CLAUDE.md)
+**Dead code:** ✅ none detected
+**Tests:** ✅ all passing, <pct>% coverage
+
+Proceeding to completion summary.
+```
+
+### Step 15: Completion Summary
 
 Print a comprehensive summary of the entire orchestration run:
 
@@ -443,10 +483,19 @@ Print a comprehensive summary of the entire orchestration run:
 - **Issues fixed:** <N> critical, <N> warning
 - **Final emulation status:** ✅ Clean / ⚠️ Accepted with <N> remaining
 
+### Phase 3 — Project Cleanup
+- **Build:** ✅ clean / ⚠️ <N> remaining issues
+- **Lint:** ✅ clean / ⚠️ <N> remaining issues
+- **Project Principles:** ✅ compliant / ⚠️ <N> violations / ⏭️ skipped (no principles in CLAUDE.md)
+- **Dead code:** ✅ none / ⚠️ <N> items remaining
+- **Tests:** ✅ passing (<pct>% coverage) / ⚠️ <N> failing, <pct>% coverage
+- **Full report:** .claude/reports/cleanup-report/SUMMARY.md
+
 ### Timeline
 - Started: <timestamp>
 - Phase 1 completed: <timestamp>
 - Phase 2 completed: <timestamp>
+- Phase 3 completed: <timestamp>
 
 ### Remaining Work
 - <N> human/cowork stories still open across <N> epics
@@ -472,7 +521,9 @@ Keep the user informed without being noisy:
 | 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) |
+| Cleanup started | Single line: "Running project cleanup..." |
+| Cleanup complete | Phase 3 summary — 5-6 lines with pass/fail per dimension |
+| Orchestration complete | Full completion summary (Step 15) |
 | Error/pause | Immediate alert with context and options |
 
 ---