Skip to content

Feat/readme update #284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slowdini merged 2 commits into from
Aug 13, 2026
Merged

Feat/readme update #284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30cf450
chore: commit readme png
slowdini Aug 12, 2026
b375665
chore(docs): readme refactor
slowdini Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
288 changes: 183 additions & 105 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
<p align="center">
<img src="assets/logo.png" alt="Slow-powers" width="360" />
<img src="assets/readme.png"
alt="Slow-powers — Agent skills with proven value, built for people who hate skills."
width="100%" />
</p>

<p align="center">
Expand All @@ -8,7 +10,7 @@
alt="CI status" /></a>
<a href="https://github.com/slowdini/slow-powers/releases/latest"><img
src="https://img.shields.io/github/v/release/slowdini/slow-powers"
alt="Latest release" /></a>
alt="Release version" /></a>
<a href="https://www.npmjs.com/package/@slowdini/slow-powers-opencode"><img
src="https://img.shields.io/npm/v/@slowdini/slow-powers-opencode"
alt="OpenCode plugin on npm" /></a>
Expand All @@ -17,171 +19,247 @@
alt="License: MIT" /></a>
<a href="#why-trust-these-skills"><img
src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fslowdini%2Fslow-powers%2Fdev%2F.github%2Fbadges%2Fevals.json"
alt="evals" /></a>
alt="Evaluation status" /></a>
<a href="https://github.com/agentskills/agentskills/tree/main/skills-ref"><img
src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fslowdini%2Fslow-powers%2Fdev%2F.github%2Fbadges%2Fskills-ref.json"
alt="skills-ref validation" /></a>
alt="Agent Skills validation" /></a>
</p>

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

<p align="center">
<img src="assets/demo/tdd-demo.gif"
alt="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."
width="760" />
</p>

<p align="center">
<sub>The <code>working-with-tdd</code> skill catching a race before it ships. Terminal themed with <a href="https://github.com/samiamorwas/synthpunk">Synthpunk Neon Dark</a>.</sub>
</p>

## 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.
<p align="center">
<img src="assets/demo/tdd-demo.gif"
alt="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."
width="760" />
</p>

**Plan mode:** plan mode → `hardening-plans` → `working-in-isolation` → `working-with-tdd` → `verifying-development-work`
<p align="center">
<sub><code>working-with-tdd</code> catches a race before it ships. Terminal
themed with <a href="https://github.com/samiamorwas/synthpunk">Synthpunk
Neon Dark</a>.</sub>
</p>

## 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).
Binary file added assets/readme.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading