bigpowers 2.87.4 → 2.87.5

package/.gemini/extensions/bigpowers/skills/plan-release/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: plan-release
+model: sonnet
+description: "RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics."
+disable-model-invocation: true
+---
+
+# Plan Release
+
+> **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.
+> **HARD GATE** — `specs/product/SCOPE_LATEST.yaml` (or legacy `specs/product/SCOPE_LATEST.yaml`) must exist. If missing, run `scope-work` first.
+
+Synthesize the conversation context into `specs/release-plan.yaml` (index) and shard detail under `specs/epics/`. No new interview — only clarify if something is genuinely ambiguous.
+
+## Outputs
+
+| File | Content |
+|------|---------|
+| `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** |
+| `specs/epics/eNN-<slug>/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list |
+| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](../../docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
+| `specs/epics/eNN-<slug>/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task |
+| `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) |
+
+## Epic Capsule Structure
+
+All epics use capsule directories (no flat/folder distinction):
+
+```
+specs/epics/e01-auth-system/
+├── epic.yaml              # Epic manifest
+├── adr/                   # Epic-local ADRs (created lazily)
+├── e01s01-login.md        # Story spec (countable-story-format)
+├── e01s01-tasks.yaml      # Decoupled task checklist
+├── e01s02-jwt.md          # Story spec
+└── e01s02-tasks.yaml      # Decoupled task checklist
+```
+
+**Rationale:** Capsule dirs achieve change isolation (C9), enable archive pruning (C2/C6), and enforce SRP by decoupling spec `.md` from execution `-tasks.yaml` (C1).
+
+## Process
+### 1. Draft epics and stories
+
+From the conversation context, define:
+- **Epics** — `e01`, `e02`, … (stable IDs; WSJF order in `release-plan.yaml` only)
+- **Stories** — `e01s01`, `e01s02`, … with Gherkin acceptance criteria
+
+WSJF-sort epics: score = (Business Value + Time Criticality + Risk Reduction) / Job Size. Highest score first.
+
+> **Security risk boost:** If an epic's `specs/security/epics/<id>/THREAT_MODEL.md` identifies HIGH or CRITICAL risk, add +2 to the WSJF numerator (BV + TC + RR + 2) to reflect the urgency of addressing security concerns before they ship. Document the boost in the epic's note field in release-plan.yaml.
+### 2. Write acceptance criteria (Gherkin)
+
+For each story, write at least one happy-path and one edge-case scenario (countable format §17 if maturity ≥ 3).
+### 3. Write tasks with verify commands
+
+Every task must have a `verify:` command. No verify command = not a task.
+### 4. Save specs/release-plan.yaml
+
+> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
+> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
+> (the expectation), not a number you intend to enforce.
+
+```yaml
+release:
+  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
+  codename: "Feature Name"
+  status: planning          # planning | in_progress | released
+  semantic_release: true
+  bump_hint: minor          # patch | minor | major — CI decides at merge
+epics:
+  - id: e01
+    title: Auth System
+    wsjf: 4.5
+    capsule_dir: epics/e01-auth-system
+  - id: e02
+    title: User Profile
+    wsjf: 3.8
+    capsule_dir: epics/e02-user-profile
+```
+### 5. Save epic manifest (`epic.yaml`)
+
+Each epic capsule directory contains an `epic.yaml` manifest:
+
+```yaml
+id: e01
+title: Auth System
+wsjf: 4.5
+total_bcps: 8
+status: in_progress
+stories:
+  - id: e01s01
+    title: Login
+    bcps: 3
+    status: todo
+    spec: e01s01-login.md
+    tasks: e01s01-tasks.yaml
+  - id: e01s02
+    title: JWT Token Management
+    bcps: 5
+    status: todo
+    spec: e01s02-jwt.md
+    tasks: e01s02-tasks.yaml
+```
+### 6. Save story specs (countable-story-format .md)
+
+Each story becomes a standalone `.md` file following [countable-story-format.md](../../docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
+### 7. Save decoupled task files (`-tasks.yaml`)
+
+Each story has a decoupled `-tasks.yaml` with implementation steps:
+
+```yaml
+story_id: e01s01
+title: Login
+status: todo
+bcps: 3
+tasks:
+  - id: 1
+    description: "Add login form component tests"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+  - id: 2
+    description: "Implement login form with validation"
+    verify: "npm test -- login-form.test.tsx"
+    status: todo
+```
+
+> **HARD GATE** — Every task MUST have a runnable `verify:` command. No `verify:` = not a task.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
+### 7b. Generate bug registry summary
+
+Read `specs/bugs/registry.yaml` and add a `bugs:` section to `release-plan.yaml` with totals by status (`fixed`, `deferred`, `wontfix`, `open`): `bugs: { total: N, fixed: N, deferred: N, wontfix: N, registry: specs/bugs/registry.yaml }`.
+
+### 8. Sync execution status
+
+```bash
+bash scripts/sync-status-from-epics.sh
+```
+### 9. Snapshot on planning close (optional)
+
+Copy to `specs/product/snapshots/release-<version>/` when the user approves the plan.
+### 10. Suggest next steps
+
+- Run `assess-impact` before `plan-work` for any story touching existing modules.
+- Run `plan-work` per story for detailed steps inside the epic shard.
+- Run `change-request` if a new requirement arrives mid-flight.

package/.gemini/extensions/bigpowers/skills/plan-tests/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: plan-tests
+model: opus
+description: "Design a risk-scaled test architecture for an epic before implementation begins. Produces prioritized scenarios, test level distribution, and fixture plans based on TEA and bigpowers principles."
+disable-model-invocation: true
+---
+
+# Plan Tests
+
+> **Spine position:** Between `slice-tasks` and `plan-work` for epics with `risk: P0|P1`. Optional (can be waived in `state.yaml`) for P2/P3.
+
+Bridges the gap between slicing and planning by systematically designing the test suite as a first-class system. Produces `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`.
+
+## Pre-flight
+- Read `specs/epics/eNN-*/` story list.
+
+## Core Workflow
+1. **Analyze Epic**: Read sliced stories in the active epic capsule.
+2. **Risk Assessment**: Map behaviors to P0–P3 risk tiers.
+3. **Level Strategy**: Classify each scenario (Unit, Integration, E2E).
+4. **Fixture Design**: Plan factories, network intercepts, mocks (see REFERENCE.md).
+5. **NFR Plan**: Define verifiable commands for Non-Functional Requirements. Skip if `--lite`.
+6. **Publish**: Generate `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`.
+
+## Hard Gates & Guardrails
+- **DO NOT** write test code or production code during this skill.
+- Scenario ID format MUST be: `SC-eNNsYY-P{0|1|2|3}-NN`.
+- `plan-work` MUST reference these scenario IDs in its §17 Gherkin acceptance criteria.
+- Default to pushing tests to the lowest possible level.
+
+## Execution Modes
+- `$bmad plan-tests`: Standard execution.
+- `$bmad plan-tests --lite`: Skips NFRs and complex fixture planning.
+
+## Verify
+
+→ verify: `test -f specs/tech-architecture/e32-TEST_PLAN_LATEST.md`
+
+## Handoff
+
+Gate: READY -> next: plan-work
+Writes: state.yaml handoff.next_skill = plan-work
+
+---
+
+# Plan Tests — Reference
+
+## Test Plan Template (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`)
+
+```markdown
+# Test Design: [eNN-slug]
+
+## 1. Risk Matrix & Scenarios
+| Scenario ID | Behavior Description | Risk | Test Level | Target File/Module |
+|-------------|----------------------|------|------------|--------------------|  
+| SC-P0-01    | Primary checkout     | P0   | Integration | checkout.spec.ts  |
+
+## 2. Fixture Architecture & Isolation
+- Data Factories: (e.g. UserFactory)
+- Network Intercepts: (e.g. MSW handlers)
+- Database State: (e.g. in-memory SQLite)
+
+## 3. NFR Verification
+| NFR Type | Requirement | Verification Command |
+|----------|-------------|----------------------|
+| Perf     | < 200ms     | `npm run test:perf`  |
+
+## 4. Out of Scope
+- [Explicitly excluded testing areas]
+```
+
+## Fixture Planning Guidance
+
+- **Data Factories**: Prefer factory functions over manual object construction.
+- **Network Intercepts**: For frontend integration tests, use tools like Mock Service Worker (MSW) to intercept and mock HTTP requests.
+- **Database State**: For backend tests, use a clean database state per test or an in-memory database to ensure isolation.

package/.gemini/extensions/bigpowers/skills/plan-work/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: plan-work
+model: opus
+description: "PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2)."
+disable-model-invocation: true
+---
+
+# story: e45s29
+
+# Plan Work
+
+> **Spine position:** Step 3 — scope-work → slice-tasks → plan-work.
+
+Produce a detailed, verifiable implementation plan in the **active epic capsule directory** (`specs/epics/eNN-slug/`). Output: a story spec `.md` file (countable-story-format) and a decoupled `eNNsYY-tasks.yaml` with runnable verify commands. "I think it works" is not a step.
+
+> **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, convert the task into "step → verify: `<cmd>`" pairs here before writing tasks — every task ships a runnable `verify:` or the plan is not done.
+>
+> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
+
+## Pre-flight
+
+Read: `release-plan.yaml`, `product/SCOPE_LATEST.yaml`, active `epics/<capsule>/epic.yaml`, `tech-architecture/tech-stack.md`, `product/GLOSSARY_LATEST.yaml`.
+
+> **ZOOM-OUT MANDATE** (v1.17.0) — If modifying an existing module: (1) State the module's **purpose**. (2) Name its **callers**. (3) List its **contracts**. Cannot answer all three? Stop — scope is misunderstood.
+
+If this plan touches an existing module, run `assess-impact` first to understand blast radius.
+
+> **DISCOVERY MANDATE** (v1.18.0) — For external API integration, verify the API signature via local docs or search and quote at least one technical detail in the step's context.
+
+> **MULTIPLE INTERPRETATIONS (HARD GATE)** — If the task admits ≥2 valid interpretations, list them and get a user decision before drafting any steps.
+
+> **COMPLEXITY PUSHBACK (HARD GATE)** — Every new abstraction MUST include a one-sentence "Reason for Depth." If it can't be filled non-trivially, the abstraction is premature — use inline code instead.
+
+> **SLOPCHECK (HARD GATE)** — For every external package, tag it `[OK]`, `[SUS]`, or `[SLOP]`. `[SUS]`/`[SLOP]` require human approval before execution.
+
+## Invocation modes
+
+- Default: full plan with zoom-out mandate, impact assessment, slopcheck
+- `--fast`: Skip zoom-out and impact assessment. Use for tasks under 3 BCPs with no module interface changes.
+
+## Process
+
+> **Timing:** `bash scripts/bp-timing.sh start plan-work` at invocation; `bash scripts/bp-timing.sh end plan-work` before handoff.
+
+1. **Explore** — Use `Explore` subagent to understand affected modules, existing test patterns, similar prior art, and dependencies.
+
+2. **Draft steps** — Break implementation into the smallest possible steps where each step leaves the codebase working, has one observable outcome, and can be verified with a single command. Red-flag check: name any rationalization you caught before moving to step 3.
+
+3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics/<id>/THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. Each task should also include an `allure:` block to drive test reporting: `severity:` maps risk to Allure severity (`P0→critical`, `P1→high`, `P2→normal`, `P3→minor`), and `categories:` is a list of relevant tags like `"Security Review"`, wave names, or test categories (see REFERENCE.md for the full template).
+
+   **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content:
+
+   | Tag | When | Required content |
+   |-----|------|------------------|
+   | `ADDED` | New requirement | Full requirement text |
+   | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior |
+   | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale |
+   | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title |
+
+   Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate.
+
+4. **Verify step format** — Every step MUST follow: `N. <What to do> → verify: <runnable command>`. See [REFERENCE.md](REFERENCE.md) for good/bad examples.
+
+4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run:
+
+```bash
+bash scripts/lib/plan-consistency-check.sh specs/epics/<capsule>/
+```
+
+Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment.
+
+4b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time.
+
+5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project.
+
+## Lifecycle Gates (e45s09)
+
+| Gate | When | Pass condition |
+|------|------|----------------|
+| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS |
+| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` |
+| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries |
+
+After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`.
+
+## Verify
+
+→ verify: `test -f scripts/lib/plan-consistency-check.sh && EPIC=$(ls -d specs/epics/*/ 2>/dev/null | grep -v archive | sort | head -1) && test -n "$EPIC" && bash scripts/lib/plan-consistency-check.sh "$EPIC" >/dev/null 2>&1`
+
+
+
+## Handoff
+
+Gate: READY -> next: kickoff-branch
+Writes: state.yaml handoff.next_skill = kickoff-branch
+
+
+<!-- story: e01s01 -->
+<!-- story: e02s02 -->
+<!-- story: e06s01 -->
+<!-- story: e06s02 -->
+
+---
+
+# Plan Work — Reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–25 | Navigation |
+| 26–27 | Output file formats |
+| 28–31 | Story spec: `specs/epics/<capsule>/eNNsYY-<slug>.md` |
+| 32–61 | Task checklist: `specs/epics/<capsule>/eNNsYY-tasks.yaml` |
+| 62–64 | Plan template |
+| 65–71 | Story [X.Y]: [title] — Implementation Steps |
+| 72–77 | Steps |
+| 78–85 | Verification Script (Step-by-Step) |
+| 86–89 | Out of scope |
+| 90–94 | Risks |
+| 95–114 | Verify step format rules |
+| 115–116 | Sub-operations |
+| 117–127 | Risk Assignment Heuristics |
+| 128–143 | Requirement delta tags (e45s29) |
+| 144–152 | Define Success |
+| 153–161 | Zoom-Out Check |
+| 162–169 | Slopcheck |
+
+## Output file formats
+
+### Story spec: `specs/epics/<capsule>/eNNsYY-<slug>.md`
+
+Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Countable). Acceptance criteria in §17.
+
+### Task checklist: `specs/epics/<capsule>/eNNsYY-tasks.yaml`
+
+```yaml
+story_id: e01s01
+title: Login
+status: failing
+bcps: 3
+tasks:
+  - id: 1
+    description: "Add login form component tests"
+    verify: "npm test -- login-form.test.tsx"
+    risk: P1
+    status: failing   # flip to passing only after verify exits 0 (e45s06)
+    allure:
+      severity: high              # P0→critical, P1→high, P2→normal, P3→minor
+      categories:
+        - "Auth"
+        - "Security Review"
+```
+
+**Allure severity mapping:**
+- `P0` → `critical`
+- `P1` → `high`
+- `P2` → `normal`
+- `P3` → `minor`
+
+`categories` is a list of relevant tags — wave names, test categories (e.g. `"unit"`, `"integration"`), or thematic groupings (e.g. `"Security Review"`).
+
+Update `specs/epics/<capsule>/epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
+
+## Plan template
+
+```
+### Story [X.Y]: [title] — Implementation Steps
+
+**type:** feat | fix | refactor
+**risk:** P0 | P1 | P2 | P3
+**context:** domain | infra
+**Context**: [One paragraph: what this story implements and why]
+
+## Steps
+
+1. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
+2. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
+...
+
+## Verification Script (Step-by-Step)
+
+[A human-readable, step-by-step script for the user to verify the story's outcome.]
+
+1. [Action 1: e.g. Start the server]
+2. [Action 2: e.g. Open browser to http://localhost:3000]
+3. [Observation: e.g. Verify that the login modal appears]
+
+## Out of scope
+
+- [Explicit exclusions]
+
+## Risks
+
+- [Anything that could go wrong and how to detect it early]
+```
+
+## Verify step format rules
+
+Every step MUST follow this exact format:
+```
+N. <What to do> → verify: <runnable command that proves it worked>
+```
+
+**Good examples:**
+```
+1. Add User model with email and name fields → verify: npm test -- user.test.ts
+2. Add POST /users endpoint → verify: curl -s -X POST http://localhost:3000/users -d '{"email":"a@b.com"}' | jq .id
+3. Add email uniqueness constraint → verify: npm test -- user-uniqueness.test.ts
+```
+
+**Bad examples (no verify command):**
+```
+1. Implement the user creation flow
+2. Write tests for the API
+```
+
+## Sub-operations
+
+### Risk Assignment Heuristics
+
+Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` exists for the epic, defer to its scenario risk mapping (`SC-eNNsYY-P0-NN`). Otherwise, apply these heuristics based on BCP and story type:
+
+- **P0**: Critical path, data loss risk, auth/security boundary, external integration, or high BCP (≥ 5).
+- **P1**: Core feature logic, state mutations, standard business value (BCP 3-4).
+- **P2**: Utility functions, UI layout changes, display-only data, low risk (BCP 2).
+- **P3**: Documentation, cosmetic tweaks, CSS variables, zero behavioral change (BCP 1).
+
+`verify-work` scales its UAT depth based on this field.
+
+### Requirement delta tags (e45s29)
+
+When modifying existing behavior in story spec § Requirements:
+
+```markdown
+#### MODIFIED: User can reset password via email link
+**Before:** Password reset required admin approval.
+**After:** Self-service reset via signed email link (expires 1h).
+
+#### REMOVED: Legacy OAuth1 login
+**Before:** OAuth1 provider supported for enterprise SSO.
+**After:** (removed) — provider deprecated; OAuth2 only.
+```
+
+Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL.
+
+### Define Success
+
+Before planning, convert task statements into observable "step → verify: <cmd>" pairs:
+- Break the task into observable outcomes (behaviors) rather than implementation steps
+- Write pairs in the format: `[What must be true] → verify: <runnable command>`
+- Challenge completeness: are all required behaviors covered?
+- Get user confirmation: "Does this capture everything the task requires?"
+- Once confirmed, these pairs become the skeleton for plan-work steps
+
+### Zoom-Out Check
+
+When modifying an existing module, confirm scope is understood:
+- State the module's **purpose** — what is it responsible for?
+- Name the **callers** — who depends on it?
+- List the **contracts** — what invariants or interfaces must be preserved?
+
+If you cannot answer all three without deep code archaeology, scope is misunderstood. Clarify with the user before writing steps.
+
+### Slopcheck
+
+For every external package proposed in the plan, tag each with one of:
+- `[OK]` — package is mature, actively maintained, appropriate scope
+- `[SUS]` — suspiciously broad, has maintenance concerns, or unclear fit
+- `[SLOP]` — unmaintained, known security issues, or out of scope
+
+`[SUS]` and `[SLOP]` require explicit human approval before the step may execute. Document tags inline next to the package name.