bigpowers 2.2.0 → 2.4.0

package/.pi/prompts/enforce-first.md

@@ -0,0 +1,77 @@
+---
+description: Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Validating, Timely) to a test suite or individual tests. Use when develop-tdd is writing tests, when test quality needs to be checked, or when user mentions F.I.R.S.T or "test quality".
+---
+
+
+# Enforce FIRST
+> **HARD GATE** — **HARD GATE** — Before shipping, ALL enforcement checks must pass: lint, typecheck, tests, coverage gates. Do NOT disable or skip checks to get to green.
+
+
+Apply the F.I.R.S.T rubric (Uncle Bob, Clean Code Chapter 9) to evaluate and improve tests.
+
+This skill is typically invoked internally by `develop-tdd` during the test-writing phase. It can also be run standalone on an existing test suite.
+
+## The F.I.R.S.T Rubric
+
+### F — Fast
+
+Tests must run quickly. Slow tests don't get run. They don't get trusted.
+
+- [ ] No real network calls (use fakes/stubs for external I/O)
+- [ ] No real database (use in-memory or transaction-rollback strategies)
+- [ ] No `sleep` or arbitrary timeouts in test code
+- [ ] The full suite runs in under 30 seconds (target; adjust to project size)
+
+**Fix:** Replace slow I/O with named fake classes. Never inline anonymous stubs.
+
+### I — Independent
+
+Tests must not depend on each other. Running in any order must produce the same result.
+
+- [ ] No shared mutable state between tests
+- [ ] Each test sets up its own data and tears it down
+- [ ] No test assumes another test ran first
+- [ ] Tests can be run individually (e.g. `npm test -- mytest.test.ts`) and pass
+
+**Fix:** Move setup into `beforeEach`. Use factory functions to build test data.
+
+### R — Repeatable
+
+Tests must pass consistently in any environment.
+
+- [ ] No dependency on machine-specific paths, ports, or environment variables (unless explicitly injected)
+- [ ] No dependency on current time without mocking the clock
+- [ ] No flakiness — a test that sometimes fails is worse than no test
+- [ ] Tests pass on CI the same way they pass locally
+
+**Fix:** Inject time, randomness, and environment as parameters. Pin seeds for anything random.
+
+### S — Self-Validating
+
+Tests must report pass or fail automatically. No human inspection required.
+
+- [ ] Tests use assertions (`expect`, `assert`, etc.) — not just `console.log`
+- [ ] Failure messages are descriptive enough to diagnose without reading the test body
+- [ ] No tests that "pass" by default when the feature is broken
+
+**Fix:** Add assertion messages. Use matchers that describe the expected behavior.
+
+### T — Timely
+
+Tests must be written at the right time — before or immediately with the code they test.
+
+- [ ] Tests are written in the same commit as the code (or the commit before, if TDD)
+- [ ] No "I'll add tests later" patterns
+- [ ] Bug fixes include a regression test that would have caught the bug
+
+**Fix:** Run `develop-tdd` — it enforces the timely principle by design.
+
+## Applying the rubric
+
+For each failing criterion:
+1. Identify which tests violate it
+2. Describe the fix
+3. Apply the fix
+4. Re-run the suite to confirm it still passes
+
+Report: "F.I.R.S.T audit complete. X criteria passed, Y fixed."

package/.pi/prompts/evolve-skill.md

