bigpowers 2.1.3 → 2.3.0

package/.pi/skills/run-evals/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: run-evals
+description: "Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs.model: sonnet"
+---
+
+
+# Run Evals
+
+> **HARD GATE** — Define evals before implementation. Code graders = runnable `verify:` commands; model graders = explicit rubric with pass/fail criteria.
+
+## Process
+
+1. Name the capability under test (one sentence).
+2. Write `specs/EVALS-<feature>.md` with:
+   - **Capability evals** (does it do the job?)
+   - **Regression evals** (did we break anything?)
+3. Assign grader type per eval: `code` (shell verify) or `model` (rubric).
+4. Run evals; log results table with pass@k (e.g. 3/3 runs).
+5. Block BUILD phase until capability evals pass at agreed k.
+
+## Artefact
+
+`specs/verifications/eNNsYY-eval-report.md` — see [REFERENCE.md](REFERENCE.md) for template. Eval reports are stored alongside verification evidence in `specs/verifications/`, keyed by story ID for traceability.
+
+## Verify
+
+→ verify: `find specs/verifications -name "*-eval-report.md" | wc -l | awk '{if($1>0) print "OK: "$1" eval reports"; else print "MISSING"}'`
+
+---
+
+# Run Evals — Reference
+
+## EVALS template
+
+```markdown
+# EVALS: <feature>
+
+## Capability
+| ID | Eval | Grader | verify / rubric |
+|----|------|--------|-----------------|
+| C1 | ... | code | `verify: npm test -- <file>` |
+| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B |
+
+## Regression
+| ID | Eval | Grader | verify / rubric |
+|----|------|--------|-----------------|
+| R1 | Full suite passes | code | `verify: npm test` |
+
+## Results
+| Run | C1 | C2 | R1 | pass@k |
+|-----|----|----|-----|--------|
+| 1 | PASS | PASS | PASS | 3/3 |
+```
+
+## pass@k
+
+Run capability evals k times (default k=3). Ship when all k pass or document known flake in `specs/state.yaml` `handoff.open_decisions`.

package/.pi/skills/run-planning/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: run-planning
+description: ""DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (specs/planning-status.yaml) through survey-context → scope-work → research-first → elaborate-spec → plan-release → slice-tasks. NOT a duplicate of plan-work or the planning spine; it orchestrates the pre-coding discover phase only.""
+---
+
+
+# Run Planning
+> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
+
+> **Role:** DISCOVER-PHASE ADVANCER — orchestrates the discover-phase sequence; hands off to the scope-work → slice-tasks → plan-work spine for implementation planning.
+
+Updates `specs/planning-status.yaml` as discover-phase skills complete.
+
+## Workflows (default keys)
+
+- `survey-context` → `scope-work` → `research-first` → `elaborate-spec` (optional) → `plan-release` → `slice-tasks`
+
+## Process
+
+1. Read `specs/planning-status.yaml` and `specs/state.yaml`.
+2. Find first workflow with `status: pending` or `optional` not yet run.
+3. Invoke the matching skill; on success set `status: done` for that workflow key.
+4. Set `state.yaml` `active_flow: planning` while in this chain.
+
+## Verify
+
+→ verify: `test -f specs/planning-status.yaml && grep -c 'status: done' specs/planning-status.yaml | awk '{if($1>=3) print "OK"; else print "INCOMPLETE"}'`

