bigpowers 2.87.2 → 2.87.4

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.87.2",
+  "version": "2.87.4",
   "description": "81 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.87.4](https://github.com/danielvm-git/bigpowers/compare/v2.87.3...v2.87.4) (2026-08-07)
+
+
+### Bug Fixes
+
+* **install:** uninstall menu now removes symlinks for all 18 tools and local installs ([#110](https://github.com/danielvm-git/bigpowers/issues/110)) ([5e8ae1c](https://github.com/danielvm-git/bigpowers/commit/5e8ae1ccd6a127502edde2b0dfb93a28609e82a3))
+
+## [2.87.3](https://github.com/danielvm-git/bigpowers/compare/v2.87.2...v2.87.3) (2026-08-07)
+
+
+### Bug Fixes
+
+* **skills:** pi no longer drops 16 skills — story tags moved inside frontmatter ([#108](https://github.com/danielvm-git/bigpowers/issues/108)) ([3d4f0cf](https://github.com/danielvm-git/bigpowers/commit/3d4f0cf33a0497a45bc525330fc048a5b2715e33))
+
 ## [2.87.2](https://github.com/danielvm-git/bigpowers/compare/v2.87.1...v2.87.2) (2026-08-05)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.87.2",
+  "version": "2.87.4",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/lib/install-helpers.js

@@ -404,23 +404,23 @@ function installLocal(tool, repoRoot) {
 
 function uninstallTool(toolId, repoRoot) {
   const homeDir = require('os').homedir();
+  // installLocal() resolves its own targets from process.cwd() at call time
+  // (bin/setup.js never passes a mode/cwd into uninstallTool), so the
+  // interactive Uninstall menu — which offers no global/local choice — must
+  // clean whichever scope was actually installed into. Previously this
+  // function only ever touched homeDir: a local install (`bigpowers install`
+  // → Local) was reported as "removed" but every local symlink survived.
+  const cwd = process.cwd();
 
   switch (toolId) {
     case 'claude': {
-      const skillsDir = path.join(homeDir, '.claude', 'skills');
-      if (fs.existsSync(skillsDir)) {
-        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-          if (!entry.isSymbolicLink()) continue;
-          const target = fs.readlinkSync(path.join(skillsDir, entry.name));
-          if (target.startsWith(repoRoot)) {
-            removeSymlink(path.join(skillsDir, entry.name));
-          }
-        }
-      }
+      removeRepoRootedSkillLinks(path.join(homeDir, '.claude', 'skills'), repoRoot);
       const hooksDir = path.join(homeDir, '.claude', 'hooks');
       removeSymlink(path.join(hooksDir, 'block-dangerous-git.sh'));
       removeSymlink(path.join(hooksDir, 'rtk-rewrite.sh'));
       removeSymlink(path.join(hooksDir, 'lib'));
+      // installLocal('claude') only links skills/ (no hooks) into cwd/.claude/skills
+      removeRepoRootedSkillLinks(path.join(cwd, '.claude', 'skills'), repoRoot);
       break;
     }
     case 'gemini':
@@ -434,18 +434,12 @@ function uninstallTool(toolId, repoRoot) {
       ]) {
         removeSymlink(path.join(homeDir, '.gemini', 'hooks', hookFile));
       }
+      // installLocal('gemini') links repoRoot/.gemini/extensions/bigpowers into cwd
+      removeSymlink(path.join(cwd, '.gemini', 'extensions', 'bigpowers'));
       break;
     case 'pi': {
-      const skillsDir = path.join(homeDir, '.pi', 'agent', 'skills');
-      if (fs.existsSync(skillsDir)) {
-        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-          if (!entry.isSymbolicLink()) continue;
-          const target = fs.readlinkSync(path.join(skillsDir, entry.name));
-          if (target.startsWith(repoRoot)) {
-            removeSymlink(path.join(skillsDir, entry.name));
-          }
-        }
-      }
+      removeRepoRootedSkillLinks(path.join(homeDir, '.pi', 'agent', 'skills'), repoRoot);
+      removeRepoRootedSkillLinks(path.join(cwd, '.pi', 'agent', 'skills'), repoRoot);
       break;
     }
     case 'hermes': {
@@ -460,6 +454,17 @@ function uninstallTool(toolId, repoRoot) {
         }
       }
       removeSymlink(path.join(homeDir, '.hermes', 'hooks', 'session-log'));
+      // installLocal('hermes') renders skills into cwd/.hermes/skills (no hook locally)
+      const localSkillsDir = path.join(cwd, '.hermes', 'skills');
+      if (fs.existsSync(localSkillsDir)) {
+        for (const entry of fs.readdirSync(localSkillsDir, { withFileTypes: true })) {
+          if (!entry.isSymbolicLink()) continue;
+          const target = fs.readlinkSync(path.join(localSkillsDir, entry.name));
+          if (target.startsWith(repoRoot) || target.includes('.hermes/skills')) {
+            removeSymlink(path.join(localSkillsDir, entry.name));
+          }
+        }
+      }
       break;
     }
     case 'zcode': {
@@ -474,6 +479,8 @@ function uninstallTool(toolId, repoRoot) {
         }
       }
       removeSymlink(path.join(homeDir, '.zcode', 'AGENTS.md'));
+      removeManagedSkillLinks(path.join(cwd, '.zcode', 'skills'), repoRoot);
+      removeSymlink(path.join(cwd, '.zcode', 'AGENTS.md'));
       break;
     }
     case 'mimo': {
@@ -488,6 +495,8 @@ function uninstallTool(toolId, repoRoot) {
         }
       }
       removeSymlink(path.join(homeDir, '.mimocode', 'AGENTS.md'));
+      removeManagedSkillLinks(path.join(cwd, '.mimocode', 'skills'), repoRoot);
+      removeSymlink(path.join(cwd, '.mimocode', 'AGENTS.md'));
       break;
     }
     case 'antigravity':
@@ -502,10 +511,20 @@ function uninstallTool(toolId, repoRoot) {
           }
         }
       }