@@ -0,0 +1,38 @@
+---
+description: Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose plan-work change, edit skill via craft-skill, re-run benchmark, record ADR. Use when a skill underperforms on benchmark or stocktake finds systemic gap.model: opus
+---
+
+
+# Evolve Skill
+
+> **HARD GATE** — No skill change ships without benchmark score ≥ pre-change baseline. Learning is measured and versioned — never implicit.
+
+## Loop
+
+1. Run `bigpowers-benchmark` (external repo); save report path in state.yaml.
+2. Identify target skill + measurable gap from report.
+3. `plan-work` — minimal change proposal with verify commands.
+4. Edit via `craft-skill` / direct SKILL.md edit; run `sync-skills.sh`.
+5. Re-run benchmark; compare scores.
+6. Record decision in `specs/adr/` + `session-state`; revert if regression.
+
+## Verify
+
+→ verify: benchmark report shows post-change score ≥ baseline (document paths in state.yaml)
+
+See [REFERENCE.md](REFERENCE.md) for ADR template.
+
+---
+
+# Evolve Skill — ADR snippet
+
+```markdown
+## ADR-XXXX: Evolve <skill-name>
+
+**Status:** Accepted
+**Benchmark:** before X% / after Y%
+**Change:** one-sentence summary
+**Evidence:** path/to/benchmark-report.md
+```
+
+Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/`

package/.pi/prompts/execute-plan.md

@@ -0,0 +1,54 @@
+---
+description: Batch-execute tasks from the active epic capsule sequentially, with a human checkpoint after each step. Use when user has an approved plan and wants step-by-step oversight.
+---
+
+
+# Execute Plan
+
+Execute tasks from the **active epic** (`specs/epics/eNN-slug/epic.yaml` story `tasks[]`) one at a time, showing evidence after each step before proceeding.
+
+> **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first.
+>
+> **HARD GATE** — Active epic must exist with runnable `verify` on each task. If missing, run `plan-release` then `plan-work` or `build-epic`.
+
+## Process
+
+### 1. Read the plan
+
+Read `specs/state.yaml` (`active_epic`, `active_story`) and the matching `specs/epics/*/epic.yaml`. Parse `depends-on` in task descriptions for execution waves.
+
+> **CONTEXT ISOLATION** — Spawn each skill with a **fresh context window**. Pass decisions only through `specs/state.yaml` `handoff` — never rely on prior chat history.
+
+Confirm with the user: step count, skip/reorder, stop-after step.
+
+### 2. Execute step by step
+
+For each task in the active story:
+
+**a. Announce** — task `desc` and `verify` command.
+
+**b. Execute** — code or `delegate-task` / `dispatch-agents` for waves.
+
+**c. Run verify** — must be green before advancing.
+
+**d. Log** — non-obvious decisions in `specs/state.yaml` under `decisions[]` or `handoff` block.
+
+**e. Checkpoint** — ask to proceed unless autonomous mode requested.
+
+**f. Story UAT** — after last task, run manual verification script from story notes or `verify-work`.
+
+On verify failure: fix and re-run; never advance on red.
+
+Update `specs/execution-status.yaml` when a story/epic completes (`bash scripts/sync-status-from-epics.sh` or direct edit).
+
+### 3. Blockers
+
+Report blocker; ask skip/adapt/stop; update epic capsule if plan changes.
+
+### 4. Final report
+
+Suggest: `verify-work` → `run-evals` → `audit-code` → `simulate-agents` → `commit-message` → `release-branch`
+
+## Rules
+
+- **Loop until behavioral correctness is verified**: if a verify command passes but the observed behavior is still wrong, return to step 1 and run the execution cycle again.

package/.pi/prompts/fix-bug.md

@@ -0,0 +1,36 @@
+---
+description: Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect.
+---
+
+
+# Fix Bug
+
+**Boundary**: Orchestrator flow — chains `investigate-bug` (entry point + RCA via `diagnose-root`) → `develop-tdd` → `validate-fix`. Does not implement RCA or write bug files directly.
+
+Orchestrates **fix_bug** flow without mixing epic build state.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug`.
+
+## Process
+
+1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file.
+2. `develop-tdd` against the bug file's verify steps.
+3. `validate-fix` — re-run failing test, full suite, lint.
+4. `bash scripts/sync-bugs-registry.sh` — refresh `specs/bugs/registry.yaml`.
+5. Clear `active_flow` or return to `build_epic` when done.
+
+## Bug file SoT
+
+One markdown file per bug with frontmatter:
+
+```yaml
+bug_id: BUG-001
+status: open
+severity: high
+scope: api
+title: Short title
+```
+
+## Verify
+
+→ verify: `test -d specs/bugs && bash scripts/sync-bugs-registry.sh`

package/.pi/prompts/grill-me.md

@@ -0,0 +1,95 @@
+---
+description: Interactive assumption-surfacing Q&A that stress-tests a plan through relentless questioning until every decision is resolved. Use when user wants to challenge a plan, validate decisions from conversation/context, or mentions "grill me". For doc-grounded variant, use grill-with-docs.
+---
+
+
+# Grill Me
+
+> **Use this vs grill-with-docs:** `grill-me` surfaces assumptions from the conversation and context alone — no documentation fetching. Use `grill-with-docs` (the doc-grounded variant) when the plan relies on a specific library or external API and every challenge must cite a real doc URL.
+
+Two modes. Default is **Design**. Switch to **Docs** by saying "grill me with docs" or when the plan relies on a specific library or external API.
+
+> **HARD GATE** — Do NOT accept a design until every hard decision has been stress-tested. "Seems right" is not a decision. Grilling must identify and resolve tensions before build begins.
+
+## Design mode (default)
+
+Interview relentlessly about every aspect of this plan until reaching shared understanding. Walk each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask one question at a time.
+
+If a question can be answered by exploring the codebase, explore it instead.
+
+## Docs mode
+
+Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](REFERENCE.md) for the full process.
+
+Short form:
+1. List every external library, third-party API, and framework behavior relied upon.
+2. Fetch the actual docs for each (`WebFetch` the official API reference).
+3. Challenge each plan assumption against the real docs: correct method signature? right version? deprecated?
+4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
+5. Update the plan for each confirmed discrepancy.
+
+---
+
+# Docs Mode — Full Process
+
+Triggered by "grill me with docs" or when a plan depends on a specific library or external API.
+
+**Why this matters:** AI agents hallucinate API methods, argument orders, and behaviors. Every assumption about an external dependency must be validated against the actual docs before code is written.
+
+## Step 1 — Identify the dependencies
+
+From the plan or conversation, list:
+- Every external library being used
+- Every third-party API being called
+- Every framework behavior being relied upon
+
+Ask: "Which of these are you most confident about? Which are you less sure of?"
+
+## Step 2 — Fetch the relevant docs
+
+For each dependency, fetch the actual documentation:
+
+```
+WebFetch the official docs for [library/API]
+```
+
+Prioritize:
+- The API reference for the specific method being used
+- The changelog for the version in use (breaking changes)
+- Migration guides if upgrading from a previous version
+- Known gotchas / FAQ sections
+
+## Step 3 — Challenge each assumption
+
+For every assumption in the plan, find the corresponding doc section and ask:
+
+- "Does the real API actually work this way? Show me the doc."
+- "Is this method available in the version you're using?"
+- "Does this argument order match the actual signature?"
+- "Are there rate limits, quotas, or timeout behaviors that affect this design?"
+- "Is this marked as deprecated in the current version?"
+
+Ask one question at a time. For each challenge, cite the specific URL and section.
+
+## Step 4 — Surface hallucinations
+
+When an assumption doesn't match the docs:
+
+> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
+
+Document each discrepancy clearly.
+
+## Step 5 — Update the plan
+
+For each confirmed discrepancy, recommend a concrete fix:
+- Correct method signature
+- Correct argument order
+- Alternative approach that matches what the library actually supports
+- Whether a spike (`spike-prototype`) is needed to validate a remaining uncertainty
+
+## Step 6 — Sign off
+
+When all major assumptions have been validated against docs, report:
+- Which assumptions were confirmed ✓
+- Which were corrected ✗ + what the correct approach is
+- Which remain uncertain → recommend `spike-prototype`

package/.pi/prompts/grill-with-docs.md

@@ -0,0 +1,37 @@
+---
+description: Doc-grounded variant of grill-me — stress-tests plan assumptions by fetching and citing real library or API documentation. Every challenge must cite a real URL. Use when the plan depends on a specific library or external API.model: opus
+---
+
+
+# Grill With Docs
+
+> **Use this vs grill-me:** `grill-with-docs` is the doc-grounded variant of `grill-me`. Use it when the plan relies on external libraries or APIs and every challenge must be grounded in and cite a real documentation URL. Use `grill-me` for context-only assumption surfacing without fetching docs.
+
+> **HARD GATE** — Every challenge must cite a real documentation URL. No hallucinated APIs.
+
+## Process
+
+1. Read the plan or design under test (`specs/release-plan.yaml + epic shards`, INTERFACE-OPTIONS.md, etc.).
+2. List assumptions that depend on external libraries or APIs.
+3. For each assumption: fetch or quote official docs; challenge with "docs say X, plan says Y."
+4. Resolve or update the plan inline; unresolved items block `plan-work`.
+
+## Docs mode rules
+
+- Cite URL + quoted snippet (method name, parameter, version).
+- If docs contradict the plan, plan loses until updated.
+- Prefer official docs over blog posts.
+
+## Verify
+
+→ verify: dialogue log contains at least one `https://` doc URL per challenged assumption
+
+See [REFERENCE.md](REFERENCE.md) for question templates.
+
+---
+
+# Grill With Docs — Question templates
+
+- "Docs at [URL] show signature `foo(bar?: Baz)`. Your plan calls `foo(bar, baz)` — which is correct?"
+- "The changelog at [URL] deprecates X in v3. Your plan still uses X — migrate or pin version?"
+- "Error handling in [URL] throws `NetworkError`. Your plan catches `Error` only — is that sufficient?"

package/.pi/prompts/guard-git.md

@@ -0,0 +1,212 @@
+---
+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/prompts/hook-commits.md

@@ -0,0 +1,93 @@
+---
+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