bigpowers 1.0.0

package/release-branch/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: release-branch
+description: Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says "release", "merge", or "open a PR".
+---
+
+# Release Branch
+
+> **HARD GATE** — Do NOT merge or release if tests fail or if coverage gates are not met. If the branch is red, return to `develop-tdd` to fix regressions or add missing tests before proceeding.
+
+Finalize a completed feature branch: verify coverage gates, open a PR, and clean up the worktree.
+
+## Process
+
+### 1. Final verification
+
+Run the full suite one last time on the feature branch:
+
+```bash
+<full test command>
+<typecheck command>
+<lint command>
+# Verify Conventional Commits history
+git log main...HEAD --oneline | grep -vE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ ERROR: Non-conventional commits found" || echo "✅ Commits verified"
+```
+
+- [ ] All tests pass
+- [ ] No type errors
+- [ ] No lint violations
+- [ ] All commits in branch history follow Conventional Commits 1.0.0
+
+### 2. Coverage check
+
+Verify coverage meets the project gates:
+
+- [ ] Overall coverage ≥ 80%
+- [ ] Business logic / domain layer coverage ≥ 95%
+
+If coverage is below the gate, stop and return to `develop-tdd` to add missing tests.
+
+### 3. Diff review
+
+```bash
+git diff main...HEAD --stat
+git log main...HEAD --oneline
+```
+
+Confirm:
+- [ ] All commits are intentional — no debug commits, no "WIP" commits
+- [ ] No secrets, credentials, or personal data in the diff
+- [ ] CONVENTIONS.md compliance across all changes
+
+### 5. Decision
+
+Present the user with the options:
+
+| Option | When to choose |
+|--------|---------------|
+| **Open PR for Release** | Feature is complete, tests pass, ready to trigger automated release |
+| **Keep branch** | More work needed; preserve for later |
+| **Discard** | Approach was wrong; start over |
+
+### 6. Create PR (Triggers Automated Release)
+
+The PR title is the **single source of truth** for the version bump. It MUST follow Conventional Commits.
+
+```bash
+# Verify PR Title first
+PR_TITLE="<type>(<scope>): <description>"
+echo "$PR_TITLE" | grep -vE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ ERROR: PR Title must follow Conventional Commits"
+
+gh pr create \
+  --title "$PR_TITLE" \
+  --body "$(cat <<'EOF'
+## Summary
+- [What this PR does]
+- [Key decisions made]
+
+## Verify
+- [ ] All tests pass
+- [ ] Coverage gates met (≥80% overall, ≥95% business logic)
+- [ ] CONVENTIONS.md compliance verified
+- [ ] PR Title follows Conventional Commits (for automated release)
+
+## specs/ artifacts
+- [List any specs/ files produced or updated]
+EOF
+)"
+```
+
+### 7. Merge (Automated)
+
+Wait for CI to pass. Merge using **Squash and Merge** to ensure the PR title becomes the commit message on `main`.
+
+```bash
+gh pr merge --squash --delete-branch
+```
+
+`semantic-release` will now automatically:
+1. Detect the commit on `main`.
+2. Determine the SemVer bump from the commit type.
+3. Tag the repo (e.g., `v2.1.0`).
+4. Generate release notes.
+
+### 8. Clean up worktree (if using git worktree)
+
+```bash
+# From the main repo root
+git worktree prune             # clear stale metadata
+git worktree remove ../<branch-name> 2>/dev/null || true
+git branch -d <branch-name>
+```
+
+- If `git worktree remove` fails due to uncommitted changes, ask the user: "There are uncommitted changes in the worktree. Force remove? (y/n)". If yes: `git worktree remove -f ../<branch-name>`.
+- If the directory `../<branch-name>` is already missing, `git worktree remove` might fail; the `|| true` ensures the process continues to branch deletion.
+
+Report: "Branch released. PR: <URL>. Worktree cleaned up."

package/request-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: request-review
+description: Dispatch a fresh reviewer agent with a clean context to critique the code after audit-code passes. The reviewer has no shared state with the coding agent and gives a genuine second opinion. Use after audit-code passes, before committing, or when user wants an independent code review.
+---
+
+# Request Review
+
+Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code.
+
+**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed.
+
+**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer.
+
+**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself.
+
+## Process
+
+### 1. Prepare the review brief
+
+Write a self-contained brief for the reviewer agent. Include:
+
+- What was built (feature description, not implementation)
+- Which files changed (the diff context)
+- What `specs/` artifacts are relevant (PLAN.md, DIAGNOSIS.md, SCOPE.md)
+- What CONVENTIONS.md requires
+- What the verify command is
+- What you're most uncertain about (where you want fresh eyes)
+
+### 2. Dispatch the reviewer agent
+
+Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed."
+
+```
+You are a code reviewer. Review the following code changes.
+
+Context: [feature description]
+CONVENTIONS.md rules: [paste relevant sections]
+specs/PLAN.md: [paste or summarize]
+
+Diff: [paste git diff or describe changed files]
+
+Verify command: [runnable command]
+
+Review for:
+1. Correctness — does the code do what was intended?
+2. CONVENTIONS.md compliance — are all rules followed?
+3. Test quality — do tests verify behavior (not implementation)?
+4. Design — are there simpler or more robust approaches?
+5. Edge cases — what inputs or states could cause failures?
+6. Security — any injection, auth, or data exposure risks?
+
+For each finding, categorize as: must-fix / should-fix / consider.
+Run the verify command and report the result.
+```
+
+### 3. Collect the report
+
+When the reviewer returns:
+- Read every finding before acting on any
+- Note the verify command result
+- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items`
+- Report the score to the user
+
+> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first.
+
+### 4. Hand off to respond-review
+
+Pass the reviewer's report to `respond-review` to categorize findings and apply fixes.
+
+Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review."

package/respond-review/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: respond-review
+description: Act on a reviewer agent's feedback systematically — categorize findings, apply fixes, verify tests still pass. Use after request-review returns a report, or when user wants to work through code review findings.
+---
+
+# Respond Review
+
+Work through reviewer findings systematically. Don't apply changes blindly — categorize first, then decide, then fix, then verify.
+
+## Process
+
+### 1. Read the full review report
+
+Read every finding before acting on any of them. Get the full picture first.
+
+### 2. Categorize findings
+
+For each finding, assign a category:
+
+| Category | Meaning | Action |
+|----------|---------|--------|
+| **must-fix** | Correctness bug, security issue, test failure, CONVENTIONS.md violation | Fix before proceeding |
+| **should-fix** | Code quality issue, naming, clarity — worth fixing but not blocking | Fix if time allows |
+| **consider** | Architectural suggestion, alternative approach — may or may not apply | Discuss with user |
+
+Create a numbered list of all findings with their categories.
+
+### 3. Confirm with user (for consider-category items)
+
+For each "consider" item, briefly describe the trade-off and ask: "Apply, skip, or discuss?"
+
+### 4. Apply must-fix items first
+
+Fix every must-fix item. For each one:
+- Describe what you're changing and why
+- Make the change
+- Run the verify command if one exists for this area
+
+### 5. Apply should-fix items
+
+Apply should-fix items. If any are large enough to warrant their own commit, note them separately.
+
+### 6. Run the full suite
+
+After all changes are applied:
+
+```bash
+<full test command>
+<typecheck command>
+<lint command>
+```
+
+- [ ] All tests pass
+- [ ] No type errors
+- [ ] No lint violations
+
+### 7. Report
+
+Summarize what was applied and what was skipped:
+
+```
+Applied (must-fix): #1, #2, #3
+Applied (should-fix): #4
+Skipped (consider): #5 — agreed with user to defer
+All tests pass.
+```
+
+Suggest next skill: `commit-message`.

package/scripts/audit-compliance.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# audit-compliance.sh — Agentic Gherkin Compliance Harness (LLM-Judge Upgrade)
+
+# --- Help Message ---
+show_help() {
+  cat <<EOF
+Usage: bash scripts/audit-compliance.sh [feature-file|directory] [options]
+
+Options:
+  --help            Show this help message
+  --dry-run         Parse the feature file without starting the judge loop
+  --scenario [name] Run only a specific scenario
+  --judge [type]    Judge type: 'binary' (exit code, default) or 'gemini' (LLM-judged)
+  --model [name]    Model name to use for judging
+
+If a directory is provided, all .feature files in that directory will be processed.
+EOF
+}
+
+# --- Arguments Parsing ---
+DRY_RUN=false
+SCENARIO_FILTER=""
+JUDGE="binary"
+MODEL=""
+INPUTS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help)
+      show_help
+      exit 0
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --scenario)
+      SCENARIO_FILTER="$2"
+      shift 2
+      ;;
+    --judge)
+      JUDGE="$2"
+      shift 2
+      ;;
+    --model)
+      MODEL="$2"
+      shift 2
+      ;;
+    -*)
+      echo "Unknown option: $1"
+      show_help
+      exit 1
+      ;;
+    *)
+      INPUTS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ ${#INPUTS[@]} -eq 0 ]]; then
+  echo "Error: No feature file or directory specified."
+  show_help
+  exit 1
+fi
+
+# --- Global Stats ---
+TOTAL_GLOBAL_PASS=0
+TOTAL_GLOBAL_FAIL=0
+
+# --- Judging Logic ---
+
+judge_with_gemini() {
+  local step="$1"
+  local feature_name="$2"
+  local scenario_name="$3"
+  local evidence="$4"
+  local report_file="$5"
+
+  echo "    [JUDGE] Sending evidence to Gemini CLI..."
+  
+  local prompt="You are the Master Test Architect judging a compliance audit.
+Benchmark Feature: $feature_name
+Scenario: $scenario_name
+Compliance Step: $step
+
+Evidence gathered from the codebase:
+---
+$evidence
+---
+
+Based on the benchmark principles, does this evidence demonstrate compliance?
+Respond strictly in the following format:
+VERDICT: [PASS/FAIL]
+RATIONALE: [One sentence explanation]"
+
+  local model_output
+  local gemini_cmd="gemini --approval-mode plan"
+  if [[ -n "$MODEL" ]]; then
+    gemini_cmd="$gemini_cmd -m $MODEL"
+  fi
+  
+  model_output=$($gemini_cmd -p "$prompt" 2>&1)
+  local exit_code=$?
+
+  if [[ $exit_code -eq 0 ]]; then
+    local verdict
+    verdict=$(echo "$model_output" | grep "VERDICT:" | cut -d' ' -f2)
+    local rationale
+    rationale=$(echo "$model_output" | grep "RATIONALE:" | cut -d' ' -f2-)
+
+    if [[ "$verdict" == "PASS" ]]; then
+      echo "      Result: PASS"
+      echo "- [x] $step (PASS) - $rationale" >> "$report_file"
+      return 0
+    else
+      echo "      Result: FAIL"
+      echo "- [ ] $step (FAIL) - $rationale" >> "$report_file"
+      return 1
+    fi
+  else
+    echo "      Result: ERROR (Gemini CLI failed)"
+    echo "- [ ] $step (ERROR) - Gemini CLI exit code $exit_code. Output: $model_output" >> "$report_file"
+    return 1
+  fi
+}
+
+judge_binary() {
+  local step="$1"
+  local exit_code="$2"
+  local evidence="$3"
+  local report_file="$4"
+
+  if [[ $exit_code -eq 0 ]]; then
+    echo "      Result: PASS"
+    echo "- [x] $step (PASS)" >> "$report_file"
+    return 0
+  else
+    echo "      Result: FAIL"
+    echo "- [ ] $step (FAIL) - $evidence" >> "$report_file"
+    return 1
+  fi
+}
+
+# --- Core Execution ---
+
+process_step() {
+  local step="$1"
+  local feature_name="$2"
+  local scenario_name="$3"
+  local report_file="$4"
+  echo "    [STEP] $step"
+  
+  if [[ "$DRY_RUN" == "true" ]]; then
+    return 0
+  fi
+
+  local sanitized_step
+  sanitized_step=$(echo "$step" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  local step_script="specs/audit/steps/${sanitized_step}.sh"
+
+  if [[ -f "$step_script" ]]; then
+    echo "    [EXEC] Gathering evidence: $step_script"
+    local evidence
+    evidence=$(bash "$step_script" 2>&1)
+    local exit_code=$?
+
+    if [[ "$JUDGE" == "gemini" ]]; then
+      judge_with_gemini "$step" "$feature_name" "$scenario_name" "$evidence" "$report_file"
+    else
+      judge_binary "$step" "$exit_code" "$evidence" "$report_file"
+    fi
+  else
+    echo "      Result: FAIL (Missing evidence: $step_script)"
+    echo "- [ ] $step (FAIL) - No verification script found at $step_script" >> "$report_file"
+    return 1
+  fi
+}
+
+run_audit_file() {
+  local FEATURE_FILE="$1"
+  echo "------------------------------------------------------------"
+  echo "FEATURE: $FEATURE_FILE"
+  
+  local REPORT_FILE="specs/audit/reports/audit-$(basename "$FEATURE_FILE" .feature)-$(date +%Y%m%d-%H%M%S).md"
+  mkdir -p specs/audit/reports
+
+  echo "# Audit Report: $FEATURE_FILE" > "$REPORT_FILE"
+  echo "Date: $(date)" >> "$REPORT_FILE"
+  echo "Mode: Autonomous Verification (Judge: $JUDGE)" >> "$REPORT_FILE"
+  echo "" >> "$REPORT_FILE"
+
+  local TOTAL_PASS=0
+  local TOTAL_FAIL=0
+  local CURRENT_FEATURE=""
+  local CURRENT_SCENARIO=""
+  local IN_SCENARIO=false
+
+  while IFS= read -r line; do
+    line=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    
+    if [[ "$line" =~ ^Feature: ]]; then
+      CURRENT_FEATURE="${line#Feature: }"
+      echo "FEATURE: $CURRENT_FEATURE"
+      echo "## Feature: $CURRENT_FEATURE" >> "$REPORT_FILE"
+    elif [[ "$line" =~ ^Scenario: ]]; then
+      CURRENT_SCENARIO="${line#Scenario: }"
+      if [[ -n "$SCENARIO_FILTER" && "$CURRENT_SCENARIO" != "$SCENARIO_FILTER" ]]; then
+        IN_SCENARIO=false
+        continue
+      fi
+      IN_SCENARIO=true
+      echo "  SCENARIO: $CURRENT_SCENARIO"
+      echo "### Scenario: $CURRENT_SCENARIO" >> "$REPORT_FILE"
+    elif [[ "$line" =~ ^(Given|When|Then|And|But)\  ]]; then
+      if [[ "$IN_SCENARIO" == "true" ]]; then
+        if process_step "$line" "$CURRENT_FEATURE" "$CURRENT_SCENARIO" "$REPORT_FILE"; then
+          ((TOTAL_PASS++))
+          ((TOTAL_GLOBAL_PASS++))
+        else
+          ((TOTAL_FAIL++))
+          ((TOTAL_GLOBAL_FAIL++))
+        fi
+      fi
+    fi
+  done < "$FEATURE_FILE"
+
+  echo ""
+  echo "File Summary: PASS: $TOTAL_PASS, FAIL: $TOTAL_FAIL"
+  echo "Report saved to: $REPORT_FILE"
+}
+
+# --- Main Execution ---
+for input in "${INPUTS[@]}"; do
+  if [[ -d "$input" ]]; then
+    for f in "$input"/*.feature; do
+      if [[ -f "$f" ]]; then
+        run_audit_file "$f"
+      fi
+    done
+  elif [[ -f "$input" ]]; then
+    run_audit_file "$input"
+  else
+    echo "Warning: Input not found: $input"
+  fi
+done
+
+echo "============================================================"
+echo "Global Audit Summary:"
+echo "  TOTAL PASS: $TOTAL_GLOBAL_PASS"
+echo "  TOTAL FAIL: $TOTAL_GLOBAL_FAIL"
+echo "============================================================"
+
+if [[ $TOTAL_GLOBAL_FAIL -gt 0 ]]; then
+  exit 1
+fi

package/scripts/cleanup-worktrees.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# cleanup-worktrees.sh — Identify and remove stale git worktrees
+set -euo pipefail
+
+# 1. Prune stale metadata (ghost worktrees where directory was manually deleted)
+echo "Pruning stale worktree metadata..."
+git worktree prune
+
+# 2. List current worktrees
+echo "Current worktrees:"
+git worktree list --porcelain | grep "^worktree" | awk '{print $2}'
+
+# 3. Identify worktrees whose branches are merged or deleted
+echo ""
+echo "Checking for stale worktrees (merged branches)..."
+MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
+
+git worktree list --porcelain | while read -r line; do
+    if [[ $line =~ ^worktree\ (.*) ]]; then
+        WT_PATH="${BASH_REMATCH[1]}"
+    elif [[ $line =~ ^branch\ refs/heads/(.*) ]]; then
+        WT_BRANCH="${BASH_REMATCH[1]}"
+        
+        # Skip main branch
+        if [[ "$WT_BRANCH" == "$MAIN_BRANCH" ]]; then
+            continue
+        fi
+
+        # Check if branch is merged into main
+        if git merge-base --is-ancestor "$WT_BRANCH" "$MAIN_BRANCH" 2>/dev/null; then
+            echo "MERGED: $WT_BRANCH at $WT_PATH"
+            echo "  Run: git worktree remove $WT_PATH && git branch -d $WT_BRANCH"
+        else
+            # Check if branch still exists (might have been deleted elsewhere)
+            if ! git show-ref --verify --quiet "refs/heads/$WT_BRANCH"; then
+                echo "MISSING BRANCH: $WT_BRANCH at $WT_PATH (branch was deleted)"
+                echo "  Run: git worktree remove $WT_PATH"
+            fi
+        fi
+    fi
+done
+
+echo ""
+echo "Cleanup complete."

package/scripts/install-cursor-skills-local.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Install skills into a project: <install-root>/.cursor/skills (not ~/.cursor/skills).
+# Usage: ./scripts/install-cursor-skills-local.sh [INSTALL_ROOT]
+#   INSTALL_ROOT defaults to the current working directory. Skills are read from
+#   this skills repository unless SOURCE_DIR is set.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+INSTALL_ROOT="$(cd "${1:-"$PWD"}" && pwd)"
+export TARGET_DIR="${TARGET_DIR:-"$INSTALL_ROOT/.cursor/skills"}"
+export SOURCE_DIR="${SOURCE_DIR:-$REPO_ROOT}"
+
+exec "$REPO_ROOT/scripts/install-cursor-skills.sh"

package/scripts/install-cursor-skills.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SOURCE_DIR="${SOURCE_DIR:-$REPO_ROOT}"
+TARGET_DIR="${TARGET_DIR:-"$HOME/.cursor/skills"}"
+
+if [[ ! -d "$SOURCE_DIR" ]]; then
+  echo "SOURCE_DIR is not a directory: $SOURCE_DIR" >&2
+  exit 1
+fi
+
+mkdir -p "$TARGET_DIR"
+
+shopt -s nullglob
+count=0
+for item in "$SOURCE_DIR"/*; do
+  [[ -d "$item" ]] || continue
+  name="$(basename "$item")"
+  [[ -f "$item/SKILL.md" ]] || continue
+  if [[ "$name" == .?* ]]; then
+    continue
+  fi
+  echo "Syncing <${name}>"
+  rsync -a --delete "$item/" "$TARGET_DIR/${name}/"
+  count=$((count + 1))
+done
+
+if [[ "$count" -eq 0 ]]; then
+  echo "No top-level skill directories with SKILL.md found in $SOURCE_DIR" >&2
+  exit 1
+fi
+
+echo "Done. Installed $count skills under $TARGET_DIR"