{"id":50805176,"url":"https://github.com/danielvm-git/bigpowers","last_synced_at":"2026-07-04T02:02:16.602Z","repository":{"id":353669443,"uuid":"1220384784","full_name":"danielvm-git/bigpowers","owner":"danielvm-git","description":"70 agent skills for spec-driven, test-first software development by solo developers","archived":false,"fork":false,"pushed_at":"2026-06-27T00:46:07.000Z","size":5001,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T02:18:31.509Z","etag":null,"topics":["ai-agents","automation","bmad","claude-code","clean-code","cursor-rules","devops","documentation-as-code","gemini-cli","productivity","software-engineering","solo-developer","spec-driven-development","tdd"],"latest_commit_sha":null,"homepage":"https://github.com/danielvm-git/bigpowers","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielvm-git.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit-code/HEURISTICS.md","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-24T21:03:16.000Z","updated_at":"2026-06-27T00:46:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danielvm-git/bigpowers","commit_stats":null,"previous_names":["danielvm-git/skills","danielvm-git/bigpowers"],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/danielvm-git/bigpowers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielvm-git%2Fbigpowers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielvm-git%2Fbigpowers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielvm-git%2Fbigpowers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielvm-git%2Fbigpowers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielvm-git","download_url":"https://codeload.github.com/danielvm-git/bigpowers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielvm-git%2Fbigpowers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35107463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","bmad","claude-code","clean-code","cursor-rules","devops","documentation-as-code","gemini-cli","productivity","software-engineering","solo-developer","spec-driven-development","tdd"],"created_at":"2026-06-13T00:05:44.009Z","updated_at":"2026-07-04T02:02:16.590Z","avatar_url":"https://github.com/danielvm-git.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bigpowers — Best-in-Class Agentic Skills\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![npm version](https://img.shields.io/npm/v/bigpowers.svg)\n![Skills](https://img.shields.io/badge/skills-73-brightgreen.svg)\n\n**Agent skills synthesizing 17 years of software engineering discipline — from Clean Code to AI-native architecture — into a single, prescriptive methodology for solo developers.**\n\n`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.\n\nIt 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.\n\nPublished 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).\n\n---\n\n## 🗺 How to Read This README\n\nThis README is a guided path, not a wall of reference. Start where you are:\n\n| You want to… | Go to |\n|:---|:---|\n| Try it in 30 seconds | [Quick Start](#-quick-start) |\n| Understand what it actually does | [Features](#-features) and [The v2.0.0 Lifecycle](#-the-v200-lifecycle) |\n| Learn the ideas behind it | [Philosophical Stack](#-philosophical-stack--how-these-ideas-concatenate) |\n| Look something up | [Hierarchy of Truth](#-hierarchy-of-truth) and [Project Structure](#-project-structure) |\n| Wire it into pi or MCP | [pi Support](#-pi-support) and [MCP Server](#-mcp-server-model-context-protocol) |\n| Contribute or hack on it | [Development](#-development) and [Contributing](#-contributing) |\n\nAfter 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.\n\n---\n\n## 🚀 Quick Start\n\n### npm (recommended)\n\n```bash\n# Global install (no lifecycle scripts — npm v10+ safe)\nnpm install -g bigpowers\nbigpowers setup     # runs sync + install, links skills to your tools\n\n# Or one-shot with npx\nnpx bigpowers setup\n```\n\nBoth commands sync skill artifacts and link them to Claude Code, Gemini CLI, and Cursor (see [Prerequisites](#-prerequisites)).\n\n### From source (contributors)\n\n```bash\ngit clone https://github.com/danielvm-git/bigpowers.git \u0026\u0026 cd bigpowers\nnpm install\nbash scripts/install.sh\n```\n\n---\n\n## 🛠 Prerequisites\n\n- **Bash**: Required for all scripts.\n- **Node.js**: v14+ (required for npm/npx).\n- **jq**: (Highly Recommended) Used for robust configuration of tool settings.\n- **AI Tools**: One or more of:\n  - [Claude Code](https://claude.ai/code)\n  - [Gemini CLI](https://github.com/google/gemini-cli)\n  - [Cursor](https://cursor.sh/)\n  - [pi](https://pi.dev/) — coding agent harness\n\n---\n\n## ✨ Features\n\n- **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.\n- **Spec-Driven Cockpit**: Uses `specs/state.yaml` and `release-plan.yaml` to maintain state across agent sessions, preventing context drift.\n- **Native IDE Support**: Automatically generates configurations for Cursor (`.cursor/rules`), Gemini CLI, and pi.\n- **Model Context Protocol (MCP)**: Dynamic tool discovery and invocation via the included MCP server.\n- **Built-in Quality Gates**: Strict verification standards (e.g., F.I.R.S.T tests, BCP accounting) enforced before any code is merged.\n\n---\n\n## 🏗 The v2.0.0 Lifecycle\n\nEvery project follows the **orchestrate-project 6-phase model** (full SOP: [`docs/WORKFLOW-SOP-v2.md`](docs/WORKFLOW-SOP-v2.md)):\n\n```\nONE TIME    seed-conventions  (CLAUDE.md, .claude/, .gemini/, agents/, skill sync)\n              ↓\nONCE/PROJECT orchestrate-project\n              │\n              ├─ Ph1 DISCOVER   survey-context, research-first, elaborate-spec\n              ├─ Ph2 ELABORATE  model-domain, grill-me, define-language, deepen-architecture\n              ├─ Ph3 PLAN       scope-work, slice-tasks, plan-work → release-plan.yaml (BCP baseline)\n              ├─ Ph4 BUILD      build-epic × N stories\n              │\n              │  Per story — 8-step build-epic cycle:\n              │   1. survey-context   ← stamps story_start in state.yaml\n              │   2. plan-work        ← [BCP N] tasks + verify: commands\n              │   3. kickoff-branch   ← worktree + feature branch\n              │   4. develop-tdd      ← RED → GREEN → REFACTOR\n              │   5. verify-work      ← UAT gate\n              │   6. audit-code       ← quality gate ≥ 94%\n              │   7. commit-message   ← Conventional Commits + semver\n              │   8. release-branch   ← land to main; writes story_end + cycle-times.yaml\n              │\n              ├─ Ph5 VERIFY     run-evals, verify-work (project-level)\n              └─ Ph6 RELEASE    semantic-release → v1.0.0 MVP tag\n```\n\n**Semver:** projects start at `0.0.0-β`; each `feat:` story → minor bump; developer declares MVP → `1.0.0`.\n\n**BCP accounting:** every task labeled `[BCP N]`; story total in `state.yaml`; BCP/hr logged to `specs/metrics/cycle-times.yaml`.\n\n**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.\n\n---\n\n## 🧠 Philosophical Stack — How These Ideas Concatenate\n\n`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.\n\n![Philosophy Diagram](docs/images/philosophy_diagram.jpg)\n\n| Era | Source | Contribution | Tension Resolved |\n|:---|:---|:---|:---|\n| **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) |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n\n### How to see the concatenation in action\n\nEach philosophical pillar has a corresponding Gherkin `.feature` file in [`specs/verifications/features/`](specs/verifications/features/) that empirically proves compliance:\n\n| Pillar | Verification |\n|:---|:---|\n| Classical Craftsmanship | `cleancode.feature` |\n| Complexity Management | `pocock.feature` |\n| Behavioral Integrity | `karpathy.feature` |\n| Spec-Driven Development | Implicit in SDD workflow |\n| Agentic Standard | `akita.feature` |\n| Project Conventions | `conventions.feature` |\n| Original Baseline | `superpowers.feature` |\n\nRun `npm run compliance` to audit all features. Score \u003c 94% = hard stop.\n\n---\n\n## 📖 Hierarchy of Truth\n\n| Level | Document | Responsibility |\n| :--- | :--- | :--- |\n| **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |\n| **Context** | `specs/tech-architecture/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |\n| **Scope** | `specs/product/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |\n| **Vision** | `specs/product/VISION_LATEST.yaml` | North star and initiative success criteria. |\n| **Decisions** | `specs/adr/` | Architectural Decision Records (irreversible choices). |\n| **Roadmap** | `specs/release-plan.yaml` + `specs/epics/` | WSJF-prioritized epics and stories with BCP baseline. |\n| **Current** | `specs/state.yaml` | Session flow, active epic, `handoff.next_skill`, timestamps. |\n| **Metrics** | `specs/metrics/cycle-times.yaml` | Per-story BCPs, cycle minutes, BCP/hr (v2.0.0). |\n| **Index** | `SKILL-INDEX.md` | Canonical list of all active skills (auto-generated). |\n| **Style** | `CONVENTIONS.md` | Coding, testing, and naming standards. |\n\n---\n\n## 📁 Project Structure\n\n- `skills/[skill-name]/`: Source files for each of the 72 skills.\n- `scripts/`: Installation, syncing, and compliance tools.\n- `specs/`: YAML cockpit — `state.yaml`, `release-plan.yaml`, `epics/`, `execution-status.yaml`, `requirements/`.\n- `specs/metrics/`: Cycle-time ledger (`cycle-times.yaml`) — per-story BCPs, timestamps, BCP/hr (v2.0.0).\n- `dashboard/`: Live monitoring tool — TUI (`npm run dashboard`) and web (`npm run dashboard:web`, port 7742).\n- `docs/`: Guides including `WORKFLOW-SOP-v2.md` (full SDLC SOP) and `using-bigpowers.md`.\n- `docs/references/`: Theoretical foundations (Uncle Bob, Ousterhout, Karpathy, etc.).\n\n---\n\n## 🔌 pi Support\n\nbigpowers generates pi Agent Skills and prompt templates alongside Cursor and Gemini artifacts via `sync-skills.sh`.\n\n### Install as a pi package\n\n```bash\n# Clone and sync to generate pi artifacts\ncd bigpowers\nbash scripts/sync-skills.sh\n\n# Install from local path as a pi package\npi install .\n\n# Or install as a pi npm package (once published with pi-package keyword)\npi install npm:bigpowers\n```\n\n**What you get:**\n- **pi skills** in `.pi/skills/` (one per SKILL.md) — loaded automatically into pi's system prompt as `\u003cavailable_skills\u003e`\n- **pi prompt templates** in `.pi/prompts/` — slash commands like `/survey-context`, `/plan-work`\n- **pi package manifest** in `.pi/package.json` — enables `pi install` with auto-discovery\n\nSkills 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.\n\n## 🔧 MCP Server (Model Context Protocol)\n\nbigpowers **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.\n\n### Start the server\n\n```bash\nnode scripts/mcp-server.js\n```\n\n### Add to Claude Code\n\n```bash\nclaude mcp add bigpowers node /path/to/bigpowers/scripts/mcp-server.js\n```\n\nOr add manually to `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"bigpowers\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/bigpowers/scripts/mcp-server.js\"]\n    }\n  }\n}\n```\n\n### Available MCP tools\n\n| Tool | Description |\n|------|-------------|\n| `bigpowers_list_skills` | List all skills with name, description, phase. Optional `phase` filter. |\n| `bigpowers_get_skill` | Get full SKILL.md content for any skill by name. |\n| `bigpowers_search_skills` | Keyword/semantic search — returns ranked matches for a query. |\n| `bigpowers_get_state` | Get current `specs/state.yaml` (active flow, epic, step). |\n| `bigpowers_invoke_skill` | Get skill instructions with optional context for agent invocation. |\n\n---\n\n## 🔄 Maintenance (Update \u0026 Uninstall)\n\n### Update\n\n**npm install:**\n\n```bash\nnpm update -g bigpowers\nbigpowers update   # re-sync and refresh symlinks\n```\n\n**git clone:**\n\n```bash\ngit pull\nnpm run sync\nbash scripts/install.sh\n```\n\n*Install uses symlinks — re-running setup refreshes links without duplicating files.*\n\n### Uninstall\n\n**npm install:**\n\n```bash\nbash \"$(npm root -g)/bigpowers/scripts/install.sh\" --uninstall\nnpm uninstall -g bigpowers\n```\n\n**git clone:**\n\n```bash\nbash scripts/install.sh --uninstall\n```\n\n### Reinstall\n\n```bash\nnpx bigpowers setup\n# or, if installed globally:\nbigpowers setup\n```\n\n---\n\n## 🧪 Development\n\n```bash\ngit clone https://github.com/danielvm-git/bigpowers.git\ncd bigpowers\nnpm install\n# Sync artifacts from SKILL.md sources\nnpm run sync\n```\n\n### Tests\n\n```bash\n# Run compliance verification against Gherkin features\nnpm run compliance\n\n# Validate YAML specifications and doctrine\nnpm run doctrine\nnpm run validate-specs\n```\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repo.\n2. Create a feature branch (`git checkout -b feature/my-thing`).\n3. Make your changes using the `bigpowers` methodology.\n4. Commit using Conventional Commits (`git commit -am 'feat: add my thing'`).\n5. Push to the branch (`git push origin feature/my-thing`).\n6. Open a Pull Request.\n\n### Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the auto-generated commit history, or [Releases](https://github.com/danielvm-git/bigpowers/releases) for GitHub release notes.\n\nFor 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).\n\n### Links\n\n- **Repository**: https://github.com/danielvm-git/bigpowers\n- **Issue Tracker**: https://github.com/danielvm-git/bigpowers/issues\n\n---\n\n## 🙏 Acknowledgements\n\nThis 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:\n\n- **Robert C. Martin (Uncle Bob)** for establishing the baseline of code hygiene and the F.I.R.S.T principles in *Clean Code*.\n- **John Ousterhout** for his paradigm-shifting views on Deep Modules and complexity management in *A Philosophy of Software Design*.\n- **Andrej Karpathy** and **Matt Pocock** for their pioneering work on agentic skills and structuring context for LLMs.\n- **Jarek Wasowski** for identifying Spec-Driven Development (SDD) as the missing link for AI agents.\n- **AkitaOnRails** for adapting classical clean code principles to the reality of the AI token economy.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n*“Simplicity is the ultimate sophistication, but integrity is the ultimate requirement.”*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielvm-git%2Fbigpowers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielvm-git%2Fbigpowers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielvm-git%2Fbigpowers/lists"}