bigpowers 2.77.0 → 2.77.2

package/scripts/check-skill-links.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# check-skill-links.py — fail on machine-absolute paths or dangling relative
+# links in skill docs. Scans skills/**/SKILL.md and .pi/skills/**/SKILL.md.
+# Run: python3 scripts/check-skill-links.py  (exit 1 with a report on failure)
+#
+# NOTE: .cursor/rules/ and .gemini/extensions/ are intentionally excluded.
+# Those trees are auto-generated from SKILL.md sources via sync-skills.sh and
+# are not published to npm, so dangling links there are a rendering gap, not a
+# source defect. Enable once the sync pipeline gains link-rewriting support.
+# See: https://github.com/danielvm-git/bigpowers/issues/78
+import glob
+import os
+import sys
+
+# Import shared patterns — single source of truth so the rewriter (srp-engine)
+# and the gate always agree on what constitutes a "link".
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from lib.link_utils import LINK_RE, EXTERNAL_RE, MACHINE_PATH_RE, strip_code_spans  # noqa: E402
+
+
+def resolve_repo_root() -> str:
+    here = os.path.dirname(os.path.abspath(__file__))
+    candidate = os.path.dirname(here)  # scripts/ -> repo root
+    if os.path.isdir(os.path.join(candidate, "skills")):
+        return candidate
+    return os.getcwd()
+
+
+def check_file_links(smd: str, root: str) -> list[str]:
+    """Return a list of problem strings for a single SKILL.md file."""
+    rel = os.path.relpath(smd, root)
+    with open(smd, encoding="utf-8") as f:
+        text = f.read()
+
+    problems = []
+
+    # Machine-absolute path check runs on raw text (line-by-line for location).
+    for i, line in enumerate(text.splitlines(), 1):
+        if MACHINE_PATH_RE.search(line):
+            problems.append(f"{rel}:{i}: machine-absolute path: {line.strip()[:100]}")
+
+    # Link check runs on shadow (code spans blanked) to avoid false positives
+    # on example paths shown inside fenced blocks or inline code.
+    shadow = strip_code_spans(text)
+    for m in LINK_RE.finditer(shadow):
+        target = m.group(2).split("#", 1)[0]  # strip fragment
+        if not target or EXTERNAL_RE.match(target) or target.startswith(("#", "/")):
+            continue
+        resolved = os.path.normpath(os.path.join(os.path.dirname(smd), target))
+        if not os.path.exists(resolved):
+            problems.append(f"{rel}: dangling link -> {target}")
+
+    return problems
+
+
+def check(root: str) -> list[str]:
+    problems = []
+    for tree in ("skills", os.path.join(".pi", "skills")):
+        pattern = os.path.join(root, tree, "*", "SKILL.md")
+        for smd in sorted(glob.glob(pattern)):
+            problems.extend(check_file_links(smd, root))
+    return problems
+
+
+def main() -> int:
+    root = resolve_repo_root()
+    problems = check(root)
+    if problems:
+        print(f"check-skill-links: {len(problems)} problem(s):")
+        for p in problems:
+            print(f"  {p}")
+        return 1
+    print("check-skill-links: OK — no machine paths or dangling links")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/generate-reference-tables.sh

@@ -32,10 +32,11 @@ BLOCK="<!-- AUTO-GENERATED-CATALOG: begin — do not edit manually; run scripts/
 for row in "${ROWS[@]}"; do
   skill="${row%% *}"
   model="${row##* }"
+  skill_rel="${skill#$REPO_ROOT/}"
   # capitalise first letter for display
   model_cap="$(echo "${model:0:1}" | tr '[:lower:]' '[:upper:]')${model:1}"
   BLOCK+="
