FP Planning Skill

Plan creation and breakdown patterns for the FP CLI

Core Planning Concepts

Plans as Issues

Key insight: In FP, plans are just elaborate issues. There's no separate "plan" entity.

A plan is an issue that:

• Has a comprehensive description (the plan document)

• Has child issues (the tasks/sub-tasks)

• May have dependencies between children

• Starts with status "todo" and transitions to "done" when all children are done

Issue Hierarchy

Plan (Parent Issue) ├── Task 1 (Child Issue) │ ├── Sub-task 1.1 (Grandchild) │ └── Sub-task 1.2 (Grandchild) ├── Task 2 (Child Issue) └── Task 3 (Child Issue)

You can nest as deep as needed, but 2-3 levels is typical:

• Level 1: Plan/Epic

• Level 2: Feature/Task

• Level 3: Sub-task/Implementation step

Dependency Modeling

Issues can depend on other issues at any level:

• Serial: Task B depends on Task A (must be sequential)

• Parallel: Tasks A and B have no dependencies (can be concurrent)

• Fan-out: Tasks B and C both depend on Task A

• Fan-in: Task D depends on both B and C

Dependencies are directional: "FP-3 depends on FP-2" means FP-2 must complete before FP-3 can start.

Planning Workflow

Phase 1: Create the Plan Issue

Start with the top-level plan/epic:

fp issue create
--title "Add user authentication system"
--description "Implement OAuth2 authentication with GitHub provider.

Goals:

• Support GitHub OAuth login
• Store user sessions securely
• Provide middleware for protected routes
• Handle token refresh

Technical approach:

• Use Cloudflare D1 for session storage
• OAuth2 library for GitHub integration
• JWT tokens for session management

Success criteria:

• Users can log in with GitHub
• Sessions persist across requests
• Protected routes require authentication"

This creates FP-1 (or whatever the next ID is).

Phase 2: Break Down Into Tasks

Identify major components/phases:

Foundation: Data models

fp issue create
--title "Design and implement data models"
--parent FP-1
--description "Create TypeScript schemas and database tables for User, Session, and Token models.

Details:

• User model: id, githubId, email, name, avatarUrl
• Session model: id, userId, token, expiresAt
• Token model: id, userId, accessToken, refreshToken, expiresAt

Files to modify:

• src/models/user.ts
• src/models/session.ts
• src/models/token.ts
• drizzle/schema.ts"

This creates FP-2 as a child of FP-1.

OAuth integration

fp issue create
--title "Implement GitHub OAuth flow"
--parent FP-1
--depends "FP-2"
--description "Set up OAuth2 flow with GitHub:

• Redirect to GitHub authorization
• Handle callback with authorization code
• Exchange code for access token
• Fetch user info from GitHub API

Files:

• src/auth/oauth.ts (new)
• src/routes/auth.ts (new)"

This creates FP-3 as a child of FP-1, dependent on FP-2.

Session management

fp issue create
--title "Implement session management"
--parent FP-1
--depends "FP-2,FP-3"
--description "Create session creation, validation, and cleanup logic.

Features:

• Create session on successful login
• Validate session on each request
• Refresh expired sessions
• Clean up old sessions (cron job)

Files:

• src/auth/session.ts (new)
• src/middleware/auth.ts (new)"

This creates FP-4, dependent on both FP-2 and FP-3.

Frontend UI

fp issue create
--title "Add login UI components"
--parent FP-1
--depends "FP-4"
--description "Create React components for authentication:

• Login button (redirects to OAuth)
• User profile dropdown
• Logout button

Files:

• app/components/LoginButton.tsx (new)
• app/components/UserProfile.tsx (new)
• app/components/LogoutButton.tsx (new)"

This creates FP-5, dependent on FP-4.

Testing and docs

fp issue create
--title "Testing and documentation"
--parent FP-1
--depends "FP-4,FP-5"
--description "Write tests and documentation:

• Unit tests for auth logic
• Integration tests for OAuth flow
• Update README with setup instructions
• Add environment variable documentation

Files:

• src/auth/tests/*.test.ts (new)
• README.md
• .env.example"

This creates FP-6, dependent on both FP-4 and FP-5.

Phase 3: Visualize and Verify

fp tree

You should see:

FP-1 [todo] Add user authentication system ├── FP-2 [todo] Design and implement data models ├── FP-3 [todo] Implement GitHub OAuth flow │ └── blocked by: FP-2 ├── FP-4 [todo] Implement session management │ └── blocked by: FP-2, FP-3 ├── FP-5 [todo] Add login UI components │ └── blocked by: FP-4 └── FP-6 [todo] Testing and documentation └── blocked by: FP-4, FP-5

Phase 4: Iterate and Refine

Review the plan:

• Are dependencies correct?

• Are any tasks too large? (If so, break them down further)

• Are descriptions clear enough?

Add missing dependency

fp issue update --depends "FP-2,FP-4" FP-5

Break down large task

fp issue create
--title "OAuth callback handler"
--parent FP-3
--description "Handle OAuth callback and exchange code for token"

fp issue create
--title "GitHub user info fetcher"
--parent FP-3
--description "Fetch user profile from GitHub API"

Update descriptions

fp issue edit FP-2 # Opens in $EDITOR

Planning Best Practices

1. Start Top-Down

Begin with the high-level goal, then decompose:

• Level 1: What is the overall feature/goal?

• Level 2: What are the major components?

• Level 3: What are the implementation steps?

2. Make Tasks Atomic

Each task should:

• Be completable in one work session (1-3 hours)

• Have a clear definition of "done"

• Produce testable output

• Touch a small, focused set of files

If a task feels too big, break it down further.

3. Identify Dependencies Early

Ask:

• Does this task need data structures from another task?

• Does this task need APIs/functions from another task?

• Can this task be done in parallel with others?

Model dependencies explicitly:

fp issue update --depends "FP-Y,FP-Z" FP-X

4. Write Clear Descriptions

Good descriptions include:

• What: Brief summary of the task

• Why: Context or rationale (if not obvious)

• How: Technical approach or key steps

• Files: Where the work happens

• Definition of Done: How to know it's complete

Example:

Implement rate limiting middleware

Why: Protect API endpoints from abuse How: Use Cloudflare's built-in rate limiting or token bucket algorithm Files: src/middleware/ratelimit.ts Done:

• Middleware blocks requests exceeding 100/minute
• Responds with 429 status code
• Tests verify rate limit enforcement

5. Plan for Testing and Docs

Always include tasks for:

• Unit tests

• Integration tests

• Documentation updates

• Configuration/environment setup

These often depend on implementation tasks being complete.

Common Planning Patterns

For detailed patterns with examples, see references/patterns.md :

• Foundation → Implementation → Integration

• Vertical Slices

• Parallel Tracks

• Research → Implementation

• Incremental Feature Flags

Updating Plans Mid-Execution

Plans often evolve as work progresses:

Adding New Tasks

Discovered new requirement

fp issue create
--title "Add token refresh logic"
--parent FP-1
--depends "FP-3"

Update dependent tasks

fp issue update --depends "FP-2,FP-3,FP-7" FP-4

Adjusting Dependencies

Realized FP-5 doesn't need FP-4 after all

fp issue update --depends "FP-2" FP-5 # This replaces the entire dependency list

To add a dependency (without removing existing), you need to include all:

fp issue show FP-5 # Check current dependencies fp issue update --depends "FP-2,FP-4,FP-6" FP-5 # Include old + new

Splitting Large Tasks

FP-3 turned out to be too big

Create sub-tasks

fp issue create --title "OAuth redirect handler" --parent FP-3 fp issue create --title "OAuth callback handler" --parent FP-3 fp issue create --title "User info fetcher" --parent FP-3

Add comment to original

fp comment FP-3 "Broke down into sub-tasks: FP-10, FP-11, FP-12"

Keep FP-3 as umbrella, or mark as Done when children are done

Reordering Work

Need to work on FP-5 before FP-4

Update dependencies to reflect new order

fp issue update --depends "FP-2,FP-5" FP-4 fp issue update --depends "FP-2" FP-5

Document why

fp comment FP-1 "Reordered plan: UI mockups (FP-5) before backend (FP-4) to get design feedback early"

Collaborative Planning

Human + Agent Planning

Phase 1: Human creates outline

Human creates the plan issue with high-level goals

fp issue create --title "Add real-time notifications" --description "[detailed goals]"

Phase 2: Agent elaborates The agent (you) can:

• Break down into technical tasks

• Add dependencies

• Identify files

• Suggest implementation approach

Agent adds structured tasks

fp issue create --title "WebSocket connection handler" --parent FP-1 fp issue create --title "Notification data model" --parent FP-1

... etc

Phase 3: Human reviews and adjusts

Human updates based on business constraints

fp issue update --depends "FP-2,FP-7" FP-3 fp comment FP-1 "Updated plan: need to integrate with existing notification system (FP-7)"

Multi-Agent Planning

Multiple agents can contribute to planning:

Agent 1 (swift-falcon): Creates foundation

fp issue create --title "Plan feature X" --parent FP-1

Agent 2 (calm-otter): Adds backend tasks

fp issue create --title "Backend API" --parent FP-1 fp comment FP-1 "Added backend tasks (FP-10-FP-13)"

Agent 3 (quick-lemur): Adds frontend tasks

fp issue create --title "UI components" --parent FP-1 --depends "FP-10" fp comment FP-1 "Added frontend tasks (FP-14-FP-16)"

Track contributions via activity log:

fp log FP-1

Plan Templates

For ready-to-use templates, see references/templates.md :

• Full-Stack Feature

• Bug Fix

• Refactoring

• Performance Optimization

Anti-Patterns (Avoid These)

❌ Using markdown task lists instead of subissues

BAD: Task checkboxes in issue description

Tasks

• Create apps/fp-vscode directory
• Set up package.json with extension manifest
• Configure esbuild to bundle extension
• Create extension.ts with activate/deactivate

This is wrong because:

• Checkboxes are not trackable by the FP system

• No dependencies can be modeled

• No status, assignee, or activity tracking

• Agents cannot pick up individual tasks

GOOD: Create proper subissues

fp issue create --title "Create apps/fp-vscode directory" --parent FP-1 fp issue create --title "Set up package.json with extension manifest" --parent FP-1 --depends "FP-2" fp issue create --title "Configure esbuild to bundle extension" --parent FP-1 --depends "FP-3" fp issue create --title "Create extension.ts with activate/deactivate" --parent FP-1 --depends "FP-4"

Rule: NEVER write - [ ] task lists in issue descriptions. Always create subissues with --parent .

❌ Creating tasks without parent

BAD: Orphan tasks

fp issue create --title "Add OAuth" fp issue create --title "Add session logic"

These are unconnected

GOOD: Hierarchy

fp issue create --title "Authentication system" fp issue create --title "Add OAuth" --parent FP-1 fp issue create --title "Add session logic" --parent FP-1 --depends "FP-2"

❌ Ignoring dependencies

BAD: No dependencies specified

fp issue create --title "Frontend auth UI" --parent FP-1 fp issue create --title "Backend auth API" --parent FP-1

Can UI be built before API? Probably not.

GOOD: Explicit dependencies

fp issue create --title "Backend auth API" --parent FP-1 fp issue create --title "Frontend auth UI" --parent FP-1 --depends "FP-2"

❌ Vague descriptions

BAD: Unclear task

fp issue create --title "Do the auth stuff" --parent FP-1

GOOD: Specific task

fp issue create
--title "Implement GitHub OAuth callback handler"
--parent FP-1
--description "Handle OAuth redirect, exchange code for token, create session"

❌ Monolithic tasks

BAD: Huge task

fp issue create --title "Build entire authentication system" --parent FP-1

This is not a task, it's the whole feature!

GOOD: Decomposed

fp issue create --title "Authentication system" fp issue create --title "OAuth integration" --parent FP-1 fp issue create --title "Session management" --parent FP-1 fp issue create --title "Auth middleware" --parent FP-1

... etc

Quick Reference

Planning Checklist

• Create parent/plan issue with clear goals

• Break down into atomic subissues with --parent (1-3 hours each)

• Never use - [ ] task lists - always create proper subissues

• Specify dependencies between tasks

• Write clear descriptions (what, why, how, done)

• Include testing and documentation tasks

• Visualize with fp tree to verify structure

Task Creation Template

fp issue create
--title "[Clear, specific title]"
--parent "[Parent issue ID]"
--depends "[Comma-separated dependency IDs]"
--priority "[low|medium|high|critical]"
--description " What: [What needs to be done] Why: [Context or rationale] How: [Technical approach] Done: [Definition of done] "

Priority is optional. Use it to indicate urgency:

• critical

• Blocking other work or urgent fix

• high

• Important, should be done soon

• medium

• Normal priority

• low

• Nice to have, can wait

Dependency Analysis Questions

• Does this task need data structures from another task?

• Does this task need APIs/functions from another task?

• Can this task be done in parallel with others?

• What needs to be done before this can start?

• What is blocked by this task?

Integration with Workflow

Planning and workflow are two sides of the same process:

Planning Phase

Use this skill to:

• Create issue hierarchy

• Model dependencies

• Write clear descriptions

Execution Phase

Use the fp-workflow skill to:

• Find next actionable task (no blockers)

• Claim work

• Log progress

• Update status

• Hand off

Feedback Loop

During execution, update the plan:

Discovered new dependency

fp issue update --depends "FP-2,FP-4,FP-8" FP-5 fp comment FP-5 "Added dependency on FP-8: need shared utility functions"

Task is too big - break it down

fp issue create --title "Subtask A" --parent FP-5 fp issue create --title "Subtask B" --parent FP-5 fp comment FP-5 "Broke down into FP-15, FP-16"

Summary

Effective planning with FP:

• Start with the goal - Create a parent issue with clear objectives

• Decompose hierarchically - Break into manageable tasks

• Model dependencies - Make execution order explicit

• Write clear descriptions - What, why, how, and done

• Include testing and docs - Plan for quality and knowledge sharing

• Iterate as you learn - Update the plan based on implementation discoveries

• Visualize with fp tree

• Verify structure and dependencies

A good plan enables agents to:

• Understand the full scope

• Pick up work autonomously

• Work in parallel

• Track progress objectively

• Hand off seamlessly

Remember: Plans are living documents. Update them as you learn during implementation.