6.1 KiB

Raw Blame History

Superpowers — Development Workflow System

A set of composable skills for disciplined, high-quality software development. Adapted from obra/superpowers for the Construction Delivery Control project.

Philosophy

Design before code — Never jump straight into implementation
Tests before code — TDD is non-negotiable
Root cause before fixes — Systematic debugging over guesswork
Evidence before claims — Verify everything before stating success
Review before merge — Catch issues early, catch them often
Isolation for focus — Use git worktrees for clean development

Skills Overview

Skill	When to Use	What It Does
brainstorming	Before any creative work	Explores intent, requirements, design. Produces a spec doc.
writing-plans	After spec is approved	Breaks work into 2-5 minute tasks with exact code and paths.
subagent-driven-development	Executing a plan	Dispatches fresh subagent per task with two-stage review.
executing-plans	Executing a plan inline	Executes tasks in-session with checkpoints.
test-driven-development	Implementing any task	RED-GREEN-REFACTOR cycle. Tests first, always.
systematic-debugging	Any bug or test failure	4-phase root cause investigation. No fixes without understanding.
requesting-code-review	After tasks, before merge	Dispatches reviewer subagent with focused context.
verification-before-completion	Before any success claim	Runs fresh verification commands before claiming results.
using-git-worktrees	Starting feature work	Creates isolated workspace on new branch.
finishing-a-development-branch	All tasks complete	Verifies tests, presents integration options, cleans up.

Workflow: Idea → Production

┌─────────────────────────────────────────────────────────────┐
│                     IDEAL WORKFLOW                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. brainstorming                                           │
│     ↓ (spec doc in docs/superpowers/specs/)                 │
│  2. writing-plans                                           │
│     ↓ (plan doc in docs/superpowers/plans/)                 │
│  3. using-git-worktrees                                     │
│     ↓ (isolated .worktrees/branch-name)                     │
│  4. subagent-driven-development (or executing-plans)        │
│     ↓ (per task: implement → spec-review → quality-review)  │
│  5. finishing-a-development-branch                          │
│     ↓ (merge / PR / keep / discard)                         │
│                                                             │
│  Throughout:                                                │
│  - test-driven-development (every task)                     │
│  - systematic-debugging (any bug)                           │
│  - verification-before-completion (every claim)             │
│  - requesting-code-review (between tasks)                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Quick Start

For a New Feature

Tell me what you want to build → I'll use brainstorming
We iterate on the design together → I'll write a spec
I'll create an implementation plan with writing-plans
I'll set up a worktree with using-git-worktrees
I'll execute the plan with subagent-driven-development or executing-plans
When done, finishing-a-development-branch gives you merge/PR options

For a Bug Fix

Tell me what's broken → I'll use systematic-debugging
I'll find root cause before proposing any fix
I'll write a failing test with test-driven-development
I'll fix, verify, and commit

For Code Review

Ask for a review → I'll use requesting-code-review
A reviewer subagent gets focused context (not session history)
Issues are reported by severity and fixed before proceeding

Project-Specific Conventions

Test runner: Vitest (npm run test)
Linter: ESLint 9 (npm run lint)
Build: Vite 6 (npm run build)
Test files: .test.js co-located with source
Components: Organized by domain in src/components/
Services: Pure functions in src/services/, Supabase adapters in src/services/supabase/
Worktrees: .worktrees/ directory (already exists and gitignored)
Specs: docs/superpowers/specs/
Plans: docs/superpowers/plans/

Skill Triggering

Skills are mandatory workflows, not optional suggestions. When the context matches a skill's description, I will announce its use and follow the prescribed process. You can always ask me to use a specific skill by name.

Key Principles

Design before code — Unexamined assumptions cause wasted work
Tests before code — If you didn't watch it fail, you don't know what it tests
Root cause before fixes — Random fixes create new bugs
Evidence before claims — Run the command, read the output, THEN claim the result
Review before merge — Fresh eyes catch what tired eyes miss
Isolation for focus — Clean workspace, clean mind

6.1 KiB Raw Blame History