-| \`$skill\` | **$model_cap** |"
+| \`$skill_rel\` | **$model_cap** |"
 done
 BLOCK+="
 

package/scripts/lib/link_utils.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""link_utils.py — shared Markdown link patterns used by srp-engine and check-skill-links.
+
+Single source of truth for what constitutes a "link" so the rewriter and the
+regression gate always agree on the definition.
+"""
+import re
+
+# Matches standard Markdown links — with or without an optional title attribute.
+#   [text](target)
+#   [text](target "title")
+# Group 1: link text, Group 2: raw target (may include URL fragment)
+LINK_RE = re.compile(
+    r'\[([^\]]*)\]\('       # [text](
+    r'([^)\s"]+)'           # target (no spaces, no quotes)
+    r'(?:\s+"[^"]*")?'      # optional title attribute: "title text"
+    r'\s*\)'                # closing )
+)
+
+# Matches scheme-prefixed (non-relative) URLs that should never be rewritten
+# or resolved as local file paths.
+EXTERNAL_RE = re.compile(r'(?i)^(https?|ftp|file|mailto):')
+
+# Detects machine-absolute paths that must not appear in skill docs.
+# Covers macOS (/Users/), Linux (/home/), and Windows (C:\Users, D:\Users …).
+MACHINE_PATH_RE = re.compile(r'file:///|/Users/|/home/|[A-Z]:\\Users')
+
+# ---------------------------------------------------------------------------
+# Markdown code-block stripping
+# ---------------------------------------------------------------------------
+
+# Fenced code block: ``` or ~~~ with optional language tag, any content, close fence.
+_FENCED_BLOCK_RE = re.compile(r'(?m)^(`{3,}|~{3,})[^\n]*\n.*?\n\1\s*$', re.DOTALL)
+# Inline code: `…` (single backtick, non-empty)
+_INLINE_CODE_RE = re.compile(r'`[^`\n]+`')
+
+
+def strip_code_spans(text: str) -> str:
+    """Return *text* with fenced blocks and inline code replaced by blank space.
+
+    Preserves original character positions so that any offset-based logic
+    remains valid; only the link-matching content is neutralised.
+    """
+    def _blank(m: re.Match) -> str:
+        return ' ' * len(m.group(0))
+
+    text = _FENCED_BLOCK_RE.sub(_blank, text)
+    text = _INLINE_CODE_RE.sub(_blank, text)
+    return text

package/scripts/lib/simple_yaml.py

@@ -7,20 +7,30 @@ def parse_simple_yaml(text: str) -> dict:
     root: dict = {}
     # Each stack entry: (indent, container, parent_dict, key_in_parent)
     stack: list = [(0, root, None, None)]
-    skip_until_indent = None  # skip block scalar continuation lines (| and >)
+    skip_until_indent = None  # indent of an active block scalar's key line
+    block: dict = {}  # active block scalar: {'lines': [...], 'style': str, 'assign': fn}
+
+    def flush_block():
+        if block:
+            block['assign'](_fold_block(block['lines'], block['style']))
+            block.clear()
+
     for i, raw in enumerate(text.splitlines()):
         stripped = raw.strip()
-        if not stripped or stripped.startswith("#"):
-            # Reset block-scalar skip on blank lines
-            continue
         indent = len(raw) - len(raw.lstrip())
-        
-        # Skip block scalar continuation (| and > in YAML)
+
+        # Inside a block scalar: capture continuation lines verbatim. Blank and
+        # '#'-prefixed lines are literal content here, not comments.
         if skip_until_indent is not None:
-            if indent > skip_until_indent:
+            if not stripped or indent > skip_until_indent:
+                if block:
+                    block['lines'].append(raw)
                 continue
-            else:
-                skip_until_indent = None
+            flush_block()
+            skip_until_indent = None
+
+        if not stripped or stripped.startswith("#"):
+            continue
         
         # Pop stack until we're at the right nesting level
         # Don't pop list containers at same indent — sibling items stay in same list
@@ -68,8 +78,11 @@ def parse_simple_yaml(text: str) -> dict:
                 v = v.strip()
                 # Detect block scalars in list items too
                 if v in ("|", ">", "|-", ">-", "|+", ">+"):
-                    item = {k: v}
+                    item = {k: None}
                     container.append(item)
+                    block.clear()
+                    block.update(lines=[], style=v,
+                                 assign=lambda s, _i=item, _k=k: _i.__setitem__(_k, s))
                     skip_until_indent = indent
                     continue
                 item = {k: _yaml_scalar(v) if v else None}
@@ -87,12 +100,18 @@ def parse_simple_yaml(text: str) -> dict:
         key = key.strip()
         val = val.strip()
         
-        # Detect block scalars (|, >, |- etc.)
+        # Detect block scalars (|, >, |- etc.) and capture their folded content.
         if val in ("|", ">", "|-", ">-", "|+", ">+"):
+            tgt = None
             if isinstance(container, list) and container:
-                container[-1][key] = val  # store the marker
+                tgt = container[-1]
             elif isinstance(container, dict):
