Back to skills
bigpowers
by danielvm-git
CursorโNot yet rated
Your rating
Brief
Agent skills synthesizing years of software engineering discipline into a prescriptive methodology for solo developers
Description
# bigpowers โ Best-in-Class Agentic Skills
[](https://github.com/danielvm-git/bigpowers/actions/workflows/test-build-release.yml)



**Agent skills synthesizing 17 years of software engineering discipline โ from Clean Code to AI-native architecture โ into a single, prescriptive methodology for solo developers.**
`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).
Docs: [bigpowers docs site](https://danielvm-git.github.io/bigpowers/) โ searchable, Google-discoverable reference for all skills, guides, and ADRs.
**This methodology publishes its own evidence โ see the [live receipts page](https://danielvm-git.github.io/bigpowers/receipts/).**
**See it working:** [bigpowers-showcase](https://github.com/danielvm-git/bigpowers-showcase) โ a real URL shortener (CLI + SQLite) built from scratch with the full spec trail committed from day one.
---
## Build status
[](https://github.com/danielvm-git/bigpowers/actions/workflows/test-build-release.yml)
Every gate (compliance, the deterministic golden suite, skill verify, story verify) runs in
one pipeline; release and the Pages deploy start only after that pipeline succeeds on `main`.
## Tech stack
| Layer | What it uses |
|---|---|
| Content | Markdown skills (`skills/*/SKILL.md`), YAML specs (`specs/`) |
| Tooling | Bash scripts, Node.js 22, Python 3 (YAML/JSON tooling) |
| Distribution | npm package, Agent Skills renders, MCP server |
| CI/CD | GitHub Actions โ gates โ release โ Pages, one pipeline |
## ๐บ How to Read This README
This README is a guided path, not a wall of reference. Start where you are:
| 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) |
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.
---
## ๐ Quick Start
### npm (recommended)
```bash
# Global install (no lifecycle scripts โ npm v10+ safe)
npm install -g bigpowers@latest
bigpowers setup # runs sync + install, links skills to your tools
# Or one-shot with npx (always fetches the newest release)
npx bigpowers@latest setup
```
Both commands sync skill artifacts and link them to Claude Code, Gemini CLI, and Cursor (see [Prerequisites](#-prerequisites)).
> **Always pin `@latest`.** With bigpowers already installed globally, a bare `npx bigpowers setup` reuses the stale global binary and `npm update -g bigpowers` doesn't reliably cross to the newest release. `npm install -g bigpowers@latest` and `npx bigpowers@latest setup` force a registry fetch every time.
### Interactive Installer
The `npx bigpowers setup` command launches an interactive menu where you can:
1. **Choose install mode**: Setup/Update or Uninstall
2. **Select location**: Global (available everywhere) or Local (current project only)
3. **Pick tools**: Select which AI tools to install skills for (Claude Code, Cursor, Gemini, pi, etc.)
4. **Confirm**: Review and confirm the installation
Use **arrow keys** to navigate, **space** to select, and **Enter** to confirm.

*Screenshot from an earlier release; the current installer may differ.*
### From source (contributors)
```bash
git clone https://github.com/danielvm-git/bigpowers.git && cd bigpowers
npm install
bash scripts/install.sh
```
---
## ๐ 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
- **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`](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`.
**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_skill` to `state.yaml`. Call `survey-context` after any interruption to resume exactly where you left off.
---
## ๐ง Philosophical Stack โ How These Ideas Concatenate
`bigpowers` is not a flat list of influences. It is a **chronological layer cake** โ each wave of thinking builds on and resolves tensions from the previous one. No layer replaces the last; each addresses a problem the prior one created.

| 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` |
| Spec-Driven Development | Implicit in SDD workflow |
| 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. |
---
## ๐ Project Structure
- `skills/[skill-name]/`: Source files for each of the 80 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.).
---
## ๐ pi Support
bigpowers generates pi Agent Skills and prompt templates alongside Cursor and Gemini artifacts via `sync-skills.sh`.
### 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
```
### Provision a consumer project (`bigpowers init`)
pi's package contract registers **skills and prompts only** โ it has no resource
type for arbitrary project files, and no lifecycle script runs on install. Skills
reference the package's `scripts/*.sh` tooling project-relative (e.g.
`bash scripts/run-skill-verify.sh`, verify gates like `test -f scripts/... &&
test -d specs/bugs`), so after installing the package, run **one command per
consumer project** to provision what the skills expect:
```bash
cd <your-project>
npx bigpowers init # or: bigpowers init
```
This symlinks `<project>/scripts` โ the installed package's `scripts/` tree and
scaffolds `specs/bugs/` + `specs/verifications/`. It refuses (never clobbers) a
`scripts/` you already own; `bigpowers init --remove` undoes it. The same step
applies to `npm i -g bigpowers` / `npx bigpowers setup` consumers.
**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
```bash
claude mcp add bigpowers node /path/to/bigpowers/scripts/mcp-server.js
```
Or add manually to `.claude/settings.json`:
```json
{
"mcpServers": {
"bigpowers": {
"command": "node",
"args": ["/path/to/bigpowers/scripts/mcp-server.js"]
}
}
}
```
### Available MCP tools
| 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. |
---
## ๐ Maintenance (Update & Uninstall)
### Update
**npm install:**
```bash
bigpowers update # fetches bigpowers@latest (global installs), then re-syncs + refreshes symlinks
```
`bigpowers update` now runs `npm install -g bigpowers@latest` for you when bigpowers is installed globally, so running it alone is enough to reach the newest release. Prefer to do it by hand? `npm install -g bigpowers@latest && bigpowers update`. (Avoid `npm update -g bigpowers` โ it does not reliably cross to `@latest`.)
**git clone:**
```bash
git pull
npm run sync
bash scripts/install.sh
```
**pi package** (installed via `~/.pi/agent/settings.json` โ `packages`):
```bash
pi update --extensions # refresh installed pi packages, including bigpowers
```
*Install uses symlinks โ re-running setup refreshes links without duplicating files.*
### Uninstall
**npm install:**
```bash
bash "$(npm root -g)/bigpowers/scripts/install.sh" --uninstall
npm uninstall -g bigpowers
```
**git clone:**
```bash
bash scripts/install.sh --uninstall
```
### Reinstall
```bash
npx bigpowers@latest setup
# or, if installed globally:
bigpowers update
```
---
## ๐งช Development
```bash
git clone https://github.com/danielvm-git/bigpowers.git
cd bigpowers
npm install
# Sync artifacts from SKILL.md sources
npm run sync
```
### Preflight
One command runs every gate before you push โ compliance, the deterministic golden
suite, skill sync, and the strict traceability check:
```bash
npm run compliance \
&& bash scripts/run-verification-gates.sh \
&& bash scripts/sync-skills.sh \
&& bash scripts/trace-stories.sh --strict
```
Preflight is the gate, not a suggestion: a red Preflight means forward work stops
until it is green or the defect is logged (see `CONVENTIONS.md` ยง Always Green).
### Tests
```bash
# Run compliance verification against Gherkin features
npm run compliance
# Validate YAML specifications and doctrine
npm run doctrine
npm run validate-specs
```
---
## ๐ค Contributing
1. Fork the repo.
2. Create a feature branch (`git checkout -b feature/my-thing`).
3. Make your changes using the `bigpowers` methodology.
4. Commit using Conventional Commits (`git commit -am 'feat: add my thing'`).
5. Push to the branch (`git push origin feature/my-thing`).
6. Open a Pull Request.
### Changelog
See [CHANGELOG.md](CHANGELOG.md) for the auto-generated commit history, or [Releases](https://github.com/danielvm-git/bigpowers/releases) for GitHub release notes.
For an executive narrative of the project's history โ 98 releases across 41 days, 4 phases, 19 epics delivered โ read [RELEASE-HISTORY.md](docs/RELEASE-HISTORY.md).
### Links
- **Repository**: https://github.com/danielvm-git/bigpowers
- **Issue Tracker**: https://github.com/danielvm-git/bigpowers/issues
---
## ๐ 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:
- **Robert C. Martin (Uncle Bob)** for establishing the baseline of code hygiene and the F.I.R.S.T principles in *Clean Code*.
- **John Ousterhout** for his paradigm-shifting views on Deep Modules and complexity management in *A Philosophy of Software Design*.
- **Andrej Karpathy** and **Matt Pocock** for their pioneering work on agentic skills and structuring context for LLMs.
- **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.
### Community Contributors
bigpowers has been shaped by contributors who extended it in their own forks.
See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the full list.
- **[Kevin Oberlies (favilo)](https://github.com/favilo/bigpowers)** โ Jujutsu VCS support across lifecycle skills + `project-runtime.sh` configurable settings library.
- **[XcluEzy7](https://github.com/XcluEzy7/bigpowers)** โ OMP plugin extension (`extensions/omp-hooks.ts`): native skill discovery, unified skill tooling, and git-safety hooks for the oh-my-pi runtime.
---
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
*โSimplicity is the ultimate sophistication, but integrity is the ultimate requirement.โ*
Installation
Install the skill from https://github.com/danielvm-git/bigpowersThis skill is not published on the ClawHub registry. Paste the prompt into your coding agent โ Claude Code, Cursor, Codex โ and it will install the skill straight from the source repository.
Open the repository