bigpowers 2.5.0 → 2.7.0

package/scripts/generate-skill-index.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# generate-skill-index.sh — Auto-generate SKILL-INDEX.md from skills-lock.json + SKILL.md frontmatter
+# This file is called by sync-skills.sh. Output is SKILL-INDEX.md at repo root.
+# DO NOT edit SKILL-INDEX.md manually — it is auto-generated.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LOCKFILE="$REPO_ROOT/skills-lock.json"
+INDEX_FILE="$REPO_ROOT/SKILL-INDEX.md"
+
+if [[ ! -f "$LOCKFILE" ]]; then
+  echo "generate-skill-index: ERROR — skills-lock.json not found. Run regenerate-lockfile.sh first." >&2
+  exit 1
+fi
+
+# Phase categorization — maps each skill to a lifecycle phase
+declare -A PHASE_MAP
+PHASE_MAP=(
+  # Discover
+  [survey-context]="Discover"
+  [research-first]="Discover"
+  [search-skills]="Discover"
+  [using-bigpowers]="Discover"
+  [map-codebase]="Discover"
+  [elaborate-spec]="Discover"
+  # Elaborate / Design
+  [model-domain]="Design"
+  [define-language]="Design"
+  [grill-me]="Design"
+  [grill-with-docs]="Design"
+  [deepen-architecture]="Design"
+  [design-interface]="Design"
+  [define-success]="Design"
+  # Plan
+  [scope-work]="Plan"
+  [slice-tasks]="Plan"
+  [plan-work]="Plan"
+  [plan-release]="Plan"
+  [plan-refactor]="Plan"
+  [assess-impact]="Plan"
+  [change-request]="Plan"
+  [run-planning]="Plan"
+  [seed-conventions]="Plan"
+  # Build
+  [develop-tdd]="Build"
+  [kickoff-branch]="Build"
+  [execute-plan]="Build"
+  [build-epic]="Build"
+  [spike-prototype]="Build"
+  [craft-skill]="Build"
+  [setup-environment]="Build"
+  [wire-observability]="Build"
+  [align-grid]="Build"
+  [orchestrate-project]="Build"
+  [guard-git]="Build"
+  [hook-commits]="Build"
+  # Verify
+  [verify-work]="Verify"
+  [validate-fix]="Verify"
+  [audit-code]="Verify"
+  [enforce-first]="Verify"
+  [run-evals]="Verify"
+  [investigate-bug]="Verify"
+  [diagnose-root]="Verify"
+  [fix-bug]="Verify"
+  [inspect-quality]="Verify"
+  [request-review]="Verify"
+  [respond-review]="Verify"
+  [trace-requirement]="Verify"
+  # Release
+  [release-branch]="Release"
+  [commit-message]="Release"
+  # Sustain
+  [session-state]="Sustain"
+  [edit-document]="Sustain"
+  [write-document]="Sustain"
+  [organize-workspace]="Sustain"
+  [reset-baseline]="Sustain"
+  [stocktake-skills]="Sustain"
+  [evolve-skill]="Sustain"
+  [terse-mode]="Sustain"
+  [delegate-task]="Sustain"
+  [dispatch-agents]="Sustain"
+  [simulate-agents]="Sustain"
+  [compose-workflow]="Sustain"
+  [migrate-spec]="Sustain"
+)
+
+# Phase order for display
+PHASE_ORDER=("Discover" "Design" "Plan" "Build" "Verify" "Release" "Sustain")
+
+# Column widths
+SKILL_COL_WIDTH=28
+DESC_COL_WIDTH=56
+
+# Build the index file
+{
+  echo "# Skill Index — Single Source of Truth"
+  echo ""
+  echo "> **DO NOT EDIT** — This file is auto-generated by \`scripts/generate-skill-index.sh\`."
+  echo "> Edit \`SKILL.md\` source files or \`skills-lock.json\` instead. Run \`bash scripts/sync-skills.sh\` to regenerate."
+  echo ""
+  echo "**Generated:** $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  echo "**Skills:** $(jq '.skills | length' "$LOCKFILE")"
+  echo ""
+
+  # Summary by phase
+  echo "---"
+  echo ""
+  echo "## Quick Navigation by Phase"
+  echo ""
+  echo "| Phase | Count | Skills |"
+  echo "|---|---|---|"
+  total=0
+  for phase in "${PHASE_ORDER[@]}"; do
+    phase_skills=()
+    for name in $(jq -r '.skills | keys[]' "$LOCKFILE" | sort); do
+      [[ "${PHASE_MAP[$name]:-}" == "$phase" ]] && phase_skills+=("$name")
+    done
+    count=${#phase_skills[@]}
+    total=$((total + count))
+    skill_list=$(IFS=,; echo "${phase_skills[*]}" | sed 's/,/, /g')
+    echo "| $phase | $count | \`$skill_list\` |"
+  done
+  echo "| **TOTAL** | **$total** | |"
+  echo ""
+
+  # Full reference table
+  echo "---"
+  echo ""
+  echo "## Full Reference Table"
+  echo ""
+  echo "| # | Phase | Skill | Description | Status |"
+  echo "|---|---|---|---|---|"
+
+  row=0
+  for phase in "${PHASE_ORDER[@]}"; do
+    for name in $(jq -r '.skills | keys[]' "$LOCKFILE" | sort); do
+      [[ "${PHASE_MAP[$name]:-}" != "$phase" ]] && continue
+      row=$((row + 1))
+      desc=$(jq -r --arg n "$name" '.skills[$n].description // ""' "$LOCKFILE" | head -c 80)
+      echo "| $row | $phase | \`$name\` | $desc | ✅ Active |"
+    done
+  done
+
+  echo ""
+  echo "**Total: $total active skills.**"
+  echo ""
+
+  # Lifecycle arc
+  echo "---"
+  echo ""
+  echo "## Lifecycle Arc"
+  echo ""
+  echo '```'
+  echo '[First time]'
+  echo 'using-bigpowers → orchestrate-project'
+  echo '                         ↓'
+  echo 'survey-context → research-first → elaborate-spec → map-codebase'
+  echo '                         ↓'
+  echo '  model-domain / define-language / grill-me / grill-with-docs'
+  echo '  design-interface / deepen-architecture / define-success'
+  echo '                         ↓'
+  echo '  scope-work → assess-impact → change-request → slice-tasks'
+  echo '  → plan-work / plan-refactor / plan-release / seed-conventions'
+  echo '                         ↓'
+  echo '    kickoff-branch → guard-git / hook-commits / setup-environment'
+  echo '                         ↓'
+  echo '       [Unknown domain?] spike-prototype → (learnings)'
+  echo '                         ↓'
+  echo '  develop-tdd (+ enforce-first) ←→ delegate-task / dispatch-agents'
+  echo '  execute-plan / build-epic / craft-skill / align-grid'
+  echo '                         ↓'
+  echo '              ★ VERIFY ★  verify-work → run-evals → audit-code'
+  echo '                         ↓'
+  echo '    fix-bug → investigate-bug → diagnose-root → validate-fix'
+  echo '                         ↓'
+  echo '      request-review → respond-review → trace-requirement'
+  echo '                         ↓'
+  echo '      commit-message → release-branch'
+  echo '                         ↓'
+  echo '   inspect-quality → organize-workspace → stocktake-skills'
+  echo '   → evolve-skill → edit-document / write-document / migrate-spec'
+  echo ''
+  echo 'Transversal utilities (any phase):'
+  echo '  terse-mode, session-state, visual-dashboard, reset-baseline,'
+  echo '  search-skills, compose-workflow, simulate-agents, wire-observability'
+  echo '```'
+  echo ""
+  echo "---"
+  echo ""
+  echo "## Status Legend"
+  echo ""
+  echo "| Icon | Meaning |"
+  echo "|---|---|"
+  echo "| ✅ Active | SKILL.md exists and is usable |"
+  echo "| 📋 Planned | Designed but not yet implemented |"
+  echo "| 🔄 Refactoring | Active but under revision |"
+  echo "| ⚠️ Deprecated | Will be removed in a future release |"
+  echo ""
+  echo "## Naming Convention Notes"
+  echo ""
+  echo "All skills follow \`verb-noun\` kebab-case (ADR-0001). Documented exceptions:"
+  echo "- \`terse-mode\` — adjective-noun; retained for clarity"
+  echo "- \`visual-dashboard\` — adjective-noun; retained for clarity"
+  echo ""
+  echo "## How to Update"
+  echo ""
+  echo "1. Run \`bash scripts/sync-skills.sh\` to regenerate this file and all artifacts."
+  echo "2. Or run \`bash scripts/generate-skill-index.sh\` to only regenerate this index."
+  echo ""
+  echo "→ verify: \`find . -maxdepth 2 -name \"SKILL.md\" | grep -v \".git\\|.cursor\\|.gemini\" | wc -l\`"
+  echo ""
+
+} > "$INDEX_FILE"
+
+count=$(jq '.skills | length' "$LOCKFILE")
+echo "generate-skill-index: wrote SKILL-INDEX.md ($count skills)"

package/scripts/regenerate-lockfile.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# regenerate-lockfile.sh — Scan all SKILL.md files and regenerate skills-lock.json
+# Output: Canonical catalog with name, description, sha256, path for every skill.
+# Run this after adding, removing, or updating any skill.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LOCKFILE="$REPO_ROOT/skills-lock.json"
+
+# Build JSON using jq from individual skill records
+# We pipe each skill as a JSON object, then jq -s merges them into an object keyed by name
+records=()
+for skill_dir in "$REPO_ROOT"/*/; do
+  skill_md="$skill_dir/SKILL.md"
+  [[ -f "$skill_md" ]] || continue
+
+  name=$(basename "$skill_dir")
+  # Extract description from YAML frontmatter (between first --- and second ---)
+  description=$(awk '/^---/{f++; next} f==1 && /^description:/{p=1; sub(/^description:[[:space:]]*/,""); print; next} f==1 && p && /^[a-z]+:/{exit} f==1 && p{print}' "$skill_md" \
+    | tr -d '\n' | sed -E 's/[[:space:]]+/ /g')
+
+  # Compute SHA-256 of full SKILL.md content (first 16 hex chars for compact uniqueness)
+  sha256=$(sha256sum "$skill_md" | cut -c1-16)
+
+  # Relative path from repo root
+  relpath="${skill_dir#$REPO_ROOT/}SKILL.md"
+
+  # Emit JSON record for this skill
+  records+=("$(jq -n --arg name "$name" \
+                       --arg desc "$description" \
+                       --arg sha "$sha256" \
+                       --arg path "$relpath" \
+    '{($name): {description: $desc, sha256: $sha, path: $path}}')")
+done
+
+# Merge all records into a single "skills" object with version
+jq -n --argjson skills "$(printf '%s\n' "${records[@]}" | jq -s 'add')" \
+  '{version: 1, skills: $skills}' > "$LOCKFILE"
+
+count=$(jq '.skills | length' "$LOCKFILE")
+echo "regenerate-lockfile: $count skills written to skills-lock.json"