-                container[key] = val
+                tgt = container
+            if tgt is not None:
+                tgt[key] = None
+                block.clear()
+                block.update(lines=[], style=val,
+                             assign=lambda s, _t=tgt, _k=key: _t.__setitem__(_k, s))
             skip_until_indent = indent
             continue
         
@@ -111,11 +130,43 @@ def parse_simple_yaml(text: str) -> dict:
                 stack.append((indent, nxt, container, key))
             else:
                 container[key] = _yaml_scalar(val)
+    flush_block()
     return root
 
 
+def _fold_block(raw_lines, style):
+    """Fold a YAML block scalar (| literal / > folded) to match PyYAML."""
+    # Strip the common leading indentation of the block's content lines.
+    indents = [len(l) - len(l.lstrip()) for l in raw_lines if l.strip()]
+    ci = min(indents) if indents else 0
+    lines = [l[ci:] if len(l) >= ci else l.strip() for l in raw_lines]
+    if style[0] == "|":  # literal: keep line breaks
+        text = "\n".join(lines)
+    else:  # folded: single break -> space, blank line -> newline
+        parts, prev_blank = [], True
+        for l in lines:
+            if l == "":
+                parts.append("\n")
+                prev_blank = True
+            else:
+                if parts and not prev_blank:
+                    parts.append(" ")
+                parts.append(l)
+                prev_blank = False
+        text = "".join(parts)
+    text = text.rstrip("\n")
+    # Chomping indicator: '-' strip, default clip (single trailing newline).
+    return text if style.endswith("-") else text + "\n"
+
+
 def _yaml_scalar(val: str):
     """Convert a YAML scalar string to Python type."""
+    stripped = val.strip()
+    # Double-quoted scalar: unescape YAML escapes (\" and \\) like PyYAML, and
+    # keep it a string (no bool/int coercion). Keeps the PyYAML-free fallback
+    # byte-identical to PyYAML for quoted descriptions.
+    if len(stripped) >= 2 and stripped[0] == '"' and stripped[-1] == '"':
+        return stripped[1:-1].replace('\\"', '"').replace("\\\\", "\\")
     val = val.strip('"').strip("'")
     if val in ("true", "false"):
         return val == "true"

package/scripts/lib/srp-engine.py

@@ -1,11 +1,99 @@
 #!/usr/bin/env python3
 # story: e48s15
+# story: BUG-2026-07-18-setup-pyyaml-missing
 import os
 import sys
 import json
 import glob
 import subprocess
