bigpowers 2.2.0 → 2.4.0

package/.pi/skills/diagnose-root/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: diagnose-root
+description: "Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use when a bug is confirmed but root cause is unclear, after investigate-bug, or when user mentions root cause analysis.model: sonnet"
+---
+
+
+# Diagnose Root
+
+**Boundary**: Canonical, reusable 4-phase RCA engine. Invoked by `investigate-bug` (as step 2 of the end-to-end flow) and by `fix-bug` (when no bug file exists). Does not write the bug file — that is `investigate-bug`'s responsibility.
+
+Four phases — do not skip. Update the active `specs/bugs/BUG-*.md` file at each phase.
+
+## Phases
+
+1. **Reproduce** — minimal steps; record environment; capture logs.
+2. **Isolate** — narrow to module/function; binary-search commits or config.
+3. **Hypothesize** — list ranked hypotheses with falsification test each.
+4. **Verify** — run falsification; confirm single root cause; link to fix plan.
+
+> **HARD GATE** — Do not propose a fix until phase 4 confirms one root cause with evidence.
+
+## Verify
+
+→ verify: `BUG_FILE=$(ls -t specs/bugs/BUG-*.md 2>/dev/null | head -1); test -n "$BUG_FILE" && grep -cE "Reproduce|Isolate|Hypothesize|Verify" "$BUG_FILE" | awk '{if($1>=4) print "OK"; else print "INCOMPLETE"}' || echo "MISSING"`

package/.pi/skills/dispatch-agents/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: dispatch-agents
+description: "Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concurrent here, no inter-task review gate)."
+---
+
+
+# Dispatch Agents
+> **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents.
+
+
+Run multiple subagents in parallel on independent tasks. Use when tasks are genuinely decoupled — no agent needs the output of another to start.
+
+**Distinct from `delegate-task`:** This skill maximizes throughput via concurrency. There is no sequential review gate between tasks. Use `delegate-task` instead when a single task needs careful two-stage oversight before proceeding.
+
+## When to use
+
+- Tasks that can run simultaneously without shared state
+- Large plans that can be broken into parallel workstreams
+- Exploration: gather information from multiple parts of the codebase at once
+
+## When NOT to use
+
+- Task B depends on Task A's output
+- You need to review Task A before Task B can start safely
+- The tasks share a file and concurrent edits would conflict
+
+## Process
+
+### 1. Confirm independence
+
+Before dispatching, verify each task pair is truly independent:
+- No shared files being written
+- No shared state (DB migrations, config files)
+- No ordering dependency between outcomes
+
+If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead.
+
+### 2. Write task briefs
+
+Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else.
+
+For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk):
+
+```
+Goal: [one sentence — what success looks like]
+In scope: [explicit file or module list]
+Out of bounds: [what NOT to touch]
+Verify: [runnable command]
+Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply]
+```
+
+Do not include the full conversation, full file contents, or decisions unrelated to this agent's task.
+
+### 3. Iterative retrieval (max 3 cycles)
+
+After each wave completes:
+1. **Dispatch** — run parallel agents with briefs.
+2. **Evaluate** — read outputs; list gaps vs goal.
+3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total).
+
+Stop when gaps empty or cycle 3 reached — escalate to user.
+
+### 4. Dispatch in parallel
+
+Spawn all agents in a single message using multiple Agent tool calls. Each agent gets its own complete brief.
+
+```
+Agent 1: brief for task A
+Agent 2: brief for task B
+Agent 3: brief for task C
+```
+
+### 5. Collect and review results
+
+When all agents return:
+- Review each result independently
+- Run all verify commands
+- Check diffs for scope violations or CONVENTIONS.md breaches
+
+### 6. Integrate
+
+Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict.
+
+Report a summary: which tasks succeeded, which need revision, and overall verify status.

