Getting Started

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.

This README is a guided path, not a wall of reference. Start where you are:

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.

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

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.

git clone https://github.com/danielvm-git/bigpowers.git && cd bigpowers
npm install
bash scripts/install.sh

• 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

• 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.

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.

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.

Each philosophical pillar has a corresponding Gherkin .feature file in specs/verifications/features/ that empirically proves compliance:

Run npm run compliance to audit all features. Score < 94% = hard stop.

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

bigpowers generates pi Agent Skills and prompt templates alongside Cursor and Gemini artifacts via sync-skills.sh.

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

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.

node scripts/mcp-server.js

claude mcp add bigpowers node /path/to/bigpowers/scripts/mcp-server.js

Or add manually to .claude/settings.json:

{
  "mcpServers": {
    "bigpowers": {
      "command": "node",
      "args": ["/path/to/bigpowers/scripts/mcp-server.js"]
    }
  }
}

npm install:

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:

git pull
npm run sync
bash scripts/install.sh

Install uses symlinks — re-running setup refreshes links without duplicating files.

npm install:

bash "$(npm root -g)/bigpowers/scripts/install.sh" --uninstall
npm uninstall -g bigpowers

git clone:

bash scripts/install.sh --uninstall

npx bigpowers@latest setup
# or, if installed globally:
bigpowers update

git clone https://github.com/danielvm-git/bigpowers.git
cd bigpowers
npm install
# Sync artifacts from SKILL.md sources
npm run sync

# Run compliance verification against Gherkin features
npm run compliance

# Validate YAML specifications and doctrine
npm run doctrine
npm run validate-specs

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.

See CHANGELOG.md for the auto-generated commit history, or 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.

• Repository: https://github.com/danielvm-git/bigpowers
• Issue Tracker: https://github.com/danielvm-git/bigpowers/issues

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.

This project is licensed under the MIT License - see the LICENSE file for details.

“Simplicity is the ultimate sophistication, but integrity is the ultimate requirement.”