diff --git a/README.md b/README.md index 55588e2..5e6cf3b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@

- Slow-powers + Slow-powers — Agent skills with proven value, built for people who hate skills.

@@ -8,7 +10,7 @@ alt="CI status" /> Latest release + alt="Release version" /> OpenCode plugin on npm @@ -17,171 +19,247 @@ alt="License: MIT" /> evals + alt="Evaluation status" /> skills-ref validation + alt="Agent Skills validation" />

# Slow-powers -Slow-powers is an agent skill set for professional software development. It enhances plan mode and debugging work, enforces best practices, and works _with_ the features of modern agents, instead of replacing them. It's the plugin for people who don't install plugins. +Slow-powers is a focused set of software-development skills for coding agents. It +is for developers who want stronger planning, test-driven development, +root-cause debugging, and final verification without manually steering every +step. -

- The working-with-tdd skill in a coding agent: write a failing test, watch it fail for the right reason, write minimal code — and the test catches a race before it ships. -

- -

- The working-with-tdd skill catching a race before it ships. Terminal themed with Synthpunk Neon Dark. -

- -## About this fork - -Slow-powers is a fork of [obra/superpowers](https://github.com/obra/superpowers). Much of the skill content is sourced from upstream, with rewrites focusing on clarity, token efficiency, and providing a generally lighter touch. - -## Quickstart - -[Claude Code](#claude-code) · [Codex CLI](#codex-cli) · [OpenCode](#opencode) · [Cline](#cline) - -## How it works - -Slow-powers is designed to improve the actual day-to-day work of software developers using agents for anything from focused debugging to generating entire features. It instructs agents to check for skills first, and use the ones that apply. The shipped skills fill real gaps in agentic development, but all discoverable skills benefit from the skill-enforcing guidance. Combined with the provided skill-writing and testing guidance, this allows you to extend your workflow with your own verified-to-be-useful skills. - -### Start in plan mode - -Even small features are developed better with a plan. Slow-powers hardens the plan to catch hallucinations and other mistakes before you review it. During implementation, skills guide the agent through best practices, working in isolation, following test-driven development, and reviewing and verifying its work before it hands it back to you. - -### Debugging - -Slow-powers guides agents through an evidence-backed, no-guess debugging approach. No "It works now!" without proof. There's also special guidance for specific, tricky-to-debug situations, generated from real-world cases. - -### Writing skills - -Skills for writing skills! Slow-powers skills are all written and evaluated following the same guidelines and processes it ships. Back up your own skills with real stats, and understand their cost in time and tokens, so you can develop custom workflows when needed. - -Skill evaluations are powered by [eval-magic](https://github.com/slowdini/eval-magic) +Install it once, then keep talking to your agent normally. Slow-powers works +mostly behind the scenes: it makes the skills available, tells the agent to load +whichever ones fit the task, and prompts the agent to review plans before they +leave plan mode. You can still request a skill by name, but routine work does not +require a separate command vocabulary. ## Installation -### Install with your agent +Slow-powers supports Claude Code, Codex CLI, OpenCode, and the Cline CLI, +software development kit (SDK), and Kanban. + +### Let your agent install it -Open the harness you want Slow-powers on and paste this prompt: +Open the agent you want to use and paste: ```text -Install the slow-powers plugin from https://github.com/slowdini/slow-powers#installation for this harness. +Install the slow-powers plugin for this harness. Follow the instructions at: +https://github.com/slowdini/slow-powers#installation ``` +Prefer to install it yourself? Use the instructions for your harness. + ### Claude Code -``` +Run these commands inside Claude Code: + +```text /plugin marketplace add slowdini/slow-powers -/plugin install slow-powers@slow-powers +/plugin install slow-powers@slowdini ``` -You can also browse and install it interactively: run `claude`, open -`/plugin`, choose the `slowdini` marketplace, and install `slow-powers`. +If the install summary asks you to reload, run `/reload-plugins`. You can also +open `/plugin`, select the `slowdini` marketplace, and install `slow-powers` +interactively. See the +[Claude Code plugin guide](https://code.claude.com/docs/en/discover-plugins) for +installation scopes and plugin management. ### Codex CLI +Add the marketplace and install the plugin: + ```bash codex plugin marketplace add slowdini/slow-powers codex plugin add slow-powers@slowdini ``` -You can also browse and install it interactively: run `codex`, open -`/plugins`, choose the `slowdini` marketplace, and install `slow-powers`. +You can also run `codex`, open `/plugins`, select the `slowdini` marketplace, +and install `slow-powers` interactively. ### OpenCode +Install the npm package globally: + ```bash -opencode plugin @slowdini/slow-powers-opencode -g +opencode plugin @slowdini/slow-powers-opencode --global ``` +This adds the npm package to your global OpenCode configuration. See the +[OpenCode plugin documentation](https://opencode.ai/docs/plugins/) for local and +configuration-file alternatives. + ### Cline +Install the plugin from its Git repository: + ```bash cline plugin install https://github.com/slowdini/slow-powers.git ``` -Cline plugins load in the Cline CLI, SDK, and Kanban — **not** the VSCode or -JetBrains extensions. On those, you can still use the skills by copying or -symlinking `skills/` into `.cline/skills/` (project) or `~/.cline/skills/` -(global); the bootstrap injection and plan gate are CLI/SDK/Kanban-only. +Cline plugins run in the Cline CLI, SDK, and Kanban, but not in the VS Code or +JetBrains extensions. In those extensions, copy or symlink `skills/` into +`.cline/skills/` for one project or `~/.cline/skills/` globally. This makes the +skills available, but the automatic bootstrap and plan-review gate remain +limited to CLI, SDK, and Kanban. See the +[Cline plugin documentation](https://docs.cline.bot/customization/plugins) for +installation scopes and source formats. -## The skills +After installation, start a fresh agent session so the plugin, its skills, and +its startup guidance are loaded. -Slow-powers provides a set of highly focused skills that ensure your agent operates with maximum discipline: +## Usage -1. **`hardening-plans`** — Instructs the agent to re-review any plans before it hands them back to you, looking for hallucinations, logical inconsistencies, and other common plan mistakes. -2. **`investigating-bugs`** — Guides the agent to locate the root cause of failures via scientific hypothesis testing, avoiding "guess-and-check" thrashing. -3. **`working-in-isolation`** — Establishes an isolated workspace (worktree or branch) so new work doesn't collide with existing or in-progress work, keeping protected branches like `main` clean. -4. **`working-with-tdd`** — Enforces a strict RED-GREEN-REFACTOR cycle, ensuring all code is backed by failing test verification first. -5. **`verifying-development-work`** — Requires running actual test/build commands and presenting concrete evidence before any success claim, with a final review pass over the change, code AND comments, before work is handed back. -6. **`writing-skills`** — Helps write and edit skills, following the same best practices that guide slow-powers itself. -7. **`evaluating-skills`** — Teaches the agent how to run skill evals, so the value of skills and prose changes can be objectively assessed. -8. **`writing-technical-docs`** — Guides the agent's technical writing — code comments, PR descriptions, READMEs, design docs — with a scale-sized writing process and evergreen-content rules that keep docs free of session narration. +Use your agent as you did before installing Slow-powers. Ordinary requests are +the intended interface: -## Why trust these skills? +```text +Add rate limiting to the public API and make the change ready for review. +``` -Most skill packs ship on vibes. Every slow-powers skill ships with a documented eval — or it doesn't ship (see [Philosophy](#philosophy)). Each skill is measured against an agent with **no skill**, so the number means "this skill made the agent better," not just "we changed something." +```text +Find out why the pagination test is flaky and fix the root cause. +``` -| Skill | Improvement vs no skill | n | Model | Last measured | -|---|---|---|---|---| -| `hardening-plans` | TBD | TBD | TBD | TBD | -| `investigating-bugs` | TBD | TBD | TBD | TBD | -| `working-with-tdd` | TBD | TBD | TBD | TBD | -| `verifying-development-work` | TBD | TBD | TBD | TBD | +```text +Review this implementation plan before I approve it. +``` -**Improvement vs no skill** is the gain in eval pass-rate (percentage points) when the same [eval-magic](https://github.com/slowdini/eval-magic) suite runs with the skill versus without it. +You do not need to name the relevant skills in these prompts. At the start of a +session, the plugin supplies guidance that requires the agent to check for an +applicable skill before it responds or acts. Each skill can then route the agent +to the next discipline the task needs—for example, from an approved plan to an +isolated workspace, test-driven implementation, and final verification. -## Intended Workflows +Plan mode receives an additional safeguard. When the agent is about to present +a plan, the harness integration gives it a dedicated chance to run +`hardening-plans`, catch missing requirements or invented file references, and +revise the plan before you review it. -The skills declare prerequisite / next-step gates so the agent follows an intended skill sequence. These gates **suggest** what comes before and after a skill once it is invoked; they do **not** restrict when any skill can be invoked. +

