bigpowers 2.1.3 → 2.3.0

package/scripts/generate-reference-tables.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Regenerates the auto-generated catalog section in docs/references/model-profiles.md
+# from live */SKILL.md frontmatter. Run after any SKILL.md addition/rename.
+# Called by sync-skills.sh and npm version hooks.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+TARGET="$REPO_ROOT/docs/references/model-profiles.md"
+
+cd "$REPO_ROOT"
+
+# --- 1. Collect live skill→model pairs ---
+declare -a ROWS=()
+while IFS= read -r line; do
+  skill_dir="${line%%/SKILL.md*}"
+  model_raw="${line##*model: }"
+  model="${model_raw// /}"
+  ROWS+=("$skill_dir $model")
+done < <(grep -r "^model:" */SKILL.md | sed 's|/SKILL.md:model:||' | sort)
+
+TOTAL=${#ROWS[@]}
+
+# --- 2. Build replacement block ---
+BLOCK="<!-- AUTO-GENERATED-CATALOG: begin — do not edit manually; run scripts/generate-reference-tables.sh -->
+| Skill | Model |
+|-------|-------|"
+for row in "${ROWS[@]}"; do
+  skill="${row%% *}"
+  model="${row##* }"
+  # capitalise first letter for display
+  model_cap="$(echo "${model:0:1}" | tr '[:lower:]' '[:upper:]')${model:1}"
+  BLOCK+="
+| \`$skill\` | **$model_cap** |"
+done
+BLOCK+="
+
+Total: **$TOTAL** skills — verify with \`ls -d \*/SKILL.md | wc -l\`
+<!-- AUTO-GENERATED-CATALOG: end -->"
+
+# --- 3. Splice block into target file ---
+# Replace between marker comments if they exist; otherwise append.
+if grep -q "AUTO-GENERATED-CATALOG: begin" "$TARGET"; then
+  python3 - "$TARGET" "$BLOCK" <<'PYEOF'
+import sys, re
+path = sys.argv[1]
+block = sys.argv[2]
+text = open(path).read()
+new_text = re.sub(
+    r'<!-- AUTO-GENERATED-CATALOG: begin.*?<!-- AUTO-GENERATED-CATALOG: end -->',
+    block,
+    text,
+    flags=re.DOTALL
+)
+open(path, 'w').write(new_text)
+PYEOF
+else
+  printf '\n\n## Full Skill Catalog (auto-generated)\n\n%s\n' "$BLOCK" >> "$TARGET"
+fi
+
+# --- 4. Update the "expect N" count assertion (legacy line) ---
+# Replaces "expect NN" with the live count so the prose stays accurate.
+sed -i.bak "s/expect [0-9]*/expect $TOTAL/" "$TARGET" && rm -f "${TARGET}.bak"
+
+echo "generate-reference-tables: updated $TARGET ($TOTAL skills)"

package/scripts/project-survey.sh

@@ -13,7 +13,7 @@ specs_files=""
 if [[ "$has_specs" == "true" ]]; then
   specs_files=$( {
     ls specs/*.yaml 2>/dev/null || true
-    ls specs/requirements/*.yaml 2>/dev/null || true
+    ls specs/product/*.yaml 2>/dev/null || true
     ls specs/*.md 2>/dev/null || true
   } | xargs -n1 basename 2>/dev/null | sort -u | tr '\n' ',' | sed 's/,$//')
 fi
@@ -34,7 +34,7 @@ if [[ -f "specs/state.yaml" ]]; then
   esac
 elif [[ -f "specs/release-plan.yaml" ]]; then
   phase="Plan"
-elif [[ -f "specs/requirements/SCOPE_LATEST.yaml" ]] || [[ -f "specs/SCOPE.md" ]]; then
+elif [[ -f "specs/product/SCOPE_LATEST.yaml" ]] || [[ -f "specs/SCOPE.md" ]]; then
   phase="Design"
 elif [[ "$current_branch" != "main" && "$current_branch" != "master" ]]; then
   phase="Initiate"

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"
 
@@ -161,4 +206,7 @@ if [[ -f "$manifest" ]]; then
   fi
 fi
 
+# Regenerate derived reference tables from live SKILL.md frontmatter
+bash "$REPO_ROOT/scripts/generate-reference-tables.sh"
+
 exit 0

package/scripts/validate-doctrine.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# Doctrine drift guard — fails CI if any tracked invariants regress.
+# Run after sync-skills.sh and before merging any branch.
+# Extended by each epic: add new assertions below the relevant section header.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+ERRORS=0
+
+fail() {
+  echo "FAIL: $*" >&2
+  ERRORS=$((ERRORS + 1))
+}
+
+pass() {
+  echo "ok  : $*"
+}
+
+# ── Epic 1: Dead skill names in model-profiles.md ─────────────────────────────
+# Scope: model-profiles.md is the canonical skill-roster reference.
+# Other docs may legitimately reference npm tools or conceptual names.
+echo "--- [Epic 1] dead skill names in docs/references/model-profiles.md ---"
+DEAD=()
+while IFS= read -r name; do
+  if [[ ! -d "$name" ]]; then
+    DEAD+=("$name")
+  fi
+done < <(grep -oE '`[a-z][a-z-]+`' docs/references/model-profiles.md \
+  | tr -d '`' \
+  | grep -E '^[a-z]+-[a-z]+(-[a-z]+)?$' \
+  | sort -u)
+
+if [[ ${#DEAD[@]} -eq 0 ]]; then
+  pass "all skill names in model-profiles.md resolve to real directories"
+else
+  for name in "${DEAD[@]}"; do
+    fail "dead skill name in model-profiles.md: '$name' has no matching directory"
+  done
+fi
+
+# ── 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/archive/" \
+  | grep -v "specs/archive" \
+  | wc -l | tr -d ' ') || true
+if [[ "$LEGACY_HITS" -eq 0 ]]; then
+  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/archive/" \
+    | grep -v "specs/archive" | head -20 >&2
+fi
+
+# ── Epic 1: Skill count consistency ───────────────────────────────────────────
+echo "--- [Epic 1] skill count consistency ---"
+LIVE_COUNT=$(ls -d */SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+STALE_COUNT_HITS=$(grep -rE "expect [0-9]+" docs/ 2>/dev/null \
+  | grep -v "expect $LIVE_COUNT" | wc -l | tr -d ' ') || true
+if [[ "$STALE_COUNT_HITS" -eq 0 ]]; then
+  pass "skill count annotations match live count ($LIVE_COUNT)"
+else
+  fail "stale skill count annotation in docs/ (live=$LIVE_COUNT, $STALE_COUNT_HITS mismatches)"
+  grep -rE "expect [0-9]+" docs/ 2>/dev/null | grep -v "expect $LIVE_COUNT" >&2
+fi
+
+# ── Epic 2: Non-canonical specs/ subpaths ─────────────────────────────────────
+# Exclusions: specs/archive, specs/epics/archive, CHANGELOG.md (auto-gen),
+#   specs/verifications/reports/ (generated reports), PLAN-evolve-structure.md
+#   (migration plan that documents the before→after paths as historical record).
+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\|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
+  pass "no legacy specs/ subpaths (requirements/, plans/, audit/)"
+else
+  fail "legacy specs/ subpaths found ($LEGACY_SPECS occurrences)"
+  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\|docs/archive/\|\.git\|node_modules\|\.gemini\|\.cursor" \
+    | grep -v "CHANGELOG\.md\|specs/verifications/reports/\|PLAN-evolve-structure\.md" \
+    | head -10 >&2
+fi
+
+# ── Epic 3: BCP slop guard ────────────────────────────────────────────────────
+echo "--- [Epic 3] BCP terminology ---"
+BCP_SLOP=$(grep -ri "build commit point" . 2>/dev/null \
+  | grep -v "specs/archive\|\.git\|node_modules\|\.gemini\|\.cursor\|validate-doctrine\.sh" \
+  | wc -l | tr -d ' ') || true
+if [[ "$BCP_SLOP" -eq 0 ]]; then
+  pass "no 'Build Commit Point' slop — BCP = Business Complexity Points"
+else
+  fail "'Build Commit Point' found ($BCP_SLOP hits) — canonical term is 'Business Complexity Points'; see docs/references/bcp.md"
+  grep -ri "build commit point" . 2>/dev/null \
+    | grep -v "specs/archive\|\.git\|node_modules\|\.gemini\|\.cursor\|validate-doctrine\.sh" | head -5 >&2
+fi
+
+# ── Epic 4: SKILL.md size cap ─────────────────────────────────────────────────
+echo "--- [Epic 4] SKILL.md size cap ---"
+if bash "$REPO_ROOT/scripts/check-skill-size.sh" >/dev/null 2>&1; then
+  pass "all SKILL.md files within tiered size cap (150 critical-path / 120 utility)"
+else
+  fail "a SKILL.md exceeds its size cap — run: bash scripts/check-skill-size.sh"
+  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
+  echo "validate-doctrine: ALL checks passed"
+  exit 0
+else
+  echo "validate-doctrine: $ERRORS check(s) FAILED" >&2
+  exit 1
+fi

package/seed-conventions/REFERENCE.md

@@ -0,0 +1,63 @@
+# Seed Conventions — Reference Templates
+
+## Agent config template (CLAUDE.md / GEMINI.md / AGENTS.md)
+
+All three files use the same structure — only the header differs:
+- `CLAUDE.md` → `# [Project Name] — Claude Code`
+- `GEMINI.md` → `# [Project Name] — Gemini CLI`
+- `AGENTS.md` → `# [Project Name] — OpenCode`
+
+```markdown
+# [Project Name] — [Agent]
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+[One sentence description]
+Stack: [language, framework, runtime]
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `[cmd]` |
+| Test   | `[cmd]` |
+| Build  | `[cmd]` |
+| Lint   | `[cmd]` |
+
+## Architecture
+[1–2 sentences. Key modules and their relationships.]
+
+## Conventions
+- [convention 1]
+- [convention 2]
+
+## Never
+- [hard stop 1]
+- [hard stop 2]
+
+## Agent Rules
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ before writing code.
+- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
+- Write the minimum code that solves the stated problem. Nothing extra.
+- Never refactor, rename, or reorganize code outside the task scope.
+- Run tests after every change. Show evidence before declaring done.
+- One clarifying question beats a wrong assumption baked into 200 lines.
+```
+
+## opencode.json template
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".cursor/rules/*.mdc"]
+}
+```
+
+## CONVENTIONS.md
+
+Use the standard bigpowers CONVENTIONS.md as the base. Fill in the project-specific defensive code categories from the interview answers.
+
+## Stack profile fragments
+
+If the user selected a stack profile, merge the matching `profiles/<name>.md` fragment into the generated `CONVENTIONS.md` under a `## Stack Conventions` section. Profiles supply language-specific commands, architecture patterns, and never-do additions.

package/seed-conventions/SKILL.md

@@ -5,8 +5,7 @@ description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project throu
 ---
 
 # Seed Conventions
-> **HARD GATE** — **HARD GATE** — Before any new code lands, confirm the project conventions are understood. Ask: 'What does a good commit message look like in this project?'
-
+> **HARD GATE** — Before any new code lands, confirm the project conventions are understood. Ask: 'What does a good commit message look like in this project?'
 
 Bootstrap a new project with the AI agent conventions it needs. Run this once at the start of a greenfield project.
 
@@ -23,196 +22,43 @@ Bootstrap a new project with the AI agent conventions it needs. Run this once at
 Ask the user these questions (one at a time, wait for each answer):
 
 1. **Project name and one-sentence description** — "What is this project? One sentence."
-
 2. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
-
-2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md` (commands, architecture, never-do).
-
-3. **Commands** — "What commands do you use for: run, test, build, lint? I'll document them so agents know how to verify their work."
-
-4. **Architecture** — "Describe the key modules and their relationships in 1–2 sentences. What are the main moving parts?"
-
-5. **Conventions** — "Any naming conventions, file organization rules, or patterns that every contributor (human or agent) must follow?"
-
-6. **Never-do list** — "What are the hard stops? Things an agent must never touch or do in this project?"
-
-7. **Defensive code categories** — "Which of these apply to your project? (Rate limit / Retry with backoff / Circuit breaker / Timeout / Graceful degradation)"
+2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md`.
+3. **Commands** — "What commands do you use for: run, test, build, lint?"
+4. **Architecture** — "Key modules and relationships in 1–2 sentences."
+5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
+6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
+7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
 
 ## Generate files
 
-After the interview, generate:
-
-### `CLAUDE.md`
-
-```markdown
-# [Project Name] — Claude Code
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-## Project
-[One sentence description]
-Stack: [language, framework, runtime]
-
-## Commands
-| Action | Command |
-|--------|---------|
-| Run    | `[cmd]` |
-| Test   | `[cmd]` |
-| Build  | `[cmd]` |
-| Lint   | `[cmd]` |
-
-## Architecture
-[1–2 sentences. Key modules and their relationships.]
-
-## Conventions
-- [convention 1]
-- [convention 2]
-
-## Never
-- [hard stop 1]
-- [hard stop 2]
-
-## Agent Rules
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
-- Write the minimum code that solves the stated problem. Nothing extra.
-- Never refactor, rename, or reorganize code outside the task scope.
-- Run tests after every change. Show evidence before declaring done.
-- One clarifying question beats a wrong assumption baked into 200 lines.
-```
-
-### `GEMINI.md`
-
-```markdown
-# [Project Name] — Gemini CLI
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-## Project
-[One sentence description]
-Stack: [language, framework, runtime]
-
-## Commands
-| Action | Command |
-|--------|---------|
-| Run    | `[cmd]` |
-| Test   | `[cmd]` |
-| Build  | `[cmd]` |
-| Lint   | `[cmd]` |
-
-## Architecture
-[1–2 sentences. Key modules and their relationships.]
-
-## Conventions
-- [convention 1]
-- [convention 2]
-
-## Never
-- [hard stop 1]
-- [hard stop 2]
-
-## Agent Rules
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
-- Write the minimum code that solves the stated problem. Nothing extra.
-- Never refactor, rename, or reorganize code outside the task scope.
-- Run tests after every change. Show evidence before declaring done.
-- One clarifying question beats a wrong assumption baked into 200 lines.
-```
-
-### `AGENTS.md`
-
-```markdown
-# [Project Name] — OpenCode
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-## Project
-[One sentence description]
-Stack: [language, framework, runtime]
-
-## Commands
-| Action | Command |
-|--------|---------|
-| Run    | `[cmd]` |
-| Test   | `[cmd]` |
-| Build  | `[cmd]` |
-| Lint   | `[cmd]` |
-
-## Architecture
-[1–2 sentences. Key modules and their relationships.]
-
-## Conventions
-- [convention 1]
-- [convention 2]
-
-## Never
-- [hard stop 1]
-- [hard stop 2]
-
-## Agent Rules
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
-- Write the minimum code that solves the stated problem. Nothing extra.
-- Never refactor, rename, or reorganize code outside the task scope.
-- Run tests after every change. Show evidence before declaring done.
-- One clarifying question beats a wrong assumption baked into 200 lines.
-```
-
-### `opencode.json`
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "instructions": [".cursor/rules/*.mdc"]
-}
-```
-
-### `CONVENTIONS.md`
-
-Use the standard bigpowers CONVENTIONS.md template, filling in the project-specific defensive code categories from the interview.
+After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
+- `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` — from the agent-config template
+- `opencode.json` — from the opencode template
+- `CONVENTIONS.md` — bigpowers standard template + project defensive code categories
 
 ### `specs/` directory
 
-Create the evolved bigpowers directory structure:
-
 ```bash
-mkdir -p specs/product
-mkdir -p specs/product/snapshots
-mkdir -p specs/epics/archive
-mkdir -p specs/tech-architecture
-mkdir -p specs/adr
-mkdir -p specs/verifications
-mkdir -p specs/bugs
-
-# Create empty placeholder files
-touch specs/product/SCOPE_LATEST.yaml
-touch specs/product/VISION_LATEST.yaml
-touch specs/product/GLOSSARY_LATEST.yaml
-touch specs/release-plan.yaml
-touch specs/execution-status.yaml
-touch specs/planning-status.yaml
-touch specs/state.yaml
-touch specs/tech-architecture/tech-stack.md
-touch specs/tech-architecture/security.md
-touch specs/tech-architecture/test.md
-touch specs/tech-architecture/design.md
-touch specs/tech-architecture/REFACTOR_LATEST.md
-touch specs/tech-architecture/IMPACT_LATEST.md
+mkdir -p specs/product specs/product/snapshots specs/epics/archive
+mkdir -p specs/tech-architecture specs/adr specs/verifications specs/bugs
+touch specs/product/SCOPE_LATEST.yaml specs/product/VISION_LATEST.yaml specs/product/GLOSSARY_LATEST.yaml
+touch specs/release-plan.yaml specs/execution-status.yaml specs/planning-status.yaml specs/state.yaml
+touch specs/tech-architecture/tech-stack.md specs/tech-architecture/security.md
+touch specs/tech-architecture/test.md specs/tech-architecture/design.md
+touch specs/tech-architecture/REFACTOR_LATEST.md specs/tech-architecture/IMPACT_LATEST.md
 touch specs/bugs/registry.yaml
-echo "# Specs\n\nAll planning documents for this project. Evolved bigpowers structure (v2.0.0+)." > specs/README.md
+echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 ```
 
-**Note:** `specs/state.yaml.lock` is NOT pre-created — it is acquired and released dynamically during writes to prevent concurrency conflicts.
+**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
+## Verify
 
 - [ ] CLAUDE.md exists and is populated
 - [ ] CONVENTIONS.md exists and includes specs/ output convention
-- [ ] specs/ directory exists
 - [ ] specs/product/ exists with SCOPE_LATEST.yaml, VISION_LATEST.yaml, GLOSSARY_LATEST.yaml
 - [ ] specs/tech-architecture/ exists with tech-stack.md, security.md, test.md, design.md
 - [ ] specs/verifications/ exists

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