@houseofwolvesllc/claude-scrum-skill 1.5.0 → 1.6.0

package/bin/install.js

@@ -27,6 +27,7 @@ if (IS_GLOBAL) {
 
 const skills = [
   'project-scaffold',
+  'project-spec',
   'sprint-plan',
   'sprint-status',
   'sprint-release',
@@ -53,6 +54,14 @@ console.log(`\n📋 Installing claude-scrum-skill (${location})...\n`);
 
 fs.mkdirSync(skillsDir, { recursive: true });
 
+// Copy shared references (not a skill, but needed by skills at ../shared/)
+const sharedSrc = path.join(SOURCE_DIR, 'shared');
+const sharedDest = path.join(skillsDir, 'shared');
+if (fs.existsSync(sharedSrc)) {
+  copyRecursive(sharedSrc, sharedDest);
+  console.log('  📁 shared references');
+}
+
 let installed = 0;
 for (const skill of skills) {
   const src = path.join(SOURCE_DIR, skill);
@@ -67,6 +76,28 @@ for (const skill of skills) {
   }
 }
 
+// Add .claude-scrum-skill to .gitignore if not already present (local install only)
+if (!IS_GLOBAL) {
+  const projectRoot = path.resolve(skillsDir, '..', '..');
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const entry = '.claude-scrum-skill';
+
+  let needsAppend = true;
+  if (fs.existsSync(gitignorePath)) {
+    const contents = fs.readFileSync(gitignorePath, 'utf8');
+    needsAppend = !contents.split('\n').some(line => line.trim() === entry);
+  }
+
+  if (needsAppend) {
+    const prefix = fs.existsSync(gitignorePath)
+      && fs.readFileSync(gitignorePath, 'utf8').length > 0
+      && !fs.readFileSync(gitignorePath, 'utf8').endsWith('\n')
+      ? '\n' : '';
+    fs.appendFileSync(gitignorePath, `${prefix}${entry}\n`);
+    console.log(`\n  📝 Added ${entry} to .gitignore`);
+  }
+}
+
 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,6 +1,6 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "1.5.0",
+  "version": "1.6.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": {

package/skills/project-cleanup/SKILL.md

@@ -12,7 +12,7 @@ Ensure the codebase is production-clean: builds without errors or warnings, pass
 ## 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).
+2. Read `../shared/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.).
@@ -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
 
 ---
 
@@ -355,7 +328,7 @@ If `--fix` was active, verify that fixes didn't introduce new problems:
 
 ## Output
 
-Save the cleanup report to `.claude/reports/cleanup-report/`. Create the directory if it doesn't exist.
+Save the cleanup report to `.claude-scrum-skill/reports/cleanup-report/`. Create the directory if it doesn't exist.
 
 ### Report Structure
 
@@ -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-emulate/SKILL.md

@@ -563,7 +563,7 @@ A clean table: Roles as rows, Actions as columns, cells showing ✅ allowed /
 
 ## Output
 
-Save the walkthrough results to the project .claude/reports. The output structure:
+Save the walkthrough results to the project .claude-scrum-skill/reports. The output structure:
 
 ```
 emulation-report/