-import yaml
+
+# Ensure scripts/lib is on the path so sibling modules (link_utils, and the
+# simple_yaml fallback below) resolve regardless of cwd.
+_LIB_DIR = os.path.dirname(os.path.abspath(__file__))
+if _LIB_DIR not in sys.path:
+    sys.path.insert(0, _LIB_DIR)
+
+from link_utils import LINK_RE, EXTERNAL_RE, strip_code_spans  # noqa: E402
+
+# End-user setup (bigpowers setup) may run on a python3 without PyYAML.
+# Prefer PyYAML for exact parsing; fall back to the dependency-free
+# simple_yaml.py (story e38s01) so setup never hard-crashes.
+try:
+    import yaml
+    _load_yaml = yaml.safe_load
+except ModuleNotFoundError:
+    from simple_yaml import parse_simple_yaml
+    _load_yaml = parse_simple_yaml
+
+def rewrite_links_for_pi(body, name):
+    """Repoint relative links so they resolve from .pi/skills/<name>/.
+
+    Sibling *.md content is inlined into the rendered SKILL.md body, but the
+    links to those files (and to repo-root docs) still point at paths relative
+    to the source dir, so they dangle in the rendered tree. Repoint them at
+    the shipped source tree (skills/, profiles/, repo-root files) so links
+    resolve in repo checkouts and npm installs alike. External, anchor, and
+    absolute links pass through untouched.
+
+    Code fences and inline code are skipped — links inside them are examples,
+    not navigation targets.
+    """
+    out_dir = os.path.join(".pi", "skills", name)
+    # Build a "shadow" copy with code spans blanked out so LINK_RE never
+    # matches inside ``` blocks or inline `code`.
+    shadow = strip_code_spans(body)
+
+    def repl(m):
+        # If this match falls inside a code span the shadow char is a space;
+        # the real body char at that position is not a '[' — so LINK_RE won't
+        # match in the shadow at all.  The sub() runs on the shadow but we
+        # return the replacement for the real body using the captured groups.
+        text, raw_target = m.group(1), m.group(2).strip()
+        if EXTERNAL_RE.match(raw_target) or raw_target.startswith(('#', '/')):
+            return m.group(0)
+        # Split fragment before normpath to avoid mangling '#section/sub'.
+        if '#' in raw_target:
+            path_part, fragment = raw_target.split('#', 1)
+            frag_suffix = '#' + fragment
+        else:
+            path_part, frag_suffix = raw_target, ''
+        resolved = os.path.normpath(os.path.join("skills", name, path_part))
+        if resolved.startswith(".."):
+            return m.group(0)  # escapes repo root; leave untouched
+        new_target = os.path.relpath(resolved, out_dir).replace(os.sep, '/') + frag_suffix
+        return f"[{text}]({new_target})"
+
+    return LINK_RE.sub(repl, shadow).replace(shadow, body) if shadow == body else _apply_repl_on_real(body, shadow, name, out_dir)
+
+
+def _apply_repl_on_real(body, shadow, name, out_dir):
+    """Apply link rewrites to *body* using *shadow* to skip code spans.
+
+    Iterates LINK_RE matches on *shadow* (which has code spans blanked) and
+    rebuilds body with only the matched positions replaced.
+    """
+    result = []
+    last = 0
+    for m in LINK_RE.finditer(shadow):
+        result.append(body[last:m.start()])
+        text, raw_target = m.group(1), m.group(2).strip()
+        if EXTERNAL_RE.match(raw_target) or raw_target.startswith(('#', '/')):
+            result.append(body[m.start():m.end()])
+        else:
+            if '#' in raw_target:
+                path_part, fragment = raw_target.split('#', 1)
+                frag_suffix = '#' + fragment
+            else:
+                path_part, frag_suffix = raw_target, ''
+            resolved = os.path.normpath(os.path.join("skills", name, path_part))
+            if resolved.startswith(".."):
+                result.append(body[m.start():m.end()])
+            else:
+                new_target = os.path.relpath(resolved, out_dir).replace(os.sep, '/') + frag_suffix
+                result.append(f"[{text}]({new_target})")
+        last = m.end()
+    result.append(body[last:])
+    return ''.join(result)
 
 def resolve_repo_root():
     lib_dir = os.path.dirname(os.path.abspath(__file__))
@@ -37,7 +125,7 @@ def parse_skill(skill_md_path):
     skill_body = '---'.join(parts[2:])
 
     try:
-        frontmatter = yaml.safe_load(frontmatter_raw)
+        frontmatter = _load_yaml(frontmatter_raw)
     except Exception as e:
         print(f"Error parsing YAML frontmatter in {skill_md_path}: {e}", file=sys.stderr)
         sys.exit(1)
@@ -83,7 +171,7 @@ def get_active_adapters(repo_root):
         return ["cursor", "gemini", "pi"]
     try:
         with open(targets_file, 'r', encoding='utf-8') as f:
-            data = yaml.safe_load(f)
+            data = _load_yaml(f.read())
         adapters = []
         for target in data.get('targets', []):
             if target.get('skill') is not None:
@@ -210,7 +298,11 @@ def main():
                 continue
 
             for adapter in adapters:
-                dispatch_to_adapter(skill_data, adapter, repo_root)
+                data = skill_data
+                if adapter == "pi":
+                    data = dict(skill_data)
+                    data["body_pi_skill"] = rewrite_links_for_pi(skill_data['body'], skill_data['name'])
+                dispatch_to_adapter(data, adapter, repo_root)
 
             if okf_mode:
                 render_okf_concept(skill_data, okf_wiki_skills)
@@ -235,6 +327,10 @@ def main():
 
     skill_data = parse_skill(skill_md_path)
 
+    if target == "pi":
+        skill_data = dict(skill_data)
+        skill_data["body_pi_skill"] = rewrite_links_for_pi(skill_data['body'], skill_data['name'])
+
     if dry_run or not target:
         print(json.dumps(skill_data, indent=2))
         return

package/scripts/sync-skills.sh

@@ -74,7 +74,7 @@ if [[ -f "$TARGETS_FILE" ]] && command -v yq >/dev/null 2>&1; then
     [[ -n "$adapter" && "$adapter" != "null" ]] && SKILL_ADAPTERS+=("$adapter")
   done < <(yq -r '.targets[] | select(.skill != null) | .skill.adapter' "$TARGETS_FILE" | sort -u)
 else