package/scripts/sync-skills.sh

@@ -174,6 +174,16 @@ if [[ -n "$OPN_TARGET" ]] && [[ -d "$OPN_TARGET" ]]; then
   echo "  → $opencode_count skills copied to $OPN_SKILLS/"
 fi
 
+# Regenerate skills-lock.json catalog
+if [[ -x "$REPO_ROOT/scripts/regenerate-lockfile.sh" ]]; then
+  bash "$REPO_ROOT/scripts/regenerate-lockfile.sh" || { echo "sync-skills: FAIL — lockfile regeneration failed" >&2; exit 1; }
+fi
+
+# Regenerate SKILL-INDEX.md from lockfile + frontmatter
+if [[ -x "$REPO_ROOT/scripts/generate-skill-index.sh" ]]; then
+  bash "$REPO_ROOT/scripts/generate-skill-index.sh" || { echo "sync-skills: FAIL — SKILL-INDEX.md generation failed" >&2; exit 1; }
+fi
+
 # Regenerate lexical skill index for search-skills
 if [[ -x "$REPO_ROOT/scripts/build-skill-index.sh" ]]; then
   bash "$REPO_ROOT/scripts/build-skill-index.sh" || true
@@ -187,6 +197,8 @@ echo "  → .gemini/extensions/bigpowers/gemini-extension.json"
 echo "  → .pi/skills/ ($skill_count skill dirs — pi Agent Skills)"
 echo "  → .pi/prompts/ ($skill_count prompt templates — pi slash commands)"
 echo "  → .pi/package.json (pi package manifest)"
