bigpowers

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-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 (Clean Code)	SRP, Boy Scout Rule, F.I.R.S.T. tests, intention-revealing names	— (foundation)
2018	Ousterhout (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, Superpowers, Pocock	Think-first planning, verb-noun skill architecture, zoom-out strategy	Raw LLMs have no discipline — they need orchestration, not raw prompting
2024	Wasowski (SDD), BCP	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 (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/ 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

# 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