bigpowers — Best-in-Class Agentic Skills

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. The skill count in the badge above is stamped automatically by sync-skills.sh; the canonical catalog is SKILL-INDEX.md.

Docs: bigpowers docs site — searchable, Google-discoverable reference for all skills, guides, and ADRs.

This methodology publishes its own evidence — see the live receipts page.

See it working: bigpowers-showcase — a real URL shortener (CLI + SQLite) built from scratch with the full spec trail committed from day one.

---

🗺 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
Understand what it actually does	Features and The v2.0.0 Lifecycle
Learn the ideas behind it	Philosophical Stack
Look something up	Hierarchy of Truth and Project Structure
Wire it into pi or MCP	pi Support and MCP Server
Contribute or hack on it	Development and 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)

# 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).

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.

From source (contributors)

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
  • Gemini CLI
  • Cursor
  • pi — 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 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):

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-wo