flow-planner

name	flow-planner
description	Plan phases, tasks, and iterations. Use when structuring new work, adding features, or organizing development plans.

Flow Planner

Help users plan and structure new work using Flow framework. Guide task structure decisions (standalone vs iterations) and suggest brainstorming for complex features.

When to Use This Skill

Activate when the user wants to add new work:

• "Add a new task"
• "Plan this feature"
• "Create iterations for..."
• "Break this down into steps"
• "How should we structure this?"
• "Add this to the plan"

Planning Philosophy

Flow's Core Principle: Plan before code. Structure work hierarchically (phases → tasks → iterations) with clear boundaries.

Key Decision: Every task is EITHER:

• Standalone - Direct action items, no iterations
• Task with Iterations - No direct action items, ONLY iterations

NEVER mix both - This is the Golden Rule.

Task Structure Decision Tree

User wants to add work
    ↓
Is it complex/multi-step?
    ↓
YES → Task with Iterations
    Break into 3-5 iterations
    Each iteration = milestone
    ↓
NO → Standalone Task
    Direct action items
    Complete in one go

When to Suggest Brainstorming

Always suggest brainstorming for:

• Complex features with multiple approaches
• Architectural decisions needed
• Integration with external systems
• Performance-critical features
• Database schema changes
• API contract design
• Security-sensitive features

Skip brainstorming for:

• Simple additions (new file, basic function)
• Well-defined tasks (clear requirements)
• Repetitive work (similar to previous tasks)
• Bug fixes with obvious solutions

Brainstorming Subject Resolution Types

When users DO need brainstorming, help them understand how subjects get resolved:

Type A: Pre-Implementation Task

When: Small blocking code change needed BEFORE iteration starts

Criteria: Required for iteration (blocking), small scope (< 30 min), can be done independently

Examples: Fix interface, rename file, update enum, fix bug

What happens: Action items go into "Pre-Implementation Tasks" section, must complete BEFORE main implementation

Type B: Immediate Documentation

When: Architectural decision that affects system design

Criteria: No code changes yet, updates PLAN.md Architecture section NOW

Examples: Design pattern choice, API contract, data model

What happens: AI updates PLAN.md immediately during brainstorming

Type C: Auto-Resolved

When: Subject answered by another subject's decision

Criteria: No independent decision needed, cascade from another subject

What happens: No action items, just note which subject resolved this

Type D: Iteration Action Items

When: Substantial feature work that IS the iteration

Criteria: Main implementation work, takes significant time (> 30 min)

Examples: Build API endpoint, implement validator, create service

What happens: These action items become the iteration's implementation action items

Complexity Indicators

Simple Task (No Brainstorming)

Indicators: Single file change, clear requirements, no integration points, < 1 hour, similar to previous work

Examples: "Add validation function", "Fix typo", "Export function", "Add logging"

Guidance: "This looks straightforward - standalone task with direct action items. No brainstorming needed."

Complex Task (Needs Brainstorming)

Indicators: Multiple approaches possible, affects architecture, integration needed, > 4 hours, user unsure

Examples: "Add authentication", "Integrate Stripe", "Implement caching", "Design database"

Guidance: "This is complex - I recommend brainstorming first. Let's discuss: [list 3-5 subjects]."

Borderline Task (Ask User)

Indicators: Moderate complexity (2-4 hours), some design decisions, user hasn't expressed preference

Examples: "Add error handling to API", "Refactor data layer", "Implement search"

Guidance: "This could go either way. We could brainstorm first, or jump into iterations if you have a clear vision. Which do you prefer?"

Step-by-Step Planning Workflow

Step 1: Understand the Request

Ask clarifying questions:

• "What's the goal of this feature?"
• "Are there any constraints or requirements?"
• "Does this build on existing work?"

Step 2: Determine Complexity

Simple → Standalone task Complex → Task with iterations Uncertain → Suggest brainstorming first

Step 3: Propose Structure

Present options to user:

I suggest structuring this as:

**Option A: Standalone Task** - "Add Feature X"
- Direct action items
- Single completion
- Estimated: 1-2 hours

