@houseofwolvesllc/claude-scrum-skill 2.1.1 → 2.1.3

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": "2.1.1",
+  "version": "2.1.3",
   "author": {
     "name": "House of Wolves LLC"
   },

package/bin/install.js

@@ -6,25 +6,9 @@ const path = require('path');
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const SOURCE_DIR = path.join(__dirname, '..', 'skills');
 const WORKFLOWS_SOURCE_DIR = path.join(__dirname, '..', 'lib', 'workflows');
+const GUIDANCE_SOURCE_DIR = path.join(__dirname, '..', 'lib', 'guidance');
 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 CONFIG_FILENAME = 'config.json';
 
 const skills = [
   'project-scaffold',
@@ -37,76 +21,207 @@ const skills = [
   'project-cleanup'
 ];
 
-function copyRecursive(src, dest) {
-  if (!fs.existsSync(src)) return;
+function main() {
+  const skillsDir = resolveSkillsDir();
+  const location = IS_GLOBAL ? 'global (~/.claude/skills/)' : `project (${skillsDir})`;
+  console.log(`\n📋 Installing claude-scrum-skill (${location})...\n`);
 
-  if (fs.statSync(src).isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true });
-    for (const item of fs.readdirSync(src)) {
-      copyRecursive(path.join(src, item), path.join(dest, item));
-    }
-  } else {
-    fs.copyFileSync(src, dest);
+  fs.mkdirSync(skillsDir, { recursive: true });
+
+  installSharedReferences(skillsDir);
+  const installed = installSkills(skillsDir);
+  installWorkflows(skillsDir);
+  installGuidance(skillsDir);
+
+  if (!IS_GLOBAL) {
+    ensureGitignoreEntry(skillsDir);
   }
+
+  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');
 }
 
-const location = IS_GLOBAL ? 'global (~/.claude/skills/)' : `project (${skillsDir})`;
-console.log(`\n📋 Installing claude-scrum-skill (${location})...\n`);
+function resolveSkillsDir() {
+  if (IS_GLOBAL) {
+    return path.join(HOME, '.claude', 'skills');
+  }
 
-fs.mkdirSync(skillsDir, { recursive: true });
+  // 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);
+  }
+  return path.join(projectRoot, '.claude', 'skills');
+}
+
+function installSharedReferences(skillsDir) {
+  const sharedSrc = path.join(SOURCE_DIR, 'shared');
+  const sharedDest = path.join(skillsDir, 'shared');
+  if (!fs.existsSync(sharedSrc)) return;
 
-// 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);
+  // config.json is user-owned: copy everything else, then merge it explicitly.
+  const skipConfig = path.join(sharedSrc, CONFIG_FILENAME);
+  copyRecursive(sharedSrc, sharedDest, skipConfig);
   console.log('  📁 shared references');
+
+  installSharedConfig(sharedSrc, sharedDest);
 }
 
