{
  "markdown": "<p align=\"center\"><strong>English</strong> · <a href=\"README.zh-CN.md\">中文</a></p>\n\n<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"beads-superpowers - Process discipline and persistent memory for AI coding agents\" width=\"100%\" />\n</p>\n\n<p align=\"center\">\n  <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-blue.svg\"></a>\n  <a href=\"https://github.com/DollarDill/beads-superpowers/releases/latest\"><img alt=\"Latest release\" src=\"https://img.shields.io/github/v/release/DollarDill/beads-superpowers?color=4f46e5\"></a>\n  <a href=\"https://github.com/DollarDill/beads-superpowers/stargazers\"><img alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/DollarDill/beads-superpowers?style=social\"></a>\n  <a href=\"CONTRIBUTING.md\"><img alt=\"PRs welcome\" src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\"></a>\n  <a href=\"https://algocents.com/beads-superpowers/\"><img alt=\"Docs\" src=\"https://img.shields.io/badge/docs-algocents.com-0ea5e9.svg\"></a>\n</p>\n\n---\n\nA plugin for Claude Code, Codex, OpenCode, and 7 more AI coding agents that makes your agent write tests before code, debug systematically instead of guessing, and remember what it worked on yesterday. Composable skills enforce the practices; a Dolt-backed issue tracker keeps context across sessions.\n\n## Quickstart\n\nThe fastest path - Claude Code with native plugin install:\n\n```bash\nbrew install beads                    # 1. Install bd (requires beads v1.1.0+)\n# From your shell:\nclaude plugin marketplace add DollarDill/beads-superpowers\nclaude plugin install beads-superpowers@beads-superpowers-marketplace\n# Or, inside a Claude Code session:\n# /plugin marketplace add DollarDill/beads-superpowers\n# /plugin install beads-superpowers@beads-superpowers-marketplace\n# Then in your project directory:\nbd init                               # 2. Bootstrap the Dolt database for this project\n```\n\nStart a new Claude Code session and type \"where are we\" - the agent will load your `bd` context and pick up where you left off.\n\nUsing a different agent? Jump to install for [Codex CLI](#codex-cli), [OpenCode](#opencode), [Cursor](#cursor), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [Antigravity](#antigravity), [Factory Droid](#factory-droid), or [Pi](#pi).\n\n## The Basic Workflow\n\n1. **research-driven-development** - When the task needs understanding first: parallel research agents investigate and write a verified knowledge-base document before any design happens.\n\n2. **brainstorming** - Refines the idea through one-question-at-a-time design dialogue, checks prior decisions in the knowledge store, and ends with a spec you approved - tracked in `bd` so it survives the session.\n\n3. **stress-test** - Adversarially interrogates the approved spec branch by branch (offered at every spec review), so flaws surface before planning.\n\n4. **writing-plans** - Turns the spec into bite-sized tasks with exact files, code, and verification steps. Every task becomes a `bd` bead.\n\n5. **stress-test** (again) - The same adversarial pass against the plan itself: task boundaries, parallel-safety, failure modes.\n\n6. **subagent-driven-development** or **executing-plans** - Dispatches a fresh subagent per task, each in its own isolated worktree (implementers follow **test-driven-development**), or executes in batches with human checkpoints.\n\n7. **requesting-code-review** - Task-level and whole-branch reviews against the plan. Critical findings block progress.\n\n8. **verification-before-completion** - Nothing is called done without a command that proves it - evidence gates every close.\n\n9. **document-release** - Audits the project docs against what actually shipped, before the branch merges.\n\n10. **finishing-a-development-branch** - Presents merge/PR options and lands the plane: close the beads, sync, push.\n\nThe agent checks for relevant skills before any task - these are mandatory workflows, not suggestions. And because every task, decision, and lesson lives in `bd`'s Dolt database, the next session starts where this one ended: type \"where are we\" and the agent picks the thread back up.\n\n## What's Inside\n\n<!-- Curation rule: every distributed skill appears here except using-superpowers - the session bootstrap, which upstream's README also leaves out. The full reference lives on the docs site. -->\n\n### Testing\n\n| Skill | What it does |\n|-------|-------------|\n| `test-driven-development` | RED-GREEN-REFACTOR loop - Iron Law: no implementation without a failing test |\n\n### Debugging\n\n| Skill | What it does |\n|-------|-------------|\n| `systematic-debugging` | 4-phase root-cause analysis before proposing any fix |\n| `verification-before-completion` | Evidence before claims - nothing is \"done\" until a command proved it |\n\n### Design & planning\n\n| Skill | What it does |\n|-------|-------------|\n| `brainstorming` | Socratic design session before any code - produces an approved spec |\n| `stress-test` | Adversarial interrogation of designs and plans, with recommended answers |\n| `writing-plans` | Bite-sized task plans - every task tracked as a `bd` bead |\n\n### Execution\n\n| Skill | What it does |\n|-------|-------------|\n| `subagent-driven-development` | Fresh agent per task with spec + quality review; parallel batch mode |\n| `executing-plans` | Batch plan execution in a single session with checkpoints |\n| `dispatching-parallel-agents` | Fans out 2+ independent tasks to parallel agents with no shared state |\n| `using-git-worktrees` | Isolated development branches per feature |\n| `requesting-code-review` | Dispatches a code-reviewer subagent with structured criteria |\n| `receiving-code-review` | Verifies review feedback against the code before implementing it - no reflexive agreement |\n| `finishing-a-development-branch` | Merge/PR flow + land the plane (close beads, sync, push) |\n\n### Documentation\n\n| Skill | What it does |\n|-------|-------------|\n| `write-documentation` | 14-rule writing system for human-facing prose - READMEs, guides, release notes |\n| `document-release` | Post-ship documentation audit - keeps the docs matching what actually shipped |\n\n### Memory & orientation\n\n| Skill | What it does |\n|-------|-------------|\n| `getting-up-to-speed` | Session orientation - loads `bd` context and produces a current-state summary |\n| `memory-curator` | Consolidates, deduplicates, and prunes the persistent memory store |\n| `session-handoff` | Writes a grounded handoff doc so the next session resumes mid-flight work |\n| `research-driven-development` | Parallel research agents → verified, persistent knowledge base |\n| `project-init` | Sets up, bootstraps, and recovers the beads/Dolt database behind persistent memory |\n\n**[Full skills reference →](https://algocents.com/beads-superpowers/skills/)**\n\n## How it works\n\nWhen you start a task, the agent runs **brainstorming** to nail down requirements before touching code, then **writing-plans** to break the work into `bd`-tracked steps that survive session restarts. During implementation it follows **test-driven-development** (failing test first, always) and can fan out to parallel subagents via **subagent-driven-development** - each agent working in its own git worktree. `bd` stores every task, decision, and note in a local Dolt database, so the agent picks up exactly where it left off next session without relying on chat history.\n\nUnderneath all of it is a production-grade standard: the agent treats every task as if real users depend on it, so it won't quietly cut a corner, drop a requirement, or weaken a security control to move faster.\n\n## Philosophy\n\n- **Design before code** - every feature starts as a spec a human approved, not a guess\n- **TDD is an Iron Law** - no implementation without a failing test\n- **Systematic over ad-hoc** - debugging follows a root-cause process, never guess-and-check\n- **Evidence before claims** - \"done\" requires a command that proves it\n- **Memory over chat history** - tasks, decisions, and lessons persist in `bd`, not in a scroll buffer\n\nThe long form lives in [Methodology](https://algocents.com/beads-superpowers/methodology/).\n\n## Docs\n\n**[algocents.com/beads-superpowers](https://algocents.com/beads-superpowers/)** - getting started, methodology, skills reference, example workflow, and tips.\n\n- [Example Workflow docs](https://algocents.com/beads-superpowers/workflow/) - Full walkthrough with diagrams\n- [Skills Reference](https://algocents.com/beads-superpowers/skills/) - All skills explained\n- [Methodology](https://algocents.com/beads-superpowers/methodology/) - Why this workflow exists\n\n## Installation\n\n> **⚠️ Coexistence warning:** Do not install alongside [obra/superpowers](https://github.com/obra/superpowers). Skill names collide - pick one or the other.\n\n### Prerequisites\n\n**Install `bd` before the plugin.** Its hooks call `bd` on every session start; without it they fail silently and you lose persistent memory. Use Homebrew (`brew install beads`) or `npm install -g @beads/bd` on any platform. Verify with `bd version`.\n\n**Note:** Native plugin install installs skills and hooks, but not `bd init` - run that yourself per project.\n\n### Claude Code\n\n```bash\nclaude plugin marketplace add DollarDill/beads-superpowers\nclaude plugin install beads-superpowers@beads-superpowers-marketplace\n```\n\nOr as slash commands inside a Claude Code session: `/plugin marketplace add DollarDill/beads-superpowers` then `/plugin install beads-superpowers@beads-superpowers-marketplace`.\n\n### Codex CLI\n\n```bash\ncodex plugin marketplace add DollarDill/beads-superpowers\ncodex plugin install beads-superpowers@beads-superpowers-marketplace\n```\n\nAfter installing, enable hooks in `~/.codex/config.toml`:\n\n```toml\n[features]\ncodex_hooks = true\n```\n\nTo get the SessionStart hook under Codex, use the scripted installer (`install.sh`) rather than the plugin channel - the plugin channel installs the skills but does not wire the hook.\n\n### OpenCode\n\nAdd to the `plugin` array in your `opencode.json` (global or project-level):\n\n```json\n{\n  \"plugin\": [\"beads-superpowers@git+https://github.com/DollarDill/beads-superpowers.git\"]\n}\n```\n\nSkills auto-register and the session bootstrap + beads context inject automatically - no other steps. Details, version pinning, migration from pre-0.12 installer copies, and troubleshooting: [.opencode/INSTALL.md](.opencode/INSTALL.md).\n\n### Cursor\n\n```text\n/add-plugin beads-superpowers\n```\n\nRun this command inside Cursor Agent. Update via the Marketplace UI.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/DollarDill/beads-superpowers\n```\n\n### GitHub Copilot CLI\n\n```bash\ncopilot plugin marketplace add DollarDill/beads-superpowers\ncopilot plugin install beads-superpowers@beads-superpowers-marketplace\n```\n\nUpdate:\n\n```bash\ncopilot plugin update beads-superpowers\n```\n\nNote: rides the Claude-plugin fallback (skills + session-start via the shared `hooks/hooks.json`), the same mechanism upstream ships; requires Copilot CLI v1.0.11+ for session-start context injection.\n\n### Kimi Code\n\n```text\n/plugins install https://github.com/DollarDill/beads-superpowers\n```\n\nRun `/new` after install to start a fresh session with the plugin active.\n\n### Antigravity\n\n```bash\nagy plugin install https://github.com/DollarDill/beads-superpowers\n```\n\nNote: reuses the Claude plugin manifest - the same mechanism upstream verified.\n\n### Factory Droid\n\n```bash\ndroid plugin marketplace add https://github.com/DollarDill/beads-superpowers\ndroid plugin install beads-superpowers@beads-superpowers-marketplace\n```\n\nNote: reuses the Claude plugin manifest - the same mechanism upstream verified.\n\n### Pi\n\n```bash\npi install git:github.com/DollarDill/beads-superpowers\n```\n\n### npx (any harness)\n\nInstalls the skills only - no hooks. Skill activation relies on your harness's native skill discovery.\n\n```bash\nnpx skills add DollarDill/beads-superpowers -g --copy -y\n```\n\n### Alternative: scripted install (`curl | bash`)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DollarDill/beads-superpowers/main/install.sh | bash\n```\n\nThe script's role is broader than just copying files. Use it when you need any of:\n\n- **Beads/Dolt bootstrap** - auto-detects whether `bd` is installed and guides setup\n- **Hook registration** - writes the SessionStart entry to settings.json (required when using the install-script path)\n- **`yegge.md` orchestrator** - optional add-on: installed only when you pass `--with-yegge`. The flag forces the scripted tarball/git install tier (the plugin and npx tiers are skipped for that run), so it can't be combined with a plugin-managed install in one command\n- **Version pinning** - `--version X.Y.Z` for reproducible CI installs\n- **CI environments** - use `--yes --skip-checksum` for unattended runs\n\nSupports: `--yes` (skip prompts), `--version X.Y.Z`, `--with-yegge`, `--dry-run`, `--skip-checksum`, `--uninstall`.\n\nUpdates: rerun your install command - plugin channels update via their marketplace, npx and the script by rerunning.\n\n## Contributing\n\nContributions are welcome - see [`CONTRIBUTING.md`](CONTRIBUTING.md). PRs target the **`dev`** branch (`main` is the released branch). Ideas and questions live in [Discussions](https://github.com/DollarDill/beads-superpowers/discussions).\n\n## Built on\n\n- **[Superpowers](https://github.com/obra/superpowers)** by Jesse Vincent - the skill system and development practices\n- **[Beads](https://github.com/gastownhall/beads)** by Steve Yegge - persistent issue tracking with cross-session memory\n\nIndividual skills adapted from:\n\n- **Garry Tan** - `document-release`, adapted from [garrytan/gstack](https://github.com/garrytan/gstack/tree/main/document-release)\n- **Matt Pocock** - `stress-test`, from [skills/grilling](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md); `session-handoff`, from [skills/handoff](https://github.com/mattpocock/skills/blob/main/skills/productivity/handoff/SKILL.md)\n- **Ivan Neustroev (\"Anbeeld\")** - the writing system behind `write-documentation`, adapted from [WRITING.md](https://github.com/Anbeeld/WRITING.md) (MIT)\n\n## License\n\n[MIT](LICENSE)\n\n## Community\n\n- **Ideas & questions:** [GitHub Discussions](https://github.com/DollarDill/beads-superpowers/discussions) - the pinned post is the front door\n- **Bugs:** [Issues](https://github.com/DollarDill/beads-superpowers/issues)\n- **Contact:** <dillon@algocents.com>\n",
  "bytes": 14427,
  "sha": "36f70752ff2ccd50640665d8350b3fb4bee475d9948cd7027392d83a3b2a99d8",
  "repo_slug": "dollardill/beads-superpowers",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_dollardill_beads_superpowers_3e545417/readme"
}