Development Workflow

---
name: development-workflow
description: "MANDATORY — invoke BEFORE any implementation, feature, bugfix, or code change. Orchestrates: consult lessons → brainstorm → plan → worktree → TDD build → UI review → code-simplify → CodeRabbit review → verify → PR → CI loop → retrospective."
---

# Development Workflow

## Overview

This skill defines the mandatory development pipeline for every task. Follow each phase in order. Skip conditions are documented per phase.

The workflow is designed for **autonomous execution**: after the user approves the plan (Phase 2), Claude executes Phases 3–9 without requiring human prompts. The user is only notified when the PR is green and ready for review, or when Claude is genuinely stuck.

### Progress Tracking

Maintain a `progress.md` file in the worktree root throughout execution. This file enables context recovery if the session is interrupted or context is compressed.

**Hygiene:** `progress.md` is ephemeral — it must NOT be committed (it's in `.gitignore`). Create it fresh per task, and delete it when the task completes (Phase 10). If a stale `progress.md` is found from a prior completed run, delete it before starting.

**Update `progress.md`** at every phase transition with:
```markdown
# Progress: [task title]

## Spec
Link: docs/plans/YYYY-MM-DD-<topic>-plan.md

## Current Phase
Phase N: [name] — [status: in-progress | completed | blocked]

## Completed Tasks
- [x] Task 1 (commit: abc1234)
- [x] Task 2 (commit: def5678)
- [ ] Task 3 (next up)

## CI Status
- PR: #NNN (or "not yet created")
- Checks: [pending | passing | failing]
- Failures: [summary of current failures, if any]
- Iteration: N/5

## Blockers
- [any issues requiring human input]

## Key Decisions
- [design decisions made during execution]

Do NOT skip phases. Do NOT start coding before phases 1-2 are complete. Do NOT claim work is done before phases 8-9 pass. This applies to EVERY task regardless of perceived simplicity.

Phase 0: Consult Lessons & Recover Context

• Read memory/lessons.md from the auto-memory directory
• Scan for entries relevant to the current task (matching category, similar patterns, related files)
• Keep relevant lessons in mind during brainstorm and implementation
• If lessons suggest a specific approach or warn against a mistake, call it out during Phase 1
• Context recovery: If progress.md exists, read it to determine where prior work left off. Resume from the last incomplete phase instead of restarting.

Skip condition: None. Always check past lessons before starting.

Phase 1: Brainstorm

Invoke: superpowers:brainstorming

• Explore project context (files, docs, recent commits)
• Ask clarifying questions (one at a time, prefer multiple choice)
• Propose 2-3 approaches with trade-offs and recommendation
• Reference any relevant lessons from Phase 0 in your proposals
• Get design approval
• Write design doc to docs/plans/YYYY-MM-DD-<topic>-design.md

Skip condition: None. Every task gets at least a brief design pass.

Phase 2: Plan

Invoke: superpowers:writing-plans

• Break design into bite-sized tasks (2-5 minutes each)
• Identify task dependencies
• Save plan to docs/plans/YYYY-MM-DD-<topic>-plan.md

Skip condition: None.

Phase 3: Isolate

Invoke: superpowers:using-git-worktrees

• Create worktree + branch for isolated development

Skip condition: Already in a worktree.

Phase 4: Build (TDD)

Invoke: superpowers:test-driven-development + superpowers:subagent-driven-development

For each task in the plan:

1. RED — Write failing test
2. GREEN — Write minimal code to pass
3. REFACTOR — Clean up while tests stay green
4. COMMIT — Commit the passing task

Use subagent-driven-development to parallelize independent tasks.

Skip condition: None. All code gets tests.

Phase 5: UI Review

Invoke: frontend-design:frontend-design

• Review against Apple/Notion design guidelines in CLAUDE.md
• Check typography scale, spacing, semantic colors, a11y
• Fix any design violations

Skip condition: No UI/component files were created or modified.

Phase 6: Simplify

Invoke: code-simplifier:code-simplifier

• Simplify and refine recently modified code
• Focus on clarity, consistency, maintainability
• Preserve all functionality

Skip condition: None.

Phase 7: CodeRabbit Review

Command: coderabbit review --plain --type committed

Review loop (max 3 iterations):

Iteration 1: Run coderabbit review --plain --type committed
  |-- No actionable findings --> Proceed to Phase 8
  +-- Has findings --> Fix them, commit fixes
       |
       Iteration 2: Run coderabbit review --plain --type committed
         |-- No actionable findings --> Proceed to Phase 8
         +-- Has findings --> Fix them, commit fixes
              |
              Iteration 3: Run coderabbit review --plain --type committed
                |-- No actionable findings --> Proceed to Phase 8
                +-- Still has findings --> Report to user for manual decision

Important: Use --type committed to review all committed changes on the branch. Parse the output for actionable suggestions vs informational notes. Only fix actionable items.

Skip condition: None.

Phase 8: Verify (Local)

Invoke: superpowers:verification-before-completion

• Set a symlink to .env.local so you can run tests in the worktree with access to env vars
• Run all relevant tests: pnpm test && pnpm test:db && pnpm test:e2e, pnpm typecheck, pnpm lint, pnpm build
• Confirm ALL pass with actual output evidence
• Never claim "tests pass" without running them
• If any check fails: Fix the issue, commit the fix, re-run. Loop locally until green before proceeding. Max 5 local fix iterations — if still failing after 5, report to user.
• Update progress.md with verification results

Skip condition: None. Evidence before assertions, always.

Pha