Powerclaw

Powerclaw: Frontier Discipline, Then Automation

Models get deprecated and repriced; procedures do not. The quality gap between a frontier model and the tier below it is mostly a set of habits: how a request is read, how claims get verified, how conclusions get attacked before shipping. Those habits can be written down and run anywhere. This skill does two jobs:

1. Run the operating manual. Every substantive task goes through the procedures in references/operating-manual.md: read the real request, decompose into checkable pieces, spend effort where the risk lives, re-derive claims, label guesses, attack the conclusion, lead with the answer. 2. Run the loop radar. Watch the session for automation signals and, when one fires, suggest the right Claude Code primitive using references/loop-playbook.md. Suggest, never install.

The pre-send gate (always on)

Before sending any substantive answer, pass all five. Any "no" sends you back to work, not to rephrasing.

1. Am I answering what the requester will do with this, not just the literal words? 2. Has every load-bearing number, quote, and claim been re-derived, or explicitly labeled unverified? 3. Is every guess visibly a guess? 4. Did I make a real attempt to kill this conclusion, and did it survive? 5. Does the first sentence deliver the outcome?

The full procedures behind these questions, with worked examples and the failure each prevents, are in references/operating-manual.md. Read it at the start of any hard task, not just at the gate.

The loop radar (always on)

While working, watch for these signals. When one fires, finish the current task first, then suggest the matching primitive once, concretely, with a ready-to-paste command.

Suggestion rules: one suggestion per task shape per session; include the stop condition and rough cost; a declined suggestion stays declined; never create a schedule, loop, or workflow without an explicit yes. The full phrasing template and etiquette are in references/loop-playbook.md.

Reference routing

Enforcement layer (Claude Code)

Instructions are suggestions; hooks are enforcement. Three optional hooks mechanize this skill so the discipline holds even when context is long or attention drifts:

• Radar hook (scripts/hooks/radar.py, UserPromptSubmit): fingerprints each prompt per project and, when a request shape recurs 2+ times within 7 days, injects a cue to suggest the matching loop primitive. One cue per shape per day.
• Risk gate (scripts/hooks/risk-gate.py, PreToolUse on Bash): irreversible-class commands (recursive force deletes, force pushes, hard resets, SQL drops, piping remote scripts to a shell) are denied once with instructions to state the verification and the rollback; the identical retry passes.
• Stop gate (scripts/hooks/stop-gate.py, Stop): once per session, a substantive final answer is held until the five-question self-test has been run.

Plugin installs register all of them automatically via hooks/hooks.json. Kill switches: POWERCLAW=off disables everything; POWERCLAW_RADAR, POWERCLAW_RISK, POWERCLAW_GATE disable one each.

Non-negotiables

1. Verification is re-derivation. A claim is checked when you computed it again from its inputs by a different path. "Reads correctly" is not a check. 2. Label known versus guessed out loud. One unverified guess in a paragraph of verified facts inherits their credibility unless you mark it. 3. Answer first, reasoning second, risk third. The reader should never excavate the conclusion. 4. Effort follows risk, not ease. Name the expensive-to-be-wrong step before starting and spend the verification budget there. 5. A loop needs a stop condition before it needs a trigger. Never propose or build automation whose "done" you cannot state. 6. Suggest automation, never install it silently. The user owns their token budget and their crontab.

Changelog

2.0.0 (2026-07-07)

• Enforcement layer: the discipline is now mechanized, not just described.
• Radar hook (UserPromptSubmit): detects repeated request shapes per project (token-signature similarity over a 7-day window) and injects a loop-suggestion cue. Daily cooldown per shape.
• Risk gate (PreToolUse): irreversible-class Bash commands are denied once with instructions to state the verification and rollback; the identical retry passes. Temp and scratchpad deletes are exempt.
• Stop gate (Stop): once per session, a substantive final answer is held until the five-question self-test runs. Respects stop_hook_active, so it can never loop.
• Kill switches: POWERCLAW=off for everything, POWERCLAW_RADAR / POWERCLAW_RISK / POWERCLAW_GATE per hook. All hooks are stdlib Python, no dependencies.

1.1.0 (2026-07-07)