-  echo "sync-skills: WARN — targets.yaml missing; using legacy render list" >&2
+  echo "sync-skills: WARN — yq unavailable or targets.yaml missing; using legacy render list (cursor gemini pi)" >&2
   SKILL_ADAPTERS=(cursor gemini pi)
 fi
 

package/scripts/test-setup-no-pyyaml.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# test-setup-no-pyyaml.sh — recurrence guard for BUG-2026-07-18-setup-pyyaml-missing
+#
+# `bigpowers setup` must not crash when the resolved python3 lacks PyYAML.
+# Two setup-path scripts hard-depended on PyYAML: srp-engine.py (import yaml)
+# and validate-skill-yaml.py (sys.exit(2) on ImportError). Both now fall back
+# to scripts/lib/simple_yaml.py. This guard asserts:
+#   1. srp-engine.py parses a skill under a PyYAML-free interpreter.
+#   2. validate-skill-yaml.py runs (does not exit 2) under the same.
+#   3. simple_yaml's output equals PyYAML's for every skill's frontmatter
+#      (covers escaped quotes and folded/literal block scalars).
+#
+# Usage: bash scripts/test-setup-no-pyyaml.sh
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+GREEN='\033[0;32m'; RED='\033[0;31m'; NC='\033[0m'
+FAILURES=0
+pass() { echo -e "${GREEN}PASS${NC} $1"; }
+fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+
+# Build a throwaway PyYAML-free interpreter — a fresh venv has no PyYAML,
+# reproducing a stock macOS python3 without touching the caller's environment.
+NOYAML_DIR="$(mktemp -d)"
+trap 'rm -rf "$NOYAML_DIR"' EXIT
+if ! python3 -m venv "$NOYAML_DIR/venv" >/dev/null 2>&1; then
+  echo "test-setup-no-pyyaml: SKIP — cannot create venv"; exit 0
+fi
+NOPY="$NOYAML_DIR/venv/bin/python"
+if "$NOPY" -c "import yaml" >/dev/null 2>&1; then
+  echo "test-setup-no-pyyaml: SKIP — fresh venv unexpectedly has PyYAML"; exit 0
+fi
+
+# 1. srp-engine.py must parse a skill's frontmatter without crashing.
+if "$NOPY" scripts/lib/srp-engine.py skills/fix-bug/SKILL.md >/dev/null 2>&1; then
+  pass "srp-engine.py parses frontmatter without PyYAML"
+else
+  fail "srp-engine.py crashed without PyYAML"
+fi
+
+# 2. validate-skill-yaml.py must not bail with exit 2 (the old PyYAML-required path).
+rc=0
+"$NOPY" scripts/validate-skill-yaml.py >/dev/null 2>&1 || rc=$?
+if [[ "$rc" -ne 2 ]]; then
+  pass "validate-skill-yaml.py runs without PyYAML (exit $rc)"
+else
+  fail "validate-skill-yaml.py bailed with exit 2 (PyYAML required)"
+fi
+
+# 3. Fallback fidelity: simple_yaml must equal PyYAML for every skill's
+#    frontmatter. Runs under python3 (CI has PyYAML); skips if PyYAML absent.
+if python3 - <<'PY'; then
+import glob, sys
+sys.path.insert(0, "scripts/lib")
+from simple_yaml import parse_simple_yaml
+try:
+    import yaml
+except ImportError:
+    print("skip: PyYAML not available for comparison"); sys.exit(0)
+bad = []
+for p in sorted(glob.glob("skills/*/SKILL.md")):
+    fm = open(p, encoding="utf-8").read().split("---")[1]
+    a = parse_simple_yaml(fm)
+    b = yaml.safe_load(fm)
+    for k in ("name", "description", "effort", "model"):
+        if a.get(k) != b.get(k):
+            bad.append(f"{p}:{k}")
+if bad:
+    print("mismatch: " + ", ".join(bad)); sys.exit(1)
+sys.exit(0)
+PY
+  pass "simple_yaml matches PyYAML for all skill frontmatter"
+else
+  fail "simple_yaml diverged from PyYAML for some skill frontmatter"
+fi
+
+if [[ "$FAILURES" -gt 0 ]]; then
+  echo "test-setup-no-pyyaml: $FAILURES failure(s)" >&2
+  exit 1
+fi
+echo "test-setup-no-pyyaml: PASS"

