bigpowers 1.0.0 → 1.1.0

package/session-state/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: session-state
+model: haiku
 description: Track implementation decisions and progress in specs/STATE.md 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.
 ---
 
@@ -9,14 +10,35 @@ Track the current state of implementation, including decisions made, pending tas
 
 ## Goal
 
-Maintain a single source of truth for the *current* state of the work in `specs/STATE.md`. This file acts as the project's short-term memory, complementing the long-term memory of `specs/CONTEXT.md` and the task-specific instructions in `specs/PLAN.md`.
+Maintain a single source of truth for the *current* state of the work in `specs/STATE.md`. This file acts as the project's short-term memory, complementing the long-term memory of `specs/CONTEXT.md` and the task-specific instructions in `specs/RELEASE-PLAN.md`.
+
+## Handoff block (cold start)
+
+When ending a session or before a context-heavy spawn, write a **Handoff** section at the top of STATE.md:
+
+```markdown
+## Handoff
+- **Last step completed:** ...
+- **Open decisions:** ...
+- **Required reading:** CONVENTIONS.md, RELEASE-PLAN.md story X.Y, ...
+- **Next skill:** verify-work | 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.md only channel between spawns |
+
 ## Workflow
 
 ### 1. Initialize (Session Start)
 
 If `specs/STATE.md` does not exist, or if starting a new major phase:
 
-- [ ] Read `specs/PLAN.md` and `specs/SCOPE.md`.
+- [ ] Read `specs/RELEASE-PLAN.md` and `specs/SCOPE.md`.
 - [ ] Get git metadata: `git branch --show-current` and `git rev-parse HEAD`.
 - [ ] Create `specs/STATE.md` with the current milestone, git metadata, pending tasks, and any active decisions.
 
@@ -64,6 +86,6 @@ Whenever a significant decision is made or a milestone is reached:
 
 ## Anti-Patterns
 
-- **Duplicate Plan**: Don't just copy `specs/PLAN.md`. The plan is the *intended* path; the state is the *actual* progress and the deviations from that path.
+- **Duplicate Plan**: Don't just copy `specs/RELEASE-PLAN.md`. The plan is the *intended* path; the state is the *actual* progress and the deviations from that path.
 - **Stale State**: Forgetting to update `specs/STATE.md` after a major refactor or decision.
 - **Verbose History**: Keep it focused on the *current* state. Use git history for the past.

package/setup-environment/SKILL.md

@@ -0,0 +1,22 @@
+---
+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
+
+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.md` under Environment.
+
+## Verify
+
+→ verify: commands from CLAUDE.md Test/Lint rows exit 0

package/simulate-agents/SKILL.md

@@ -0,0 +1,24 @@
+---
+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
+
+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/slice-tasks/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: slice-tasks
+description: Break a plan or PRD into independently-grabbable vertical-slice tasks in specs/TASKS.md. Use after scope-work or plan-release, before plan-work, when user wants implementation tickets or tracer-bullet slices.
+model: sonnet
+---
+
+# Slice Tasks
+
+Produce `specs/TASKS.md` — vertical slices, each independently deliverable and testable.
+
+## Process
+
+1. Read `specs/SCOPE.md` and/or `specs/RELEASE-PLAN.md`.
+2. Cut **tracer-bullet slices** (thin end-to-end paths first, then depth).
+3. Each task entry: `id`, `title`, `depends-on:` (optional), `verify:` command, `story:` link.
+4. Order by WSJF within the file.
+
+> **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration.
+
+## Verify
+
+→ verify: `test -f specs/TASKS.md && grep -c "verify:" specs/TASKS.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`

package/spike-prototype/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: spike-prototype
+model: sonnet
 description: Throw-away prototype for unknown problem spaces. Output is learning notes in specs/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".
 ---
 

package/stocktake-skills/REFERENCE.md

@@ -0,0 +1,8 @@
+# Stocktake checklist
+
+- [ ] SKILL.md exists at repo root `<name>/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)

package/stocktake-skills/SKILL.md

@@ -0,0 +1,28 @@
+---
+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
+
+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.

package/survey-context/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: survey-context
+model: haiku
 description: Per-task context survey — reads specs/ and CONVENTIONS.md, maps the current lifecycle phase, and suggests the next skill to invoke. Use at the start of any new task, when returning to a project after a break, or when unsure what to do next.
 ---
 
@@ -23,10 +24,9 @@ specs/
 ├── UBIQUITOUS_LANGUAGE.md → glossary status
 ├── SCOPE.md            → scope definition status
 ├── TASKS.md            → task breakdown status
-├── PLAN.md             → implementation plan status
+├── RELEASE-PLAN.md     → implementation plan status
 ├── REFACTOR.md         → refactor plan status
-├── DIAGNOSIS.md        → active bug investigation
-├── BUG-LOG.md          → historical bug log
+├── bugs/               → bug investigations (BUG-*.md) + BUG-LOG.md
 └── SPIKE-*.md          → spike learning notes
 ```
 