**Option B: Task with 3 Iterations**
- Iteration 1: Basic implementation
- Iteration 2: Add advanced features
- Iteration 3: Polish and optimize
- Estimated: 4-6 hours

Which approach fits better?

Step 4: Create the Structure

Read DASHBOARD.md to find current phase and task count, then create appropriate files:

For new phase: Create .flow/phase-N/ directory, update DASHBOARD.md with new phase entry

For new task: Create .flow/phase-N/task-M.md, add to DASHBOARD.md progress overview

For new iteration: Add iteration section to existing task file

Use templates from TEMPLATES.md for proper structure.

Step 5: Add Context

Help user fill in:

• Purpose: Why this task exists
• Dependencies: What it requires/blocks
• Design Notes: Key considerations
• Action Items: Concrete steps (standalone) or iteration goals (with iterations)

Starting Work (Phase/Task)

Starting a Phase

When user wants to begin work on a phase:

1. Read DASHBOARD.md to find the phase
2. Verify phase status is ⏳ PENDING (not already 🚧 IN PROGRESS)
3. Update DASHBOARD.md:
   • Change phase status from ⏳ PENDING to 🚧 IN PROGRESS
   • Update "Current Work" section to point to this phase
4. Report to user: "Phase N: [Name] is now in progress. Starting with Task 1."

Starting a Task

When user wants to begin work on a task:

1. Read DASHBOARD.md to find the task
2. Verify task status is ⏳ PENDING (not already 🚧 IN PROGRESS)
3. Update task file:
   • Change **Status**: ⏳ PENDING to **Status**: 🚧 IN PROGRESS
4. Update DASHBOARD.md:
   • Change task status marker from ⏳ to 🚧
   • Update "Current Work" section to point to this task
5. Report to user: "Task N: [Name] is now in progress. [Guidance on first step]"

Next Action Suggestions

When user asks "what's next" or "what should I work on":

If Nothing In Progress

Read DASHBOARD.md to find next ⏳ PENDING item:

• If current phase has pending tasks → "Start Task N: [Name]"
• If current phase complete → "Start Phase N+1: [Name]"
• If project complete → "All work complete! 🎉"

If Work In Progress

Read current work context:

• If task has pending iterations → "Continue with Iteration N"
• If iteration needs planning → "Add iterations to break down the work"
• If unclear → "What aspect would you like to work on next?"

Task Structure Patterns

See TEMPLATES.md for complete templates:

• Standalone Task: Direct action items, no iterations
• Task with Iterations: Skeleton → Veins → Flesh pattern
• Task with Brainstorming: Design decisions first, then implementation

Best Practices

1. Always clarify complexity - Don't assume, ask user
2. Suggest iterations for complex work - Better to break down than have massive tasks
3. Propose brainstorming when uncertain - Design first, implement second
4. Use Flow's metaphor - Skeleton → Veins → Flesh
5. Keep iterations focused - Each should have clear goal and completion criteria

Task Structure Golden Rules

DO:

• ✅ Standalone task with action items
• ✅ Task with iterations (no direct action items)
• ✅ Each iteration has specific goal
• ✅ Iterations build on each other

DON'T:

• ❌ Mix action items and iterations in same task
• ❌ Create task with only 1 iteration (make it standalone)
• ❌ Make iterations too large (break down further)
• ❌ Skip brainstorming for complex features

Iteration Sizing Guidelines

Good Iteration Size:

• Completable in 1-2 hours
• Clear completion criteria
• Testable milestone
• Adds incremental value

Too Large (split into multiple iterations):

• "Implement entire feature"
• "Build and test everything"
• No clear milestone

Too Small (combine or make standalone):

• "Add one line of code"
• "Rename a variable"
• Trivial changes

Examples

Example 1: User Asks to Add Feature

User: "I want to add real-time notifications"

AI Process:
1. Assess complexity: Complex feature (WebSocket, multiple components)
2. Suggest structure: Task with 3 iterations
3. Propose brainstorming: Technology choice, message format, persistence
4. Create task file with iteration structure

