supersam/docs/superpowers

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

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

For a Bug Fix

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

For Code Review

1. Ask for a review → I'll use requesting-code-review
2. A reviewer subagent gets focused context (not session history)
3. 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

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