bigpowers 2.87.2 → 2.87.3

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.87.2",
+  "version": "2.87.3",
   "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,10 @@
+## [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.3",
   "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/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/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": {