+ The working-with-tdd skill in a coding agent: write a failing test, + watch it fail for the right reason, write minimal code, and catch a race + before it ships. +

-**Plan mode:** plan mode → `hardening-plans` → `working-in-isolation` → `working-with-tdd` → `verifying-development-work` +

+ working-with-tdd catches a race before it ships. Terminal + themed with Synthpunk + Neon Dark. +

+ +## Included skills + +The following skills cover the development workflow and the maintenance of the +skill set itself: + +- [`hardening-plans`](skills/hardening-plans/SKILL.md) reviews a drafted plan for + missing requirements, hallucinated files, placeholders, and inconsistencies + before presenting it. +- [`working-in-isolation`](skills/working-in-isolation/SKILL.md) chooses a safe + branch or worktree without colliding with in-progress work or editing a + protected base branch. +- [`working-with-tdd`](skills/working-with-tdd/SKILL.md) follows a verified + red-green-refactor cycle for features, refactors, and bug fixes. +- [`investigating-bugs`](skills/investigating-bugs/SKILL.md) reproduces failures, + gathers evidence, tests one hypothesis at a time, and fixes the root cause + instead of guessing. +- [`verifying-development-work`](skills/verifying-development-work/SKILL.md) + reviews the diff and presents fresh test, build, or lint evidence before + claiming work is complete. +- [`writing-technical-docs`](skills/writing-technical-docs/SKILL.md) writes and + reviews comments, READMEs, design docs, pull request descriptions, and other + technical documentation for the intended readers. +- [`writing-skills`](skills/writing-skills/SKILL.md) drafts concise, + cross-harness skills with clear triggers and behavior-shaping instructions. +- [`evaluating-skills`](skills/evaluating-skills/SKILL.md) designs realistic + comparisons that test whether a skill or revision improves agent behavior. +- [`auditing-slow-powers-usage`](skills/auditing-slow-powers-usage/SKILL.md) helps + Slow-powers maintainers audit how the skill set performed across a completed, + real-world session. + +## Why trust these skills? + +Agent instructions can sound convincing without changing behavior. Slow-powers +treats that as an evaluation problem: + +- Every shipped skill has inspectable evaluation (eval) cases under its `evals/` + directory. +- `new-skill` evals compare the skill with a no-skill baseline; revision evals + compare proposed wording with the prior version. +- Eval cases and notes stay beside each skill. A promoted baseline adds its + grading artifacts there too, so the result and its limitations can be + reviewed. +- A dedicated workflow validates all shipped skills against the Agent Skills + specification. Repository tests exercise each harness integration. + +The badges at the top report the published evaluation and specification status. +Skill evaluations are designed with [`evaluating-skills`](skills/evaluating-skills/SKILL.md) +and run with [eval-magic](https://github.com/slowdini/eval-magic). -**Debugging:** (`working-in-isolation`) → `investigating-bugs` → `verifying-development-work` +## Design principles -## Philosophy +Slow-powers is intentionally opinionated about a few practices: -Slow-powers skills follow a few opinionated principles: +- Plans deserve a final skeptical review before implementation begins. +- Code changes start from an isolated workspace and a failing test. +- Debugging begins with reproduction and evidence, not a speculative patch. +- Completion claims include a diff review and fresh verification output. +- Behavior-shaping skill changes are evaluated instead of accepted on prose + quality alone. -- Test-Driven Development — write tests first, always -- Plan mode — even small features should start with a plan -- Prefer branches to worktrees — branches are easier for human review and testing, worktrees are better for agent isolation -- Skills need evals — evals prove a new skill is better than no skill, and an edit to an existing skill is valuable +The skills reinforce native agent features rather than replacing them. Plan +mode remains plan mode, your harness keeps its own tools and permissions, and +you retain control over approval, integration, and publishing decisions. -## Repository structure +## Project background -Flat layout — skills and assets live at root, harness-specific integration lives in top-level directories: +Slow-powers is a fork of +[obra/superpowers](https://github.com/obra/superpowers). Much of the original +skill content comes from upstream; Slow-powers rewrites and extends it with an +emphasis on clarity, token efficiency, cross-harness behavior, and a lighter +day-to-day touch. -- `skills/` — All slow-powers skills -- `assets/` — Icons and images shared across harnesses -- `tests/` — Cross-cutting and harness-specific tests -- `.claude-plugin/` — Claude Code plugin manifest and hooks -- `.codex-plugin/` — OpenAI Codex plugin manifest +## Development + +The repository ships the same skills across four harness integrations: + +- `skills/` — shared skills, references, assets, and evals +- `assets/` — images and icons shared by the README and harnesses +- `.claude-plugin/` — Claude Code plugin manifests +- `.codex-plugin/` — Codex plugin manifest - `opencode/` — OpenCode plugin -- `cline/` — Cline plugin entry point -- `.claude-plugin/marketplace.json` — Claude Code marketplace registry -- `package.json` — OpenCode + Cline plugin manifests + dev tooling +- `cline/` — Cline CLI/SDK/Kanban plugin +- `hooks/` — shared startup and plan-mode hooks +- `tests/` — repository and harness contract tests + +Install dependencies and run the local checks with Bun: + +```bash +bun install +bun test +bun run check +``` -## Releasing +### Release process -Releases are cut from `dev` and tagged from `main`: +Releases move from `dev` to `main` through a release pull request: -1. Merge feature PRs into `dev` after CI passes. -2. When ready to ship, trigger the **Release PR** workflow with the next - version number. It bumps every manifest via `scripts/bump-version.ts`, - commits to `dev`, and opens a `dev → main` PR. -3. Review the release PR (full test matrix runs on it) and merge. -4. Merging to `main` automatically tags `vX.Y.Z`, creates the GitHub release, - and publishes `@slowdini/slow-powers-opencode` to npm. - Notes come from the release PR body, or auto-generated if empty. +1. Merge feature pull requests into `dev` after CI passes. +2. Run the **Release PR** workflow with the intended version. It updates every + manifest and opens a `dev` to `main` pull request. +3. Review and merge the release pull request after its full test matrix passes. +4. The merge tags the version, creates the GitHub release, and publishes + `@slowdini/slow-powers-opencode` to npm. -See `.github/workflows/` for the workflow definitions. +See [`.github/workflows/`](.github/workflows/) for the workflow definitions. ## License -MIT — see [`LICENSE`](./LICENSE). +Slow-powers is available under the [MIT License](LICENSE). diff --git a/assets/readme.png b/assets/readme.png new file mode 100644 index 0000000..7eb3db9 Binary files /dev/null and b/assets/readme.png differ