+echo "  → skills-lock.json (catalog with SHA-256 hashes)"
+echo "  → SKILL-INDEX.md (auto-generated skill reference)"
 echo "  → opencode.json (CLAUDE.md + CONVENTIONS.md instructions)"
 [[ -n "$OPN_TARGET" ]] && echo "  → bigpowers-opencode: $opencode_count skills"
 

package/search-skills/SKILL.md

@@ -5,17 +5,65 @@ model: haiku
 ---
 
 # Search Skills
-> **HARD GATE** — **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
 
+> **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
+>
+> **HARD GATE** — Do NOT use external embedding APIs or AI-based semantic search. This is a lexical-only index (ADR: zero external dependency).
 
-Lexical search only — no embedding service (ADR: zero external dependency).
+Lexical search only — no embedding service (ADR: zero external dependency). The index is a flat markdown file (`specs/SKILL-SEARCH-INDEX.md`) built from every SKILL.md's YAML frontmatter — name, description, and key phrases. No vector DB, no API calls, no network dependency.
+
+## When to use
+
+- You're unsure which skill to invoke for a user's request
+- At the start of `research-first` to find pre-existing skills that might solve the problem
+- When a user asks "is there a skill for X?"
+- Before calling a skill by name, to confirm it's the right one
+
+## Pre-flight
+
+- [ ] Does `specs/SKILL-SEARCH-INDEX.md` exist? If not, run `bash scripts/build-skill-index.sh`.
+- [ ] Is the index fresh? Check its timestamp — if > 24 hours old or after any SKILL.md change, regenerate.
 
 ## Process
 
