bigpowers 2.2.0 → 2.4.0

package/scope-work/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: scope-work
-description: Define what is in and out of scope for the current effort and save as specs/product/SCOPE_LATEST.yaml. Use when user wants a PRD, scope definition, or before plan-release on a new initiative.
+description: "PLANNING SPINE STEP 1 of 3 — Scope the work: define what is in and out of scope and save as specs/product/SCOPE_LATEST.yaml. Use before slice-tasks or plan-release on any new initiative. Not a substitute for slice-tasks (step 2) or plan-work (step 3)."
 model: sonnet
 ---
 
 # Scope Work
 
+> **Spine position:** Step 1 — scope-work → slice-tasks → plan-work.
+
 Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.yaml`.
 
 ## Process

package/scripts/sync-skills.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# sync-skills.sh — generate Cursor and Gemini CLI artifacts from SKILL.md source files
+# sync-skills.sh — generate Cursor, Gemini CLI, and pi artifacts from SKILL.md source files
 # Run this after adding or updating any skill. Symlinks carry changes through automatically.
 set -euo pipefail
 
@@ -9,12 +9,17 @@ GEMINI_EXT_DIR="$REPO_ROOT/.gemini/extensions/bigpowers"
 GEMINI_SKILLS="$GEMINI_EXT_DIR/skills"
 GEMINI_COMMANDS="$GEMINI_EXT_DIR/commands"
 GEMINI_MANIFEST="$GEMINI_EXT_DIR/gemini-extension.json"
+PI_SKILLS="$REPO_ROOT/.pi/skills"
+PI_PROMPTS="$REPO_ROOT/.pi/prompts"
+PI_PACKAGE_JSON="$REPO_ROOT/.pi/package.json"
 
-mkdir -p "$CURSOR_RULES" "$GEMINI_SKILLS" "$GEMINI_COMMANDS"
+mkdir -p "$CURSOR_RULES" "$GEMINI_SKILLS" "$GEMINI_COMMANDS" "$PI_SKILLS" "$PI_PROMPTS"
 
 # Clear old artifacts to ensure a clean sync
 rm -rf "${GEMINI_SKILLS:?}"/*
 rm -rf "${GEMINI_COMMANDS:?}"/*
+rm -rf "${PI_SKILLS:?}"/*
+rm -rf "${PI_PROMPTS:?}"/*
 
 # We'll collect metadata for the manifest if needed, 
 # though skills/commands are auto-discovered.
@@ -82,6 +87,28 @@ for skill_dir in "$REPO_ROOT"/*/; do
     echo "prompt = \"@{$prompt_file}\""
   } > "$GEMINI_COMMANDS/$name.toml"
 
+  # 4. Write pi skill: .pi/skills/<name>/SKILL.md
+  # Pi implements the Agent Skills standard — same YAML frontmatter + body format
+  mkdir -p "$PI_SKILLS/$name"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: \"$description\""
+    echo "---"
+    echo ""
+    echo "$body"
+  } > "$PI_SKILLS/$name/SKILL.md"
+
+  # 5. Write pi prompt template: .pi/prompts/<name>.md
+  # Slash-command templates expandable via /<name> in pi's editor
+  {
+    echo "---"
+    echo "description: $description"
+    echo "---"
+    echo ""
+    echo "$body"
+  } > "$PI_PROMPTS/$name.md"
+
   skill_count=$((skill_count + 1))
 done
 
@@ -94,7 +121,22 @@ jq -n --arg name "bigpowers" \
       --arg desc "${skill_count} skills — ${pkg_desc}" \
       '{name: $name, version: $version, description: $desc}' > "$GEMINI_MANIFEST"
 
-# 4. Write OpenCode configuration: opencode.json (minimal project-level config)
+# 6. Write pi package config: .pi/package.json
+# Enables pi install (local path, npm, or git) with auto-discovered skills and prompts
+jq -n --arg version "$pkg_version" \
+      --arg desc "${skill_count} skills — ${pkg_desc}" \
+      '{
+        "name": "bigpowers",
+        "version": $version,
+        "description": $desc,
+        "keywords": ["pi-package"],
+        "pi": {
+          "skills": ["./skills"],
+          "prompts": ["./prompts"]
+        }
+      }' > "$PI_PACKAGE_JSON"
+
+# 7. Write OpenCode configuration: opencode.json (minimal project-level config)
 # Skills are loaded on-demand via opencode's native skill tool, not instructions.
 # Full opencode integration lives in the bigpowers-opencode repo.
 {
@@ -140,6 +182,9 @@ echo "  → .cursor/rules/ ($skill_count .mdc files)"
 echo "  → .gemini/extensions/bigpowers/skills/ (Agent Skills)"
 echo "  → .gemini/extensions/bigpowers/commands/ (Slash Commands)"
 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 "  → opencode.json (CLAUDE.md + CONVENTIONS.md instructions)"
 [[ -n "$OPN_TARGET" ]] && echo "  → bigpowers-opencode: $opencode_count skills"
 

package/scripts/validate-doctrine.sh

@@ -40,23 +40,21 @@ else
   done
 fi
 
-# ── Epic 1: Legacy MD artifact names in docs/ (excluding historical file-structure/) ──
-# docs/file-structure/ is intentional historical comparison material (Epic 6 archives it).
+# ── Epic 1: Legacy MD artifact names in live docs/ (docs/archive/ exempt) ─────
+# docs/archive/ holds historical/exploratory material (Epic 6); legacy names there are expected.
 echo "--- [Epic 1] legacy MD artifact names in docs/ ---"
 LEGACY_HITS=$(grep -rE "PLAN\.md|STATE\.md|PROJECT\.md|CONTEXT\.md|SUMMARY\.md|VERIFICATION\.md|RESEARCH\.md|RELEASE-PLAN\.md" \
   docs/ 2>/dev/null \
-  | grep -v "docs/file-structure/" \
-  | grep -v "docs/report-gsd-integration.md" \
+  | grep -v "docs/archive/" \
   | grep -v "specs/archive" \
   | wc -l | tr -d ' ') || true
 if [[ "$LEGACY_HITS" -eq 0 ]]; then
-  pass "no legacy MD artifact names in docs/ (outside file-structure/)"
+  pass "no legacy MD artifact names in live docs/ (docs/archive/ exempt)"
 else
   fail "legacy MD artifact names found in docs/ ($LEGACY_HITS occurrences)"
   grep -rE "PLAN\.md|STATE\.md|PROJECT\.md|CONTEXT\.md|SUMMARY\.md|VERIFICATION\.md|RESEARCH\.md|RELEASE-PLAN\.md" \
     docs/ 2>/dev/null \
-    | grep -v "docs/file-structure/" \
-    | grep -v "docs/report-gsd-integration.md" \
+    | grep -v "docs/archive/" \
     | grep -v "specs/archive" | head -20 >&2
 fi
 
@@ -80,7 +78,7 @@ echo "--- [Epic 2] canonical specs/ subpaths ---"
 LEGACY_SPECS=$(grep -rE "specs/(requirements|plans|audit)\b" \
   --include="*.md" --include="*.sh" --include="*.yaml" --include="*.yml" --include="*.json" . \
   2>/dev/null \
-  | grep -v "specs/archive\|specs/epics/archive\|\.git\|node_modules\|\.gemini\|\.cursor" \
+  | grep -v "specs/archive\|specs/epics/archive\|docs/archive/\|\.git\|node_modules\|\.gemini\|\.cursor" \
   | grep -v "CHANGELOG\.md\|specs/verifications/reports/\|PLAN-evolve-structure\.md" \
   | wc -l | tr -d ' ') || true
 if [[ "$LEGACY_SPECS" -eq 0 ]]; then
@@ -90,7 +88,7 @@ else
   grep -rE "specs/(requirements|plans|audit)\b" \
     --include="*.md" --include="*.sh" --include="*.yaml" --include="*.yml" --include="*.json" . \
     2>/dev/null \
-    | grep -v "specs/archive\|specs/epics/archive\|\.git\|node_modules\|\.gemini\|\.cursor" \
+    | grep -v "specs/archive\|specs/epics/archive\|docs/archive/\|\.git\|node_modules\|\.gemini\|\.cursor" \
     | grep -v "CHANGELOG\.md\|specs/verifications/reports/\|PLAN-evolve-structure\.md" \
     | head -10 >&2
 fi
@@ -117,6 +115,23 @@ else
   bash "$REPO_ROOT/scripts/check-skill-size.sh" 2>&1 | grep "^FAIL:" >&2 || true
 fi
 
+# ── Epic 5: Critical-path skills document a handoff target ─────────────────────
+echo "--- [Epic 5] critical-path handoff targets ---"
+CRITICAL_HANDOFF=(survey-context plan-work develop-tdd verify-work audit-code release-branch kickoff-branch commit-message)
+MISSING_HANDOFF=()
+for s in "${CRITICAL_HANDOFF[@]}"; do
+  if [[ -f "$s/SKILL.md" ]] && ! grep -qiE "handoff|next_skill|next:" "$s/SKILL.md"; then
+    MISSING_HANDOFF+=("$s")
+  fi
+done
+if [[ ${#MISSING_HANDOFF[@]} -eq 0 ]]; then
+  pass "all critical-path skills document a handoff target"
+else
+  for s in "${MISSING_HANDOFF[@]}"; do
+    fail "critical-path skill '$s' has no documented handoff/next_skill"
+  done
+fi
+
 # ── Summary ────────────────────────────────────────────────────────────────────
 echo "---"
 if [[ "$ERRORS" -eq 0 ]]; then

package/seed-conventions/SKILL.md

@@ -53,6 +53,8 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 
 **Note:** `specs/state.yaml.lock` is NOT pre-created — acquired/released dynamically.
 
+`specs/state.yaml` carries a top-level `workflow_mode` key (`team-pr` | `solo-git`, default `team-pr`). This is the **canonical integrate-mode signal** for all skills — set it once here and skills such as `release-branch` read it from this file instead of sniffing profile files.
+
 ## Verify
 
 - [ ] CLAUDE.md exists and is populated

package/slice-tasks/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: slice-tasks
-description: Break a plan or PRD into vertical-slice stories in specs/epics/ (replaces legacy TASKS.md). Use after scope-work or plan-release, before plan-work.
+description: "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical-slice stories in specs/epics/. Use after scope-work (step 1), before plan-work (step 3). Not a substitute for scope-work or plan-work."
 model: sonnet
 ---
 
 # Slice Tasks
 
+> **Spine position:** Step 2 — scope-work → slice-tasks → plan-work.
+
 Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical slices, each independently deliverable and testable. Output: decoupled `eNNsYY-tasks.yaml` files with runnable verify commands. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use capsule dirs + `execution-status.yaml`.
 
 ## Process

package/survey-context/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: survey-context
 model: haiku
-description: Per-task context survey — reads specs/ and CONVENTIONS.md, maps the current lifecycle phase, and suggests the next skill to invoke. Use at the start of any new task, when returning to a project after a break, or when unsure what to do next.
+description: Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first.
 ---
 
 # Survey Context
 
 Read the project's current state and give a phase map + next-skill recommendation. This is the "where am I?" skill — run it at the start of every task.
 
+> **Use this vs map-codebase:** `survey-context` consumes existing specs and docs (fast; does not re-derive). `map-codebase` builds the tech-stack doc from scratch by scanning the codebase. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
 > **HARD GATE** — Read specs/ files before suggesting next steps. If state.yaml is stale or contradicts the codebase, request clarification rather than assuming intent.
 
 Orchestrate-project 6 phases: Phase 1 Discover - Phase 2 Elaborate - Phase 3 Plan - Phase 4 Build - Phase 5 Verify - Phase 6 Release

package/write-document/SKILL.md

@@ -8,6 +8,8 @@ description: Write, organize, and sync high-integrity technical documents using
 
 Create high-signal technical documentation that serves as an expert collaborator for both humans and AI. This skill enforces the BMAD principles to prevent context rot and ensure architectural durability.
 
+**Distinct from `edit-document`:** Use this skill to create a document that does not yet exist. Use `edit-document` when a document already exists and needs restructuring, clarity, or prose improvements.
+
 > **HARD GATE** — Every document must have a clear "Reason for Existence." If a document doesn't provide actionable leverage for a caller or test, do not create it.
 
 ## The BMAD Principles