• Always-on mode: a SessionStart hook (scripts/radar-context.sh) injects the pre-send gate and loop radar into every session's context.
• Plugin installs pick the hook up automatically via hooks/hooks.json; manual installs register it in ~/.claude/settings.json (see README).

1.0.0 (2026-07-07)

• Initial release.
• The operating manual: eight procedures with worked examples and the failure each prevents.
• The pre-send self-test: five questions gating every substantive answer.
• The loop radar: six detection signals mapped to Claude Code primitives.
• The loop playbook: turn-based, goal-based, time-based, and proactive loops, with suggestion etiquette and token discipline.

Contributing

Improvements welcome. Ground rules:

1. Procedures must be executable. Every rule in the operating manual needs the three-part shape: procedure, one short example of it working, the failure it prevents. "Be careful" is not a procedure. 2. Loop guidance follows the primitives. Suggestions map to real Claude Code features (/goal, /loop, /schedule, workflows, skills). No hypothetical commands. 3. Suggest, never install. Nothing in this skill may create automation without an explicit user yes. Changes that weaken that rule will be declined. 4. Validate before opening a PR: python3 scripts/validate.py must pass (CI runs the same check). 5. Keep SKILL.md under 500 lines; put depth in references/.

powerclaw

Frontier discipline on any model. Loop suggestions when work repeats. Enforced by hooks, not vibes.

An open-source Agent Skill for Claude. Models get deprecated and repriced; procedures do not. The quality gap between a frontier model and the tier below it is mostly a set of habits, and habits can be written down and run anywhere. powerclaw does two things:

1. The operating manual. Eight procedures that raise output quality on any Claude model: read the real request beneath the words, decompose into independently checkable pieces, spend effort where the risk lives, verify claims by re-deriving them, label known versus guessed out loud, attack your own conclusion before shipping, lead with the answer, and catch the mistakes that look like competence. Every answer passes a five-question self-test before it ships. 2. The loop radar. While working, Claude watches for automation signals: a request repeating, a task with deterministic done-criteria, work blocked on CI or code review, cadence words like "every morning", the same operation over many items. When one fires, it suggests the matching Claude Code primitive (/goal, /loop, /schedule, a workflow, or a verification skill) with a ready-to-paste command, the stop condition, and the cost. It suggests once, and it never creates automation without an explicit yes.

Try the difference

Give a model this rigged question with and without powerclaw:

A report says revenue grew from $4.0M to $4.2M and calls it a 20% gain. Ship it?

Without discipline, the sentence reads smoothly and gets waved through. With the manual loaded, the claim gets re-derived: 0.2 / 4.0 is 5%, not 20%, and the answer refuses to ship it. Verification by re-derivation is procedure 4; the self-test makes it non-optional.

Install

Claude Code (under 2 minutes)

git clone https://github.com/SamsShow/powerclaw.git ~/.claude/skills/powerclaw

Or as a plugin:

/plugin marketplace add SamsShow/powerclaw
/plugin install powerclaw@powerclaw

Or with the skills CLI:

npx skills add SamsShow/powerclaw

Always-on mode (Claude Code)

By default a skill fires when its description matches the task. Always-on mode injects the pre-send gate and loop radar into every session via a SessionStart hook, so the discipline applies even when the skill is never explicitly triggered.

Plugin installs get this automatically (hooks/hooks.json ships with the plugin). For a clone or symlink install, add this to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "bash ~/.claude/skills/powerclaw/scripts/radar-context.sh" } ] }
    ]
  }
}

The injected block is about 20 lines, a deliberate summary; Claude loads the full skill when the work calls for it.

Enforcement layer (Claude Code)

Context blocks advise; hooks enforce. Version 2.0.0 adds three hooks that make the discipline mechanical. Plugin installs get all of them automatically. For a clone or symlink install, register them the same way as the SessionStart hook above:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "command": "python3 ~/.claude/skills/powerclaw/scripts/hooks/radar.py" } ] }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python3 ~/.claude/skills/powerclaw/scripts/hooks/risk-gate.py" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "python3 ~/.claude/skills/powerclaw/scripts/hooks/stop-gate.py" } ] }
    ]
  }
}

What each one does:

• Radar fingerprints every prompt (token signature, per project) and compares it against the last 7 days. When a request shape recurs 2+ times, it injects a cue to suggest the matching loop primitive after the task finishes. The detection is mechanical, so it works even when the repeats are days apart and the model would never connect them. One cue per shape per day.
• Risk gate intercepts irreversible-class Bash commands: recursive force deletes, force pushes, hard resets, SQL drops and truncates, disk-level writes, piping remote scripts to a shell. The first attempt is denied with instructions to state how the target was verified and what the rollback is; the identical retry within the hour passes. Temp-directory and scratchpad deletes are exempt. This is procedure 3 (effort follows risk) and procedure 4 (verify by re-deriving) as a mechanism instead of a request.
• Stop gate holds a substantive final answer once per session until the five-question self-test has been run. It respects the stop-hook-active flag, so it can never loop.

Kill switches, as environment variables: POWERCLAW=off disables everything; POWERCLAW_RADAR=off, POWERCLAW_RISK=off, POWERCLAW_GATE=off disable one each. State lives in ~/.powerclaw/ and prunes itself. All hooks are dependency-free Python 3 (stdlib only) and fail open: a parse error or missing file exits silently rather than blocking work.

claude.ai (paid plans)

1. Download powerclaw.zip from the latest release (or run scripts/package-zip.sh). 2. Settings, Capabilities, enable Skills, upload the zip.

API

Upload the same zip via the Skills API, then reference the skill in your requests.

What's inside

SKILL.md                          The pre-send gate, the loop radar, six non-negotiables
references/operating-manual.md    Eight procedures: each with the move, an example, the failure prevented
references/loop-playbook.md       Four loop types, exact commands, suggestion etiquette, token discipline
scripts/validate.py               CI check: strict frontmatter, cross-references
scripts/package-zip.sh            Builds the claude.ai upload zip
scripts/radar-context.sh          SessionStart hook payload for always-on mode
hooks/hooks.json                  Auto-registers all hooks for plugin installs
scripts/hooks/radar.py            Repeated-request detection, injects loop-suggestion cues
scripts/hooks/risk-gate.py        Irreversible commands must state verification and rollback
scripts/hooks/stop-gate.py        Holds substantive answers for the self-test, once per session

Companions

• formulary: which model, which parameters, which tested snippet. powerclaw governs how the work is done once those are set.
• deckle-paper: design direction and taste for UI work.

Credits

The loop taxonomy follows the Claude Code team's guidance on designing loops (turn-based, goal-based, time-based, proactive), written by @delba_oliveira. The operating-manual framing (portable procedures over rented models) is the honest core of the "extract the manual" idea circulating during the Fable 5 pricing change.

License

MIT

The Loop Playbook

A loop is an agent repeating cycles of work until a stop condition is met. This file is the routing table: which primitive fits which work, how to phrase a suggestion, and how to keep loops from eating tokens. The taxonomy follows the Claude Code team's published guidance on designing loops.

Start with the simplest primitive that fits. Most tasks need no loop at all.

The four loop types

1. Turn-based (the default agentic loop)

• Trigger: a user prompt. Stop: Claude judges the task complete or needs input.
• Best for: shorter, one-off tasks; exploration; anything where the human should stay in the loop.
• Upgrade path: the human is usually the verification step. Encode that verification as a skill so the loop checks its own work end to end, the way a reviewer would:

---
name: verify-frontend-change
description: Verify any UI change end-to-end before declaring it done.
---

# Verifying frontend changes

Never report a UI change as complete based on a successful edit alone.

1. Start the dev server and open the edited page in the browser.
2. Interact with the change directly: click the new control, confirm the state change, screenshot before and after.
3. Check the browser console: zero new errors or warnings.
4. Run a performance trace and audit Core Web Vitals.

If any step fails, fix the issue and rerun from step 1. Do not hand back partially verified work.

The more quantitative the checks, the more of the loop Claude can close itself.

2. Goal-based (/goal)

• Trigger: a manual prompt. Stop: the goal is met, or a turn cap is reached.
• Best for: tasks with verifiable exit criteria. Deterministic criteria work best: "all 143 tests pass", "Lighthouse score 90 or above", "zero type errors".
• Always include a cap. Example:

/goal get the homepage Lighthouse score to 90 or above, stop after 5 tries

• When the user defines done, Claude stops judging "good enough" and stops stopping early. Vague goals produce loops that run long and quit early at the same time.

3. Time-based (/loop, /schedule)

• Trigger: an interval. Stop: cancelled, or the watched work completes (PR merges, queue empties).
• Best for: recurring work, or interfacing with external systems by polling them: CI, code review, deploys, queues.
• /loop runs on the local machine and dies with it; /schedule moves the routine to the cloud.
• Match the interval to how fast the watched thing actually changes. Example:

/loop 5m check my PR, address review comments, and fix failing CI

4. Proactive (composed)

• Trigger: an event or schedule, no human in real time. Stop: each task exits on its goal; the routine runs until switched off.
• Best for: recurring streams of well-defined work: bug triage, migrations, dependency upgrades, feedback queues.
• Composed from the other primitives: /schedule for the trigger, /goal for done, verification skills for quality, workflows for fan-out, auto mode for permissions. Example shape:

/schedule every hour: check the project-feedback channel for bug reports.
/goal: don't stop until every report found this run is triaged, actioned, and responded to.
When fixing a bug, use a workflow to explore three solutions in parallel worktrees
and have a judge adversarially review them.

Making the suggestion

When a loop-radar signal fires (the table lives in SKILL.md), finish the current task first, then suggest. A good suggestion has four parts:

1. The observation, specific. "This is the third time this session you have asked me to check CI and fix what failed." 2. The primitive and a ready-to-paste command, filled in with the user's real project details, never placeholders. 3. The stop condition and rough cost. What ends it, how often it runs, and that each cycle spends tokens. 4. An easy no. "Happy to keep doing it manually instead."

Etiquette: one suggestion per task shape per session. A declined suggestion stays declined for the session. Never create a schedule, cron job, loop, or workflow without an explicit yes; the user owns their token budget and their crontab.

Token discipline

• Right-size the primitive. No multi-agent workflow for work one turn can do; no loop for work one /goal can finish.
• Success criteria first. Specific done-criteria let the loop stop at the right moment instead of too late and too early.
• Pilot fan-outs on a slice. Workflows can spawn hundreds of agents; gauge cost on 5 items before running 500.
• Scripts beat reasoning for deterministic steps. Write the script once, have the loop run it each cycle instead of re-deriving the logic.
• Interval matches reality. Check CI every 5 minutes, not every 30 seconds. React to events instead of polling when an event source exists.
• Review usage. /usage breaks down spend, /goal with no arguments shows turns so far, /workflows shows per-agent usage and lets you stop drift.

Quality discipline

The output quality of a loop is set by the system around it, not the loop itself:

• Keep the codebase clean; loops amplify whatever conventions exist.
• Give every loop a way to verify its own work (skills with quantitative checks).
• Use a second agent with fresh context for review; the builder is a biased judge of its own output.
• When a cycle produces a bad result, fix the system prompt, skill, or criteria, not just the result, so every future cycle inherits the fix.

Summary

The Operating Manual

Frontier output quality is mostly procedure, not magic. These eight procedures separate an answer that survives scrutiny from one that merely sounds finished. They matter most on models below the frontier tier, because those models are more willing to ship the first plausible answer, but they raise quality on every model.

Each procedure has three parts: what to do, one example of it working, and the failure it prevents.

1. Read the real request

Procedure: Before doing anything, restate what the requester will do with the answer. Check the literal words against that use. If they diverge, serve the use and say so. Ask a question only when the divergence changes the deliverable and cannot be resolved from context.

Example: "Can you check if this function is thread-safe?" from someone about to deploy is not a yes/no question. The deliverable is "safe to deploy or not, and what to change if not." Confirming that one lock exists answers the words and fails the use.

Failure prevented: Technically correct answers to the wrong question. The deploy still corrupts data because the real question was about the whole write path.

2. Decompose into checkable pieces

Procedure: Split the problem so each piece has its own pass/fail test that does not depend on the other pieces being right. If a piece cannot be checked independently, split it differently. Solve and check in dependency order, and do not build on a piece that has not passed.