+      // installLocal('antigravity') renders into cwd/.agents/skills and — only
+      // if absent — symlinks cwd/AGENTS.md. Skip the local skills dir entirely
+      // when cwd === repoRoot: that's this repo's own tracked .agents/skills
+      // source tree (the installer's rendered-skill INPUT), not an install
+      // target, and must never be touched by uninstall.
+      if (cwd !== repoRoot) {
+        removeManagedSkillLinks(path.join(cwd, '.agents', 'skills'), repoRoot);
+      }
+      removeSymlink(path.join(cwd, 'AGENTS.md'));
       break;
     }
     case 'cursor':
       removeSymlink(path.join(homeDir, '.cursor', 'rules'));
+      removeSymlink(path.join(cwd, '.cursor', 'rules'));
       break;
     case 'codex':
       {
@@ -518,7 +537,60 @@ function uninstallTool(toolId, repoRoot) {
         }
       }
       removeSymlink(path.join(homeDir, '.codex', 'hooks', 'pre-tool-git-guard.sh'));
+      removeSymlink(path.join(homeDir, '.codex', 'AGENTS.md'));
+      // installLocal('codex') only symlinks cwd/.codex/AGENTS.md (no skills/hooks locally)
+      removeSymlink(path.join(cwd, '.codex', 'AGENTS.md'));
       break; // story: e65s02
+    case 'qwen':
+      removeManagedSkillLinks(path.join(homeDir, '.qwen', 'skills'), repoRoot);
+      removeSymlink(path.join(homeDir, '.qwen', 'QWEN.md'));
+      removeSymlink(path.join(homeDir, '.qwen', 'hooks', 'pre-tool-git-guard.sh'));
+      break; // story: e68s02
+    case 'codebuddy':
+      removeManagedSkillLinks(path.join(homeDir, '.codebuddy', 'skills'), repoRoot);
+      removeSymlink(path.join(homeDir, '.codebuddy', 'AGENTS.md'));
+      removeSymlink(path.join(homeDir, '.codebuddy', 'hooks', 'pre-tool-git-guard.sh'));
+      break; // story: e72s02
+    case 'cline':
+      removeManagedSkillLinks(path.join(homeDir, '.cline', 'skills'), repoRoot);
+      break; // story: e66s02
+    case 'kilo':
+    case 'kilocode': {
+      const rulesDir = path.join(homeDir, '.kilocode', 'rules');
+      if (fs.existsSync(rulesDir)) {
+        for (const f of fs.readdirSync(rulesDir)) {
+          if (!f.endsWith('.md')) continue;
+          removeSymlink(path.join(rulesDir, f));
+        }
+      }
+      removeManagedFile(path.join(homeDir, '.kilocode', 'AGENTS.md'));
+      break; // story: e67s02
+    }
+    case 'trae':
+      removeManagedSkillLinks(path.join(homeDir, '.trae', 'skills'), repoRoot);
+      removeSymlink(path.join(homeDir, '.trae', 'AGENTS.md'));
+      removeSymlink(path.join(homeDir, '.trae', 'hooks', 'pre-tool-git-guard.sh'));
+      break; // story: e70s02
+    case 'windsurf': {
+      const rulesDir = path.join(homeDir, '.codeium', 'windsurf', 'rules');
+      if (fs.existsSync(rulesDir)) {
+        for (const f of fs.readdirSync(rulesDir)) {
+          if (!f.endsWith('.md')) continue;
+          removeSymlink(path.join(rulesDir, f));
+        }
+      }
+      removeManagedFile(path.join(homeDir, '.codeium', 'windsurf', 'AGENTS.md'));
+      removeSymlink(path.join(homeDir, '.codeium', 'windsurf', 'hooks', 'pre-tool-git-guard.sh'));
+      break; // story: e73s02
+    }
+    case 'opencode':
+      removeManagedSkillLinks(path.join(homeDir, '.config', 'opencode', 'skills'), repoRoot);
+      removeSymlink(path.join(homeDir, '.config', 'opencode', 'AGENTS.md'));
+      break; // story: e62s02
+    case 'copilot':
+      removeManagedSkillLinks(path.join(homeDir, '.copilot', 'skills'), repoRoot);
+      removeManagedFile(path.join(homeDir, '.copilot', 'AGENTS.md'));
+      break; // story: e71s02
   }
 }
 
