bigpowers 2.1.3 → 2.3.0

package/.pi/skills/guard-git/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: guard-git
+description: "Block dangerous git commands (push, force push, reset --hard, clean, branch -D, checkout/restore .) and enforce Conventional Commits & Branch Protection before an AI agent runs them. Installs hook scripts for Claude Code, Cursor, Cursor CLI, and Gemini CLI; documents Google Antigravity Terminal deny lists. Use when the user wants git safety hooks, to block git push or destructive git in agents, or to mirror the same policy across AI coding tools."
+---
+
+
+# Guard Git
+> **HARD GATE** — **HARD GATE** — Before committing, verify: branch is not main/master, author is correct, git user is configured. Bad commits are hard to fix.
+
+
+Installs a shared hook that blocks destructive git operations and enforces workflow discipline. **Requires `jq` on the agent's PATH** when the hook runs.
+
+## What gets blocked/enforced
+
+- **Safety**: `git push --force`, `git reset --hard`, `git clean -f`, `git branch -D`, `git checkout .`, `git restore .`.
+- **Discipline**: Blocks direct commits or pushes to protected branches (`main`, `master`) unless `GIT_BIGPOWERS_LAND=1` (set only by `scripts/land-branch.sh`).
+- **Allows**: `git push origin <feature-branch>` for backup/CI; solo land push to `main` only inside `land-branch.sh`.
+- **Standardization**: Enforces [Conventional Commits](https://www.conventionalcommits.org/) for all `git commit` commands.
+- **Secrets**: Blocks commits containing common secret patterns (`sk-`, `ghp_`, `AKIA`, `xoxb-`, `-----BEGIN` private keys) — see [REFERENCE.md](REFERENCE.md).
+
+## Quick start
+
+1. **Scope**: ask project-only vs global (paths differ per product).
+2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory.
+3. **Run `chmod +x`** on `pre-tool-use.sh`.
+4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys.
+5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md).
+
+| Client | Mechanism | Config |
+|--------|-----------|--------|
+| Claude Code | `PreToolUse` (Bash) | `.claude/settings.json` or `~/.claude/settings.json` |
+| Cursor / Cursor CLI | `beforeShellExecution` | `.cursor/hooks.json` or `~/.cursor/hooks.json` |
+| Gemini CLI | `BeforeTool` + `run_shell_command` | `.gemini/settings.json` or `~/.gemini/settings.json` |
+| Google Antigravity | Built-in Terminal **Deny list** | Settings UI (no shell hook) |
+
+**Modes (env on the hook command):** `GIT_GUARDRAILS_MODE` is `claude` (default) or `cursor` → stderr + exit `2` on block. Set `gemini` for Gemini CLI → JSON `decision` on stdout.
+
+## Customization
+
+To add or remove patterns or protected branches, edit `pre-tool-use.sh`.
+
+## Advanced
+
+Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: [REFERENCE.md](REFERENCE.md).
+
+---
+
+# Git guardrails — reference
+
+## Secret patterns (audit + pre-commit)
+
+Agents must not commit files containing:
+
+- `sk-` (OpenAI API keys)
+- `ghp_` / `gho_` (GitHub tokens)
+- `AKIA` (AWS access key id)
+- `xoxb-` (Slack bot tokens)
+- `-----BEGIN` private keys
+
+Use `audit-code` supply-chain checklist before commit. Consider `git-secrets` or custom pre-commit hook in target projects.
+
+## Copy layout
+
+The main script is `pre-tool-use.sh`.
+
+```text
+<hooks-dir>/pre-tool-use.sh
+```
+
+Example project locations:
+
+- Claude: `.claude/hooks/`
+- Cursor: `.cursor/hooks/`
+- Gemini: `.gemini/hooks/`
+
+Use the same layout for user-level hooks (`~/.claude/hooks`, `~/.cursor/hooks`, `~/.gemini/hooks`).
+
+---
+
+## Claude Code
+
+Hook command does **not** need `GIT_GUARDRAILS_MODE` (defaults to `claude`).
+
+**Project** (`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-tool-use.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Cursor and Cursor CLI
+
+Use `beforeShellExecution`. Set `GIT_GUARDRAILS_MODE=cursor`.
+
+**Project** (`.cursor/hooks.json`):
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "GIT_GUARDRAILS_MODE=cursor .cursor/hooks/pre-tool-use.sh",
+        "matcher": "git"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Gemini CLI
+
+Use `BeforeTool` with matcher `run_shell_command`. Set **`GIT_GUARDRAILS_MODE=gemini`**.
+
+**Project** (`.gemini/settings.json`):
+
+```json
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "run_shell_command",
+        "hooks": [
+          {
+            "name": "git-guardrails",
+            "type": "command",
+            "command": "GIT_GUARDRAILS_MODE=gemini \"$GEMINI_PROJECT_DIR\"/.gemini/hooks/pre-tool-use.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Google Antigravity
+
+Add **Deny list** entries in **Antigravity → Settings → Terminal**:
+
+- `git push --force`
+- `git push origin main`
+- `git push origin master`
+- `git reset --hard`
+- `git clean`
+- `git branch -D`
+- `git checkout .`
+- `git restore .`
+
+---
+
+## Verify (local tests)
+
+**1. Block push to main without land mode (Claude mode):**
+```bash
+echo '{"tool_input":{"command":"git push origin main"}}' | ./pre-tool-use.sh
+# Expected: exit 2, protected branch message
+```
+
+**2. Allow push to main with GIT_BIGPOWERS_LAND=1:**
+```bash
+GIT_BIGPOWERS_LAND=1 echo '{"tool_input":{"command":"git push origin main"}}' | ./pre-tool-use.sh
+# Expected: exit 0 (when on main)
+```
+
+**3. Allow push to feature branch:**
+```bash
+echo '{"tool_input":{"command":"git push -u origin feat/my-task"}}' | ./pre-tool-use.sh
+# Expected: exit 0
+```
+
+**4. Conventional Commits (Gemini mode):**
+```bash
+echo '{"tool_input":{"command":"git commit -m \"bad message\""}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
+# Expected: exit 0, {"decision":"deny", "reason":"..."}
+```
+
+**5. Protected Branch commit (Cursor mode):**
+```bash
+# Run on 'main' branch
+echo '{"command":"git commit -m \"feat: valid message\""}' | GIT_GUARDRAILS_MODE=cursor ./pre-tool-use.sh
+# Expected: exit 2, "Direct commits to protected branch 'main' are forbidden"
+```
+
+**6. Land script exists:**
+```bash
+test -x scripts/land-branch.sh && echo OK
+```
+
+**7. Allow (Gemini mode):**
+```bash
+echo '{"tool_input":{"command":"git status"}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
+# Expected: exit 0, {"decision":"allow"}
+```

package/.pi/skills/hook-commits/SKILL.md

@@ -0,0 +1,94 @@
+---
+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
+> **HARD GATE** — **HARD GATE** — Pre-commit and commit-msg hooks must run before any commit lands. Skipping hooks (`--no-verify`) is forbidden unless explicitly authorized for a specific commit and documented.
+
+
+## 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/.pi/skills/inspect-quality/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: inspect-quality
+description: "Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/bugs/registry.yaml 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
+> **HARD GATE** — **HARD GATE** — Quality metrics (coverage, lint, cyclomatic complexity, security scans) must be monitored. If a metric degrades, surface it as a blocker. Do NOT accept regressions.
+
+
+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/bugs/registry.yaml` 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/bugs/registry.yaml
+
+Append the issue to `specs/bugs/registry.yaml`. Create the `specs/bugs/` directory if it doesn't exist.
+
+#### registry.yaml format
+
+The file maintains a Markdown table with the following columns (derived from structured audit practice):
+
+| Field | Description |
+|-------|-------------|
+| `bug_id` | `BUG-YYYY-MM-DDTHHMMSS` |
+| `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 |
+| `file` | path to detailed `specs/bugs/BUG-*.md` (filled in by investigate-bug) |
+| `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-DDTHHMMSS: [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
+
+- **bug_id** uses full timestamp: `BUG-YYYY-MM-DDTHHMMSS` — matches the individual bug file name in `specs/bugs/`
+- **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/.pi/skills/investigate-bug/SKILL.md

@@ -0,0 +1,118 @@
+---
+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/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions "triage", or wants to plan a fix."
+---
+
+
+# Investigate Bug
+
+**Boundary**: End-to-end bug entry point — history check → RCA (via `diagnose-root`) → fix approach → TDD plan → bug file. Delegates the 4-phase RCA to `diagnose-root`; does not re-implement it.
+
+Investigate a reported problem, find its root cause, and write a TDD fix plan to `specs/bugs/BUG-*.md`. This is a mostly hands-off workflow — minimize questions to the user.
+
+## Process
+
+### 0. Read previous bug history
+
+Before starting diagnosis:
+
+1. Read `specs/bugs/registry.yaml` (if it exists) — check for prior bugs in the same `scope` or with similar symptoms.
+2. If a relevant prior bug is found, read the corresponding `specs/bugs/BUG-*.md` file to understand previous root cause analysis and fix approach.
+3. Note in your investigation whether this is a recurrence, a related issue, or novel.
+
+### 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)
+
+Run the 4-phase root-cause analysis via the `diagnose-root` skill (Reproduce → Isolate → Hypothesize → Verify). That skill is the canonical RCA engine — do not re-implement the phases here.
+
+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
+
+> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until `diagnose-root` Phase 4 produces a verified root cause. "It probably is X" is not verified.
+
+### 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 the bug file
+
+Save the investigation and fix plan to `specs/bugs/BUG-NNN-slug.md`. Create the `specs/bugs/` directory if it doesn't exist.
+
+After writing, append a row to `specs/bugs/registry.yaml` with: bug_id (same timestamp), date, severity, priority, scope, summary, and file path. Create `specs/bugs/registry.yaml` if it doesn't exist.
+
+<diagnosis-template>
+
+# BUG-YYYY-MM-DDTHHMMSS: [short title]
+
+## 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 the bug file, print a one-line summary of the root cause and suggest running `kickoff-branch` next to create a fix branch.

package/.pi/skills/kickoff-branch/SKILL.md

@@ -0,0 +1,100 @@
+---
+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. Anchor on default branch (main or master)
+
+> **HARD GATE** — Kickoff MUST start from an updated, clean default branch in the **primary** repository root (not a linked worktree).
+
+```bash
+# Detect default branch
+DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
+
+git checkout "$DEFAULT"
+git pull --ff-only origin "$DEFAULT"   # skip if no remote
+git status                             # working tree MUST be clean
+git log --oneline -5
+```
+
+If working tree is dirty, ask the user to stash or commit first. If not on `$DEFAULT` after checkout, stop and fix before continuing.
+
+### 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 `specs/release-plan.yaml + epic capsule directories` already exists.
+
+## Handoff
+
+Gate: READY -> next: develop-tdd
+Writes: state.yaml handoff.next_skill = develop-tdd