104 lines
6.1 KiB
Markdown
104 lines
6.1 KiB
Markdown
# 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
|