bigpowers 2.83.4 → 2.84.1

package/.windsurf/rules/write-document.md

@@ -0,0 +1,255 @@
+---
+name: write-document
+model: sonnet
+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.
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 5–16 | Navigation |
+| 18–24 | Sections intro |
+| 26–178 | README section templates (1–15) |
+| 180–183 | Verify |
+
+## 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/.zcode/skills/audit-code/SKILL.md

@@ -95,6 +95,10 @@ bash scripts/lib/parallel-review-worktrees.sh audit-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)
 
+### Refactoring Smells (Fowler)
+
+Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man.
+
 ### Code Style (CONVENTIONS.md)
 
 - [ ] Functions: 4–20 lines; split if longer
@@ -106,13 +110,6 @@ bash scripts/lib/parallel-review-worktrees.sh audit-code
 - [ ] 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.

package/.zcode/skills/grill-me/SKILL.md

@@ -18,6 +18,14 @@ Interview relentlessly about every aspect of this plan until reaching shared und
 
 If a question can be answered by exploring the codebase, explore it instead.
 
+### Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by exploring the codebase, reading docs, or checking APIs. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the code, go find it. Only ask questions where the user's judgment is needed.
+
 ## 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.
@@ -29,6 +37,10 @@ Short form:
 4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
 5. Update the plan for each confirmed discrepancy.
 
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+
 ---
 
 # Docs Mode — Full Process

package/.zcode/skills/grill-with-docs/SKILL.md

@@ -23,6 +23,18 @@ description: "Doc-grounded variant of grill-me — stress-tests plan assumptions
 - If docs contradict the plan, plan loses until updated.
 - Prefer official docs over blog posts.
 
+## Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by reading docs, checking APIs, or exploring the codebase. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the docs, go fetch it. Only ask questions where the user's judgment is needed.
+
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+
 ## Verify
 
 → verify: `grep -c 'https\?://' skills/grill-with-docs/SKILL.md | awk '{if($1>=2) print "OK"; else print "NEEDS DOCS"}'`

package/.zcode/skills/request-review/SKILL.md

@@ -86,6 +86,7 @@ Review for:
 4. Design — are there simpler or more robust approaches?
 5. Edge cases — what inputs or states could cause failures?
 6. Security — any injection, auth, or data exposure risks?
+7. Refactoring smells — explicitly name any detected Fowler smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man
 
 For each finding, categorize as: must-fix / should-fix / consider.
 Run the verify command and report the result.