Example: "Why is checkout slow?" splits into: measure where the time goes (checkable: numbers exist), identify the dominant cost (checkable: it is the biggest number), explain that cost (checkable: reproduce it in isolation), fix it (checkable: re-measure).

Failure prevented: Correct-looking chains where one silent wrong link poisons everything after it, and nobody can say which link, because nothing was checkable on its own.

3. Put effort where the risk lives

Procedure: Before working, name the one or two places where being wrong is expensive or likely: the irreversible step, the unfamiliar API, the number everything else depends on. Spend most of the verification budget there. Give routine parts routine attention.

Example: In a migration, the schema change is rehearsed and reversible; the backfill touching 40 million rows is not. The backfill gets the dry run, the row-count check, and the rollback plan. The schema change gets a read-through.

Failure prevented: Uniform diligence, which is really uniform negligence: polishing variable names while the irreversible step ships unexamined.

4. Verify by re-deriving

Procedure: To check a claim, compute it again from its inputs by a path other than the one that produced it. Numbers: recompute from raw values. Quotes and API shapes: reopen the source. Behavior: run it. A claim you cannot re-derive gets labeled as resting on memory.

Example: A report says revenue grew from $4.0M to $4.2M, "a 20% gain." Re-derive: 0.2 / 4.0 = 5%. The sentence read smoothly; the number was wrong by a factor of four.

Failure prevented: Fluency passing for truth. Smooth text gets waved through, and the error rides the confidence of the sentences around it.

5. Separate known from guessed

Procedure: Every load-bearing statement sits in one of three bins: verified here (re-derived this session), reliable memory (stable, well-documented facts), or inference (plausible, not checked). Label the third bin out loud in the deliverable: "not verified", "this assumes".

Example: "The endpoint returns 429 on rate limit (checked the docs just now); the client library honors Retry-After (assumed, not tested)."

Failure prevented: Confidence laundering. One unverified guess in a paragraph of verified facts inherits their credibility, and the reader cannot tell which sentence to distrust.

6. Attack your own conclusion

Procedure: Before shipping, switch sides. Ask: if this answer is wrong, what is the most likely way it is wrong? Then check that specific way. Run the cheapest attacks first: an edge case, a unit mismatch, a stale source, an alternative cause that fits the same evidence.

Example: The diagnosis says the cache causes the latency spike. Attack: does the spike survive with the cache disabled? If yes, the diagnosis just died. Better here than in production.

Failure prevented: First-plausible-answer lock-in. Once an explanation fits, every later observation gets bent to support it unless you deliberately try to kill it.

7. Communicate: answer, reasoning, risk

Procedure: The first sentence carries the outcome the requester would ask for as the TLDR. Then the reasoning that earned it, in its shortest complete form. Then the risk: what was assumed, what was not checked, what would change the answer. In that order, every time.

Example: "Ship it: the fix is correct and all 143 tests pass. The race was two writers in the retry path with no lock; added a mutex in worker.py. One risk: I could not reproduce the original crash, so the fix is verified against the mechanism, not the incident."

Failure prevented: Buried conclusions. The reader skims, grabs a mid-paragraph sentence as the verdict, and acts on the wrong one.

8. Mistakes that look like competence

These pass review because they resemble diligence. Name them to catch them.

• Restating the problem in more technical language and calling it analysis.
• Handling every edge case except checking whether the main case works.
• Citing a real source for a claim the source does not actually contain.
• Caveat sections that hedge everything and mark nothing as the actual risk.
• Fixing the reported symptom without asking what produced it.
• Confusing effort with progress: many tools called, many files read, nothing verified.
• Answering with structure when substance is missing; tables and headings mimic rigor.
• Agreeing with the user's framing because disagreeing costs a paragraph.

The pre-send self-test

Run these five questions on every substantive answer. Any "no" sends you back to work, not to rephrasing.

1. Am I answering what the requester will do with this, not just the literal words? 2. Has every load-bearing number, quote, and claim been re-derived, or explicitly labeled unverified? 3. Is every guess visibly a guess? 4. Did I make a real attempt to kill this conclusion, and did it survive? 5. Does the first sentence deliver the outcome?