package/.pi/skills/scope-work/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: scope-work
+description: ""PLANNING SPINE STEP 1 of 3 — Scope the work: define what is in and out of scope and save as specs/product/SCOPE_LATEST.yaml. Use before slice-tasks or plan-release on any new initiative. Not a substitute for slice-tasks (step 2) or plan-work (step 3)."model: sonnet"
+---
+
+
+# Scope Work
+
+> **Spine position:** Step 1 — scope-work → slice-tasks → plan-work.
+
+Turn the current conversation into a bounded PRD at `specs/product/SCOPE_LATEST.yaml`.
+
+## Process
+
+1. Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any).
+2. Interview (if needed): goal, users, in-scope, out-of-scope, constraints, success metrics.
+3. Write `specs/product/SCOPE_LATEST.yaml` with: `core_value`, `summary`, `in_scope[]`, `out_of_scope[]`, `constraints`, `success_criteria`, `references`.
+4. Run `research-first` if external dependencies are proposed.
+
+> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`.
+
+## Verify
+
+→ verify: `test -f specs/product/SCOPE_LATEST.yaml && grep -c 'out_of_scope' specs/product/SCOPE_LATEST.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`

package/.pi/skills/search-skills/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: search-skills
+description: "Find the right bigpowers skill from natural-language intent using a local lexical index over SKILL.md frontmatter. Use when unsure which skill to invoke, or at start of research-first.model: haiku"
+---
+
+
+# Search Skills
+> **HARD GATE** — **HARD GATE** — Search results must be ranked by relevance. Do NOT return all matches without prioritization. Use skill metadata (phase, purpose, frequency) to rank.
+
+
+Lexical search only — no embedding service (ADR: zero external dependency).
+
+## Process
+
+1. Run `bash scripts/build-skill-index.sh` if `specs/SKILL-SEARCH-INDEX.md` is stale.
+2. Search index: `rg -i "<keywords>" specs/SKILL-SEARCH-INDEX.md`
+3. Read top 3 matches' `description` and "Use when" triggers.
+4. Recommend one skill with rationale; invoke via orchestrator or direct call.
+
+## Verify
+
+→ verify: `test -f specs/SKILL-SEARCH-INDEX.md && echo OK || (bash scripts/build-skill-index.sh && test -f specs/SKILL-SEARCH-INDEX.md && echo OK)`

package/.pi/skills/seed-conventions/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: seed-conventions
+description: "Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory with evolved bigpowers structure (product/, tech-architecture/, verifications/, epics/archive/). Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet."
+---
+
+
+# Seed Conventions
+> **HARD GATE** — Before any new code lands, confirm the project conventions are understood. Ask: 'What does a good commit message look like in this project?'
+
+Bootstrap a new project with the AI agent conventions it needs. Run this once at the start of a greenfield project.
+
+## What this creates
+
+- `CLAUDE.md` — Claude Code session config (project-specific)
+- `CONVENTIONS.md` — shared rules for all AI agents
+- `specs/` — the specs directory where all planning output will live
+- `AGENTS.md` — for OpenCode and other agents (optional)
+- `GEMINI.md` — for Gemini CLI (optional)
+
+## Interview
+
+Ask the user these questions (one at a time, wait for each answer):
+
+1. **Project name and one-sentence description** — "What is this project? One sentence."
+2. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
+2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md`.
+3. **Commands** — "What commands do you use for: run, test, build, lint?"
+4. **Architecture** — "Key modules and relationships in 1–2 sentences."
+5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
+6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
+7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
+
+## Generate files
+
+After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
+- `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` — from the agent-config template
+- `opencode.json` — from the opencode template
+- `CONVENTIONS.md` — bigpowers standard template + project defensive code categories
+
+### `specs/` directory
+
+```bash
+mkdir -p specs/product specs/product/snapshots specs/epics/archive
+mkdir -p specs/tech-architecture specs/adr specs/verifications specs/bugs
+touch specs/product/SCOPE_LATEST.yaml specs/product/VISION_LATEST.yaml specs/product/GLOSSARY_LATEST.yaml
+touch specs/release-plan.yaml specs/execution-status.yaml specs/planning-status.yaml specs/state.yaml
+touch specs/tech-architecture/tech-stack.md specs/tech-architecture/security.md
+touch specs/tech-architecture/test.md specs/tech-architecture/design.md
+touch specs/tech-architecture/REFACTOR_LATEST.md specs/tech-architecture/IMPACT_LATEST.md
+touch specs/bugs/registry.yaml
+echo "# Specs\n\nAll planning documents for this project." > specs/README.md
+```
+
+**Note:** `specs/state.yaml.lock` is NOT pre-created — acquired/released dynamically.
+
+`specs/state.yaml` carries a top-level `workflow_mode` key (`team-pr` | `solo-git`, default `team-pr`). This is the **canonical integrate-mode signal** for all skills — set it once here and skills such as `release-branch` read it from this file instead of sniffing profile files.
+
+## Verify
+
+- [ ] CLAUDE.md exists and is populated
+- [ ] CONVENTIONS.md exists and includes specs/ output convention
+- [ ] specs/product/ exists with SCOPE_LATEST.yaml, VISION_LATEST.yaml, GLOSSARY_LATEST.yaml
+- [ ] specs/tech-architecture/ exists with tech-stack.md, security.md, test.md, design.md
+- [ ] specs/verifications/ exists
+- [ ] specs/epics/archive/ exists
+- [ ] specs/bugs/registry.yaml exists
+- [ ] Confirm with user: "Does CLAUDE.md accurately describe your project?"
+
+---
+
+# Seed Conventions — Reference Templates
+
+## Agent config template (CLAUDE.md / GEMINI.md / AGENTS.md)
+
+All three files use the same structure — only the header differs:
+- `CLAUDE.md` → `# [Project Name] — Claude Code`
+- `GEMINI.md` → `# [Project Name] — Gemini CLI`
+- `AGENTS.md` → `# [Project Name] — OpenCode`
+
+```markdown
+# [Project Name] — [Agent]
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+[One sentence description]
+Stack: [language, framework, runtime]
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `[cmd]` |
+| Test   | `[cmd]` |
+| Build  | `[cmd]` |
+| Lint   | `[cmd]` |
+
+## Architecture
+[1–2 sentences. Key modules and their relationships.]
+
+## Conventions
+- [convention 1]
+- [convention 2]
+
+## Never
+- [hard stop 1]
+- [hard stop 2]
+
+## Agent Rules
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ before writing code.
+- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
+- Write the minimum code that solves the stated problem. Nothing extra.
+- Never refactor, rename, or reorganize code outside the task scope.
+- Run tests after every change. Show evidence before declaring done.
+- One clarifying question beats a wrong assumption baked into 200 lines.
+```
+
+## opencode.json template
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".cursor/rules/*.mdc"]
+}
+```
+
+## CONVENTIONS.md
+
+Use the standard bigpowers CONVENTIONS.md as the base. Fill in the project-specific defensive code categories from the interview answers.
+
+## Stack profile fragments
+
+If the user selected a stack profile, merge the matching `profiles/<name>.md` fragment into the generated `CONVENTIONS.md` under a `## Stack Conventions` section. Profiles supply language-specific commands, architecture patterns, and never-do additions.