@@ -53,12 +53,12 @@ Based on what you've found, identify which PMBOK phase this project is currently
 | Phase | Signals |
 |-------|---------|
 | **Discover** | No specs/ yet, or only rough notes |
-| **Design** | specs/SCOPE.md exists but no PLAN.md |
-| **Plan** | specs/TASKS.md or PLAN.md exists; on `main`/`master` branch |
+| **Design** | specs/SCOPE.md exists but no RELEASE-PLAN.md |
+| **Plan** | specs/TASKS.md or RELEASE-PLAN.md exists; on `main`/`master` branch |
 | **Initiate** | On a feature branch; no code changes yet |
-| **Execute** | PLAN.md exists; on feature branch; steps in progress |
-| **Verify** | All implementation steps for a story/epic are done; awaiting UAT |
-| **Bug** | DIAGNOSIS.md exists; on `main`/`master` |
+| **Execute** | RELEASE-PLAN.md exists; on feature branch; steps in progress |
+| **Verify** | Implementation done; run `verify-work` or `run-evals`; awaiting UAT |
+| **Bug** | `specs/bugs/BUG-*.md` exists; on `main`/`master` |
 | **Review** | All code written; no PR yet |
 | **Integrate** | PR open; tests passing |
 | **Sustain** | Ongoing; no active task |
@@ -70,12 +70,13 @@ Based on the phase and state, recommend the most useful next step:
 - **If in Plan/Bug phase and on `main`**: Suggest `kickoff-branch` next.
 - **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan`.
 - **If in Execute phase**: Suggest `develop-tdd` (continue step X) or `execute-plan`.
+- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals` (capability evals).
 
 Example:
 ```
 Phase: Plan
 Active branch: main
-PLAN.md: exists
+RELEASE-PLAN.md: exists
 
 Suggested next: kickoff-branch (to create feature/auth branch)
 ```
@@ -86,8 +87,8 @@ Be specific — name the exact skill and why. If multiple options exist, list th
 
 If something looks wrong:
 - Broken tests in the baseline
-- DIAGNOSIS.md open with no active fix branch
-- PLAN.md with missing verify commands
+- `specs/bugs/BUG-*.md` open with no active fix branch
+- RELEASE-PLAN.md with missing verify commands or Verification Script sections
 - CONVENTIONS.md violations in recent commits
 
 Report blockers first, before recommendations.

package/terse-mode/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: terse-mode
+model: haiku
 description: Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use ONLY when context is critically long and compressing output is necessary to continue. Not a strategy — token discipline comes from code shape (small functions, unique names, headless tests), not terser prompts. Use when user says "caveman mode", "terse mode", "less tokens", "be brief", or invokes /terse-mode.
 ---
 

package/trace-requirement/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: trace-requirement
+model: haiku
 description: Link story IDs from specs/RELEASE-PLAN.md to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
 ---
 

package/using-bigpowers/SKILL.md

@@ -1,11 +1,23 @@
 ---
 name: using-bigpowers
+model: sonnet
 description: One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks "where do I start?", or when the skills system needs to be explained.
 ---
 
 # Using bigpowers
 
