# Superpowers — Development Workflow System

A set of composable skills for disciplined, high-quality software development. Adapted from [obra/superpowers](https://github.com/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](skills/brainstorming/SKILL.md)** | Before any creative work | Explores intent, requirements, design. Produces a spec doc. |
| **[writing-plans](skills/writing-plans/SKILL.md)** | After spec is approved | Breaks work into 2-5 minute tasks with exact code and paths. |
| **[subagent-driven-development](skills/subagent-driven-development/SKILL.md)** | Executing a plan | Dispatches fresh subagent per task with two-stage review. |
| **[executing-plans](skills/executing-plans/SKILL.md)** | Executing a plan inline | Executes tasks in-session with checkpoints. |
| **[test-driven-development](skills/test-driven-development/SKILL.md)** | Implementing any task | RED-GREEN-REFACTOR cycle. Tests first, always. |
| **[systematic-debugging](skills/systematic-debugging/SKILL.md)** | Any bug or test failure | 4-phase root cause investigation. No fixes without understanding. |
| **[requesting-code-review](skills/requesting-code-review/SKILL.md)** | After tasks, before merge | Dispatches reviewer subagent with focused context. |
| **[verification-before-completion](skills/verification-before-completion/SKILL.md)** | Before any success claim | Runs fresh verification commands before claiming results. |
| **[using-git-worktrees](skills/using-git-worktrees/SKILL.md)** | Starting feature work | Creates isolated workspace on new branch. |
| **[finishing-a-development-branch](skills/finishing-a-development-branch/SKILL.md)** | 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