-let installed = 0;
-for (const skill of skills) {
-  const src = path.join(SOURCE_DIR, skill);
-  const dest = path.join(skillsDir, skill);
+function installSharedConfig(sharedSrc, sharedDest) {
+  const defaultPath = path.join(sharedSrc, CONFIG_FILENAME);
+  const destPath = path.join(sharedDest, CONFIG_FILENAME);
 
-  if (fs.existsSync(src)) {
-    copyRecursive(src, dest);
-    console.log(`  ✅ ${skill}`);
-    installed++;
-  } else {
-    console.log(`  ⚠️  ${skill} — source not found, skipping`);
+  try {
+    const { action } = installConfig(defaultPath, destPath);
+    console.log(configLogLine(action));
+  } catch (error) {
+    console.log(`  ⚠️  config install failed (${error.message}) — skills still installed`);
   }
 }
 
+function configLogLine(action) {
+  switch (action) {
+    case 'default':
+      return '  📁 config (default)';
+    case 'merged':
+      return '  🔧 config (merged — your settings preserved)';
+    case 'recovered':
+      return `  ⚠️  config was invalid JSON — backed up to ${CONFIG_FILENAME}.bak, wrote default`;
+    default:
+      throw new Error(`unknown config action: ${action}`);
+  }
+}
+
+function installSkills(skillsDir) {
+  let installed = 0;
+  for (const skill of skills) {
+    const src = path.join(SOURCE_DIR, skill);
+    const dest = path.join(skillsDir, skill);
+
+    if (fs.existsSync(src)) {
+      copyRecursive(src, dest);
+      console.log(`  ✅ ${skill}`);
+      installed++;
+    } else {
+      console.log(`  ⚠️  ${skill} — source not found, skipping`);
+    }
+  }
+  return installed;
+}
+
 // Copy lib/workflows/ → <skillsDir>/_workflows/ (v2.0.0+).
-// Underscore prefix prevents Claude Code from registering as a skill.
-if (fs.existsSync(WORKFLOWS_SOURCE_DIR)) {
+// Underscore prefix prevents Claude Code from registering it as a skill.
+function installWorkflows(skillsDir) {
+  if (!fs.existsSync(WORKFLOWS_SOURCE_DIR)) return;
   const workflowsDest = path.join(skillsDir, '_workflows');
   copyRecursive(WORKFLOWS_SOURCE_DIR, workflowsDest);
   console.log('  ⚙️  _workflows (lib/workflows + schemas)');
 }
 
-// Add .claude-scrum-skill to .gitignore if not already present (local install only)
-if (!IS_GLOBAL) {
+// Copy lib/guidance/ → <skillsDir>/_guidance/ (v2.1.3+).
+// Underscore prefix keeps these internal — orchestrator-injected situational
+// guidance for core epics, never registered as user-facing skills.
+function installGuidance(skillsDir) {
+  if (!fs.existsSync(GUIDANCE_SOURCE_DIR)) return;
+  const guidanceDest = path.join(skillsDir, '_guidance');
+  copyRecursive(GUIDANCE_SOURCE_DIR, guidanceDest);
+  console.log('  🧭 _guidance (design-patterns + domain-modeling)');
+}
+
+function ensureGitignoreEntry(skillsDir) {
   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);
+  const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+  if (existing.split('\n').some(line => line.trim() === entry)) return;
+
+  const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(gitignorePath, `${prefix}${entry}\n`);
+  console.log(`\n  📝 Added ${entry} to .gitignore`);
+}
+
+function copyRecursive(src, dest, skipPath) {
+  if (!fs.existsSync(src)) return;
+  if (skipPath && path.resolve(src) === path.resolve(skipPath)) return;
+
+  if (fs.statSync(src).isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const item of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, item), path.join(dest, item), skipPath);
+    }
+  } else {
+    fs.copyFileSync(src, dest);
   }
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Pure deep-merge: returns a new object. Recurses plain objects; arrays and
+// scalars are leaves with the override winning. Orphan override keys survive.
+function deepMerge(defaults, overrides) {
+  const merged = { ...defaults };
 
-  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`);
+  for (const key of Object.keys(overrides)) {
+    const defaultValue = defaults[key];
+    const overrideValue = overrides[key];
+
+    if (isPlainObject(defaultValue) && isPlainObject(overrideValue)) {
+      merged[key] = deepMerge(defaultValue, overrideValue);
+    } else {
+      merged[key] = overrideValue;
+    }
+  }
+
+  return merged;
+}
+
+function serializeConfig(config) {
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+// Three-branch config installer. Returns { action }:
+//   'default'   — dest absent, default copied verbatim.
+//   'merged'    — dest valid JSON, deep-merged with user values winning.
+//   'recovered' — dest invalid JSON, backed up to .bak, default written.
+function installConfig(defaultPath, destPath) {
+  const defaults = JSON.parse(fs.readFileSync(defaultPath, 'utf8'));
+
+  if (!fs.existsSync(destPath)) {
+    fs.writeFileSync(destPath, serializeConfig(defaults));
+    return { action: 'default' };
   }
+
+  const rawDest = fs.readFileSync(destPath, 'utf8');
+  const userConfig = parseConfig(rawDest);
+
+  if (userConfig === undefined) {
+    fs.copyFileSync(destPath, `${destPath}.bak`);
+    fs.writeFileSync(destPath, serializeConfig(defaults));
+    return { action: 'recovered' };
+  }
+
+  fs.writeFileSync(destPath, serializeConfig(deepMerge(defaults, userConfig)));
+  return { action: 'merged' };
+}
+
+function parseConfig(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+if (require.main === module) {
+  main();
 }
 
-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');
+module.exports = { deepMerge, installConfig, installSkills, installGuidance };

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@houseofwolvesllc/claude-scrum-skill",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "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": {},
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "postinstall": "node bin/install.js"
+    "postinstall": "node bin/install.js",
+    "test": "node --test"
   },
   "keywords": [
     "claude",

package/skills/project-orchestrate/SKILL.md

@@ -17,7 +17,7 @@ Fully autonomous project lifecycle driver. Plans sprints, executes stories via p
 2. Read `../shared/config.json` to determine the scaffolding mode (`scaffolding` key: `"local"`, `"github"`, `"jira"`, or `"trello"`, default: `"local"`). If `"local"`, also read the `paths.backlog` and `paths.context` values (`paths.context` defaults to `.claude-scrum-skill/context` and is where Step 3 subagents look for per-epic CONTEXT.md files). Read `../shared/references/PROVIDERS.md` for provider-specific API commands when using a remote provider.
 3. 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.
 3a. Read `../shared/references/ENGINEERING_BASELINE.md` — the universal engineering baseline (Clean Code, Test-Driven Development, and the simple-design Arbitration Rule). It applies to **all** work this orchestration drives, across every epic and story. Resolve its absolute path; you will pass it to the sprint pipeline as `baselinePath` so every implementation and review subagent follows it. Order of precedence: project `CLAUDE.md` > engineering baseline > situational guidance (`design-patterns`, `domain-modeling`).
-3b. **Subdomain classification gates situational guidance.** `/project-spec` classifies each epic as `core`, `supporting`, or `generic`, and `/project-scaffold` persists that classification into epic metadata: the `subdomain` field of each `_epic.md` frontmatter (local mode) or a `subdomain:<value>` label on the epic's issues (remote modes). Read the classification from that epic metadata — the single authoritative source — and do NOT re-derive it. At implementation time, only **`core`** epics receive the situational guidance skills (`design-patterns`, `domain-modeling`); `supporting`, `generic`, and unclassified epics get the baseline only. Resolve the absolute `SKILL.md` paths for the `design-patterns` and `domain-modeling` skills so you can pass them as `situationalGuidance` for core epics.
+3b. **Subdomain classification gates situational guidance.** `/project-spec` classifies each epic as `core`, `supporting`, or `generic`, and `/project-scaffold` persists that classification into epic metadata: the `subdomain` field of each `_epic.md` frontmatter (local mode) or a `subdomain:<value>` label on the epic's issues (remote modes). Read the classification from that epic metadata — the single authoritative source — and do NOT re-derive it. At implementation time, only **`core`** epics receive the situational guidance skills (`design-patterns`, `domain-modeling`); `supporting`, `generic`, and unclassified epics get the baseline only. The two guidance files ship in the non-registered `_guidance/` directory — the same mechanism `_workflows/` uses, where the underscore prefix keeps Claude Code from registering them as user-facing skills. Their absolute paths are `<skills-root>/_guidance/design-patterns/SKILL.md` and `<skills-root>/_guidance/domain-modeling/SKILL.md`, where `<skills-root>` is the parent directory of this SKILL.md's parent (for a SKILL.md at `~/.claude/skills/project-orchestrate/SKILL.md`, `<skills-root>` is `~/.claude/skills`). The same algorithm works for global, local, and plugin install layouts. Pass these two paths as `situationalGuidance` for core epics — there is exactly one place to look, no `node_modules` hunting.
 4. Read `../shared/references/PERSONAS.md` for role preambles. When spawning
    subagents, select the persona matching each story's `persona:*` label (GitHub mode)
    or `persona` frontmatter field (local mode). If no persona exists, use `impl` (the default).
@@ -412,7 +412,7 @@ backendMode:        local | github | jira | trello
 repoIdentifier:     <owner/repo> (github mode only)
 personaPreambles:   { impl: "...", ops: "...", research: "..." }
 baselinePath:       <absolute path to shared/references/ENGINEERING_BASELINE.md> (always set; applies to every story)
-situationalGuidance: <array of absolute SKILL.md paths for design-patterns and domain-modeling — set ONLY when the current epic's subdomain is `core`; omit or pass [] for supporting/generic/untagged epics>
+situationalGuidance: <the two guidance SKILL.md paths from the non-registered _guidance/ directory — `<skills-root>/_guidance/design-patterns/SKILL.md` and `<skills-root>/_guidance/domain-modeling/SKILL.md` (resolve `<skills-root>` per Step 3b) — set ONLY when the current epic's subdomain is `core`; omit or pass [] for supporting/generic/untagged epics>
 ```
 
 Wait for the workflow to return. The return is `SprintStoryReturn[]` — one entry per completed (or blocked / failed) story per `lib/workflows/schemas/SprintStoryReturnSchema.json`.