Deep Dive: How obra/superpowers Forces a Disciplined Agent Workflow

Companion to the hands-on tutorial: Run a skills-driven development workflow with Superpowers on Cui.Guru. The tutorial shows how to install and run it. This post explains why it works.

obra/superpowers (314k stars when I read it) is a methodology delivered as 15 composable skills: brainstorming, writing-plans, subagent-driven-development, test-driven-development, systematic-debugging, finishing-a-development-branch and more. The interesting part is not any one skill. It is how they are chained and how the chain is made to actually fire.

The workflow in motion

Architecture: a hook plus a skill chain

Skills normally load only when the model decides they are relevant. Superpowers does not trust that. A SessionStart hook (hooks/hooks.json) runs on startup, clear and compact, and injects the full text of one skill, using-superpowers, into the context:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start", "shell": "bash" }]
      }
    ]
  }
}

The session-start script reads skills/using-superpowers/SKILL.md, JSON-escapes it, and emits it in whichever shape the harness expects: additional_context for Cursor, hookSpecificOutput.additionalContext for Claude Code, top-level additionalContext for Copilot CLI and others.

The chain is a pipeline. This is a conceptual map rather than an exact invocation graph: brainstorming hands off to writing-plans, and worktree setup happens when execution starts.

The core design idea: make the right path the default

Three choices carry most of the weight.

1. Rules the model cannot negotiate away. The bootstrap skill opens with this:

If you think there is even a 1% chance a skill might apply to what you are doing,
you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

It then lists the rationalisations an agent tends to produce (“This is just a simple question”, “I need more context first”, “The skill is overkill”) and answers each one. This is prompt design as adversarial testing: the skill is written against the excuses the model actually makes.

2. Gates that need a human, and only those. brainstorming forbids implementing until the human picks an approach and approves a design doc. subagent-driven-development goes the other way: once there is a plan, it must not stall. It lists the only four reasons to stop, an irreversible or destructive operation, a security-sensitive action, a side effect outside the worktree such as a merge or publish, and a plan so broken that every path is a guess. Everything else is a “ruling” recorded in a ledger with its cost if wrong. Approval is spent where it matters and nowhere else.

3. Context isolation as a quality tool. The same skill explains why it uses subagents:

They should never inherit your session's context or history — you construct
exactly what they need. This also preserves your own context for coordination work.

Each task gets a fresh implementer, then a spec-compliance and code-quality review, then a broad whole-branch review at the end. The coordinator stays small, and each worker sees only a crafted brief.

Code worth reading: the TDD iron law

test-driven-development is short and absolute:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

Its state machine is embedded as a Graphviz dot block in the skill, which the agent can read as a precise loop: write the failing test, verify it fails for the right reason, write minimal code, verify green, refactor while staying green, next. A failure that is wrong (not the expected one) sends you back to red rather than forward. Diagrams-as-instructions are compact and hard to misread.

Takeaways

• Do not rely on automatic skill discovery for process skills. Inject the one routing skill at session start.
• Write skills against the model’s own excuses, not just the happy path.
• Spend human approval on design and irreversible actions. Let the rest run.
• Isolate worker context and review each unit, so quality does not depend on one long conversation.
• When the agent goes off-plan, use diagnosing-superpowers to ask what went wrong in the session instead of tweaking prompts blindly.

Want the hands-on version? Follow the Cui.Guru tutorial, or tell us what to cover next.