bigpowers 2.43.5 → 2.44.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.43.5",
+  "version": "2.44.0",
   "description": "72 skills — 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/.pi/prompts/using-bigpowers.md

@@ -98,7 +98,7 @@ Start the HTTP dashboard with `visual-dashboard` → `GET /api/status?projectDir
 - **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 epic task must have `verify: <runnable command>`. Evidence over claims.
-- **70 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+- **The full catalog is auto-generated.** See `SKILL-INDEX.md`; find skills with `search-skills`.
 
 ## After this
 

package/.pi/skills/using-bigpowers/SKILL.md

@@ -100,7 +100,7 @@ Start the HTTP dashboard with `visual-dashboard` → `GET /api/status?projectDir
 - **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 epic task must have `verify: <runnable command>`. Evidence over claims.
-- **70 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+- **The full catalog is auto-generated.** See `SKILL-INDEX.md`; find skills with `search-skills`.
 
 ## After this
 

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.44.0](https://github.com/danielvm-git/bigpowers/compare/v2.43.5...v2.44.0) (2026-07-02)
+
+
+### Features
+
+* **repo:** move 72 skill sources to skills/ directory ([89ab1d9](https://github.com/danielvm-git/bigpowers/commit/89ab1d9d588bcac74b7186b7bd8170c3c4df8242))
+
 ## [2.43.5](https://github.com/danielvm-git/bigpowers/compare/v2.43.4...v2.43.5) (2026-07-02)
 
 

package/CLAUDE.md

@@ -4,7 +4,7 @@ Read CONVENTIONS.md before any GitHub or git operation.
 
 ## Project
 
-bigpowers — 61 agent skills for spec-driven, test-first software development by solo developers.
+bigpowers — agent skills for spec-driven, test-first software development by solo developers (skill count and catalog are auto-generated in `SKILL-INDEX.md`; never hardcode the count in docs).
 Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
 
 ## Commands
@@ -21,11 +21,11 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 
 ## Architecture
 
-Collection of 61 verb-noun skills, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
+Collection of verb-noun skills under `skills/`, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
 
 ## Conventions
 
-- Skill directories use verb-noun naming (two words, kebab-case)
+- Skill directories under `skills/` use verb-noun naming (two words, kebab-case)
 - Every skill has a single SKILL.md file as its source of truth
 - All planning/spec output goes to specs/ at project root
 - Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts

package/CONTRIBUTING.md

@@ -85,7 +85,7 @@ npm run sync
 
 ```
 bigpowers/
-├── [skill-name]/       # Each skill has its own directory with SKILL.md
+├── skills/[skill-name]/  # Each skill has its own directory with SKILL.md
 ├── scripts/            # Install, sync, validation, and compliance scripts
 ├── specs/              # YAML cockpit — state.yaml, release-plan.yaml, epics/
 ├── docs/               # Guides and references

package/CONVENTIONS.md

@@ -202,7 +202,7 @@ The agent implements defensive code only for categories explicitly listed here.
 
 ## Skill Naming — Conventions and Exceptions
 
-All skill directories use a two-word `verb-noun` kebab-case pair (ADR-0001). Grep for any skill
+All skill directories under `skills/` use a two-word `verb-noun` kebab-case pair (ADR-0001). Grep for any skill
 name must return < 5 results across the repo.
 
 **Documented exceptions** (adjective-noun retained for clarity; renaming would reduce usability):
@@ -212,5 +212,6 @@ name must return < 5 results across the repo.
 | `terse-mode` | adjective-noun | `enable-terse` implies a toggle; `terse-mode` names a mode state |
 | `visual-dashboard` | adjective-noun | `view-dashboard` implies read-only; `show-dashboard` collides with `show` verbs |
 | `deploy` | single verb | Well-known DevOps single-word concept; renames like `deploy-app` or `deploy-service` are redundant since deploy always targets an application |
+| `grill-with-docs` | three-word verb-prep-noun | Variant of `grill-me`; the `-with-docs` suffix is the distinguishing feature — collapsing it would hide the doc-grounded contract |
 
 Any new exception requires an entry in this table before the skill is published.

package/README.md

@@ -1,108 +1,121 @@
-# bigpowers
+# bigpowers — Best-in-Class Agentic Skills
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![npm version](https://img.shields.io/npm/v/bigpowers.svg)
+![Skills](https://img.shields.io/badge/skills-72-brightgreen.svg)
 
-![npm version](https://img.shields.io/badge/npm-v2.43.2-blue.svg)
+**Agent skills synthesizing 17 years of software engineering discipline — from Clean Code to AI-native architecture — into a single, prescriptive methodology for solo developers.**
 
-![Skills](https://img.shields.io/badge/skills-72-brightgreen.svg)
+`bigpowers` provides a prescriptive, vertical-slice methodology for building software with AI agents (Claude Code, Gemini CLI, Cursor, pi). It bridges the gap between raw LLM capabilities and professional engineering standards.
+
+It is not a random collection of best practices. It is a chronological layer cake of ideas — each wave of thinking (Uncle Bob → Ousterhout → Karpathy → Wasowski → Akita) builds on and resolves tensions from the last, culminating in a 6-phase lifecycle with hard gates, a 94% quality threshold, and a YAML cockpit (`specs/state.yaml`) that keeps both human and agent aligned across sessions.
+
+Published on npm: [bigpowers](https://www.npmjs.com/package/bigpowers). The skill count in the badge above is stamped automatically by `sync-skills.sh`; the canonical catalog is [`SKILL-INDEX.md`](SKILL-INDEX.md).
+
+---
+
+## 🗺 How to Read This README
 
-> 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers.
+This README is a guided path, not a wall of reference. Start where you are:
 
-`bigpowers` is not a random collection of best practices. It is a highly opinionated, chronological layer cake of ideas, combining classical software craftsmanship with modern AI-native architecture. 
+| You want to… | Go to |
+|:---|:---|
+| Try it in 30 seconds | [Quick Start](#-quick-start) |
+| Understand what it actually does | [Features](#-features) and [The v2.0.0 Lifecycle](#-the-v200-lifecycle) |
+| Learn the ideas behind it | [Philosophical Stack](#-philosophical-stack--how-these-ideas-concatenate) |
+| Look something up | [Hierarchy of Truth](#-hierarchy-of-truth) and [Project Structure](#-project-structure) |
+| Wire it into pi or MCP | [pi Support](#-pi-support) and [MCP Server](#-mcp-server-model-context-protocol) |
+| Contribute or hack on it | [Development](#-development) and [Contributing](#-contributing) |
 
-It provides a 6-phase lifecycle with hard gates, a 94% quality threshold, and a YAML cockpit (`specs/state.yaml`) that keeps both human and AI agents perfectly aligned across complex software projects. By enforcing strict boundaries and verifiable outcomes, it allows solo developers to orchestrate multi-agent workflows with predictable, high-quality results.
+After installing, ask your agent to run the `using-bigpowers` skill — it is the one-time bootstrap that explains the lifecycle and tells you which skill to call first for your situation.
 
-## Prerequisites
+---
 
-- **Runtime**: Node.js v14+
-- **Environment**: Bash (required for all internal scripts)
-- **Tooling**: jq (highly recommended for configuration)
-- **AI Tools**: Claude Code, Gemini CLI, Cursor, or pi
+## 🚀 Quick Start
 
-## Installation
+### npm (recommended)
 
 ```bash
-# One-shot setup: downloads, syncs artifacts, and links skills
+# One-shot setup — downloads, syncs artifacts, and links skills to your tools
 npx bigpowers
 
-# Or install globally
+# Or install globally and run the setup command anytime
 npm install -g bigpowers
 bigpowers
 ```
 
-## Usage
+Both commands sync skill artifacts and link them to Claude Code, Gemini CLI, and Cursor (see [Prerequisites](#-prerequisites)).
+
+### From source (contributors)
 
 ```bash
-# Update and re-sync your local skills
-npm update -g bigpowers
-bigpowers
+git clone https://github.com/danielvm-git/bigpowers.git && cd bigpowers
+npm install          # runs postinstall: sync + link
+# or manually:
+bash scripts/install.sh
+npm run sync
 ```
 
-For deep usage, integrate the generated skills directly into your favorite AI tool (Claude Code, Gemini CLI, Cursor). Use the provided MCP Server to expose skills dynamically:
+---
 
-```bash
-node scripts/mcp-server.js
-```
+## 🛠 Prerequisites
+
+- **Bash**: Required for all scripts.
+- **Node.js**: v14+ (required for npm/npx).
+- **jq**: (Highly Recommended) Used for robust configuration of tool settings.
+- **AI Tools**: One or more of:
+  - [Claude Code](https://claude.ai/code)
+  - [Gemini CLI](https://github.com/google/gemini-cli)
+  - [Cursor](https://cursor.sh/)
+  - [pi](https://pi.dev/) — coding agent harness
 
-## Features
+---
 
-- **72 Purpose-Built Skills**: From `survey-context` to `develop-tdd`, each skill is a targeted tool for a specific phase of development.
+## ✨ Features
+
+- **Purpose-Built Skills**: From `survey-context` to `develop-tdd`, each skill is a targeted tool for a specific phase of development. See [`SKILL-INDEX.md`](SKILL-INDEX.md) for the full auto-generated catalog.
 - **Spec-Driven Cockpit**: Uses `specs/state.yaml` and `release-plan.yaml` to maintain state across agent sessions, preventing context drift.
 - **Native IDE Support**: Automatically generates configurations for Cursor (`.cursor/rules`), Gemini CLI, and pi.
 - **Model Context Protocol (MCP)**: Dynamic tool discovery and invocation via the included MCP server.
 - **Built-in Quality Gates**: Strict verification standards (e.g., F.I.R.S.T tests, BCP accounting) enforced before any code is merged.
 
-🏗 The v2.0.0 Lifecycle
+---
 
-Every project follows the orchestrate-project 6-phase model (full SOP: docs/[WORKFLOW-SOP-v2.md](http://WORKFLOW-SOP-v2.md)):
+## 🏗 The v2.0.0 Lifecycle
 
-ONE TIME    seed-conventions  ([CLAUDE.md](http://CLAUDE.md), .claude/, .gemini/, agents/, skill sync)
+Every project follows the **orchestrate-project 6-phase model** (full SOP: [`docs/WORKFLOW-SOP-v2.md`](docs/WORKFLOW-SOP-v2.md)):
 
+```
+ONE TIME    seed-conventions  (CLAUDE.md, .claude/, .gemini/, agents/, skill sync)
               ↓
-
 ONCE/PROJECT orchestrate-project
-
               │
-
               ├─ Ph1 DISCOVER   survey-context, research-first, elaborate-spec
-
               ├─ Ph2 ELABORATE  model-domain, grill-me, define-language, deepen-architecture
-
               ├─ Ph3 PLAN       scope-work, slice-tasks, plan-work → release-plan.yaml (BCP baseline)
-
               ├─ Ph4 BUILD      build-epic × N stories
-
               │
-
               │  Per story — 8-step build-epic cycle:
-
               │   1. survey-context   ← stamps story_start in state.yaml
-
               │   2. plan-work        ← [BCP N] tasks + verify: commands
-
               │   3. kickoff-branch   ← worktree + feature branch
-
               │   4. develop-tdd      ← RED → GREEN → REFACTOR
-
               │   5. verify-work      ← UAT gate
-
               │   6. audit-code       ← quality gate ≥ 94%
-
               │   7. commit-message   ← Conventional Commits + semver
-
               │   8. release-branch   ← land to main; writes story_end + cycle-times.yaml
-
               │
-
               ├─ Ph5 VERIFY     run-evals, verify-work (project-level)
-
               └─ Ph6 RELEASE    semantic-release → v1.0.0 MVP tag
+```
 
-Semver: projects start at 0.0.0-β; each feat: story → minor bump; developer declares MVP → 1.0.0.
+**Semver:** projects start at `0.0.0-β`; each `feat:` story → minor bump; developer declares MVP → `1.0.0`.
 
-BCP accounting: every task labeled [BCP N]; story total in state.yaml; BCP/hr logged to specs/metrics/cycle-times.yaml.
+**BCP accounting:** every task labeled `[BCP N]`; story total in `state.yaml`; BCP/hr logged to `specs/metrics/cycle-times.yaml`.
 
-next_skill signaling: each critical-path skill writes [handoff.next](http://handoff.next)_skill to state.yaml. Call survey-context after any interruption to resume exactly where you left off.
+**next_skill signaling:** each critical-path skill writes `handoff.next_skill` to `state.yaml`. Call `survey-context` after any interruption to resume exactly where you left off.
+
+---
 
 ## 🧠 Philosophical Stack — How These Ideas Concatenate
 
@@ -110,96 +123,174 @@ next_skill signaling: each critical-path skill writes [handoff.next](http://hand
 
 ![Philosophy Diagram](docs/images/philosophy_diagram.jpg)
 
-
-| Era           | Source                                                                                                                                                                                               | Contribution                                                                       | Tension Resolved                                                                 |
-| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
-| **2008**      | [Uncle Bob](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) (Clean Code)                                                                                            | SRP, Boy Scout Rule, F.I.R.S.T. tests, intention-revealing names                   | — (foundation)                                                                   |
-| **2018**      | [Ousterhout](https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201) (*A Philosophy of Software Design*)                                                                    | Deep modules, information hiding, define errors out of existence                   | Small functions alone create shallow modules with bloated interfaces             |
-| **2023–24**   | [Karpathy](https://github.com/multica-ai/andrej-karpathy-skills), [Superpowers](https://github.com/obra/superpowers), [Pocock](https://github.com/mattpocock/skills)                                 | Think-first planning, verb-noun skill architecture, zoom-out strategy              | Raw LLMs have no discipline — they need orchestration, not raw prompting         |
-| **2024**      | [Wasowski](https://medium.com/@wasowski.jarek/sdd-writing-specifications-for-ai-bdd-as-the-missing-link-spec-driven-development-ad1b540b7f75) (SDD), [BCP](https://github.com/flow-ciandt/bcp-agent) | Specs as the human-agent interface; business complexity as a pre-build sizing unit | Agents drift without a verifiable spec — BDD Gherkin closes the loop             |
-| **2026**      | [Akita](https://akitaonrails.com/2026/04/20/clean-code-para-agentes-de-ia/) (*Clean Code for AI Agents*)                                                                                             | Grep-ability, structured JSON logging, token economy, remediation hints in errors  | Uncle Bob's rules were written for humans — agents need different code hygiene   |
-| **Synthesis** | BMAD + GSD (self-authored)                                                                                                                                                                           | 6-phase lifecycle, hard gates, 94% quality threshold, `specs/state.yaml` cockpit   | All the above are principles; bigpowers turns them into an executable discipline |
-
+| Era | Source | Contribution | Tension Resolved |
+|:---|:---|:---|:---|
+| **2008** | [Uncle Bob](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) (Clean Code) | SRP, Boy Scout Rule, F.I.R.S.T. tests, intention-revealing names | — (foundation) |
+| **2018** | [Ousterhout](https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201) (*A Philosophy of Software Design*) | Deep modules, information hiding, define errors out of existence | Small functions alone create shallow modules with bloated interfaces |
+| **2023–24** | [Karpathy](https://github.com/multica-ai/andrej-karpathy-skills), [Superpowers](https://github.com/obra/superpowers), [Pocock](https://github.com/mattpocock/skills) | Think-first planning, verb-noun skill architecture, zoom-out strategy | Raw LLMs have no discipline — they need orchestration, not raw prompting |
+| **2024** | [Wasowski](https://medium.com/@wasowski.jarek/sdd-writing-specifications-for-ai-bdd-as-the-missing-link-spec-driven-development-ad1b540b7f75) (SDD), [BCP](https://github.com/flow-ciandt/bcp-agent) | Specs as the human-agent interface; business complexity as a pre-build sizing unit | Agents drift without a verifiable spec — BDD Gherkin closes the loop |
+| **2026** | [Akita](https://akitaonrails.com/2026/04/20/clean-code-para-agentes-de-ia/) (*Clean Code for AI Agents*) | Grep-ability, structured JSON logging, token economy, remediation hints in errors | Uncle Bob's rules were written for humans — agents need different code hygiene |
+| **Synthesis** | BMAD + GSD (self-authored) | 6-phase lifecycle, hard gates, 94% quality threshold, `specs/state.yaml` cockpit | All the above are principles; bigpowers turns them into an executable discipline |
 
 ### How to see the concatenation in action
 
 Each philosophical pillar has a corresponding Gherkin `.feature` file in [`specs/verifications/features/`](specs/verifications/features/) that empirically proves compliance:
 
-
-| Pillar                  | Verification             |
-| :----------------------- | :------------------------ |
-| Classical Craftsmanship | `cleancode.feature`      |
-| Complexity Management   | `pocock.feature`         |
-| Behavioral Integrity    | `karpathy.feature`       |
+| Pillar | Verification |
+|:---|:---|
+| Classical Craftsmanship | `cleancode.feature` |
+| Complexity Management | `pocock.feature` |
+| Behavioral Integrity | `karpathy.feature` |
 | Spec-Driven Development | Implicit in SDD workflow |
-| Agentic Standard        | `akita.feature`          |
-| Project Conventions     | `conventions.feature`    |
-| Original Baseline       | `superpowers.feature`    |
+| Agentic Standard | `akita.feature` |
+| Project Conventions | `conventions.feature` |
+| Original Baseline | `superpowers.feature` |
+
+Run `npm run compliance` to audit all features. Score < 94% = hard stop.
+
+---
+
+## 📖 Hierarchy of Truth
+
+| Level | Document | Responsibility |
+| :--- | :--- | :--- |
+| **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |
+| **Context** | `specs/tech-architecture/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |
+| **Scope** | `specs/product/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |
+| **Vision** | `specs/product/VISION_LATEST.yaml` | North star and initiative success criteria. |
+| **Decisions** | `specs/adr/` | Architectural Decision Records (irreversible choices). |
+| **Roadmap** | `specs/release-plan.yaml` + `specs/epics/` | WSJF-prioritized epics and stories with BCP baseline. |
+| **Current** | `specs/state.yaml` | Session flow, active epic, `handoff.next_skill`, timestamps. |
+| **Metrics** | `specs/metrics/cycle-times.yaml` | Per-story BCPs, cycle minutes, BCP/hr (v2.0.0). |
+| **Index** | `SKILL-INDEX.md` | Canonical list of all active skills (auto-generated). |
+| **Style** | `CONVENTIONS.md` | Coding, testing, and naming standards. |
 
+---
 
-Run `npm run compliance` to audit all features. Score &lt; 94% = hard stop.
+## 📁 Project Structure
 
+- `skills/[skill-name]/`: Source files for each of the 72 skills.
+- `scripts/`: Installation, syncing, and compliance tools.
+- `specs/`: YAML cockpit — `state.yaml`, `release-plan.yaml`, `epics/`, `execution-status.yaml`, `requirements/`.
+- `specs/metrics/`: Cycle-time ledger (`cycle-times.yaml`) — per-story BCPs, timestamps, BCP/hr (v2.0.0).
+- `dashboard/`: Live monitoring tool — TUI (`npm run dashboard`) and web (`npm run dashboard:web`, port 7742).
+- `docs/`: Guides including `WORKFLOW-SOP-v2.md` (full SDLC SOP) and `using-bigpowers.md`.
+- `docs/references/`: Theoretical foundations (Uncle Bob, Ousterhout, Karpathy, etc.).
 
+---
 
-🔧 MCP Server (Model Context Protocol)
+## 🔌 pi Support
 
-bigpowers ships an MCP server that exposes all skills as callable MCP tools. Agents can discover and invoke skills dynamically instead of relying on a static system prompt.
+bigpowers generates pi Agent Skills and prompt templates alongside Cursor and Gemini artifacts via `sync-skills.sh`.
 
-Start the server
+### Install as a pi package
 
+```bash
+# Clone and sync to generate pi artifacts
+cd bigpowers
+bash scripts/sync-skills.sh
+
+# Install from local path as a pi package
+pi install .
+
+# Or install as a pi npm package (once published with pi-package keyword)
+pi install npm:bigpowers
+```
+
+**What you get:**
+- **pi skills** in `.pi/skills/` (one per SKILL.md) — loaded automatically into pi's system prompt as `<available_skills>`
+- **pi prompt templates** in `.pi/prompts/` — slash commands like `/survey-context`, `/plan-work`
+- **pi package manifest** in `.pi/package.json` — enables `pi install` with auto-discovery
+
+Skills are loaded on-demand via progressive disclosure: only descriptions are always in context; the full SKILL.md loads when the agent reads it. Prompt templates expand in pi's editor with autocomplete.
+
+## 🔧 MCP Server (Model Context Protocol)
+
+bigpowers **includes** an MCP server (`scripts/mcp-server.js`) that exposes the skill catalog as callable MCP tools, so agents can discover and invoke skills dynamically instead of relying on a static system prompt. It is not active until you register it with your agent — see below.
+
+### Start the server
+
+```bash
 node scripts/mcp-server.js
+```
 
-Add to Claude Code
+### Add to Claude Code
 
+```bash
 claude mcp add bigpowers node /path/to/bigpowers/scripts/mcp-server.js
+```
 
-Or add manually to .claude/settings.json:
+Or add manually to `.claude/settings.json`:
 
+```json
 {
-
   "mcpServers": {
-
     "bigpowers": {
-
       "command": "node",
-
       "args": ["/path/to/bigpowers/scripts/mcp-server.js"]
-
     }
-
   }
-
 }
+```
 
-Available MCP tools
+### Available MCP tools
 
-Tool	Description
+| Tool | Description |
+|------|-------------|
+| `bigpowers_list_skills` | List all skills with name, description, phase. Optional `phase` filter. |
+| `bigpowers_get_skill` | Get full SKILL.md content for any skill by name. |
+| `bigpowers_search_skills` | Keyword/semantic search — returns ranked matches for a query. |
+| `bigpowers_get_state` | Get current `specs/state.yaml` (active flow, epic, step). |
+| `bigpowers_invoke_skill` | Get skill instructions with optional context for agent invocation. |
 
-bigpowers_list_skills	List all 70 skills with name, description, phase. Optional phase filter.
+---
 
-bigpowers_get_skill	Get full [SKILL.md](http://SKILL.md) content for any skill by name.
+## 🔄 Maintenance (Update & Uninstall)
 
-bigpowers_search_skills	Keyword/semantic search — returns ranked matches for a query.
+### Update
 
-bigpowers_get_state	Get current specs/state.yaml (active flow, epic, step).
+**npm install:**
 
-bigpowers_invoke_skill	Get skill instructions with optional context for agent invocation.
+```bash
+npm update -g bigpowers
+bigpowers    # re-sync and refresh symlinks
+```
 
-Tool	Description
+**git clone:**
 
-bigpowers_list_skills	List all 72 skills with name, description, phase. Optional phase filter.
+```bash
+git pull
+npm run sync
+```
+
+*Install uses symlinks — re-running setup refreshes links without duplicating files.*
+
+### Uninstall
 
-bigpowers_get_skill	Get full [SKILL.md](http://SKILL.md) content for any skill by name.
+**npm install:**
+
+```bash
+bash "$(npm root -g)/bigpowers/scripts/install.sh" --uninstall
+npm uninstall -g bigpowers
+```
 
-bigpowers_search_skills	Keyword/semantic search — returns ranked matches for a query.
+**git clone:**
 
-bigpowers_get_state	Get current specs/state.yaml (active flow, epic, step).
+```bash
+bash scripts/install.sh --uninstall
+```
 
-bigpowers_invoke_skill	Get skill instructions with optional context for agent invocation.
+### Reinstall
 
+```bash
+npx bigpowers
+# or, if installed globally:
+bigpowers
+```
 
+---
 
-## Development
+## 🧪 Development
 
 ```bash
 git clone https://github.com/danielvm-git/bigpowers.git
@@ -209,7 +300,7 @@ npm install
 npm run sync
 ```
 
-## Tests
+### Tests
 
 ```bash
 # Run compliance verification against Gherkin features
@@ -220,7 +311,9 @@ npm run doctrine
 npm run validate-specs
 ```
 
-## Contributing
+---
+
+## 🤝 Contributing
 
 1. Fork the repo.
 2. Create a feature branch (`git checkout -b feature/my-thing`).
@@ -229,16 +322,18 @@ npm run validate-specs
 5. Push to the branch (`git push origin feature/my-thing`).
 6. Open a Pull Request.
 
-## Changelog
+### Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/danielvm-git/bigpowers/releases).
 
-## Links
+### Links
+
+- **Repository**: https://github.com/danielvm-git/bigpowers
+- **Issue Tracker**: https://github.com/danielvm-git/bigpowers/issues
 
-- **Repository**: [https://github.com/danielvm-git/bigpowers](https://github.com/danielvm-git/bigpowers)
-- **Issue Tracker**: [https://github.com/danielvm-git/bigpowers/issues](https://github.com/danielvm-git/bigpowers/issues)
+---
 
-## Acknowledgements
+## 🙏 Acknowledgements
 
 This project is a synthesis of decades of software engineering thought. It would not be possible without the foundational work of the authors who wrote the inspirational articles and books that shaped this methodology:
 
@@ -248,6 +343,11 @@ This project is a synthesis of decades of software engineering thought. It would
 - **Jarek Wasowski** for identifying Spec-Driven Development (SDD) as the missing link for AI agents.
 - **AkitaOnRails** for adapting classical clean code principles to the reality of the AI token economy.
 
-## License
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-MIT — see [LICENSE](LICENSE) for details.
+---
+*“Simplicity is the ultimate sophistication, but integrity is the ultimate requirement.”*

package/SKILL-INDEX.md

@@ -3,7 +3,6 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-07-02T16:00:53Z
 **Skills:** 72
 
 ---
@@ -160,5 +159,5 @@ All skills follow `verb-noun` kebab-case (ADR-0001). Documented exceptions:
 1. Run `bash scripts/sync-skills.sh` to regenerate this file and all artifacts.
 2. Or run `bash scripts/generate-skill-index.sh` to only regenerate this index.
 
-→ verify: `find . -maxdepth 2 -name "SKILL.md" | grep -v ".git\|.cursor\|.gemini" | wc -l`
+→ verify: `find . skills -maxdepth 2 -name "SKILL.md" 2>/dev/null | grep -v ".git\|.cursor\|.gemini\|.pi" | sort -u | wc -l`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.43.5",
+  "version": "2.44.0",
   "description": "72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/add-model-frontmatter.sh

@@ -2,6 +2,9 @@
 # add-model-frontmatter.sh — one-time helper; idempotent model: injection
 set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# SKILLS_ROOT: use skills/ when it exists, fall back to repo root
+SKILLS_ROOT="$REPO_ROOT"
+[[ -d "$REPO_ROOT/skills" ]] && SKILLS_ROOT="$REPO_ROOT/skills"
 
 # Bash 3.2-compatible model mapping (no declare -A)
 get_model() {
@@ -12,7 +15,7 @@ get_model() {
   esac
 }
 
-for skill_dir in "$REPO_ROOT"/*/; do
+for skill_dir in "$SKILLS_ROOT"/*/; do
   skill_md="$skill_dir/SKILL.md"
   [[ -f "$skill_md" ]] || continue
   name=$(basename "$skill_dir")

package/scripts/audit-catalog.sh

@@ -7,21 +7,24 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 cd "$REPO_ROOT"
+# SKILLS_ROOT: use skills/ when it exists, fall back to repo root
+SKILLS_ROOT="$REPO_ROOT"
+[[ -d "$REPO_ROOT/skills" ]] && SKILLS_ROOT="$REPO_ROOT/skills"
 
 ORPHANS=()
 MISSING=()
 
-# Check: every .pi/skills/<name>/ dir must have a matching <name>/SKILL.md source
+# Check: every .pi/skills/<name>/ dir must have a matching source SKILL.md
 for d in .pi/skills/*/; do
   name=$(basename "$d")
-  if [ ! -f "$name/SKILL.md" ]; then
+  if [ ! -f "$SKILLS_ROOT/$name/SKILL.md" ]; then
     ORPHANS+=("$name")
   fi
 done
 
-# Check: every root-level SKILL.md dir must have a matching .pi/skills/<name>/SKILL.md
-for f in ./*/SKILL.md; do
-  name=$(echo "$f" | cut -d/ -f2)
+# Check: every SKILLS_ROOT SKILL.md dir must have a matching .pi/skills/<name>/SKILL.md
+for f in "$SKILLS_ROOT"/*/SKILL.md; do
+  name=$(basename "$(dirname "$f")")
   # Skip non-skill directories
   case "$name" in
     docs|node_modules|scripts|specs|dashboard|test) continue ;;
@@ -33,8 +36,8 @@ done
 
 PI_COUNT=$(ls -d .pi/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
 SRC_COUNT=0
-for f in ./*/SKILL.md; do
-  name=$(echo "$f" | cut -d/ -f2)
+for f in "$SKILLS_ROOT"/*/SKILL.md; do
+  name=$(basename "$(dirname "$f")")
   case "$name" in
     docs|node_modules|scripts|specs|dashboard|test) continue ;;
   esac