-Welcome to **bigpowers** — a lifecycle of 37 agent skills for production-ready, TDD-driven software by solo developers.
+Welcome to **bigpowers** — a lifecycle of **58** agent skills for production-ready, TDD-driven software by solo developers.
+
+## Install
+
+```bash
+npx bigpowers                  # one-shot setup
+npm install -g bigpowers       # global install, then run: bigpowers
+```
+
+From source (contributors): `git clone` → `npm install` or `bash scripts/install.sh`.
+
+Package: [bigpowers on npm](https://www.npmjs.com/package/bigpowers)
 
 ## What bigpowers is
 
@@ -16,7 +28,7 @@ A curated set of skills organized around the PMBOK developer lifecycle. Each ski
 ```
 BOOTSTRAP   using-bigpowers (this skill, first time only)
               ↓
-DISCOVER    survey-context → elaborate-spec
+DISCOVER    survey-context → research-first → elaborate-spec
               ↓
 DESIGN      model-domain / define-language / grill-me / deepen-architecture / design-interface
               ↓
@@ -28,6 +40,8 @@ SPIKE?      spike-prototype → (feeds back to plan-work)
               ↓
 EXECUTE     develop-tdd + enforce-first ←→ delegate-task / dispatch-agents / execute-plan
               ↓
+VERIFY      run-evals → verify-work
+              ↓
 HARDEN      wire-observability (any phase)
               ↓
 BUG?        investigate-bug → diagnose-root → validate-fix
@@ -52,13 +66,25 @@ UTILITY     terse-mode / craft-skill / edit-document (any phase)
 | Bug to fix | `investigate-bug` |
 | Code ready for review | `audit-code` |
 | Shipping a feature | `commit-message` → `release-branch` |
+| Solo dev, PRs feel heavy | Enable `profiles/solo-git.md` → `specs/WORKFLOW-solo-git.md` → land via `scripts/land-branch.sh` |
+
+## Solo Git profile
+
+If you work alone and do not want PR ceremony every task:
+
+1. Read [profiles/solo-git.md](../profiles/solo-git.md).
+2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`.
+3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`.
+
+You still use worktrees, protected `main`, and verification gates — only the integrate step changes.
 
 ## Key conventions
 
 - **specs/ is your memory.** All domain docs, plans, and investigation outputs go in `specs/` at your project root.
-- **`gh` for PRs only.** Never create GitHub issues from skills — use local Markdown files instead.
+- **Integrate:** team default is `gh pr` (team-pr); solo profile uses `land-branch.sh`. Never create GitHub issues from skills — use local Markdown files instead.
 - **One skill, one thing.** If you're unsure which skill to call, call `survey-context` — it reads your current state and recommends the next step.
-- **verify: every step.** Every task in `specs/PLAN.md` must have a `verify: <runnable command>`. Evidence over claims.
+- **verify: every step.** Every task in `specs/RELEASE-PLAN.md` must have a `verify: <runnable command>`. Evidence over claims.
+- **58 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
 
 ## After this
 

package/validate-fix/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: validate-fix
+model: haiku
 description: Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says "is this fixed?", or before closing an investigation.
 ---
 
@@ -58,9 +59,9 @@ For every bug fixed, add at least one prevention layer:
 - [ ] At least one hardening mechanism added
 - [ ] Hardening mechanism is tested
 
-### 6. Update specs/DIAGNOSIS.md
+### 6. Update the bug file and BUG-LOG.md
 
-If a `specs/DIAGNOSIS.md` exists for this bug, append the resolution:
+Find the most recent `specs/bugs/BUG-*.md` file and append the resolution:
 
 ```markdown
 ## Resolution
@@ -73,14 +74,17 @@ If a `specs/DIAGNOSIS.md` exists for this bug, append the resolution:
 **Commit:** `fix(<scope>): <description>`
 ```
 
-- [ ] specs/DIAGNOSIS.md updated with resolution
+Also update the corresponding row in `specs/bugs/BUG-LOG.md`: set `status` to `fixed`, fill in `files_changed`, `approach`, `risk_level`, `commit_message`, and any other resolution fields.
+
+- [ ] specs/bugs/BUG-*.md updated with resolution
+- [ ] specs/bugs/BUG-LOG.md row updated with resolution fields
 
 ### 7. Behavioral Proof (HARD GATE)
 
 Mechanical verification (tests passing) is only half the fix. You must prove **behavioral correctness**.
 
 - [ ] Manually demonstrate the fixed behavior (e.g., via `run_shell_command` or `web_fetch`)
-- [ ] Compare the output/state against the "Expected Behavior" in `specs/DIAGNOSIS.md`
+- [ ] Compare the output/state against the "Expected Behavior" in the bug file
 - [ ] Show the user evidence of the behavior, not just the test logs
 
 ## Rules
@@ -88,6 +92,6 @@ Mechanical verification (tests passing) is only half the fix. You must prove **b
 - **Loop until behavioral correctness is verified**: if any checklist item fails, or if the behavior is still incorrect despite passing tests, return to step 1 and run all checks again from the top — do not declare done until every item is green and the behavior is proven correct in a single run.
 - **Never use `@ts-ignore`, `as any`, or `// eslint-disable`** to "fix" a bug — these suppress the symptom without fixing the root cause
 - **Never mark the task done if any test is still failing**
-- **The verify command from specs/DIAGNOSIS.md or specs/PLAN.md must pass**
+- **The verify command from specs/bugs/BUG-*.md or specs/PLAN.md must pass**
 
 Suggest next skill: `audit-code` → `commit-message`.

package/verify-work/REFERENCE.md

@@ -0,0 +1,23 @@
+# Verify Work — Reference
+
+## Cold-start smoke
+
+```bash
+# Example — adapt to project CLAUDE.md
+pkill -f "<dev-server>" 2>/dev/null || true
+rm -rf .next/cache node_modules/.cache 2>/dev/null || true
+<run command> &
+sleep 3 && curl -sf http://localhost:<port>/health || echo "BOOT FAIL"
+```
+
+## Gaps template
+
+```markdown
+## Gaps (verify-work)
+
+| Step | Expected | Actual | Status |
+|------|----------|--------|--------|
+| 1 | ... | ... | FAIL |
+```
+
+Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work.

package/verify-work/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: verify-work
+description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code, when a story needs proof it works.
+model: haiku
+---
+
+# Verify Work
+
+> **HARD GATE** — No story is "done" until its `## Verification Script` from RELEASE-PLAN.md is confirmed by the user or agent with evidence.
+
+> **HARD GATE** — Do NOT run verify-work on `main` or `master`. Run from the feature branch or worktree created by `kickoff-branch`.
+
+Review answers "is the code good?"; Verify answers "does the built thing do what was promised?"
+
+## Process
+
+0. **Branch check** (before any gates):
+
+```bash
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+# Must not be main or master — run kickoff-branch first
+```
+
+1. Read the story's `## Verification Script` from `specs/RELEASE-PLAN.md`.
+2. **Cold-start smoke** (if app): stop server, clear caches, boot from scratch.
+3. Run mechanical gates: build → typecheck → lint → full test suite (commands from CLAUDE.md).
+4. **Step-by-step UAT**: one user-observable action at a time; record pass/fail.
+5. **Gaps loop**: failed steps → log as Gaps → feed back to `plan-work` → re-verify until pass.
+
+## UAT dialogue
+
+- Pass: user confirms `yes` / `next` / `ok` per step.
+- Fail: capture expected vs actual; do not mark story done.
+
+## Verify
+
+→ verify: `grep -c "Verification Script" specs/RELEASE-PLAN.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+
+See [REFERENCE.md](REFERENCE.md) for cold-start and gaps template.

package/visual-dashboard/SKILL.md

@@ -1,12 +1,62 @@
 ---
 name: visual-dashboard
-description: Start a browser-based dashboard that visualizes architecture, implementation plans, and project status. Use when showing complex diagrams, progress roadmaps, or UI mockups would be clearer than text. Persists artifacts in .bigpowers/dashboard/.
+model: sonnet
+description: Start a browser-based dashboard that visualizes architecture, implementation plans, and project status. Use when showing complex diagrams, progress roadmaps, or UI mockups would be clearer than text. Persists artifacts in .bigpowers/dashboard/. Also maintains specs/STATE.md and specs/RELEASE-PLAN.md in the correct format for the opencode progress panel.
 ---
 
 # Visual Dashboard
 
 Browser-based visual companion for bigpowers. Visualizes architecture, plans, and status.
 
+## Opencode Progress Panel
+
+Projects using bigpowers in opencode get a **live progress panel** (right sidebar) that reads `specs/STATE.md` and `specs/RELEASE-PLAN.md` directly. Toggle it with the document icon (⬚) in the opencode session header.
+
+### Spec file format requirements
+
+**`specs/STATE.md`** — the parser extracts:
+- Project name from `# Session State: <name>`
+- Milestone from `## Current Milestone` → first `**bold**` = name, `(parens)` = status
+- Pending items from `## Pending` → `- [ ]` / `- [x]` lines
+
+```markdown
+# Session State: my-project
+
+## Current Milestone
+
+**v1.0.0 — Feature Name** (in progress)
+
+## Pending
+
+- [ ] Remaining task
+- [x] Completed task
+```
+
+**`specs/RELEASE-PLAN.md`** — the parser extracts:
+- Workstreams from `### WSN — Title · WSJF N.N` headings
+- Steps from `- [ ]` / `- [x]` lines inside each workstream block
+
+```markdown
+## Workstreams (WSJF order)
+
+### WS1 — Feature Area · WSJF 4.5
+
+- [x] Step already done
+- [ ] Step pending
+
+→ verify: `<command>`
+```
+
+**Parser rules:**
+- Only `[ ]` and `[x]`/`[X]` are recognised as step markers.
+- `→ verify:` lines are ignored.
+- Steps outside a `### WSN —` block are not picked up.
+- Missing `## Current Milestone` → panel shows "No specs found".
+
+After completing a step, update the checkbox in-place; the panel auto-refreshes every 30 s or on manual ↺.
+
+---
+
 ## When to Use
 
 Use when the user would understand the project state better by seeing it than reading it.

package/wire-observability/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: wire-observability
+model: sonnet
 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.
 ---
 

package/write-document/REFERENCE.md

@@ -0,0 +1,166 @@
+# 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.