package/.pi/skills/session-state/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: session-state
+description: "Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached."
+---
+
+
+# Session State
+> **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct.
+
+
+Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot."
+
+## Goal
+
+Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/tech-architecture/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.
+
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
+
+## Handoff block (cold start)
+
+When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`:
+
+```yaml
+handoff:
+  last_step_completed: "e02s01 verify-work passed"
+  open_decisions:
+    - "Use folder mode for e07 (>5 stories)"
+  required_reading:
+    - CONVENTIONS.md
+    - specs/epics/e02-verification/epic.yaml
+  next_skill: develop-tdd
+```
+
+## Strategic compaction
+
+| Trigger | Action |
+|---------|--------|
+| Phase transition (Plan → Build → Verify) | Compact handoff; archive verbose decisions to ADR |
+| Context > 70% estimated | Run terse-mode for status only; move detail to specs/ |
+| Before `dispatch-agents` wave | `state.yaml` only channel between spawns |
+
+## Workflow
+
+### 1. Initialize (Session Start)
+
+If `specs/state.yaml` does not exist, or if starting a new major phase:
+
+- [ ] Read `specs/release-plan.yaml` and `specs/product/SCOPE_LATEST.yaml`.
+- [ ] Get git metadata: `git branch --show-current` and `git rev-parse --short HEAD`.
+- [ ] Create `specs/state.yaml` with active flow, git, handoff, and epic cycle if in build.
+
+### 2. Load (Context Refresh)
+
+When starting a new session or after a significant context flush:
+
+- [ ] Read `specs/state.yaml` to understand where the previous agent left off.
+- [ ] Read `specs/execution-status.yaml` for story progress (do not infer from release-plan).
+- [ ] Verify git matches `state.yaml` `git.branch` / `git.hash`.
+
+### 3. Update (Decision Point/Milestone)
+
+Whenever a significant decision is made or a milestone is reached:
+
+- [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash <hash>` (or edit directly).
+- [ ] Update `handoff.open_decisions` with rationale.
+- [ ] Update `epic_cycle` when advancing `ship-epic` steps.
+- [ ] Record open questions under `handoff.open_decisions` or an ADR.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
+
+## State Write-Lock Protocol
+
+> **HARD GATE** — Before any write to `specs/state.yaml` or `specs/execution-status.yaml`, acquire `specs/state.yaml.lock`. Release it immediately after the write. A stale lock (>60s) may be force-released.
+
+### Acquire
+
+1. Check if `specs/state.yaml.lock` exists.
+2. If it exists, read the agent ID and timestamp inside.
+3. If the lock is stale (>60s old), remove it and proceed.
+4. If the lock is fresh (<60s), wait 2s and retry (max 15 attempts = 30s).
+5. Write `agent_id: <name>\nacquired_at: <ISO-8601>` to `specs/state.yaml.lock`.
+
+### Release
+
+1. After the write to `state.yaml` or `execution-status.yaml` completes:
+2. `rm specs/state.yaml.lock`
+
+### Lock format (`specs/state.yaml.lock`)
+
+```yaml
+agent_id: session-state
+acquired_at: "2026-06-11T14:30:00Z"
+```
+
+
+
+## Operations
+
+### show-state (absorbed)
+
+Print the current session state: `cat specs/state.yaml`, then display `active_flow` and `handoff.next_skill` for quick reference.
+
+### reset-state (absorbed)
+
+Clear ephemeral session state. Set `active_epic_id`, `active_story_id`, and `epic_cycle.current_step` to `null` in `specs/state.yaml`. Use when ending a phase or starting a new project context.
+
+### compact-state (absorbed)
+
+Archive verbose decisions before a context transition. Move all entries from `handoff.open_decisions` to their appropriate location:
+
+- **System-wide decisions** → `specs/adr/NNNN-slug.md` (global Architectural Decision Records)
+- **Epic-scoped decisions** → `specs/epics/<active_epic_id>-<slug>/adr/NNNN-slug.md` (epic-local ADRs, archived with epic)
+
+After archiving, reset `handoff.open_decisions` to an empty list.
+
+## File Format: specs/state.yaml
+
+```yaml
+active_flow: build_epic       # planning | build_epic | fix_bug
+active_epic_id: e02
+active_story_id: e02s01       # required when epic mode: folder
+active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
+release:
+  target_version: "3.0.0"
+  last_tag: null
+  last_publish: null
+epic_cycle:
+  current_step: develop-tdd
+  next_skill: develop-tdd
+  completed_steps: [kickoff-branch]
+bug_cycle:
+  current_step: null
+  completed_steps: []
+git:
+  branch: feat/e02-verify
+  hash: abc1234
+handoff:
+  last_step_completed: null
+  open_decisions: []
+  next_skill: survey-context
+```
+
+## Anti-Patterns
+
+- **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`.
+- **Stale State**: Forgetting to update `state.yaml` after a major refactor or decision.
+- **Status in release-plan**: Story/epic status lives only in `execution-status.yaml`.

package/.pi/skills/setup-environment/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: setup-environment
+description: "Pre-install dependencies and configure tools before development work begins. Use at session start on a fresh clone, before kickoff-branch, or when user says setup environment or install deps.model: haiku"
+---
+
+
+# Setup Environment
+> **HARD GATE** — **HARD GATE** — Environment setup must be idempotent and reproducible. If setup fails, provide clear error messages and remediation steps. Do NOT assume prior state.
+
+
+Idempotent prep so BUILD phase commands succeed on first run.
+
+## Checklist
+
+1. Read `CLAUDE.md` / `CONVENTIONS.md` for required runtimes and commands.
+2. Verify runtime versions (`node -v`, `swift --version`, etc.).
+3. Install dependencies (`npm ci`, `bundle install`, etc.) — prefer lockfile installs.
+4. Copy `.env.example` → `.env` if documented; never commit secrets.
+5. Run smoke: lint + one fast test or `--version` on key tools.
+6. Record versions in `specs/state.yaml` under Environment.
+
+## Verify
+
+→ verify: commands from CLAUDE.md Test/Lint rows exit 0

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

@@ -0,0 +1,26 @@
+---
+name: simulate-agents
+description: "Run Mock User and Auditor agents against a feature in fresh contexts before human review. Use after verify-work, before request-review, when user wants pre-review simulation.model: sonnet"
+---
+
+
+# Simulate Agents
+> **HARD GATE** — **HARD GATE** — Simulations are hypothetical. Do NOT use sim results to make production decisions without validation on real agents. Sims help discover gaps, not replace testing.
+
+
+Two roles, **isolated contexts** (no shared state with BUILD agent):
+
+1. **Mock User** — follows Verification Script; reports UX gaps in plain language.
+2. **Auditor** — checks CONVENTIONS.md, security checklist, test coverage; structured pass/fail.
+
+## Process
+
+1. Read story Verification Script + changed files diff.
+2. Spawn Mock User: step through UAT script; log failures.
+3. Spawn Auditor: run `audit-code` checklist cold.
+4. Write `specs/SIMULATION-<feature>.md` with both reports.
+5. Failed items → `respond-review` or `plan-work` gaps — do not skip human review.
+
+## Verify
+
+→ verify: `test -f specs/SIMULATION-*.md && grep -c "Mock User\|Auditor" specs/SIMULATION-*.md | awk '{if($1>=2) print "OK"}'`

package/.pi/skills/slice-tasks/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: slice-tasks
+description: ""PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical-slice stories in specs/epics/. Use after scope-work (step 1), before plan-work (step 3). Not a substitute for scope-work or plan-work."model: sonnet"
+---
+
+
+# Slice Tasks
+
+> **Spine position:** Step 2 — scope-work → slice-tasks → plan-work.
+
+Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical slices, each independently deliverable and testable. Output: decoupled `eNNsYY-tasks.yaml` files with runnable verify commands. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use capsule dirs + `execution-status.yaml`.
+
+## Process
+
+1. Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`.
+2. Cut **tracer-bullet slices** (thin end-to-end paths first, then depth).
+3. Each story: writes `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`). Story spec `.md` files are written by `plan-work` and follow [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md).
+4. Order by WSJF in `release-plan.yaml` epic list.
+
+> **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration.
+
+## Verify
+
+→ verify: `find specs/epics -name "*-tasks.yaml" | wc -l | awk '{if($1>0) print "OK: "$1" task files"; else print "MISSING"}'`