@@ -533,6 +605,61 @@ function removeSymlink(p) {
   return false;
 }
 
+// Strict variant of removeManagedSkillLinks: only removes symlinks whose
+// target starts with THIS repoRoot exactly (no 'bigpowers' substring match).
+// Used for claude/pi, where a looser match could delete symlinks pointing at
+// an unrelated bigpowers checkout elsewhere on disk (e.g. a second clone).
+function removeRepoRootedSkillLinks(skillsDir, repoRoot) {
+  if (!fs.existsSync(skillsDir)) return;
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isSymbolicLink()) continue;
+    const linkPath = path.join(skillsDir, entry.name);
+    let target;
+    try {
+      target = fs.readlinkSync(linkPath);
+    } catch {
+      continue;
+    }
+    if (target.startsWith(repoRoot)) {
+      removeSymlink(linkPath);
+    }
+  }
+}
+
+// Remove bigpowers-managed skill symlinks from a tool's skills dir. Only touches
+// symlinks that resolve back into the repo (installGlobal creates them via
+// linkRenderedSkills → linkDir), leaving any user-authored entries alone.
+function removeManagedSkillLinks(skillsDir, repoRoot) {
+  if (!fs.existsSync(skillsDir)) return;
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isSymbolicLink()) continue;
+    const linkPath = path.join(skillsDir, entry.name);
+    let target;
+    try {
+      target = fs.readlinkSync(linkPath);
+    } catch {
+      continue;
+    }
+    if (target.startsWith(repoRoot) || target.includes('bigpowers')) {
+      removeSymlink(linkPath);
+    }
+  }
+}
+
+// Remove a file the installer placed as a plain copy (kilo/windsurf/copilot use
+// fs.copyFileSync for AGENTS.md, so removeSymlink would skip it). Also handles
+// the symlink case so it's safe on either install shape.
+function removeManagedFile(p) {
+  try {
+    const stat = fs.lstatSync(p);
+    if (stat.isSymbolicLink() || stat.isFile()) {
+      fs.unlinkSync(p);
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
 function detectExistingInstall() {
   const homeDir = require('os').homedir();
   const marker = path.join(homeDir, '.claude', 'skills', 'survey-context');

package/scripts/lib/skill-common.sh

@@ -48,6 +48,9 @@ parse_frontmatter() {
     fi
     [ "$in_block" -ne 1 ] && continue
 
+    # Skip comment lines (e.g. # story: tags inside the frontmatter block)
+    [[ "$line" == \#* || "$line" == \<\!--* ]] && continue
+
     case "$line" in
       name:*)
         name="${line#name: }"
@@ -76,6 +79,8 @@ parse_frontmatter() {
       continue
     fi
     [ "$continued" -eq 0 ] && continue
+    # Skip comment lines (e.g. # story: tags inside the frontmatter block)
+    [[ "$line" == \#* || "$line" == \<\!--* ]] && continue
     # If next field starts (unindented key:), stop
     [[ "$line" =~ ^[a-zA-Z_]+: ]] && break
     desc="$desc $line"
@@ -103,7 +108,7 @@ parse_frontmatter_okf() {
   _PF_NAME=$(awk '/^---/{f++} f==1 && /^name:/{print; exit}' "$file" | sed 's/^name:[[:space:]]*//')
   _PF_MODEL=$(awk '/^---/{f++} f==1 && /^model:/{print; exit}' "$file" | sed 's/^model:[[:space:]]*//')
   _PF_EFFORT=$(awk '/^---/{f++} f==1 && /^effort:/{print; exit}' "$file" | sed 's/^effort:[[:space:]]*//')
-  _PF_DESCRIPTION=$(awk '/^---/{f++; next} f==1 && /^description:/{p=1; sub(/^description:[[:space:]]*/,""); print; next} f==1 && p && /^[a-z]+:/{exit} f==1 && p{print}' "$file" \
+  _PF_DESCRIPTION=$(awk '/^---/{f++; next} f==1 && /^description:/{p=1; sub(/^description:[[:space:]]*/,""); print; next} f==1 && p && /^[a-z]+:/{exit} f==1 && p && !/^[[:space:]]*#/ && !/^[[:space:]]*<!--/{print}' "$file" \
     | tr -d '\n' \
     | sed -E 's/[[:space:]]+/ /g')
 

package/scripts/test-install-helpers.js

@@ -87,6 +87,116 @@ try {
   uninstallTool('cursor', ROOT);
   assert.ok(!fs.existsSync(rulesDst), 'uninstallTool(cursor) must remove rules symlink');
 
+  // Regression: every tool the uninstall menu offers must have a real uninstall
+  // path. Before this, qwen/codebuddy/cline/kilo/trae/windsurf/opencode/copilot
+  // had install cases but no uninstall case — uninstall reported success while
+  // leaving every symlink in place.
+  installGlobal({ id: 'qwen', name: 'Qwen Code' }, ROOT);
+  const qwenSkills = path.join(tmpHome, '.qwen', 'skills');
+  const qwenSample = fs.existsSync(qwenSkills)
+    && fs.readdirSync(qwenSkills).find((n) => {
+      try { return fs.lstatSync(path.join(qwenSkills, n)).isSymbolicLink(); } catch { return false; }
+    });
+  assert.ok(qwenSample, 'qwen install must create at least one skill symlink');
+  uninstallTool('qwen', ROOT);
+  assert.ok(
+    !fs.existsSync(path.join(qwenSkills, qwenSample)),
+    'uninstallTool(qwen) must remove repo-rooted skill symlinks'
+  );
+
+  // copilot writes AGENTS.md as a plain copy (not a symlink); uninstall must
+  // still remove it via removeManagedFile.
+  installGlobal({ id: 'copilot', name: 'Copilot' }, ROOT);
+  const copilotAgents = path.join(tmpHome, '.copilot', 'AGENTS.md');
+  const copilotHadAgents = fs.existsSync(copilotAgents);
+  uninstallTool('copilot', ROOT);
+  if (copilotHadAgents) {
+    assert.ok(!fs.existsSync(copilotAgents), 'uninstallTool(copilot) must remove copied AGENTS.md');
+  }
+  const copilotSkills = path.join(tmpHome, '.copilot', 'skills');
+  if (fs.existsSync(copilotSkills)) {
+    const leftover = fs.readdirSync(copilotSkills).find((n) => {
+      try { return fs.lstatSync(path.join(copilotSkills, n)).isSymbolicLink(); } catch { return false; }
+    });
+    assert.ok(!leftover, 'uninstallTool(copilot) must remove skill symlinks');
+  }
+
+  // Regression: uninstallTool() only ever touched homeDir. The interactive
+  // Uninstall menu (bin/setup.js handleUninstall) never asks global-vs-local
+  // and calls uninstallTool(toolId, ROOT) unconditionally — so a *local*
+  // install (`bigpowers install` → Local) was reported "removed" while every
+  // local symlink survived, for every tool. Verify local install/uninstall
+  // round-trips for tools spanning each install shape: skill-symlink dir
+  // (pi, claude), single linked dir (cursor, gemini), and a linked file
+  // (codex AGENTS.md).
+  const { installLocal } = require('../scripts/lib/install-helpers.js');
+  const savedCwd = process.cwd();
+  const tmpCwd = mkdtempSync(path.join(os.tmpdir(), 'bp-install-helpers-local-'));
+  try {
+    process.chdir(tmpCwd);
+
+    installLocal({ id: 'pi', name: 'pi' }, ROOT);
+    const localPiSkills = path.join(tmpCwd, '.pi', 'agent', 'skills');
+    const localPiSample = fs.readdirSync(localPiSkills).find((n) => {
+      try { return fs.lstatSync(path.join(localPiSkills, n)).isSymbolicLink(); } catch { return false; }
+    });
+    assert.ok(localPiSample, 'local pi install must create at least one skill symlink');
+    uninstallTool('pi', ROOT);
+    assert.ok(
+      !fs.existsSync(path.join(localPiSkills, localPiSample)),
+      'uninstallTool(pi) must also remove LOCAL (cwd) skill symlinks, not just global'
+    );
+
+    installLocal({ id: 'claude', name: 'Claude Code' }, ROOT);
+    const localClaudeSkills = path.join(tmpCwd, '.claude', 'skills');
+    const localClaudeSample = fs.readdirSync(localClaudeSkills).find((n) => {
+      try { return fs.lstatSync(path.join(localClaudeSkills, n)).isSymbolicLink(); } catch { return false; }
+    });
+    assert.ok(localClaudeSample, 'local claude install must create at least one skill symlink');
+    uninstallTool('claude', ROOT);
+    assert.ok(
+      !fs.existsSync(path.join(localClaudeSkills, localClaudeSample)),
+      'uninstallTool(claude) must also remove LOCAL (cwd) skill symlinks, not just global'
+    );
+
+    installLocal({ id: 'cursor', name: 'Cursor' }, ROOT);
+    const localCursorRules = path.join(tmpCwd, '.cursor', 'rules');
+    assert.ok(fs.lstatSync(localCursorRules).isSymbolicLink(), 'local cursor install must symlink .cursor/rules');
+    uninstallTool('cursor', ROOT);
+    assert.ok(!fs.existsSync(localCursorRules), 'uninstallTool(cursor) must remove LOCAL .cursor/rules symlink');
+
+    installLocal({ id: 'gemini', name: 'Gemini' }, ROOT);
+    const localGeminiExt = path.join(tmpCwd, '.gemini', 'extensions', 'bigpowers');
+    assert.ok(fs.lstatSync(localGeminiExt).isSymbolicLink(), 'local gemini install must symlink extensions/bigpowers');
+    uninstallTool('gemini', ROOT);
+    assert.ok(!fs.existsSync(localGeminiExt), 'uninstallTool(gemini) must remove LOCAL extensions/bigpowers symlink');
+
+    installLocal({ id: 'codex', name: 'Codex' }, ROOT);
+    const localCodexAgents = path.join(tmpCwd, '.codex', 'AGENTS.md');
+    assert.ok(fs.lstatSync(localCodexAgents).isSymbolicLink(), 'local codex install must symlink AGENTS.md');
+    uninstallTool('codex', ROOT);
+    assert.ok(!fs.existsSync(localCodexAgents), 'uninstallTool(codex) must remove LOCAL AGENTS.md symlink');
+  } finally {
+    process.chdir(savedCwd);
+    rmSync(tmpCwd, { recursive: true, force: true });
+  }
+
+  // Guard against future drift: assert the menu's supported set matches the
+  // uninstall switch. Any id in SUPPORTED_IDS with no uninstall case regresses
+  // this bug (silent no-op reported as success).
+  const helpersSrc = fs.readFileSync(path.join(ROOT, 'scripts', 'lib', 'install-helpers.js'), 'utf8');
+  const uninstallBody = helpersSrc.slice(helpersSrc.indexOf('function uninstallTool'));
+  const setupText = fs.readFileSync(path.join(ROOT, 'bin/setup.js'), 'utf8');
+  const supportedLine = setupText.match(/const SUPPORTED_IDS = new Set\(\[([^\]]*)\]\)/);
+  assert.ok(supportedLine, 'SUPPORTED_IDS must be declarable from bin/setup.js');
+  const supportedIds = supportedLine[1].match(/'([^']+)'/g).map((s) => s.replace(/'/g, ''));
+  for (const id of supportedIds) {
+    assert.ok(
+      new RegExp(`case '${id}':`).test(uninstallBody),
+      `uninstallTool must handle '${id}' (listed in SUPPORTED_IDS) — else uninstall silently no-ops`
+    );
+  }
+
   const installPaths = [
     path.join(ROOT, 'scripts', 'install.sh'),
     ...fs.readdirSync(path.join(ROOT, 'scripts', 'lib'))

package/scripts/validate-skill-yaml.py

@@ -1,5 +1,21 @@
 #!/usr/bin/env python3
-"""Validate YAML frontmatter in all .pi/skills/*/SKILL.md files."""
+"""Validate YAML frontmatter in SKILL.md files (sources + generated .pi/skills).
+
+Rules per file (sources and generated copies alike):
+
+  R1  file must start with the frontmatter delimiter '---' at byte 0.
+      pi (dist/utils/frontmatter.js) and the Agent Skills spec require the
+      opening delimiter to be the first characters of the file. Story tags
+      (`# story:` / `<!-- story: -->`) must live INSIDE the frontmatter block
+      as YAML comments, or below the closing delimiter — never above it,
+      or pi drops the skill as "description is required".
+      (story: BUG-2026-08-06-pi-drops-skills-frontmatter)
+  R2  frontmatter must parse as YAML (PyYAML or bundled simple_yaml).
+  R3  description must not embed 'model: sonnet' as literal text.
+
+Exits 1 on any failure. Called by the sync-skills.sh post-generation guard
+and by scripts/test-setup-no-pyyaml.sh.
+"""
 import glob
 import sys
 import os
@@ -17,64 +33,99 @@ except ModuleNotFoundError:
     from simple_yaml import parse_simple_yaml
     _load_yaml = parse_simple_yaml
 
-SKILLS_DIR = ".pi/skills"
-files = sorted(glob.glob(f"{SKILLS_DIR}/*/SKILL.md"))
+# Source of truth (skills/*/SKILL.md) and the pi-distributed copy (.pi/skills).
+SKILL_ROOTS = ["skills", ".pi/skills"]
+
+
+def validate_tree(root):
+    """Return (passed, delimiter_failures, parse_failures, semantic_failures)."""
+    files = sorted(glob.glob(os.path.join(root, "*/SKILL.md")))
+    parse_failures = []
+    semantic_failures = []
+    delimiter_failures = []
+    passed = []
+
+    for path in files:
+        skill_name = os.path.basename(os.path.dirname(path))
+        with open(path) as f:
+            content = f.read()
+
+        # R1 — pi's frontmatter gate: opening delimiter must be at byte 0.
+        if not content.startswith("---"):
+            delimiter_failures.append((skill_name, "file must start with '---' (story tags belong inside the frontmatter block or below it)"))
+            continue
 
-parse_failures = []
-semantic_failures = []
-passed = []
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            parse_failures.append((skill_name, "missing frontmatter delimiters"))
+            continue
 
-for path in files:
-    skill_name = os.path.basename(os.path.dirname(path))
-    with open(path) as f:
-        content = f.read()
+        frontmatter = parts[1]
 
-    parts = content.split("---", 2)
-    if len(parts) < 3:
-        parse_failures.append((skill_name, "missing frontmatter delimiters"))
-        continue
+        try:
+            data = _load_yaml(frontmatter)
+        except Exception as e:
+            parse_failures.append((skill_name, str(e).split("\n")[0]))
+            continue
 
-    frontmatter = parts[1]
+        if data is None:
+            parse_failures.append((skill_name, "empty frontmatter"))
+            continue
 
-    try:
-        data = _load_yaml(frontmatter)
-    except Exception as e:
-        parse_failures.append((skill_name, str(e).split("\n")[0]))
-        continue
+        # R3 — semantic check: model hint embedded in description
+        desc = data.get("description", "")
+        if desc and "model: sonnet" in desc:
+            semantic_failures.append(skill_name)
 
-    if data is None:
-        parse_failures.append((skill_name, "empty frontmatter"))
-        continue
+        passed.append(skill_name)
 
-    # Semantic check: model hint embedded in description
-    desc = data.get("description", "")
-    if desc and "model: sonnet" in desc:
-        semantic_failures.append(skill_name)
+    return passed, delimiter_failures, parse_failures, semantic_failures
 
-    passed.append(skill_name)
 
-# Report
-print(f"Total SKILL.md files: {len(files)}")
-print(f"Parse OK: {len(passed)}")
-print(f"Parse FAIL: {len(parse_failures)}")
-print(f"Semantic issues (model in desc): {len(semantic_failures)}")
+all_passed = []
+all_delimiter = []
+all_parse = []
+all_semantic = []
+
+for root in SKILL_ROOTS:
+    passed, delimiter_failures, parse_failures, semantic_failures = validate_tree(root)
+    all_passed += passed
+    all_delimiter += delimiter_failures
+    all_parse += parse_failures
+    all_semantic += semantic_failures
+    total = len(passed) + len(delimiter_failures) + len(parse_failures) + len(semantic_failures)
+    print(f"[{root}] SKILL.md files: {total} — parse OK: {len(passed)}")
+
+print()
+print(f"Total SKILL.md files: {len(all_passed) + len(all_delimiter) + len(all_parse) + len(all_semantic)}")
+print(f"Parse OK: {len(all_passed)}")
+print(f"Delimiter FAIL (must start with '---'): {len(all_delimiter)}")
+print(f"Parse FAIL: {len(all_parse)}")
+print(f"Semantic issues (model in desc): {len(all_semantic)}")
 print()
 
-if parse_failures:
+if all_delimiter:
+    print("=== DELIMITER FAILURES (file does not start with '---') ===")
+    for name, err in all_delimiter:
+        print(f"  {name}: {err}")
+    print()
+
+if all_parse:
     print("=== PARSE FAILURES ===")
-    for name, err in parse_failures:
+    for name, err in all_parse:
         print(f"  {name}: {err}")
     print()
 
-if semantic_failures:
+if all_semantic:
     print("=== SEMANTIC ISSUES (model embedded in description) ===")
-    for name in sorted(semantic_failures):
+    for name in sorted(all_semantic):
         print(f"  {name}")
     print()
 
-if parse_failures or semantic_failures:
-    print(f"FAIL: {len(parse_failures)} parse + {len(semantic_failures)} semantic issues")
+if all_delimiter or all_parse or all_semantic:
+    n = len(all_delimiter) + len(all_parse) + len(all_semantic)
+    print(f"FAIL: {n} issues ({len(all_delimiter)} delimiter + {len(all_parse)} parse + {len(all_semantic)} semantic)")
     sys.exit(1)
 else:
-    print("PASS: all SKILL.md YAML frontmatter valid")
+    print("PASS: all SKILL.md YAML frontmatter valid (sources + .pi/skills)")
     sys.exit(0)

package/skills/audit-code/SKILL.md

@@ -1,7 +1,7 @@
+---
 # story: e51s04
 # story: e45s18
 # story: e45s31
----
 name: audit-code
 model: haiku
 effort: standard

package/skills/craft-skill/SKILL.md

@@ -1,7 +1,7 @@
-# story: e45s02
-<!-- story: e45s12 -->
-<!-- story: e79s02 -->
 ---
+# story: e45s02
+# story: e45s12
+# story: e79s02
 name: craft-skill
 model: sonnet
 effort: standard

package/skills/deepen-architecture/SKILL.md

@@ -1,6 +1,6 @@
-# story: e45s31
-<!-- story: e45s14 -->
 ---
+# story: e45s31
+# story: e45s14
 name: deepen-architecture
 model: sonnet
 effort: standard

package/skills/deploy/SKILL.md

@@ -1,5 +1,5 @@
-<!-- story: e45s15 -->
 ---
+# story: e45s15
 name: deploy
 description: "Build → verify artifact → deploy → wait → smoke deployment pipeline. Platform-agnostic (MCP or CLI), with configurable timeout, retry with exponential backoff, and integrated health-check. The deploy half of CI/CD: run after build to push to production."
 model: sonnet

package/skills/develop-tdd/SKILL.md

@@ -1,10 +1,10 @@
+---
 # story: e80s01
 # story: e80s03
 # story: e51s04
 # story: e45s06
 # story: e45s08
 # story: e45s34
----
 name: develop-tdd
 model: sonnet
 effort: standard

package/skills/diagnose-stall/SKILL.md

@@ -1,5 +1,5 @@
-# story: e45s38
 ---
+# story: e45s38
 name: diagnose-stall
 model: haiku
 effort: light

package/skills/enforce-first/SKILL.md

@@ -1,5 +1,5 @@
-# story: e80s01
 ---
+# story: e80s01
 name: enforce-first
 model: haiku
 effort: standard

package/skills/fix-bug/SKILL.md

@@ -1,5 +1,5 @@
-# story: e51s04
 ---
+# story: e51s04
 name: fix-bug
 model: sonnet
 effort: standard

package/skills/gate-trace/SKILL.md

@@ -1,6 +1,6 @@
+---
 # story: e80s01
 # story: e45s05
----
 name: gate-trace
 description: "Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability."
 # story: e38s06

package/skills/plan-work/SKILL.md

@@ -1,9 +1,9 @@
+---
 # story: e45s04
 # story: e45s06
 # story: e45s09
 # story: e45s33
 # story: e45s35
----
 name: plan-work
 model: opus
 effort: standard

package/skills/quick-fix/SKILL.md

@@ -1,5 +1,5 @@
-# story: e51s04
 ---
+# story: e51s04
 name: quick-fix
 description: "Streamlined fast-path for trivial data-only fixes — no TDD, no branching ceremony. Collapses 6 skills into 2 for changes that are purely data with no logic risk. Aborts with fallback to investigate-bug if guardrails trigger."
 model: sonnet

package/skills/request-review/SKILL.md

@@ -1,7 +1,7 @@
-# story: e45s07
-<!-- story: e45s07 -->
-<!-- story: e45s17 -->
 ---
+# story: e45s07
+# story: e45s07
+# story: e45s17
 name: request-review
 model: opus
 effort: standard

package/skills/run-evals/SKILL.md

@@ -1,5 +1,5 @@
-# story: e45s37
 ---
+# story: e45s37
 name: run-evals
 description: Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs.
 model: sonnet

package/skills/smoke-test/SKILL.md

@@ -1,5 +1,5 @@
-# story: e80s02
 ---
+# story: e80s02
 name: smoke-test
 phase: verify
 description: "Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill."

package/skills/validate-contracts/SKILL.md

@@ -1,5 +1,5 @@
-# story: e80s02
 ---
+# story: e80s02
 name: validate-contracts
 phase: verify
 description: "Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy."

package/skills/validate-fix/SKILL.md

@@ -1,7 +1,7 @@
+---
 # story: e80s01
 # story: e80s04
 # story: e45s08
----
 name: validate-fix
 model: haiku
 effort: standard

package/skills-lock.json

@@ -13,7 +13,7 @@
     },
     "audit-code": {
       "description": "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check.",
-      "sha256": "b0342883680fee6c",
+      "sha256": "6c37decb8b323a18",
       "path": "skills/audit-codeSKILL.md"
     },
     "audit-plan": {
@@ -48,12 +48,12 @@
     },
     "craft-skill": {
       "description": "Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle.",
-      "sha256": "f3b08c24979f1857",
+      "sha256": "b1d4efb0dcecb204",
       "path": "skills/craft-skillSKILL.md"
     },
     "deepen-architecture": {
       "description": "Find deepening opportunities in a codebase, informed by the domain language in specs/tech-architecture/tech-stack.md and the decisions in specs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.",
-      "sha256": "da2760c0cb49a3e4",
+      "sha256": "ee41e4524031fee3",
       "path": "skills/deepen-architectureSKILL.md"
     },
     "define-language": {
@@ -73,7 +73,7 @@
     },
     "deploy": {
       "description": "\"Build → verify artifact → deploy → wait → smoke deployment pipeline. Platform-agnostic (MCP or CLI), with configurable timeout, retry with exponential backoff, and integrated health-check. The deploy half of CI/CD: run after build to push to production.\"",
-      "sha256": "ddfcbfbfc464c620",
+      "sha256": "d355906aff894cfc",
       "path": "skills/deploySKILL.md"
     },
     "design-interface": {
@@ -83,7 +83,7 @@
     },
     "develop-tdd": {
       "description": "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md).",
-      "sha256": "8b3934e2291b863d",
+      "sha256": "433c1315e6604899",
       "path": "skills/develop-tddSKILL.md"
     },
     "diagnose-root": {
@@ -93,7 +93,7 @@
     },
     "diagnose-stall": {
       "description": "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned.",
-      "sha256": "c0fe87349399c112",
+      "sha256": "983d5a3a922af07d",
       "path": "skills/diagnose-stallSKILL.md"
     },
     "dispatch-agents": {
@@ -113,7 +113,7 @@
     },
     "enforce-first": {
       "description": "Apply the F.I.R.S.T test quality rubric (per CONVENTIONS.md §Tests) to a test suite or individual tests. Use when develop-tdd is writing tests, when test quality needs to be checked, or when user mentions F.I.R.S.T or \"test quality\".",
-      "sha256": "1ec1183ee6377917",
+      "sha256": "567d0efaa59d1262",
       "path": "skills/enforce-firstSKILL.md"
     },
     "evolve-skill": {
@@ -138,12 +138,12 @@
     },
     "fix-bug": {
       "description": "Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect.",
-      "sha256": "8e9e5922211b7e3b",
+      "sha256": "575a3ce60745c5c3",
       "path": "skills/fix-bugSKILL.md"
     },
     "gate-trace": {
       "description": "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\"",
-      "sha256": "87e0c49ff90ec34c",
+      "sha256": "097c31ec960861ce",
       "path": "skills/gate-traceSKILL.md"
     },
     "generate-allure-report": {
@@ -238,7 +238,7 @@
     },
     "plan-work": {
       "description": "\"PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2).\"",
-      "sha256": "32c2bcaf16cb4ad2",
+      "sha256": "0558f03399e6b93f",
       "path": "skills/plan-workSKILL.md"
     },
     "publish-package": {
@@ -248,7 +248,7 @@
     },
     "quick-fix": {
       "description": "\"Streamlined fast-path for trivial data-only fixes — no TDD, no branching ceremony. Collapses 6 skills into 2 for changes that are purely data with no logic risk. Aborts with fallback to investigate-bug if guardrails trigger.\"",
-      "sha256": "6a1b70cb1530c428",
+      "sha256": "5631a3980b214748",
       "path": "skills/quick-fixSKILL.md"
     },
     "release-branch": {
@@ -258,7 +258,7 @@
     },
     "request-review": {
       "description": "Dispatch a fresh reviewer agent with a clean context to critique the code after audit-code passes. The reviewer has no shared state with the coding agent and gives a genuine second opinion. Use after audit-code passes, before committing, or when user wants an independent code review.",
-      "sha256": "f362641a467c3000",
+      "sha256": "f395a14585b78aaf",
       "path": "skills/request-reviewSKILL.md"
     },
     "research-first": {
@@ -283,7 +283,7 @@
     },
     "run-evals": {
       "description": "Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs.",
-      "sha256": "d20ba2bece1b1c72",
+      "sha256": "7bc7cfd24a41d9e3",
       "path": "skills/run-evalsSKILL.md"
     },
     "run-planning": {
@@ -338,7 +338,7 @@
     },
     "smoke-test": {
       "description": "\"Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill.\"",
-      "sha256": "050170d66ada581e",
+      "sha256": "407669c94dee6b53",
       "path": "skills/smoke-testSKILL.md"
     },
     "spike-prototype": {
@@ -373,12 +373,12 @@
     },
     "validate-contracts": {
       "description": "\"Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy.\"",
-      "sha256": "d93c9ae2953ac457",
+      "sha256": "6541a7f72b3f0493",
       "path": "skills/validate-contractsSKILL.md"
     },
     "validate-fix": {
       "description": "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says \"is this fixed?\", or before closing an investigation.",
-      "sha256": "f94972af3fd48e3e",
+      "sha256": "d7fac868ccbf5dbe",
       "path": "skills/validate-fixSKILL.md"
     },
     "verify-work": {