Structure Created:
**Task: Real-Time Notifications** (3 iterations)

**Iteration 1: Skeleton - WebSocket Connection**
- Goal: Establish basic WebSocket connection
- Set up WebSocket server, implement client connection, basic keepalive

**Iteration 2: Veins - Notification System**
- Goal: Core notification sending/receiving
- Design message format, server-side broadcast, client-side handlers

**Iteration 3: Flesh - UI & Polish**
- Goal: User-facing notification display
- Create UI component, add history, implement dismiss/mark-read

Before Starting:
Suggest brainstorming: WebSocket library choice (ws, socket.io, native)? Notification types? Persistence strategy?

Example 2: User Asks to Fix Bug

User: "The search filter isn't working correctly"

AI Process:
1. Assess complexity: Simple bug fix (focused scope)
2. Suggest structure: Standalone task
3. Skip brainstorming: Clear requirements
4. Create task file with action items

Task Created:
**Task: Fix Search Filter Bug**

**Action Items**:
- [ ] Reproduce bug with test case
- [ ] Debug filter logic
- [ ] Identify root cause (likely query building)
- [ ] Implement fix
- [ ] Add unit test for this scenario
- [ ] Verify fix resolves issue

Estimated: 1-2 hours

Example 3: Guiding Brainstorming Subject Resolution

User: "Let's brainstorm the retry logic for API calls"

AI Response:
Great! Let me suggest subjects to discuss:

Subjects:
1. Retry Strategy - Exponential backoff vs fixed delay?
2. Error Classification - Which errors trigger retry?
3. Max Retry Attempts - How many before giving up?
4. Existing Error Handler - Need to update ErrorHandler.ts for async?
5. Timeout Configuration - Per-request vs total operation?

I'll help categorize each decision by resolution type (A/B/C/D).

---

[After discussing Subject 4...]

User: "We need to update ErrorHandler.ts to support async operations"

AI Response:
This is Type A (Pre-Implementation Task):

✅ Blocking? YES - Can't implement retry without async support
✅ Small? YES - Estimated 20-30 minutes
✅ Independent? YES - Self-contained change

Resolution Type: A

Action Items (Pre-Implementation):
- [ ] Update ErrorHandler.ts to support async operations
- [ ] Add retryAsync() method
- [ ] Update 3 existing call sites
- [ ] Add tests for async error handling

Must complete BEFORE running implementation.

---

[After discussing Subject 1...]

User: "Let's use exponential backoff with base delay of 1 second"

AI Response:
This is Type D (Iteration Action Items):

✅ Substantial work? YES - Core feature implementation
✅ Takes > 30 min? YES - Estimated 2-3 hours
✅ Main iteration work? YES - This IS what we're building

Resolution Type: D

Action Items (Implementation):
- [ ] Create RetryPolicy class
- [ ] Implement exponential backoff algorithm (base: 1s, max: 32s)
- [ ] Add configuration for max retries (default: 3)
- [ ] Integrate with API client
- [ ] Add tests for retry scenarios

These become the iteration's implementation action items.

Files Read/Write

READ:

• .flow/DASHBOARD.md - Find current phase, count tasks, check structure
• .flow/phase-N/task-M.md - Existing tasks (when adding iterations)

WRITE:

• .flow/phase-N/ - Create new phase directories
• .flow/phase-N/task-M.md - Create new task files, add iterations
• .flow/DASHBOARD.md - Add tasks/phases to progress overview, update status

Validation Gates

• Before adding phase: Verify previous phase has at least one task
• Before adding task: Verify phase directory exists
• Before starting task/phase: Verify not already IN PROGRESS
• Before adding iteration: Verify task file exists

References

• Task Structure Rules: TEMPLATES.md - Complete templates for all task types
• Framework Reference: .flow/framework/DEVELOPMENT_FRAMEWORK.md lines 238-566 (Task structure)
• Brainstorming Pattern: .flow/framework/DEVELOPMENT_FRAMEWORK.md lines 1167-1797