Philosophy & Principles

The four core principles that make Superpowers enforce better development practices

Overview

Superpowers is built on four core principles that transform how AI coding agents work. These aren’t just guidelines - they’re enforced by the skills system.

From the README:

Test-Driven Development

Write tests first, always

Systematic over ad-hoc

Process over guessing

Complexity reduction

Simplicity as primary goal

Evidence over claims

Verify before declaring success

Principle 1: Test-Driven Development

The Philosophy

From skills/test-driven-development/SKILL.md:12-14:

Core principle: If you didn’t watch the test fail, you don’t know if it tests the right thing.

Violating the letter of the rules is violating the spirit of the rules.

TDD isn’t just about writing tests - it’s about proving your tests work before trusting them.

Why It Matters

The “Tests After” Trap

From skills/test-driven-development/SKILL.md:207-225:

“I’ll write tests after to verify it works”

Tests written after code pass immediately. Passing immediately proves nothing:

• Might test wrong thing
• Might test implementation, not behavior
• Might miss edge cases you forgot
• You never saw it catch the bug

Test-first forces you to see the test fail, proving it actually tests something.

Tests vs. Manual Testing

Why Manual Testing Isn't Enough

From skills/test-driven-development/SKILL.md:217-226:

“I already manually tested all the edge cases”

Manual testing is ad-hoc. You think you tested everything but:

• No record of what you tested
• Can’t re-run when code changes
• Easy to forget cases under pressure
• “It worked when I tried it” ≠ comprehensive

Automated tests are systematic. They run the same way every time.

How Superpowers Enforces It

The test-driven-development skill enforces the RED-GREEN-REFACTOR cycle:

From skills/test-driven-development/SKILL.md:33-45:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

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

No exceptions:

• Don’t keep it as “reference”
• Don’t “adapt” it while writing tests
• Don’t look at it
• Delete means delete

Common Rationalizations (And Why They’re Wrong)

From skills/test-driven-development/SKILL.md:256-270:

Excuse	Reality
”Too simple to test”	Simple code breaks. Test takes 30 seconds.
”I’ll test after”	Tests passing immediately prove nothing.
”Tests after achieve same goals”	Tests-after = “what does this do?” Tests-first = “what should this do?"
"Already manually tested”	Ad-hoc ≠ systematic. No record, can’t re-run.
”Deleting X hours is wasteful”	Sunk cost fallacy. Keeping unverified code is technical debt.
”Need to explore first”	Fine. Throw away exploration, start with TDD.
”TDD will slow me down”	TDD faster than debugging. Pragmatic = test-first.

The Pragmatic Argument

From skills/test-driven-development/SKILL.md:236-244:

“TDD is dogmatic, being pragmatic means adapting”

TDD IS pragmatic:

• Finds bugs before commit (faster than debugging after)
• Prevents regressions (tests catch breaks immediately)
• Documents behavior (tests show how to use code)
• Enables refactoring (change freely, tests catch breaks)

“Pragmatic” shortcuts = debugging in production = slower.

Principle 2: Systematic Over Ad-Hoc

The Philosophy

Ad-hoc development is guessing. Systematic development is following a proven process.

From skills/using-superpowers/SKILL.md:7-11:

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

This is not negotiable. This is not optional. You cannot rationalize your way out of this.

How It Contrasts With Typical Development

Ad-Hoc vs. Systematic Development

Typical Ad-Hoc Development:

User: Add OAuth to the app
Agent: Sure! *immediately starts writing code*
Agent: *30 minutes later* Done! Here's the implementation.
User: Wait, I wanted Google AND GitHub support
Agent: Oh, let me refactor... *another hour*
User: The session handling is broken
Agent: Let me debug... *finds no tests to verify behavior*

Superpowers Systematic Development:

User: Add OAuth to the app
Agent: *invokes brainstorming skill*
Agent: Which providers do you need?
User: Google and GitHub
Agent: *asks about session management, security requirements*
Agent: *proposes 3 approaches with trade-offs*
Agent: *presents complete design in sections*
User: Looks good!
Agent: *creates git worktree, writes detailed plan*
Agent: *dispatches subagents with TDD enforcement*
Agent: *two-stage review catches issues early*
Agent: All done! 8 new tests, all passing.

Result:

• Ad-hoc: 2+ hours, broken features, no tests, frustrated user
• Systematic: 2 hours, working features, full test coverage, validated design

Red Flags of Ad-Hoc Thinking

From skills/using-superpowers/SKILL.md:56-73:

Thought	Why It’s Ad-Hoc	Systematic Alternative
”This is just a simple question”	Assumes context, skips planning	Check for skills before responding
”Let me explore first”	Undirected wandering	Skills tell you HOW to explore
”I’ll just do this one thing”	One thing becomes many	Check skills BEFORE doing anything
”This feels productive”	Activity ≠ progress	Disciplined action via skills
”The skill is overkill”	Assumes simplicity lasts	Simple things become complex

The Brainstorming Anti-Pattern

From skills/brainstorming/SKILL.md:18-20:

Anti-Pattern: “This Is Too Simple To Need A Design”

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. “Simple” projects are where unexamined assumptions cause the most wasted work.

How Superpowers Enforces It

1. Skill Check First

   From skills/using-superpowers/SKILL.md:23-24:

   “Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check.”

2. Mandatory Workflows

   From README line 94:

   “The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.”

3. Hard Gates

   Skills contain <HARD-GATE> sections that prevent skipping critical steps.

   From skills/brainstorming/SKILL.md:14-16:

   Do NOT invoke any implementation skill, write any code, scaffold any 
   project, or take any implementation action until you have presented 
   a design and the user has approved it.
   

Principle 3: Complexity Reduction

The Philosophy

Simplicity isn’t about doing less - it’s about doing exactly what’s needed and nothing more.

YAGNI: You Aren’t Gonna Need It

From skills/brainstorming/SKILL.md:92-94:

One of the key principles emphasized in brainstorming:

• YAGNI ruthlessly - Remove unnecessary features from all designs

And from the README (line 11):

It emphasizes true red/green TDD, YAGNI (You Aren’t Gonna Need It), and DRY.

Minimal Implementation

From skills/test-driven-development/SKILL.md:132-166:

Good vs. Over-Engineered Code

Good (Minimal):

async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

Just enough to pass the test.

Bad (Over-Engineered):

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> {
  // YAGNI - all this complexity wasn't tested
}

The test only needed 3 retries. Don’t add:

• Configurable retry counts
• Backoff strategies
• Retry callbacks

Add them WHEN you need them, with tests first.

Bite-Sized Tasks

From skills/writing-plans/SKILL.md:20-27:

Complexity reduction extends to planning:

Each step is one action (2-5 minutes):

• “Write the failing test” - step
• “Run it to make sure it fails” - step
• “Implement the minimal code to make the test pass” - step
• “Run the tests and make sure they pass” - step
• “Commit” - step

Breaking work into tiny pieces reduces cognitive load and makes progress visible.

How Superpowers Enforces It

GREEN Step

TDD skill mandates: “Write simplest code to pass the test. Don’t add features, refactor other code, or ‘improve’ beyond the test.”

YAGNI in Design

Brainstorming skill emphasizes: “YAGNI ruthlessly - Remove unnecessary features from all designs”

Granular Plans

Writing-plans skill requires bite-sized tasks (2-5 minutes each)

Spec Compliance Review

Subagent-driven development checks for: “Nothing extra was added (YAGNI)“

Principle 4: Evidence Over Claims

The Philosophy

Don’t declare success until you’ve proven it.

From skills/test-driven-development/SKILL.md:113-125:

Verify RED - Watch It Fail

MANDATORY. Never skip.

Confirm:

• Test fails (not errors)
• Failure message is expected
• Fails because feature missing (not typos)

Test passes? You’re testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

And:

Verify GREEN - Watch It Pass

MANDATORY.

Confirm:

• Test passes
• Other tests still pass
• Output pristine (no errors, warnings)

The Verification Loop

Every phase includes verification:

1. Worktree Setup

   From skills/using-git-worktrees/SKILL.md:121-134:

   Run tests to ensure worktree starts clean. If tests fail, report failures and ask whether to proceed.

2. Implementation

   TDD cycle requires watching tests fail, then watching them pass.

3. Code Review

   Two-stage review: spec compliance, then code quality.

4. Branch Completion

   From skills/finishing-a-development-branch/SKILL.md:18-36:

   Verify tests pass before presenting merge options. If tests fail, cannot proceed.

Why “It Works For Me” Isn’t Enough

From skills/test-driven-development/SKILL.md:218-226:

“I already manually tested all the edge cases”

Manual testing is ad-hoc. You think you tested everything but:

• No record of what you tested
• Can’t re-run when code changes
• Easy to forget cases under pressure
• “It worked when I tried it” ≠ comprehensive

Automated tests are systematic. They run the same way every time.

The Verification Checklist

From skills/test-driven-development/SKILL.md:327-340:

Before marking work complete:

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason (feature missing, not typo)
• Wrote minimal code to pass each test
• All tests pass
• Output pristine (no errors, warnings)
• Tests use real code (mocks only if unavoidable)
• Edge cases and errors covered

Can’t check all boxes? You skipped TDD. Start over.

How Superpowers Enforces It

Mandatory Test Verification

TDD skill requires watching tests fail AND pass. No skipping.

Clean Baselines

Git worktrees skill verifies tests pass before starting work.

Two-Stage Review

Spec compliance review proves it does what the plan says. Code quality review proves it’s well-built.

Final Verification

Finishing branch skill runs full test suite before merge/PR.

How These Principles Work Together

The four principles create a reinforcing system:

1. TDD provides evidence

   Watching tests fail and pass proves the code works and the tests are valid.

2. Evidence prevents complexity

   When you must verify everything, you stop adding unneeded features.

3. Simplicity enables process

   Bite-sized tasks and minimal implementations make systematic workflows feasible.

4. Process enforces TDD

   Skills contain hard gates that prevent skipping the RED-GREEN-REFACTOR cycle.

Real-World Impact

Before Superpowers

Typical AI Agent Development

User: “Add a feature to export user data”

Agent:

• Immediately starts writing code
• Adds export to CSV, JSON, XML (“might need them”)
• No tests (“I’ll add them later”)
• Doesn’t ask about requirements
• 200 lines of code, 3 edge cases missed
• User discovers bugs in production
• No systematic way to prevent regressions

Time: 30 minutes
Quality: Broken, untested, over-engineered
User Satisfaction: Low (fixing bugs in production)

With Superpowers

Systematic Superpowers Development

User: “Add a feature to export user data”

Agent:

1. Brainstorming (10 min)

   • “What format do you need?” → “Just CSV for now”
   • “What fields should be included?” → “Email, name, created date”
   • Proposes 3 approaches, recommends standard CSV library
   • Presents design covering data selection, formatting, error handling
   • Saves design doc

2. Git Worktree (2 min)

   • Creates isolated workspace
   • Verifies clean test baseline

3. Writing Plan (5 min)

   • Breaks into 4 bite-sized tasks
   • Each task has: test → verify fail → implement → verify pass → commit

4. Subagent-Driven Development (20 min)

   • Fresh subagent per task
   • TDD enforced: watched each test fail, then pass
   • Two-stage review after each task
   • 4 new tests, all passing

5. Finishing Branch (3 min)

   • Verifies all tests pass
   • Creates PR with summary

Time: 40 minutes
Quality: Working, tested (4 tests), exactly what’s needed
User Satisfaction: High (works correctly, easy to extend later)

The Difference

10 Minutes Slower

But saves hours of debugging and fixing production issues

Tests Included

Not “I’ll add them later” (which never happens)

Right Feature Built

CSV only, not CSV + JSON + XML you don’t need

Proven Quality

Tests watched failing and passing - evidence it works

Common Objections

”This will slow me down”

From skills/test-driven-development/SKILL.md:268:

TDD faster than debugging. Pragmatic = test-first.

Yes, Superpowers adds 10-15 minutes upfront for brainstorming and planning. But it saves hours of:

• Debugging issues that could have been caught by tests
• Refactoring over-engineered solutions
• Re-implementing features that didn’t match requirements
• Fixing regressions because there were no tests

”The process feels rigid”

From skills/using-superpowers/SKILL.md:86-91:

Rigid (TDD, debugging): Follow exactly. Don’t adapt away discipline.

Flexible (patterns): Adapt principles to context.

The skill itself tells you which. Rigidity exists only where it prevents common mistakes.

”I know what I’m doing, I don’t need a checklist”

From skills/using-superpowers/SKILL.md:67-69:

Thought	Reality
”I know what that means”	Knowing the concept ≠ using the skill. Invoke it.
”I remember this skill”	Skills evolve. Read current version.

Even experts benefit from checklists. Ask any surgeon or pilot.

Key Takeaways

TDD Proves Tests Work

Watching tests fail first proves they actually test something. Tests-after prove nothing.

Process Beats Guessing

Systematic workflows prevent wasted work from unexamined assumptions.

Simple Beats Clever

Build exactly what’s needed. Add complexity WHEN needed, with tests first.

Show, Don't Tell

Verify every claim. Clean baselines, test verification, code review.

Next Steps

Skills Overview

Learn how the skills system enforces these principles

Workflow

See the complete development process in action

Get Started

Install Superpowers and start using it