-1. Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` is stale.
-2. Search index: `rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md`
-3. Read top 3 matches' `description` and "Use when" triggers.
-4. Recommend one skill with rationale; invoke via orchestrator or direct call.
+1. **Refresh index if stale** — Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` doesn't exist or was modified before the last SKILL.md change.
+
+2. **Search the index** — Use ripgrep on the lexical index:
+   ```
+   rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md
+   ```
+   The index contains each skill's name, description, phase, and key use-case phrases, so natural language queries work well even without embeddings.
+
+3. **Rank results** — Read the top 3 matches. Evaluate by:
+   - **Exactness** — Does the description literally match the user's intent?
+   - **Phase fit** — Is the skill designed for the current lifecycle phase?
+   - **Trigger phrases** — Does the skill's "Use when" section match the situation?
+
+4. **Recommend one skill** — Select the single best-matching skill. Provide:
+   - The skill name
+   - Why it's the best match (citing the description or trigger phrase)
+   - What it produces (artifact, dialogue, or state change)
+
+5. **Invoke** — Call the skill directly or through the orchestrator. If no match found, suggest the closest phase-appropriate skill or `using-bigpowers` as a general entry point.
+
+## Index Format
+
+`specs/SKILL-SEARCH-INDEX.md` contains one section per skill:
+```markdown
+## <skill-name>
+- **Description:** <from frontmatter>
+- **Phase:** <lifecycle phase>
+- **Triggers:** <key phrases from description>
+- **Keywords:** <extracted terms>
+```
+
+## Why Not Semantic Search?
+
+- Zero network dependency — works fully offline
+- Zero cost — no API keys, no usage limits
+- Instant — ripgrep on a local file is sub-second
+- Deterministic — same query always returns same results
+- Auditable — you can read the full index
 
 ## Verify