package/.pi/skills/edit-document/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: edit-document
+description: "Edit and improve documents by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, restructure, or improve any document — including specs/ files, articles, READMEs, or technical writing."
+---
+
+
+# Edit Document
+
+**Distinct from `write-document`:** Use this skill when the document already exists and needs restructuring, clarity, or prose improvements. Use `write-document` to create a document from scratch.
+
+> **HARD GATE** — Document edits must preserve intent and accuracy. Do NOT remove or contradict existing content without understanding why it was written. Check git history for context.
+
+## Process
+
+1. First, divide the document into sections based on its headings. Think about the main points made in each section.
+
+Consider that information is a directed acyclic graph, and that pieces of information can depend on other pieces of information. Make sure that the order of the sections and their contents respects these dependencies.
+
+Confirm the sections with the user.
+
+2. For each section:
+
+2a. Rewrite the section to improve clarity, coherence, and flow. Use maximum 240 characters per paragraph.

package/.pi/skills/elaborate-spec/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: elaborate-spec
+description: "Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn "I want X" into a concrete spec."
+---
+
+
+# Elaborate Spec
+
+Turn a rough idea into a clear specification through focused dialogue. No code is written during this skill — the output is shared understanding and a refined problem statement.
+
+> **HARD GATE** — Do NOT proceed with planning or implementation until the problem space is clearly understood. Success criteria, actors, and scope must be explicit before drafting a plan.
+
+## Process
+
+### 1. Listen first
+
+Let the user describe their idea in their own words. Do not interrupt or redirect. Take notes on:
+- The core problem they're trying to solve
+- Who is affected (actors)
+- What success looks like to them
+- Any constraints they've already identified
+
+### 2. Ask clarifying questions
+
+Ask one question at a time. Work through these areas:
+
+**Problem clarity**
+- What is the current behavior (or lack of behavior) that prompted this?
+- Who experiences this problem? How often?
+- What's the cost of not solving it?
+
+**Solution boundaries**
+- What is explicitly IN scope?
+- What is explicitly OUT of scope?
+- Are there existing solutions (internal or external) this replaces or integrates with?
+
+**Success criteria**
+- How will you know this is done?
+- What does the happy path look like end-to-end?
+- What are the key failure modes to handle?
+
+**Constraints**
+- Any performance requirements?
+- Any compatibility constraints (existing APIs, data formats)?
+- Any non-negotiable implementation decisions already made?
+
+### 2.5. Multiple Interpretations (HARD GATE)
+
+> **HARD GATE** — If the request admits ≥2 valid interpretations, do NOT guess. You must list them and ask the user to choose before proceeding. Proceeding with unresolved ambiguity is a failure of integrity.
+
+Present the options clearly:
+> "I see two ways to read this:
+> 1. [Interpretation A] — my recommendation because [reason]
+> 2. [Interpretation B]
+> Which is closer to what you mean?"
+
+### 3. Surface hidden assumptions
+
+Once the user has answered the main questions, probe for assumptions:
+- "You mentioned X — does that mean Y is also true?"
+- "What happens when Z fails?"
+- "Is this for internal users, external users, or both?"
+
+### 4. Synthesize and confirm
+
+Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md):
+- The problem (feeds into §1 Business narrative)
+- The solution and main flow (feeds into §5)
+- The key constraints and alternative flows (feeds into §6)
+- The success criteria (feeds into §17 Gherkin)
+- What's out of scope (feeds into §18)
+
+Ask: "Is this an accurate summary? Anything missing or wrong?"
+
+### 5. Suggest next skill
+
+Once the spec is clear, recommend the next step:
+- If domain model needs work → `model-domain`
+- If ready to plan → `plan-release` (creates epic capsules with `epic.yaml` + story `.md` + `-tasks.yaml`) then `plan-work` per story
+- If a spike is needed first → `spike-prototype`
+- If architecture decisions are needed → `deepen-architecture` or `grill-me`
+- If the plan depends on a specific library or API → `grill-me` in docs mode

package/.pi/skills/enforce-first/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: enforce-first
+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/skills/evolve-skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: evolve-skill
+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/skills/execute-plan/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: execute-plan
+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/skills/fix-bug/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: fix-bug
+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/skills/grill-me/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: grill-me
+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/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: grill-with-docs
+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?"