bigpowers 2.58.7 → 2.58.9

package/.pi/package.json

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

package/.pi/prompts/using-bigpowers.md

@@ -12,8 +12,9 @@ Welcome to **bigpowers** — a lifecycle of **70** agent skills for production-r
 ## Install
 
 ```bash
-npx bigpowers                  # one-shot setup
-npm install -g bigpowers       # global install, then run: bigpowers
+npx bigpowers setup           # one-shot setup
+npm install -g bigpowers       # global install
+bigpowers setup                # sync skills + link to your tools
 ```
 
 From source (contributors): `git clone` → `npm install` or `bash scripts/install.sh`.

package/.pi/skills/using-bigpowers/SKILL.md

@@ -14,8 +14,9 @@ Welcome to **bigpowers** — a lifecycle of **70** agent skills for production-r
 ## Install
 
 ```bash
-npx bigpowers                  # one-shot setup
-npm install -g bigpowers       # global install, then run: bigpowers
+npx bigpowers setup           # one-shot setup
+npm install -g bigpowers       # global install
+bigpowers setup                # sync skills + link to your tools
 ```
 
 From source (contributors): `git clone` → `npm install` or `bash scripts/install.sh`.

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.58.9](https://github.com/danielvm-git/bigpowers/compare/v2.58.8...v2.58.9) (2026-07-04)
+
+
+### Bug Fixes
+
+* **trace:** exclude backlog stories from strict P0 gate ([4341ea0](https://github.com/danielvm-git/bigpowers/commit/4341ea0360a74bf5955a25174827c19d5c996a94))
+
+## [2.58.8](https://github.com/danielvm-git/bigpowers/compare/v2.58.7...v2.58.8) (2026-07-04)
+
+
+### Bug Fixes
+
+* **release-pipeline:** stop YAML round-trip corruption, recover specs ([db09bbf](https://github.com/danielvm-git/bigpowers/commit/db09bbf34ed10092bd874cb7ce46af9de3fce563))
+
 ## [2.58.7](https://github.com/danielvm-git/bigpowers/compare/v2.58.6...v2.58.7) (2026-07-03)
 
 

package/CLAUDE.md

@@ -13,7 +13,7 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 
 | Action  | Command |
 |---------|---------|
-| Install | `npx bigpowers` or `npm install -g bigpowers` |
+| Install | `npm install -g bigpowers && bigpowers setup` |
 | Run     | `bash scripts/sync-skills.sh` |
 | Test    | N/A (documentation project) |
 | Build   | `bash scripts/install.sh` (from source) |

package/CONTRIBUTING.md

@@ -9,7 +9,7 @@ Be respectful, constructive, and patient. We're building tools for developers
 ## Before You Start
 
 1. **Read the docs.** Start with [`README.md`](README.md), [`CLAUDE.md`](CLAUDE.md), and [`CONVENTIONS.md`](CONVENTIONS.md). These define the project's architecture, conventions, and engineering standards.
-2. **Run bigpowers.** Install with `npx bigpowers` and walk through the experience as a user before contributing as a developer.
+2. **Run bigpowers.** Install with `npm install -g bigpowers && bigpowers setup` and walk through the experience as a user before contributing as a developer.
 3. **Understand the lifecycle.** bigpowers follows a 6-phase methodology: Discover → Elaborate → Plan → Build → Verify → Release. Read [`docs/WORKFLOW-SOP-v2.md`](docs/WORKFLOW-SOP-v2.md) for the full SOP.
 
 ## How to Contribute
@@ -66,8 +66,10 @@ Documentation is a first-class contribution. You don't need to write code to hel
 git clone https://github.com/danielvm-git/bigpowers.git
 cd bigpowers
 
-# Install dependencies + run postinstall sync
+# Install dependencies
 npm install
+# Sync skills and set up symlinks
+bash scripts/install.sh
 
 # Or manually:
 bash scripts/install.sh

package/GEMINI.md

@@ -13,7 +13,7 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 
 | Action  | Command |
 |---------|---------|
-| Install | `npx bigpowers` or `npm install -g bigpowers` |
+| Install | `npm install -g bigpowers && bigpowers setup` |
 | Run     | `bash scripts/sync-skills.sh` |
 | Test    | N/A (documentation project) |
 | Build   | `bash scripts/install.sh` (from source) |

package/README.md

@@ -36,12 +36,12 @@ After installing, ask your agent to run the `using-bigpowers` skill — it is th
 ### npm (recommended)
 
 ```bash
-# One-shot setup — downloads, syncs artifacts, and links skills to your tools
-npx bigpowers
-
-# Or install globally and run the setup command anytime
+# Global install (no lifecycle scripts — npm v10+ safe)
 npm install -g bigpowers
-bigpowers
+bigpowers setup     # runs sync + install, links skills to your tools
+
+# Or one-shot with npx
+npx bigpowers setup
 ```
 
 Both commands sync skill artifacts and link them to Claude Code, Gemini CLI, and Cursor (see [Prerequisites](#-prerequisites)).
@@ -50,10 +50,8 @@ Both commands sync skill artifacts and link them to Claude Code, Gemini CLI, and
 
 ```bash
 git clone https://github.com/danielvm-git/bigpowers.git && cd bigpowers
-npm install          # runs postinstall: sync + link
-# or manually:
+npm install
 bash scripts/install.sh
-npm run sync
 ```
 
 ---
@@ -253,7 +251,7 @@ Or add manually to `.claude/settings.json`:
 
 ```bash
 npm update -g bigpowers
-bigpowers    # re-sync and refresh symlinks
+bigpowers update   # re-sync and refresh symlinks
 ```
 
 **git clone:**
@@ -261,6 +259,7 @@ bigpowers    # re-sync and refresh symlinks
 ```bash
 git pull
 npm run sync
+bash scripts/install.sh
 ```
 
 *Install uses symlinks — re-running setup refreshes links without duplicating files.*
@@ -283,9 +282,9 @@ bash scripts/install.sh --uninstall
 ### Reinstall
 
 ```bash
-npx bigpowers
+npx bigpowers setup
 # or, if installed globally:
-bigpowers
+bigpowers setup
 ```
 
 ---

package/package.json

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

package/scripts/golden-g08-anti-vacuity.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# golden-g08-anti-vacuity.sh — validate-specs-yaml.sh Anti-Vacuity Self-Test (G-08)
+#
+# Proves that validate-specs-yaml.sh CAN detect structurally corrupt YAML
+# (BUG-2026-07-03-validate-specs-no-real-parser bug class). It is fed a
+# fixture where specs/verifications/fixtures/corrupt-yaml/release-plan.yaml
+# is deliberately flattened/corrupt (matching the real yaml-roundtrip
+# corruption pattern) while still containing every string the grep-only
+# checks look for (^epics:, version:, ^release:). A validator that only
+# greps for those strings passes vacuously; a validator that really parses
+# the YAML must FAIL.
+#
+# Mirrors scripts/golden-g07-negative-path.sh's fixture + non-zero-exit
+# pattern.
+#
+# Usage: bash scripts/golden-g08-anti-vacuity.sh
+# Exit 0: validate-specs-yaml.sh correctly detected the corrupt fixture
+# Exit 1: validate-specs-yaml.sh passed vacuously on the corrupt fixture
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FIXTURE_DIR="$REPO_ROOT/specs/verifications/fixtures/corrupt-yaml"
+VALIDATOR="$REPO_ROOT/scripts/validate-specs-yaml.sh"
+
+echo "=== G-08: Anti-Vacuity Self-Test (validate-specs-yaml.sh) ==="
+echo "Fixture: $FIXTURE_DIR"
+echo ""
+
+if [[ ! -f "$FIXTURE_DIR/release-plan.yaml" ]]; then
+  echo "ERROR: fixture not found: $FIXTURE_DIR/release-plan.yaml"
+  exit 1
+fi
+
+set +e
+actual_output=$(bash "$VALIDATOR" "$FIXTURE_DIR" 2>&1)
+actual_exit=$?
+set -e
+
+echo "$actual_output"
+echo ""
+
+if [[ $actual_exit -ne 0 ]]; then
+  echo -e "${GREEN}PASS${NC} validate-specs-yaml.sh correctly detected the corrupt fixture (exit $actual_exit)"
+  echo "G-08: PASS"
+  exit 0
+else
+  echo -e "${RED}FAIL${NC} validate-specs-yaml.sh passed vacuously on a structurally corrupt fixture (exit 0)"
+  echo "G-08: FAIL — fail-open risk (same bug class as GAP-1 / BUG-2026-07-03-validate-specs-no-real-parser)"
+  exit 1
+fi

package/scripts/golden-g09-yaml-roundtrip.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# golden-g09-yaml-roundtrip.sh — yaml-tools.py Lossless Round-Trip Self-Test (G-09)
+#
+# Proves yaml-tools.py's `set` command preserves structure it doesn't touch
+# (BUG-2026-07-03-yaml-roundtrip-corruption bug class). The old hand-rolled
+# parser/dumper had no concept of YAML lists or block scalars and flattened
+# both on every write. This feeds `set` a fixture containing an epics[] list
+# (nested dicts + a flow-style list) and a block scalar (`note: >`), changes
+# one unrelated field, and asserts:
+#   1. the file still parses as valid YAML afterward
+#   2. the epics[] list still has the same length and nested keys
+#   3. fields untouched by the `set` call keep their original values
+#   4. the targeted field actually changed
+#
+# Usage: bash scripts/golden-g09-yaml-roundtrip.sh
+# Exit 0: round trip is lossless
+# Exit 1: round trip destroyed structure (corruption bug is back)
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FIXTURE="$REPO_ROOT/specs/verifications/fixtures/yaml-roundtrip/sample.yaml"
+TOOL="$REPO_ROOT/scripts/yaml-tools.py"
+
+echo "=== G-09: yaml-tools.py Lossless Round-Trip Self-Test ==="
+
+if [[ ! -f "$FIXTURE" ]]; then
+  echo "ERROR: fixture not found: $FIXTURE"
+  exit 1
+fi
+
+WORKDIR="$(mktemp -d)"
+trap 'rm -rf "$WORKDIR"' EXIT
+cp "$FIXTURE" "$WORKDIR/sample.yaml"
+
+python3 "$TOOL" set "$WORKDIR/sample.yaml" release.version "9.9.9-test"
+
+set +e
+RESULT="$(python3 -c "
+import sys, yaml
+
+try:
+    with open(sys.argv[1]) as f:
+        d = yaml.safe_load(f)
+except yaml.YAMLError as e:
+    print('FAIL: file no longer parses as YAML:', str(e).splitlines()[0])
+    sys.exit(1)
+
+errors = []
+
+if d.get('release', {}).get('version') != '9.9.9-test':
+    errors.append('targeted field release.version was not updated')
+
+epics = d.get('epics')
+if not isinstance(epics, list) or len(epics) != 2:
+    errors.append(f'epics[] list destroyed: expected 2 items, got {epics!r}')
+else:
+    if epics[0].get('id') != 'e19' or epics[0].get('wsjf') != 4.7:
+        errors.append('epics[0] fields not preserved')
+    if 'note' not in epics[0] or 'Delivered' not in epics[0].get('note', ''):
+        errors.append('epics[0].note (block scalar) not preserved')
+    if epics[1].get('id') != 'e40' or epics[1].get('depends_on') != ['e39', 'e28']:
+        errors.append('epics[1] fields (incl. flow-style list) not preserved')
+
+if d.get('release', {}).get('codename') != 'Deepening':
+    errors.append('release.codename (untouched sibling field) not preserved')
+
+if d.get('bigpowers_version') != '2.58.7':
+    errors.append('bigpowers_version (untouched top-level field) not preserved')
+
+if errors:
+    for e in errors:
+        print('FAIL:', e)
+    sys.exit(1)
+
+print('OK: round trip is lossless')
+sys.exit(0)
+" "$WORKDIR/sample.yaml")"
+EXIT=$?
+set -e
+
+echo "$RESULT"
+
+if [[ $EXIT -eq 0 ]]; then
+  echo -e "${GREEN}PASS${NC} yaml-tools.py round trip is lossless"
+  echo "G-09: PASS"
+  exit 0
+else
+  echo -e "${RED}FAIL${NC} yaml-tools.py round trip destroyed structure"
+  echo "G-09: FAIL — same bug class as BUG-2026-07-03-yaml-roundtrip-corruption"
+  exit 1
+fi

package/scripts/install.sh

@@ -242,6 +242,6 @@ else
   if [[ -d "$REPO_ROOT/.git" ]]; then
     echo "  git pull && ./scripts/sync-skills.sh"
   else
-    echo "  npm update -g bigpowers && bigpowers"
+    echo "  npm update -g bigpowers && bigpowers update"
   fi
 fi

package/scripts/lib/trace-stories.py

@@ -366,7 +366,10 @@ if STRICT:
         wsjf_sorted = sorted(set(s["wsjf"] for s in matrix_stories), reverse=True)
         cutoff_idx = max(0, len(wsjf_sorted) // 4 - 1)
         p0_threshold = wsjf_sorted[cutoff_idx] if cutoff_idx < len(wsjf_sorted) else 0
-        uncovered_p0 = [s["id"] for s in matrix_stories if s["wsjf"] >= p0_threshold and len(s["links"]) == 0]
+        # Only flag non-backlog stories — backlog stories haven't been implemented yet
+        uncovered_p0 = [s["id"] for s in matrix_stories
+            if s["wsjf"] >= p0_threshold and len(s["links"]) == 0
+            and s["status"] != "backlog"]
         if uncovered_p0:
             print(f"trace-stories.sh: STRICT FAIL — P0 stories with 0% coverage: {', '.join(uncovered_p0)}", file=sys.stderr)
             sys.exit(2)

package/scripts/run-golden-suite.sh

@@ -32,6 +32,9 @@ GATES=(
   "compliance:npm run compliance:false"
   "g04-selftest:bash scripts/golden-g04-selftest.sh:true"
   "g07-negative-path:bash scripts/golden-g07-negative-path.sh:false"
+  "g08-anti-vacuity:bash scripts/golden-g08-anti-vacuity.sh:false"
+  "g09-yaml-roundtrip:bash scripts/golden-g09-yaml-roundtrip.sh:false"
+  "specs-parse:bash scripts/validate-specs-yaml.sh:false"
 )
 
 GREEN='\033[0;32m'

package/scripts/validate-specs-yaml.sh

@@ -1,38 +1,98 @@
 #!/usr/bin/env bash
-# validate-specs-yaml.sh — required keys for state, release-plan, execution-status
+# validate-specs-yaml.sh — real-parse gate + required keys for state,
+# release-plan, execution-status.
+#
+# BUG-2026-07-03-validate-specs-no-real-parser: this validator used to only
+# grep for key strings, so a structurally flattened/corrupt YAML file that
+# still contained those strings passed vacuously. It now really parses every
+# specs/**/*.yaml with PyYAML first, and runs the required-key checks
+# against the *parsed* objects, not against grep.
 set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 SPECS="${1:-$REPO_ROOT/specs}"
 
 err=0
-need() {
-  local file="$1" pattern="$2" msg="$3"
+
+# ── Phase 1: real parse pass — every specs/**/*.yaml must be valid YAML ──────
+parse_report="$(python3 -c "
+import sys, glob, os
+import yaml
+
+specs = sys.argv[1]
+bad = []
+for f in sorted(glob.glob(os.path.join(specs, '**', '*.yaml'), recursive=True)):
+    # Test fixtures (e.g. specs/verifications/fixtures/corrupt-yaml/) hold
+    # deliberately-broken YAML for the G-07/G-08 negative-path golden checks.
+    # Skip them when scanning a real specs/ tree — but still validate them
+    # when a fixture dir is itself the target (G-08 invokes this script
+    # with the fixture dir as $SPECS directly).
+    rel = os.path.relpath(f, specs)
+    if rel.startswith('verifications' + os.sep + 'fixtures' + os.sep):
+        continue
+    try:
+        yaml.safe_load(open(f))
+    except yaml.YAMLError as e:
+        bad.append((f, str(e).splitlines()[0] if str(e) else type(e).__name__))
+
+for f, msg in bad:
+    print(f'PARSE ERROR: {f}: {msg}')
+
+sys.exit(1 if bad else 0)
+" "$SPECS")" || err=1
+
+if [[ -n "$parse_report" ]]; then
+  echo "$parse_report"
+fi
+
+if [[ "$err" -ne 0 ]]; then
+  echo "validate-specs-yaml: FAIL — one or more specs/**/*.yaml files are not valid YAML"
+  exit 1
+fi
+
+# ── Phase 2: required-key checks against the parsed objects, not grep ────────
+need_key() {
+  local file="$1" py_check="$2" msg="$3"
   if [[ ! -f "$file" ]]; then
     echo "missing: $file"
     err=1
     return
   fi
-  if ! grep -qE "$pattern" "$file"; then
+  if ! python3 -c "
+import sys, yaml
+d = yaml.safe_load(open(sys.argv[1])) or {}
+sys.exit(0 if ($py_check) else 1)
+" "$file" 2>/dev/null; then
     echo "$file: $msg"
     err=1
   fi
 }
 
-need "$SPECS/state.yaml" '^active_flow:' 'missing active_flow'
-need "$SPECS/release-plan.yaml" '^release:' 'missing release block'
-need "$SPECS/release-plan.yaml" 'version:' 'missing release.version'
-need "$SPECS/release-plan.yaml" '^epics:' 'missing epics list'
-need "$SPECS/execution-status.yaml" '^development_status:' 'missing development_status'
+need_key "$SPECS/state.yaml" "isinstance(d.get('active_flow'), str)" 'missing active_flow'
+need_key "$SPECS/release-plan.yaml" "isinstance(d.get('release'), dict)" 'missing release block'
+need_key "$SPECS/release-plan.yaml" "isinstance(d.get('release'), dict) and 'version' in d['release']" 'missing release.version'
+need_key "$SPECS/release-plan.yaml" "isinstance(d.get('epics'), list) and len(d['epics']) > 0" 'missing epics list'
+need_key "$SPECS/execution-status.yaml" "isinstance(d.get('development_status'), dict)" 'missing development_status'
 
+# ── Phase 3: every epic's `file` reference must exist, read from the parsed object ──
 if [[ -f "$SPECS/release-plan.yaml" ]]; then
-  while IFS= read -r f; do
-    [[ -z "$f" ]] && continue
-    path="$SPECS/$f"
-    if [[ ! -f "$path" ]]; then
+  missing_files="$(python3 -c "
+import sys, os, yaml
+specs = sys.argv[1]
+d = yaml.safe_load(open(os.path.join(specs, 'release-plan.yaml'))) or {}
+for epic in d.get('epics') or []:
+    if not isinstance(epic, dict):
+        continue
+    f = epic.get('file')
+    if f and not os.path.isfile(os.path.join(specs, f)):
+        print(os.path.join(specs, f))
+" "$SPECS")"
+  if [[ -n "$missing_files" ]]; then
+    while IFS= read -r path; do
+      [[ -z "$path" ]] && continue
       echo "release-plan: missing epic file $path"
       err=1
-    fi
-  done < <(grep -E '^\s+file:' "$SPECS/release-plan.yaml" | sed 's/.*file:[[:space:]]*//; s/^"//; s/"$//')
+    done <<< "$missing_files"
+  fi
 fi
 
 if [[ "$err" -ne 0 ]]; then

package/scripts/yaml-tools.py

@@ -1,78 +1,29 @@
 #!/usr/bin/env python3
-"""Minimal YAML helpers for bigpowers specs (no external deps)."""
+"""YAML helpers for bigpowers specs.
+
+BUG-2026-07-03-yaml-roundtrip-corruption: this used to hand-roll a
+"_parse_simple_yaml" reader with no concept of YAML lists or block
+scalars, and re-serialize with a matching hand-rolled dumper. Any file
+with a `- item` sequence (every epics[] list, every stories[] list) or
+a block scalar (`note: >`) got silently flattened and destroyed on the
+very first `set` call. It now uses PyYAML's safe_load/safe_dump for a
+real, information-preserving round trip.
+"""
 from __future__ import annotations
 
-import re
 import sys
 from pathlib import Path
 from typing import Any
 
-
-def _parse_simple_yaml(text: str) -> dict[str, Any]:
-    """Parse flat and one-level-nested YAML (no lists of objects)."""
-    root: dict[str, Any] = {}
-    stack: list[tuple[int, dict[str, Any]]] = [(0, root)]
-    for raw in text.splitlines():
-        if not raw.strip() or raw.strip().startswith("#"):
-            continue
-        indent = len(raw) - len(raw.lstrip())
-        line = raw.strip()
-        if ":" not in line:
-            continue
-        key, _, val = line.partition(":")
-        key = key.strip()
-        val = val.strip()
-        while stack and indent < stack[-1][0]:
-            stack.pop()
-        cur = stack[-1][1]
-        if val == "":
-            nxt: dict[str, Any] = {}
-            cur[key] = nxt
-            stack.append((indent + 2, nxt))
-        else:
-            if val in ("true", "false"):
-                cur[key] = val == "true"
-            elif val.startswith('"') and val.endswith('"'):
-                cur[key] = val[1:-1]
-            elif val.startswith("'") and val.endswith("'"):
-                cur[key] = val[1:-1]
-            else:
-                try:
-                    if "." in val:
-                        cur[key] = float(val)
-                    else:
-                        cur[key] = int(val)
-                except ValueError:
-                    cur[key] = val
-    return root
-
-
-def _dump_value(val: Any, indent: int) -> str:
-    sp = " " * indent
-    if isinstance(val, dict):
-        lines = []
-        for k, v in val.items():
-            if isinstance(v, dict):
-                lines.append(f"{sp}{k}:")
-                lines.append(_dump_value(v, indent + 2).rstrip())
-            elif isinstance(v, bool):
-                lines.append(f"{sp}{k}: {'true' if v else 'false'}")
-            elif isinstance(v, (int, float)):
-                lines.append(f"{sp}{k}: {v}")
-            else:
-                s = str(v).replace('"', '\\"')
-                lines.append(f'{sp}{k}: "{s}"')
-        return "\n".join(lines) + "\n"
-    return f"{sp}{val}\n"
-
-
-def dump_yaml(data: dict[str, Any]) -> str:
-    return _dump_value(data, 0)
+import yaml
 
 
 def set_path(path: Path, dotted_key: str, value: str) -> None:
+    """Surgically set one dotted-path key, preserving everything else in the file."""
     text = path.read_text(encoding="utf-8") if path.exists() else ""
-    data = _parse_simple_yaml(text) if text.strip() else {}
+    loaded: Any = yaml.safe_load(text) if text.strip() else {}
+    data: dict[str, Any] = loaded if isinstance(loaded, dict) else {}
+
     parts = dotted_key.split(".")
     cur: Any = data
     for part in parts[:-1]:
@@ -80,6 +31,7 @@ def set_path(path: Path, dotted_key: str, value: str) -> None:
             cur[part] = {}
         cur = cur[part]
     last = parts[-1]
+
     if value.lower() in ("true", "false"):
         cur[last] = value.lower() == "true"
     else:
@@ -90,16 +42,24 @@ def set_path(path: Path, dotted_key: str, value: str) -> None:
                 cur[last] = float(value)
             except ValueError:
                 cur[last] = value.strip('"').strip("'")
+
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(dump_yaml(data), encoding="utf-8")
+    # sort_keys=False preserves author-intended ordering (e.g. epics[]
+    # sequencing by WSJF priority) instead of alphabetizing every key.
+    path.write_text(
+        yaml.safe_dump(data, sort_keys=False, allow_unicode=True, width=100),
+        encoding="utf-8",
+    )
 
 
 def validate_file(path: Path, required_keys: list[str]) -> list[str]:
-    errors: list[str] = []
     if not path.exists():
         return [f"missing: {path}"]
-    text = path.read_text(encoding="utf-8")
-    data = _parse_simple_yaml(text)
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        return [f"{path}: PARSE ERROR: {str(e).splitlines()[0]}"]
+    errors: list[str] = []
     for key in required_keys:
         parts = key.split(".")
         cur: Any = data

package/skills/using-bigpowers/SKILL.md

@@ -14,8 +14,9 @@ Welcome to **bigpowers** — a lifecycle of **70** agent skills for production-r
 ## Install
 
 ```bash
-npx bigpowers                  # one-shot setup
-npm install -g bigpowers       # global install, then run: bigpowers
+npx bigpowers setup           # one-shot setup
+npm install -g bigpowers       # global install
+bigpowers setup                # sync skills + link to your tools
 ```
 
 From source (contributors): `git clone` → `npm install` or `bash scripts/install.sh`.

package/skills-lock.json

@@ -328,7 +328,7 @@
     },
     "using-bigpowers": {
       "description": "One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks \"where do I start?\", or when the skills system needs to be explained.",
-      "sha256": "e467775c61f943c8",
+      "sha256": "33f6d163b536e87d",
       "path": "skills/using-bigpowers/SKILL.md"
     },
     "validate-contracts": {