package/scripts/validate-skill-yaml.py

@@ -4,11 +4,18 @@ import glob
 import sys
 import os
 
+# Prefer PyYAML; fall back to the dependency-free scripts/lib/simple_yaml.py
+# (story e38s01) so `bigpowers setup` works on a python3 without PyYAML.
+# story: BUG-2026-07-18-setup-pyyaml-missing
+_LIB = os.path.join(os.path.dirname(os.path.abspath(__file__)), "lib")
 try:
     import yaml
-except ImportError:
-    print("ERROR: PyYAML required — pip install pyyaml")
-    sys.exit(2)
+    _load_yaml = yaml.safe_load
+except ModuleNotFoundError:
+    if _LIB not in sys.path:
+        sys.path.insert(0, _LIB)
+    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"))
@@ -30,8 +37,8 @@ for path in files:
     frontmatter = parts[1]
 
     try:
-        data = yaml.safe_load(frontmatter)
-    except yaml.YAMLError as e:
+        data = _load_yaml(frontmatter)
+    except Exception as e:
         parse_failures.append((skill_name, str(e).split("\n")[0]))
         continue
 

package/skills/audit-code/SKILL.md

@@ -31,7 +31,7 @@ Apply the full checklist to churn-ranked files in descending order. Files with z
 - Default: full checklist
 - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
 - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.
-- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or:
+- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree:
 
 ```bash
 bash scripts/lib/parallel-review-worktrees.sh audit-code

package/skills/craft-skill/SKILL.md

@@ -33,7 +33,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
    - Any reference materials to include?
    - What specs/ output does it produce (if any)?
 
-2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../docs/PRINCIPLES.md):
+2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/PRINCIPLES.md):
    - Is it atomic (verb-noun)?
    - Is it "deep" (simple interface, complex internal logic)?
    - Does it include Hard Gates?
@@ -46,7 +46,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
 
    **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source.
 
-4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../docs/references/model-profiles.md).
+4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md).
 
 > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
 

package/skills/elaborate-spec/SKILL.md

@@ -65,7 +65,7 @@ Once the user has answered the main questions, probe for assumptions:
 
 ### 4. Synthesize and confirm
 
-Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md):
+Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md):
 - The problem (feeds into §1 Business narrative)
 - The solution and main flow (feeds into §5)
 - The key constraints and alternative flows (feeds into §6)

package/skills/evolve-skill/REFERENCE.md

@@ -9,4 +9,4 @@
 **Evidence:** path/to/benchmark-report.md
 ```
 
-Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/`
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path.

package/skills/grill-me/REFERENCE.md

@@ -43,7 +43,7 @@ Ask one question at a time. For each challenge, cite the specific URL and sectio
 
 When an assumption doesn't match the docs:
 
-> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
+> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
 
 Document each discrepancy clearly.
 

package/skills/guard-git/SKILL.md

@@ -22,7 +22,7 @@ Installs a shared hook that blocks destructive git operations and enforces workf
 ## Quick start
 
 1. **Scope**: ask project-only vs global (paths differ per product).
-2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory.
+2. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory.
 3. **Run `chmod +x`** on `pre-tool-use.sh`.
 4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys.
 5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md).

package/skills/investigate-bug/SKILL.md

@@ -124,6 +124,6 @@ After writing the bug file, print a one-line summary of the root cause and sugge
 
 <!-- story: e35s10 -->
 
-- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm
-- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating
+- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm
+- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating
 

package/skills/model-domain/CONTEXT-FORMAT.md

@@ -57,9 +57,9 @@ _Avoid_: Client, buyer, account
 
 ## Contexts
 
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders
+- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments
+- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping
 
 ## Relationships
 

package/skills/plan-refactor/SKILL.md

@@ -82,8 +82,8 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next
 
 <!-- story: e35s10 -->
 
-- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy
-- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change
+- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy
+- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change
 
 ## Verify
 

package/skills/plan-release/SKILL.md

@@ -17,7 +17,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s
 |------|---------|
 | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** |
 | `specs/epics/eNN-<slug>/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list |
-| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
+| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
 | `specs/epics/eNN-<slug>/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task |
 | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) |
 
@@ -102,7 +102,7 @@ stories:
 ```
 ### 6. Save story specs (countable-story-format .md)
 
-Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
+Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
 ### 7. Save decoupled task files (`-tasks.yaml`)
 
 Each story has a decoupled `-tasks.yaml` with implementation steps: