fp-plan

FP Plan Skill

Create plans and break them down into trackable issues.

Prerequisites

Before using fp commands, check setup:

# Check if fp is installed
fp --version

If fp is not installed, tell the user:

The fp CLI is not installed. Install it with:

curl -fsSL https://setup.fp.dev/install.sh | sh -s

# Check if project is initialized
fp tree

If project is not initialized, ask the user if they want to initialize:

This project hasn't been initialized with fp. Would you like to initialize it?

If yes:

fp init

---

When This Skill Triggers

1. User asks to "create a plan", "break down feature", "design implementation"
2. User pastes a Linear, GitHub, or Notion URL (import external issue/doc)
3. User runs /plan with no arguments (interactive plan import from ~/.claude/plans/)

---

Importing from External Sources

Detecting URLs

When user pastes a URL, detect the source and fetch content:

GitHub Issues (github.com/owner/repo/issues/123):

gh issue view <url> --json title,body,labels,state

Linear Issues (linear.app/team/issue/TEAM-123): Extract the issue ID (e.g., TEAM-123) from the URL, then use the get_issue MCP tool from the Linear server.

Notion Pages (notion.so/...): Use the notion-fetch MCP tool from the Notion server with the full URL or page ID.

After Fetching

Create an FP issue from the extracted content:

fp issue create \
  --title "<extracted title>" \
  --description "<extracted body/content>"

Then offer to break it down into subtasks (see Planning Workflow below).

---

Interactive Plan Import (when /plan invoked alone)

When user runs /plan with no additional text:

1. Check for existing plans:

   ls -la ~/.claude/plans/*.md 2>/dev/null
   

2. If plans exist, use AskUserTool to prompt:

   Found plans in ~/.claude/plans/:

   1. moonlit-brewing-lynx.md
   2. swift-falcon-auth.md
   3. [Create new plan instead]

   Which plan would you like to import?

3. Parse the selected plan:

   • Extract title from first # heading
   • Strip "Plan: " prefix if present
   • Identify numbered lists or ## sections as potential subtasks

4. Create issues:

   • Parent issue with full plan content as description
   • Subtasks for each identified section/step

---

Planning Workflow

Core Concept: Plans are Issues

In FP, a plan is just an issue that:

• Has a comprehensive description (the plan document)
• Has child issues (the tasks/subtasks)
• May have dependencies between children

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)

Typical depth: 2-3 levels (Plan → Task → Subtask).

Dependency Modeling

• Serial: Task B depends on Task A (--depends)
• Parallel: No dependencies (can run concurrently)
• Fan-out/Fan-in: Multiple dependencies

---

Step-by-Step Planning

Step 1: Create the Plan Issue

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

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 <PREFIX>-1.

Step 2: Break Down Into Tasks

# Foundation: Data models
fp issue create \
  --title "Design and implement data models" \
  --parent <PREFIX>-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"

Creates <PREFIX>-2 as child of <PREFIX>-1.

# OAuth integration (depends on data models)
fp issue create \
  --title "Implement GitHub OAuth flow" \
  --parent <PREFIX>-1 \
  --depends "<PREFIX>-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)"

Creates <PREFIX>-3, dependent on <PREFIX>-2.

# Session management (depends on models + OAuth)
fp issue create \
  --title "Implement session management" \
  --parent <PREFIX>-1 \
  --depends "<PREFIX>-2,<PREFIX>-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

Files:
- src/auth/session.ts (new)
- src/middleware/auth.ts (new)"

Creates <PREFIX>-4, dependent on both <PREFIX>-2 and <PREFIX>-3.

# Frontend UI (depends on session management)
fp issue create \
  --title "Add login UI components" \
  --parent <PREFIX>-1 \
  --depends "<PREFIX>-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)"

Creates <PREFIX>-5, dependent on <PREFIX>-4.

# Testing and docs (depends on implementation)
fp issue create \
  --title "Testing and documentation" \
  --parent <PREFIX>-1 \
  --depends "<PREFIX>-4,<PREFIX>-5" \
  --description "Write tests and documentation:
- Unit tests for auth logic
- Integration tests for OAuth flow
- Update README with setup instructions

Files:
- src/auth/__tests__/*.test.ts (new)
- README.md
- .env.example"

Creates <PREFIX>-6, dependent on <PREFIX>-4 and <PREFIX>-5.

Step 3: Visualize and Verify

fp tree

Shows full hierarchy. Expected output:

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

To focus on just the plan you created:

fp tree <PREFIX>-1

To see only remaining work:

fp tree --status todo

Step 4: Iterate and Refine

# Add missing dependency
fp issue update --depends "<PREFIX>-2,<PREFIX>-4" <PREFIX>-5

# Break down large task further
fp issue create \
  --title "OAuth callback handler" \
  --parent <PREFIX>-3 \
  --description "Handle OAuth callback and exchange code for token"

fp issue create \
  --title "GitHub user info fetcher" \
  --parent <PREFIX>-3 \
  --description "Fetch user profile from GitHub API"

# Document the breakdown
fp comment <PREFIX>-3 "Broke down into sub-tasks: <PREFIX>-10, <PREFIX>-11"

---

Best Practices

Make Tasks Atomic

Each task should:

• Be completable in one work session (1-3 hours)
• Have a clear definition of "done"
• Touch a small, focused set of files

Write Clear Descriptions

Include:

• What: Brief summary of the task
• Why: Context or rationale
• How: Technical approach or key steps
• Files: Where the work happens
• Done: Definition of done

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]
Files: [Key files to modify]
Done: [Definition of done]
"

---

Updating Plans Mid-Execution

Adding New Tasks

fp issue create \
  --title "Add token refresh logic" \
  --parent <PREFIX>-1 \
  --depends "<PREFIX>-3"

# Update dependent tasks
fp issue update --depends "<PREFIX>-2,<PREFIX>-3,<PREFIX>-7" <PREFIX>-4

Adjusting Dependencies

# Replace entire dependency list
fp issue update --depends "<PREFIX>-2" <PREFIX>-5

# To add without removing, include all existing + new
fp issue show <PREFIX>-5  # Check current deps
fp issue update --depends "<PREFIX>-2,<PREFIX>-4,<PREFIX>-6" <PREFIX>-5

Splitting Large Tasks

# Create sub-tasks
fp issue create --title "OAuth redirect handler" --parent <PREFIX>-3
fp issue create --title "OAuth callback handler" --parent <PREFIX>-3 --depends "<PREFIX>-10"
fp issue create --title "User info fetcher" --parent <PREFIX>-3 --depends "<PREFIX>-11"

# Document
fp comment <PREFIX>-3 "Broke down into sub-tasks: <PREFIX>-10, <PREFIX>-11, <PREFIX>-12"

---

Anti-Patterns

❌ Using markdown task lists instead of subissues

# BAD: Checkboxes in description
- [ ] Create directory
- [ ] Set up package.json
- [ ] Configure build

Checkboxes aren't trackable. Create proper subissues instead:

# GOOD
fp issue create --title "Create directory" --parent <PREFIX>-1
fp issue create --title "Set up package.json" --parent <PREFIX>-1 --depends "<PREFIX>-2"
fp issue create --title "Configure build" --parent <PREFIX>-1 --depends "<PREFIX>-3"

❌ Creating orphan tasks

# BAD: Unconnected tasks
fp issue create --title "Add OAuth"
fp issue create --title "Add session logic"

# GOOD: Hierarchy
fp issue create --title "Authentication system"
fp issue create --title "Add OAuth" --parent <PREFIX>-1
fp issue create --title "Add session logic" --parent <PREFIX>-1 --depends "<PREFIX>-2"

❌ Ignoring dependencies

# BAD: No dependencies
fp issue create --title "Frontend UI" --parent <PREFIX>-1
fp issue create --title "Backend API" --parent <PREFIX>-1

# GOOD: Explicit order
fp issue create --title "Backend API" --parent <PREFIX>-1
fp issue create --title "Frontend UI" --parent <PREFIX>-1 --depends "<PREFIX>-2"

❌ Monolithic tasks

# BAD: Entire feature as one task
fp issue create --title "Build authentication system"

# GOOD: Decomposed
fp issue create --title "Authentication system"
fp issue create --title "OAuth integration" --parent <PREFIX>-1
fp issue create --title "Session management" --parent <PREFIX>-1
fp issue create --title "Auth middleware" --parent <PREFIX>-1

---

Quick Reference

Planning Checklist

• Create parent issue with clear goals
• Break into atomic subtasks (--parent)
• Model dependencies (--depends)
• Write clear descriptions
• Visualize with fp tree
• Never use - [ ] checkbox lists

Key Commands

fp issue create --title "..." --parent <id> --depends "<ids>" --description "..."
fp issue update --depends "<ids>" <id>
fp tree
fp issue show <id>
fp comment <id> "message"