bigpowers 1.0.0

package/hook-commits/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: hook-commits
+description: Set up pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
+---
+
+# Hook Commits
+
+## What This Sets Up
+
+- **Husky** pre-commit hook
+- **lint-staged** running Prettier on all staged files
+- **Prettier** config (if missing)
+- **typecheck** and **test** scripts in the pre-commit hook
+
+## Steps
+
+### 1. Detect package manager
+
+Check for `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lockb` (bun). Use whichever is present. Default to npm if unclear.
+
+### 2. Install dependencies
+
+Install as devDependencies:
+
+```
+husky lint-staged prettier
+```
+
+### 3. Initialize Husky
+
+```bash
+npx husky init
+```
+
+This creates `.husky/` dir and adds `prepare: "husky"` to package.json.
+
+### 4. Create `.husky/pre-commit`
+
+Write this file (no shebang needed for Husky v9+):
+
+```
+npx lint-staged
+npm run typecheck
+npm run test
+```
+
+**Adapt**: Replace `npm` with detected package manager. If repo has no `typecheck` or `test` script in package.json, omit those lines and tell the user.
+
+### 5. Create `.lintstagedrc`
+
+```json
+{
+  "*": "prettier --ignore-unknown --write"
+}
+```
+
+### 6. Create `.prettierrc` (if missing)
+
+Only create if no Prettier config exists. Use these defaults:
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "semi": true,
+  "arrowParens": "always"
+}
+```
+
+### 7. Verify
+
+- [ ] `.husky/pre-commit` exists and is executable
+- [ ] `.lintstagedrc` exists
+- [ ] `prepare` script in package.json is `"husky"`
+- [ ] `prettier` config exists
+- [ ] Run `npx lint-staged` to verify it works
+
+### 8. Commit
+
+Stage all changed/created files and commit with message: `chore: add pre-commit hooks (husky + lint-staged + prettier)`
+
+This will run through the new pre-commit hooks — a good smoke test that everything works.
+
+## Notes
+
+- Husky v9+ doesn't need shebangs in hook files
+- `prettier --ignore-unknown` skips files Prettier can't parse (images, etc.)
+- The pre-commit runs lint-staged first (fast, staged-only), then full typecheck and tests

package/hooks/pre-tool-use.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# bigpowers — pre-tool-use.sh
+# Harness-agnostic Git Safety Hook for Claude Code, Cursor, and Gemini CLI.
+# Enforces:
+# 1. Block dangerous commands (push, reset --hard, etc.)
+# 2. Enforce Conventional Commits for 'git commit'
+# 3. Block direct commits/pushes to protected branches (main, master)
+
+set -euo pipefail
+
+# Configuration
+PROTECTED_BRANCHES=("main" "master")
+DANGEROUS_PATTERNS=(
+  "git push"
+  "git reset --hard"
+  "git clean -fd"
+  "git clean -f"
+  "git branch -D"
+  "git checkout \\."
+  "git restore \\."
+  "push --force"
+  "reset --hard"
+)
+CONVENTIONAL_COMMITS_REGEX='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:[[:space:]].+'
+
+# Detect mode from environment (for Gemini/Claude/Cursor parity)
+# GIT_GUARDRAILS_MODE: claude (default) | cursor | gemini
+MODE="${GIT_GUARDRAILS_MODE:-claude}"
+
+# Read input from stdin
+INPUT=$(cat)
+
+# Extract command using jq (standard in bigpowers)
+COMMAND=$(echo "$INPUT" | jq -r '.command // .tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  [ "$MODE" = "gemini" ] && echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# 1. Check for dangerous patterns
+for p in "${DANGEROUS_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qE "$p"; then
+    REASON="BLOCKED: '$COMMAND' matches dangerous pattern '$p'. Use a safer approach or ask the user."
+    if [ "$MODE" = "gemini" ]; then
+      jq -nc --arg reason "$REASON" '{decision: "deny", reason: $reason}'
+    else
+      echo "$REASON" >&2
+      exit 2
+    fi
+    exit 0
+  fi
+done
+
+# 2. Check for git commit / git push
+if [[ "$COMMAND" =~ git[[:space:]]+commit ]] || [[ "$COMMAND" =~ git[[:space:]]+push ]]; then
+  CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+  # Branch protection
+  if [[ "$COMMAND" =~ git[[:space:]]+push ]]; then
+    for b in "${PROTECTED_BRANCHES[@]}"; do
+      if [[ "$COMMAND" =~ [[:space:]]+$b ]] || [[ "$CURRENT_BRANCH" == "$b" ]]; then
+        REASON="BLOCKED: Direct push to protected branch '$b' is forbidden. Use a feature branch and PR."
+        if [ "$MODE" = "gemini" ]; then
+          jq -nc --arg reason "$REASON" '{decision: "deny", reason: $reason}'
+        else
+          echo "$REASON" >&2
+          exit 2
+        fi
+        exit 0
+      fi
+    done
+  fi
+
+  # Conventional Commits for 'git commit'
+  if [[ "$COMMAND" =~ git[[:space:]]+commit ]]; then
+    # Extract message from -m flag
+    MSG=""
+    if [[ "$COMMAND" =~ -m[[:space:]]+\"([^\"]+)\" ]]; then
+      MSG="${BASH_REMATCH[1]}"
+    elif [[ "$COMMAND" =~ -m[[:space:]]+\'([^\']+)\' ]]; then
+      MSG="${BASH_REMATCH[1]}"
+    fi
+
+    if [ -n "$MSG" ]; then
+      SUBJECT=$(echo "$MSG" | head -n 1)
+      if [[ ! "$SUBJECT" =~ $CONVENTIONAL_COMMITS_REGEX ]]; then
+        REASON="BLOCKED: Commit message must follow Conventional Commits: <type>(<scope>): <subject>. Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore."
+        if [ "$MODE" = "gemini" ]; then
+          jq -nc --arg reason "$REASON" '{decision: "deny", reason: $reason}'
+        else
+          echo "$REASON" >&2
+          exit 2
+        fi
+        exit 0
+      fi
+
+      if [ ${#SUBJECT} -gt 72 ]; then
+        REASON="BLOCKED: Commit subject line must be 72 characters or less."
+        if [ "$MODE" = "gemini" ]; then
+          jq -nc --arg reason "$REASON" '{decision: "deny", reason: $reason}'
+        else
+          echo "$REASON" >&2
+          exit 2
+        fi
+        exit 0
+      fi
+    fi
+
+    # Block direct commits to main
+    for b in "${PROTECTED_BRANCHES[@]}"; do
+      if [[ "$CURRENT_BRANCH" == "$b" ]]; then
+        REASON="BLOCKED: Direct commits to protected branch '$b' are forbidden. Use kickoff-branch to start a feature branch."
+        if [ "$MODE" = "gemini" ]; then
+          jq -nc --arg reason "$REASON" '{decision: "deny", reason: $reason}'
+        else
+          echo "$REASON" >&2
+          exit 2
+        fi
+        exit 0
+      fi
+    done
+  fi
+fi
+
+# Allow everything else
+if [ "$MODE" = "gemini" ]; then
+  echo '{"decision":"allow"}'
+fi
+exit 0

package/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+module.exports = {
+  name: 'bigpowers',
+  version: require('./package.json').version,
+};

package/inspect-quality/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: inspect-quality
+description: Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/BUG-LOG.md with a structured audit schema. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, or mentions "QA session".
+---
+
+# Inspect Quality
+
+Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and log each issue to `specs/BUG-LOG.md` with a structured, durable format.
+
+## For each issue the user raises
+
+### 1. Listen and lightly clarify
+
+Let the user describe the problem in their own words. Ask **at most 2–3 short clarifying questions** focused on:
+
+- What they expected vs what actually happened
+- Steps to reproduce (if not obvious)
+- Whether it's consistent or intermittent
+
+Do NOT over-interview. If the description is clear enough to log, move on.
+
+### 2. Explore the codebase in the background
+
+Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it's to:
+
+- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE.md` if present)
+- Understand what the feature is supposed to do
+- Identify the user-facing behavior boundary
+
+### 3. Assess scope: single issue or breakdown?
+
+Break down when:
+
+- The fix spans multiple independent areas
+- There are clearly separable concerns that could be worked on in parallel
+- The user describes something with multiple distinct failure modes
+
+Keep as a single issue when:
+
+- It's one behavior that's wrong in one place
+- The symptoms are all caused by the same root behavior
+
+### 4. Log to specs/BUG-LOG.md
+
+Append the issue to `specs/BUG-LOG.md`. Create the file and `specs/` directory if they don't exist.
+
+#### BUG-LOG.md format
+
+The file maintains a Markdown table with the following columns (derived from structured audit practice):
+
+| Field | Description |
+|-------|-------------|
+| `bug_id` | `BUG-YYYY-MM-DD-NNN` |
+| `date` | `YYYY-MM-DD` |
+| `severity` | `critical` / `high` / `medium` / `low` |
+| `priority` | `p0` / `p1` / `p2` / `p3` |
+| `scope` | kebab-case area (e.g. `auth`, `checkout`) |
+| `what_happened` | actual behavior (user-facing terms) |
+| `what_expected` | expected behavior |
+| `steps_to_reproduce` | numbered steps |
+| `root_cause` | one-line hypothesis |
+| `files_changed` | filled in after fix |
+| `approach` | filled in after fix |
+| `risk_level` | `low` / `medium` / `high` |
+| `new_tests` | count (filled in after fix) |
+| `type_check` | `pass` / `fail` (filled in after fix) |
+| `lint` | `pass` / `fail` (filled in after fix) |
+| `commit_type` | `fix` / `fix!` / `feat` (filled in after fix) |
+| `release_type` | `patch` / `minor` / `major` (filled in after fix) |
+| `commit_message` | Conventional Commits message (filled in after fix) |
+| `follow_ups` | semicolon-separated follow-up items |
+| `status` | `open` / `in-progress` / `fixed` / `wont-fix` |
+
+When a bug is fixed (via `validate-fix`), update the relevant row with the resolution fields.
+
+#### Issue body (for context below the table)
+
+For each bug, also append a detail section:
+
+```markdown
+### BUG-YYYY-MM-DD-NNN: [short title]
+
+**What happened:** [actual behavior, plain language]
+**What I expected:** [expected behavior]
+**Steps to reproduce:**
+1. [Step 1]
+2. [Step 2]
+
+**Additional context:** [domain-language observations, no file paths]
+```
+
+#### Rules for all entries
+
+- **No file paths or line numbers** — these go stale
+- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE.md` if it exists)
+- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws"
+- **Reproduction steps are mandatory** — if you can't determine them, ask the user
+
+### 5. Continue the session
+
+After logging, ask: "Next issue, or are we done?" Keep going until the user says done. Each issue is independent — don't batch them.

package/investigate-bug/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: investigate-bug
+description: Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/DIAGNOSIS.md. Use when user reports a bug, wants to investigate a problem, mentions "triage", or wants to plan a fix.
+---
+
+# Investigate Bug
+
+Investigate a reported problem, find its root cause, and write a TDD fix plan to `specs/DIAGNOSIS.md`. This is a mostly hands-off workflow — minimize questions to the user.
+
+## Process
+
+### 1. Capture the problem
+
+Get a brief description of the issue from the user. If they haven't provided one, ask ONE question: "What's the problem you're seeing?"
+
+Do NOT ask follow-up questions yet. Start investigating immediately.
+
+### 2. Explore and diagnose (4-phase RCA)
+
+Use the Agent tool with subagent_type=Explore to investigate the codebase. Run these phases in order:
+
+**Phase 1 — Reproduce**: Confirm the failure is consistent. Document exact inputs, environment, and observed vs. expected output. Do not proceed until you can reproduce reliably.
+
+**Phase 2 — Isolate**: Trace the code path from entry point to failure. Binary-search the call stack to find which layer first produces wrong output. Target: a single function or module where the wrong behavior first appears.
+
+**Phase 3 — Hypothesize**: Write a falsifiable hypothesis: "The bug occurs because [condition] causes [behavior] instead of [expected]." Generate at least 2 alternatives. Rank by probability.
+
+**Phase 4 — Verify**: Add a targeted assertion or log that fires if your top hypothesis is correct. Run the reproduction case. If confirmed, document the root cause. If not, return to Phase 3 with new evidence.
+
+> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until Phase 4 produces a verified root cause. "It probably is X" is not verified.
+
+Also look at:
+- Recent changes to affected files (`git log --oneline <file>`)
+- Existing tests (what's tested, what's missing)
+- Similar patterns elsewhere in the codebase that work correctly
+
+### 3. Identify the fix approach
+
+Based on your investigation, determine:
+
+- The minimal change needed to fix the root cause
+- Which modules/interfaces are affected
+- What behaviors need to be verified via tests
+- Whether this is a regression, missing feature, or design flaw
+- Risk level: Low / Medium / High
+
+### 4. Design TDD fix plan
+
+Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:
+
+- **RED**: Describe a specific test that captures the broken/missing behavior
+- **GREEN**: Describe the minimal code change to make that test pass
+
+Rules:
+- Tests verify behavior through public interfaces, not implementation details
+- One test at a time, vertical slices (NOT all tests first, then all code)
+- Each test should survive internal refactors
+- Include a final refactor step if needed
+- **Durability**: Only suggest fixes that would survive radical codebase changes. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state.
+
+### 5. Write specs/DIAGNOSIS.md
+
+Save the investigation and fix plan to `specs/DIAGNOSIS.md`. Create the `specs/` directory if it doesn't exist.
+
+<diagnosis-template>
+
+## Problem
+
+A clear description of the bug or issue, including:
+- What happens (actual behavior)
+- What should happen (expected behavior)
+- How to reproduce (if applicable)
+
+## Root Cause Analysis
+
+Describe what you found during investigation:
+- The code path involved
+- Why the current code fails
+- Any contributing factors
+- Risk level: Low / Medium / High
+
+Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts instead.
+
+## TDD Fix Plan
+
+A numbered list of RED-GREEN cycles:
+
+1. **RED**: Write a test that [describes expected behavior]
+   **GREEN**: [Minimal change to make it pass]
+   **verify**: [runnable command]
+
+2. **RED**: Write a test that [describes next behavior]
+   **GREEN**: [Minimal change to make it pass]
+   **verify**: [runnable command]
+
+**REFACTOR**: [Any cleanup needed after all tests pass]
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] All new tests pass
+- [ ] Existing tests still pass
+
+## Resolution
+
+<!-- filled in by validate-fix -->
+
+</diagnosis-template>
+
+After writing `specs/DIAGNOSIS.md`, print a one-line summary of the root cause and suggest running `kickoff-branch` next to create a fix branch.

package/kickoff-branch/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: kickoff-branch
+description: Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions "start a branch" or "new worktree".
+---
+
+# Kickoff Branch
+
+> **HARD GATE** — Direct work on `main` or `master` is PROHIBITED. Every task MUST start with this skill to create a feature branch or worktree.
+>
+> **HARD GATE** — Do NOT proceed with development until a clean test baseline is verified. If the current base branch is failing tests, stop and fix the baseline before creating a new worktree.
+
+Create an isolated working environment before touching any code. A clean baseline proves tests pass before you start — so any failure you see later was caused by your changes, not pre-existing issues.
+
+## Process
+
+### 1. Confirm task name
+
+Ask if not already known: "What's the name of this feature or task?" Use it as the branch name slug (kebab-case, max 40 chars).
+
+### 2. Check current state
+
+```bash
+git status          # ensure working tree is clean
+git log --oneline -5  # confirm you're on the right base branch
+```
+
+If working tree is dirty, ask the user to stash or commit first.
+
+### 3. Pre-flight & Conflict Resolution
+
+Before creating the worktree, verify the target environment is clean:
+
+```bash
+# 1. Check for existing directory
+ls -d ../<task-slug> 2>/dev/null
+
+# 2. Check for existing branch
+git branch --list <task-slug>
+
+# 3. Check for "ghost" worktrees (metadata exists but directory is gone)
+git worktree list | grep "<task-slug>"
+```
+
+**Handling Conflicts:**
+- **Directory exists:** If `../<task-slug>` already exists, ask the user if they want to use it or delete it.
+- **Branch exists:** If the branch exists but no worktree is attached, ask to use the existing branch (`git worktree add ../<task-slug> <task-slug>`) or delete it.
+- **Ghost worktree:** If `git worktree list` shows the path but the directory is missing, run `git worktree prune` to clear the stale metadata.
+
+### 4. Create worktree + branch
+
+```bash
+# From the main repo root (not another worktree)
+git worktree add ../<task-slug> -b <task-slug>
+cd ../<task-slug>
+```
+
+If the user prefers a branch without a worktree:
+```bash
+git checkout -b <task-slug>
+```
+
+### 4. Verify clean baseline
+
+Run the full test suite and confirm it passes before writing any code:
+
+```bash
+# Use the project's test command from CLAUDE.md or package.json
+npm test    # or: pytest, go test ./..., cargo test, etc.
+```
+
+- [ ] All tests pass
+- [ ] No type errors (`npm run typecheck` or equivalent)
+- [ ] No lint errors (`npm run lint` or equivalent)
+
+If the baseline is broken, **stop and tell the user**. Do not proceed with development on a broken baseline.
+
+### 5. Confirm readiness
+
+Report the baseline result:
+```
+✓ Baseline clean: 42 tests passed, 0 failed
+Branch: <task-slug>
+Worktree: ../<task-slug>
+Ready to develop.
+```
+
+Suggest next skill: `develop-tdd` to start the TDD loop, or `execute-plan` if a specs/PLAN.md already exists.

package/map-codebase/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: map-codebase
+description: "High-fidelity codebase surveying — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists them into specs/CONTEXT.md. Goes beyond survey-context by identifying 'signals' for planning."
+---
+
+# Map Codebase
+
+Perform a deep architectural and structural analysis of the codebase. Unlike `survey-context` which identifies "where we are", `map-codebase` identifies "what we are dealing with" and "how things are done".
+
+## Process
+
+### 1. Identify Core Stack & Dependencies
+- Scan `package.json`, `Cargo.toml`, `requirements.txt`, etc.
+- Identify primary framework, runtime, and critical libraries (ORM, Auth, State, UI).
+- Note version constraints and any deprecated or unusual dependencies.
+
+### 2. Map High-Level Architecture
+- Identify the entry points (CLI, Web, API).
+- Map the primary data flow (e.g., Controller → Service → Repository).
+- Identify where business logic lives vs. where I/O lives.
+- Look for established patterns (e.g., hexagonal, layered, feature-folders).
+
+### 3. Analyze "Gray Areas" (The "How")
+Search for patterns and anti-patterns in these categories:
+- **Error Handling:** Are exceptions caught early or bubbled? Is there a global error handler? Are error messages structured?
+- **API Shapes:** Is it REST, GraphQL, or RPC? What is the casing (camelCase, snake_case)? How are responses structured?
+- **Type Safety:** Is it strictly typed? Are there many `any` or `unsafe` blocks? Are interfaces used for DIP?
+- **Observability:** Is there structured logging? Are there health checks? Where do logs go?
+- **Testing:** What is the test coverage strategy? Are mocks used? Where do tests live?
+
+### 4. Identify Planning "Signals"
+Look for signals that will influence upcoming plans:
+- **Consistency Gaps:** "Half the project uses async/await, the other half uses Promises."
+- **Debt Hotspots:** "The `AuthManager` is 1500 lines and handles both JWT and session logic."
+- **Integration Points:** "We need to talk to the Stripe API, but there's no wrapper yet."
+- **Conventions:** "The team always uses functional components over classes."
+
+### 5. Persist to specs/CONTEXT.md
+Compile all findings into `specs/CONTEXT.md`. This file serves as the project's "Long-Term Memory".
+
+```markdown
+# Project Context
+
+## Stack
+- [Framework/Language]
+- [Key Libraries]
+
+## Architecture
+- [Pattern Description]
+- [Data Flow]
+
+## Conventions (Observed)
+- [Error Handling Pattern]
+- [API Design]
+- [Type System]
+
+## Signals / Active Considerations
+- [Gap 1]
+- [Hotspot 2]
+```
+
+## When to Use
+- When first joining a project.
+- Before a major refactor or architectural change.
+- When `survey-context` reveals a lack of domain knowledge.
+- To refresh `specs/CONTEXT.md` after significant changes.