package/.pi/skills/spike-prototype/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: spike-prototype
+description: "Throw-away prototype for unknown problem spaces. Output is learning notes in specs/archive/spikes/SPIKE-<name>.md, not production code. Use when the domain or technology is unexplored, when estimates are impossible without experimentation, or when user says "spike", "prototype", or "proof of concept"."
+---
+
+
+# Spike Prototype
+> **HARD GATE** — **HARD GATE** — Spikes are time-boxed experiments, not shipping code. Results must be throwaway or clearly isolated. Do NOT merge a spike without a plan to integrate it or replace it with a proper implementation.
+
+
+A spike is a time-boxed experiment to answer a specific question. The code is thrown away. The learning is kept in `specs/archive/spikes/SPIKE-<name>.md`.
+
+**The spike produces learning, not code to ship.** If you find yourself cleaning up spike code for production, stop — run `plan-work` and `develop-tdd` instead with the insights you gained.
+
+## When to spike
+
+- The technology is unfamiliar (new library, API, infrastructure)
+- The approach is uncertain (multiple solutions exist; none has been tried)
+- Estimates are impossible without seeing how the thing actually behaves
+- A key assumption needs to be validated before committing to a design
+
+## Process
+
+### 1. Define the question
+
+Before writing a single line, state the question the spike must answer:
+
+> "Can we [specific thing] using [specific approach] within [constraint]?"
+
+Examples:
+- "Can we stream large files from S3 to the client without buffering in memory?"
+- "Does the Stripe webhook SDK handle signature verification correctly in our edge runtime?"
+- "Can we achieve < 100ms p99 response time for the search endpoint with a naive Postgres full-text search?"
+
+A spike with no question is just unplanned coding. Refuse to start if the question isn't clear.
+
+### 2. Set a timebox
+
+Agree on a timebox with the user: 30 minutes, 1 hour, 2 hours. When time is up, stop — even if the question isn't fully answered. Partial learning is still learning.
+
+### 3. Experiment
+
+Write the simplest code that could answer the question. Ignore:
+- Error handling
+- Test coverage
+- Code quality
+- Production concerns
+
+Focus entirely on answering the question.
+
+### 4. Write specs/archive/spikes/SPIKE-<name>.md
+
+Save the learning to `specs/archive/spikes/SPIKE-<name>.md`. Create the `specs/` directory if it doesn't exist.
+
+<spike-template>
+
+# Spike: [name]
+
+## Question
+
+[The specific question this spike was answering]
+
+## Result
+
+[Answered / Partially answered / Not answered]
+
+## Findings
+
+[What you learned — concrete observations, not opinions]
+
+## Evidence
+
+[Code snippet, benchmark result, API response, or screenshot that proves the finding]
+
+## Implications for the plan
+
+[How this changes the approach, the design, or the estimate]
+
+## What was NOT explored
+
+[Known gaps — things the spike didn't validate]
+
+## Recommendation
+
+[Should we proceed with this approach? If yes, what does plan-work need to account for?]
+
+</spike-template>
+
+### 5. Delete the spike code
+
+After writing the findings, delete or discard the spike code. It is not meant to ship.
+
+### 6. Feed back into plan-work
+
+The spike findings are the input to `plan-work`. Call `plan-work` next, informed by `specs/archive/spikes/SPIKE-<name>.md`.

package/.pi/skills/stocktake-skills/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: stocktake-skills
+description: "Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected.model: sonnet"
+---
+
+
+# Stocktake Skills
+> **HARD GATE** — **HARD GATE** — Skill inventory must be current. Missing HARD GATEs, stale descriptions, or broken verify commands are defects, not cosmetic. Fix them in `evolve-skill`.
+
+
+Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX mismatches.
+
+## Modes
+
+| Mode | Scope |
+|------|-------|
+| **Quick Scan** | Skills changed since last tag or in current diff |
+| **Full** | All 58 skills per SKILL-INDEX.md |
+
+## Process
+
+1. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches.
+2. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
+3. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
+
+## Verify
+
+→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING`
+
+See [REFERENCE.md](REFERENCE.md) for checklist.
+
+---
+
+# Stocktake checklist
+
+- [ ] SKILL.md exists at repo root `&lt;name&gt;/SKILL.md`
+- [ ] Listed in SKILL-INDEX.md with correct phase
+- [ ] `description` includes "Use when..."
+- [ ] At least one HARD GATE callout
+- [ ] specs/ output documented if applicable
+- [ ] No edit to `.cursor/rules/` or `.gemini/` (generated only)