bigpowers 2.2.0 → 2.4.0

package/.pi/prompts/wire-observability.md

@@ -0,0 +1,92 @@
+---
+description: Add structured JSON logging, observability commands, and idempotent setup scripts to a project. Use when a project needs production-readiness instrumentation, when user wants structured logging, or as a production-readiness gate at any phase of development.
+---
+
+
+# Wire Observability
+> **HARD GATE** — **HARD GATE** — Observability is not optional. Before shipping, verify: structured logging is in place, key metrics are instrumented, error cases emit signals. 'We'll add metrics later' becomes 'never.'
+
+
+Add structured logging, observability commands, and idempotent setup scripts. Can be invoked at any phase — recommended at the end of the first working slice, before the first deploy.
+
+## What this sets up
+
+1. **Structured JSON logging** — machine-readable logs for debugging and observability
+2. **Observability commands** — how to check the system's health documented in CLAUDE.md
+3. **Idempotent setup scripts** — scripts that can be run repeatedly without side effects
+
+## Process
+
+### 1. Assess current state
+
+Check what's already in place:
+- Is there a logging library? (pino, winston, structlog, zap, slog, etc.)
+- Is logging JSON or plain text?
+- Is there a health check endpoint or command?
+- Are there setup scripts? Are they idempotent?
+
+### 2. Add structured JSON logging
+
+**For user-facing CLI output:** plain text is fine.
+**For everything else:** structured JSON.
+
+Structured log entry format:
+```json
+{
+  "level": "info",
+  "timestamp": "2025-01-15T10:23:45.123Z",
+  "message": "User created",
+  "userId": "usr_abc123",
+  "requestId": "req_xyz789"
+}
+```
+
+Guidelines:
+- Include `level`, `timestamp`, `message` in every entry
+- Add context fields relevant to the operation (userId, requestId, traceId)
+- Log at boundaries: HTTP requests in/out, DB queries, external API calls, background job start/end
+- Log errors with stack traces: `logger.error({ err, context }, "Operation failed")`
+- **Never log secrets, passwords, tokens, or PII**
+
+### 3. Document observability commands in CLAUDE.md
+
+Add an "Observability" section to the project's CLAUDE.md:
+
+```markdown
+## Observability
+
+| What | Command |
+|------|---------|
+| View logs | `<log tail command>` |
+| Health check | `<health check command>` |
+| Check DB connection | `<db ping command>` |
+| View metrics | `<metrics command>` |
+```
+
+### 4. Write idempotent setup scripts
+
+An idempotent script can be run multiple times and always produces the same result (no errors on re-run).
+
+Pattern: check if the thing already exists before creating it.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Idempotent: only create if not exists
+if ! psql -c "SELECT 1 FROM pg_database WHERE datname = 'myapp'" | grep -q 1; then
+  createdb myapp
+  echo "Database created"
+else
+  echo "Database already exists, skipping"
+fi
+```
+
+Place setup scripts in `scripts/setup.sh` (or language-appropriate equivalent). Document the command in CLAUDE.md under Commands.
+
+### 5. Verify
+
+- [ ] Run the app and confirm JSON logs appear in the correct format
+- [ ] Run `scripts/setup.sh` twice — second run should produce no errors
+- [ ] Health check command returns success
+- [ ] No sensitive data in log output

package/.pi/prompts/write-document.md

@@ -0,0 +1,244 @@
+---
+description: Write, organize, and sync high-integrity technical documents using the BMAD methodology. Ensures every document is Bold, Minimal, Actionable, and Durable. Use when creating architectural docs, technical guides, or organizing the specs/ directory.
+---
+
+
+# Write Document (BMAD)
+
+Create high-signal technical documentation that serves as an expert collaborator for both humans and AI. This skill enforces the BMAD principles to prevent context rot and ensure architectural durability.
+
+**Distinct from `edit-document`:** Use this skill to create a document that does not yet exist. Use `edit-document` when a document already exists and needs restructuring, clarity, or prose improvements.
+
+> **HARD GATE** — Every document must have a clear "Reason for Existence." If a document doesn't provide actionable leverage for a caller or test, do not create it.
+
+## The BMAD Principles
+
+| Principle | Execution |
+| :--- | :--- |
+| **B**old | Make strong assertions. Define clear boundaries and "Never" rules. No "it might" or "usually." |
+| **M**inimal | High-density, low-filler. **Circuit Breaker**: If the file exceeds 300 lines or the session exceeds 20 turns, you MUST run `terse-mode` and compact state before saving. |
+| **A**ctionable | Link every doc to a verifiable outcome. **Architectural Docs**: Verify via Gherkin features (`specs/verifications/features/`) or grep-based structure checks (`grep -c "pattern" file`) that prove the design's *constraints* are present. |
+| **D**urable | Design for the long-term. **Scalability**: Use "Nested Indexing"—root files link to module-level `GEMINI.md` indexes; do not list individual sub-files in the root. |
+
+## Process
+
+### 1. Identify the Artifact Type & Scope
+
+Choose the correct BMAD-BigPowers artifact:
+- **Decision Record (ADR)**: For "Why" decisions (saved to `specs/adr/`).
+- **Context Map**: For system-wide architectural mapping (`specs/tech-architecture/tech-stack.md`).
+- **Technical Guide**: For "How-to" with verification (saved to `<module>/REFERENCE.md`).
+- **Behavioral Feature**: Gherkin-style compliance specs (saved to `specs/verifications/features/`).
+- **Project README**: Project-facing documentation (saved to `README.md` at project root).
+
+**Cross-Cutting Concerns**: If a doc affects multiple modules, place the authoritative source in the lowest common ancestor directory and use "Delegates" (one-line pointers) in sub-directories to maintain the Single Source of Truth without violating the Stepdown Rule.
+
+### 2. Draft with Semantic Velocity
+
+> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
+
+Write the document focusing on "Expert Collaboration":
+- **Instructions over Descriptions**: Tell the reader (human or AI) exactly how to interact with the system.
+- **Provenance Links**: Link to ADRs, Issues, or Commits to preserve intent.
+- **The Stepdown Rule**: Information should descend exactly one level of abstraction. If a root doc needs to explain a leaf-level detail, it must point to a sub-index first.
+
+### Quick README (Project READMEs only)
+
+1. Ask: "Project name? One-sentence description?"
+2. Generate `README.md` at project root using the template in [REFERENCE.md](REFERENCE.md) — no TOC, no second interview round.
+3. Fill gaps from `CLAUDE.md` commands if available; use `TODO` markers otherwise.
+4. Output and suggest `edit-document` for polish.
+
+→ verify: `grep -c "^## " README.md | awk '{if($1>=7) print "OK"}'`
+
+### 3. Apply the 94% Quality Gate
+
+Before finalizing, audit the document against these red flags:
+- [ ] **Filler Language**: Are there pleasantries or "I hope this helps"? (Delete them).
+- [ ] **Ambiguity**: Are there "usually," "often," or "it depends" without specific conditions?
+- [ ] **Dead Ends**: Does the document end without a "Next Step" or "Verification" command?
+- [ ] **Shallow Content**: Does it restate the code without explaining the *intent* or *contracts*?
+
+### 4. Sync and Organize
+
+- **Big Powers Hierarchy**: Place the document in the correct tier (Global -> Project -> Sub-directory). Project READMEs are an exception — they go to project root (`README.md`), not `specs/`.
+- **Nested Indexing**: If adding a module-level doc, ensure the module's `GEMINI.md` is updated. If the module's index is new, add it to the root `GEMINI.md`.
+- **Sync**: Run `scripts/sync-skills.sh` if the document is a `SKILL.md` or affects generated artifacts.
+
+## Rules
+
+- **Minimalism is a requirement**: If a document can be a 5-line table, do not make it a 5-line essay.
+- **Verifiable outcomes**: Every technical document must include at least one `verify:` command. For architecture, this can be a `grep` or `run_shell_command` that validates the existence of required files or patterns.
+- **No speculative docs**: Do not write documentation for features that do not exist yet unless explicitly doing `elaborate-spec`.
+
+
+Suggest next skill: `audit-code` or `sync-skills.sh`.
+
+---
+
+# Project README Template
+
+Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
+
+## Sections
+
+### 1. Title + Badges
+
+```markdown
+# Project Name
+
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+![npm version](https://img.shields.io/npm/v/your-package.svg)
+
+```
+
+Fill badges from CLAUDE.md stack info if available. Default to license + version badges.
+
+### 2. Tagline
+
+```markdown
+> One-line description of what this project does and why it matters.
+```
+
+### 3. Description
+
+2-3 paragraphs: what problem it solves, who it's for, and what makes it different.
+
+### 4. Prerequisites
+
+```markdown
+## Prerequisites
+
+- **Runtime**: Node.js v18+ (from CLAUDE.md)
+- **Package manager**: npm (or pnpm/yarn)
+```
+
+Auto-fill from CLAUDE.md commands section when possible.
+
+### 5. Installation
+
+```markdown
+## Installation
+
+```bash
+npm install -g your-package
+# or
+npx your-package
+```
+```
+
+Prefer npx one-shot if applicable; list global install as alternative.
+
+### 6. Usage
+
+```markdown
+## Usage
+
+```bash
+your-command --help
+your-command do-something
+```
+```
+
+Include the most common 1-2 commands. Link to full docs if they exist.
+
+### 7. Features
+
+```markdown
+## Features
+
+- Feature 1: short description
+- Feature 2: short description
+```
+
+3-6 bullet points of what the project does. Derived from the project's purpose.
+
+### 8. Configuration
+
+```markdown
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VAR_NAME` | `value` | What it controls |
+```
+
+Use `TODO` markers if unknown.
+
+### 9. Development Setup
+
+```markdown
+## Development
+
+```bash
+git clone <repo-url>
+cd project
+npm install
+```
+```
+
+Auto-fill from CLAUDE.md `Run` and `Build` commands.
+
+### 10. Running Tests
+
+```markdown
+## Tests
+
+```bash
+npm test
+npm run lint
+```
+```
+
+Auto-fill from CLAUDE.md `Test` and `Lint` commands.
+
+### 11. Contributing
+
+```markdown
+## Contributing
+
+1. Fork the repo.
+2. Create a feature branch (`git checkout -b feature/my-thing`).
+3. Commit changes (`git commit -am 'Add my thing'`).
+4. Push (`git push origin feature/my-thing`).
+5. Open a Pull Request.
+```
+
+### 12. Changelog
+
+```markdown
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases).
+```
+
+### 13. Links
+
+```markdown
+## Links
+
+- Repository: https://github.com/user/repo
+- Issue tracker: https://github.com/user/repo/issues
+```
+
+### 14. License
+
+```markdown
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+```
+
+Detect from CLAUDE.md or project LICENSE file.
+
+### 15. Credits (optional)
+
+```markdown
+## Credits
+
+Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+```
+
+## Verify
+
+After generation, run: `grep -c "^## " README.md` — expect ≥ 7 section headings.

package/.pi/skills/assess-impact/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: assess-impact
+description: "Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks "what does this break?"."
+---
+
+
+# Assess Impact
+
+> **HARD GATE** — Run this skill before `plan-work` whenever a change touches an existing module, symbol, or file used by more than one caller. Skip only for net-new code with no existing dependents.
+
+Find the blast radius of the proposed change before a single line is written.
+
+## Process
+
+### 1. Identify the target
+
+Name the symbol, module, or file being changed. If the user hasn't specified, ask one question: "What exactly are you changing?"
+
+### 2. Find dependents
+
+```
+grep -rn "[symbol-name]" . --include="*.ts" | grep -v node_modules
+git log --oneline -10 -- [file-path]
+```
+
+→ verify: `grep -rn "[target]" . | wc -l`
+
+### 3. Map to release plan stories
+
+Read `specs/release-plan.yaml + epic capsule directories` (if it exists). For each dependent found in Step 2, identify which story owns that module. List stories that will be affected by the change.
+
+→ verify: `grep -c "Story" specs/release-plan.yaml + epic capsule directories 2>/dev/null || echo "no release plan"`
+
+### 4. List test coverage
+
+Find tests that exercise the target:
+
+```
+grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
+```
+
+→ verify: `grep -rn "[target]" . --include="*.test.*" | wc -l`
+
+### 5. Classify risk
+
+| Level | Condition |
+|-------|-----------|
+| Low   | ≤ 2 callers, all covered by tests |
+| Medium | 3–10 callers, partial test coverage |
+| High  | > 10 callers, or shared API/interface, or no tests |
+
+### 6. Write specs/IMPACT.md
+
+```
+## Target
+[symbol or file being changed]
+
+## Dependents ([count])
+- [file]: [caller or usage]
+
+## Affected Stories
+- Story [X.Y]: [title]
+
+## Test Coverage
+- [test file]: covers [scenario]
+- Gap: [untested behavior]
+
+## Risk: Low / Medium / High
+[One-sentence rationale]
+
+## Recommended action
+[Proceed / Add tests first / Discuss design]
+```
+
+→ verify: `grep "Risk:" specs/IMPACT.md`
+
+Suggest `plan-work` once risk is understood and any test gaps are noted.

package/.pi/skills/audit-code/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: audit-code
+description: "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check."
+---
+
+
+# Audit Code
+> **HARD GATE** — **HARD GATE** — Audit must check for: bugs (correctness), security, performance, and clarity. Do NOT skip security review if the code touches user data, auth, or external APIs.
+
+
+Run this self-review before asking anyone else to look at the code. The goal is to catch everything that is clearly wrong or missing — so the reviewer can focus on design and architecture, not hygiene.
+
+**Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes.
+
+## Modes
+
+- Default: full checklist
+- --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
+
+## Checklist
+
+### Supply Chain & Security
+
+- [ ] slopcheck run for new dependencies; packages tagged in plan-work: `[OK]`, `[SUS]`, or `[SLOP]`
+- [ ] No `[SLOP]` packages without documented human approval
+- [ ] No secrets in diff (`sk-`, `ghp_`, `AKIA`, `.env` values) — see `guard-git` patterns
+- [ ] OWASP Top 10 spot-check: injection, broken auth, sensitive data exposure, misconfiguration (see `docs/references/security-threats.md`)
+
+### Provenance & Metadata
+
+- [ ] New plan artefacts include `type:` and `context:` metadata
+- [ ] Implementation steps reference ADR or commit SHA where decisions were made
+
+### Law of Demeter
+
+- [ ] No method chains through unrelated objects (e.g. `a.getB().getC().doX()`)
+- [ ] Collaborators talk to immediate neighbors only; law violations need explicit justification
+
+### CONVENTIONS.md Compliance
+
+- [ ] All output files are in `specs/` (no docs written to project root)
+- [ ] No `gh issue create` calls anywhere in new/modified skills or scripts
+- [ ] `gh` used only for PRs and repo clone operations
+- [ ] No GitHub REST API called directly (no curl/fetch to api.github.com)
+
+### Scope
+
+- [ ] Changes are limited to what was asked — nothing extra refactored or reorganized
+- [ ] No speculative features added
+- [ ] No files touched outside the stated scope
+- [ ] Changes are surgical: only code strictly required for the task; no refactoring, reorganization, or cleanup outside task scope (Boy Scout Rule applied surgically, not broadly)
+
+### Boy Scout Rule
+
+- [ ] Every file I touched is cleaner than when I found it
+- [ ] No dead code left behind
+- [ ] No commented-out code blocks
+
+### Types and Safety
+
+- [ ] No `any` types introduced (TypeScript) or untyped public functions (Python/Go/etc.)
+- [ ] No `@ts-ignore` or `// eslint-disable` added
+- [ ] No `as unknown as X` casts that bypass type safety
+
+### Test Coverage
+
+- [ ] Every new function has at least one test
+- [ ] Every bug fix has a regression test
+- [ ] Tests verify behavior through public interfaces (not implementation details)
+- [ ] Tests are F.I.R.S.T compliant (use `enforce-first` if unsure)
+
+### SOLID and Heuristics
+
+- [ ] Single Responsibility: no function or module doing two unrelated things
+- [ ] Open/Closed: extended through interfaces, not by modifying stable code
+- [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable
+- [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)
+
+### Code Style (CONVENTIONS.md)
+
+- [ ] Functions: 4–20 lines; split if longer
+- [ ] Functions: descend exactly one level of abstraction (The Stepdown Rule / G34)
+- [ ] Files: under 300 lines (ideally 200–300)
+- [ ] Names: specific and unique (grep returns < 5 hits for each name)
+- [ ] No duplication — shared logic extracted (DRY / G5)
+- [ ] Early returns over nested ifs; max 2 levels of indentation
+- [ ] Conditionals: expressed as positives (G29)
+- [ ] Comments explain WHY, not WHAT
+
+### Agent Readability (Akita's Lens)
+
+- [ ] Functions are small enough to fit in a standard context window (4–20 lines)
+- [ ] Names are unique and specific enough to be `grep`-able (grep returns < 5 hits)
+- [ ] Types are explicit (no `any`, no inferred return types for public APIs)
+- [ ] Code avoids deep nesting (max 2 levels) and uses early returns
+
+### Red Flags
+
+Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.
+
+## Output
+
+Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed.
+
+If all items pass: suggest running `request-review` for an independent second opinion.
+If any items fail: fix them before proceeding.
+
+## Handoff
+
+Gate: READY -> next: commit-message
+Writes: state.yaml handoff.next_skill = commit-message
+
+---
+
+# Clean Code Heuristics (Chapter 17)
+
+A summary of Robert C. Martin's catalogue of code smells and heuristics, used as the technical benchmark for `audit-code`.
+
+## Comments (C)
+- **C1: Inappropriate Information**: Comments should only hold technical notes. Metadata (author, change history) belongs in Git.
+- **C2: Obsolete Comment**: Update or delete comments that are no longer accurate.
+- **C3: Redundant Comment**: Don't describe code that adequately describes itself (e.g., `i++; // increment i`).
+- **C4: Poorly Written Comment**: If you write a comment, spend time making it the best it can be.
+- **C5: Commented-Out Code**: Delete it. Git remembers it.
+
+## Environment (E)
+- **E1: Build Requires More Than One Step**: Building should be a single trivial operation (e.g., `bash install.sh`).
+- **E2: Tests Require More Than One Step**: Running all tests should be one simple command (e.g., `npm test`).
+
+## Functions (F)
+- **F1: Too Many Arguments**: 0 is ideal, 1-2 is fine, 3 requires special justification. Never > 3.
+- **F2: Output Arguments**: Avoid them. If a function changes state, it should change the state of its owning object.
+- **F3: Flag Arguments**: Boolean arguments are a smell that the function does > 1 thing.
+- **F4: Dead Function**: Discard methods that are never called.
+
+## General (G)
+- **G1: Multiple Languages in One Source File**: Try to minimize the mixing of languages (e.g., HTML inside Java).
+- **G5: Duplication (DRY)**: **The root of all evil.** Every time you see duplication, it's a missed opportunity for abstraction.
+- **G6: Code at Wrong Level of Abstraction**: High-level concepts in base classes; low-level details in derivatives.
+- **G25: Replace Magic Numbers with Named Constants**: No "naked" numbers or strings.
+- **G28: Encapsulate Conditionals**: Prefer `if (shouldBePublished())` over complex boolean logic.
+- **G29: Avoid Negative Conditionals**: Prefer `if (buffer.shouldCompact())` over `if (!buffer.shouldNotCompact())`.
+- **G30: Functions Should Do One Thing**: If a function can be split into sections, it's doing too much.
+- **G31: Hidden Temporal Couplings**: If execution order matters, make the dependency explicit via arguments.
+- **G34: Functions Should Descend Only One Level of Abstraction**: The Stepdown Rule.
+
+## Naming (N)
+- **N1: Choose Descriptive Names**: Names should reveal intent and be updated as code evolves.
+- **N4: Unambiguous Names**: Names should make the working of a function/variable clear.
+- **N7: Names Should Describe Side-Effects**: Describe everything the function is or does.
+
+## Tests (T)
+- **T1: Insufficient Tests**: A test suite should test everything that could possibly break.
+- **T4: An Ignored Test Is a Question about an Ambiguity**: Document the reason for `@Ignore`.
+- **T5: Test Boundary Conditions**: Most bugs happen at the boundaries; test them exhaustively.
+- **T8: Test Coverage Patterns Can Be Revealing**: Analyze what code is *not* executed to find gaps.
+- **T9: Tests Should Be Fast**: Slow tests don't get run.

package/.pi/skills/build-epic/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: build-epic
+description: "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work."
+---
+
+
+# Build Epic
+
+Scope: one story. Called by orchestrate-project Phase 4. Not a replacement for orchestrate-project.
+
+Orchestrates the **build** flow for a single epic: survey → plan tasks → kickoff → TDD → verify → audit → commit → release.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: build_epic` and `active_epic: eNN` before starting.
+>
+> **HARD GATE** — Not on `main`/`master` before step 3 (kickoff-branch).
+
+## Eight steps (`epic_cycle` in state.yaml)
+
+| Step | Skill / action |
+|------|----------------|
+| 1 | `survey-context` — confirm epic + story |
+| 2 | `plan-work` — flesh out story `tasks[]` in `specs/epics/eNN-slug/epic.yaml` |
+| 3 | `kickoff-branch` — feature branch + clean baseline |
+| 4 | `develop-tdd` — red-green per task |
+| 5 | `verify-work` — UAT + mechanical gates |
+| 6 | `audit-code` — self-review checklist |
+| 7 | `commit-message` — Conventional Commits draft |
+| 8 | `release-branch` — PR or solo land |
+
+## Process
+
+1. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-slug/epic.yaml`.
+2. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count (Business Complexity Points story size) from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
+3. If `epic_cycle.step` missing, set to `1`.
+4. Run **only the current step** (resume mode) unless user asked for full auto-run.
+5. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
+6. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
+
+## Handoff
+
+Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.
+
+## Verify
+
+→ verify: `grep -q 'active_flow: build_epic' specs/state.yaml && test -f specs/epics/*/epic.yaml`