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

• User asks to "create a plan", "break down feature", "design implementation"

• User pastes a Linear, GitHub, or Notion URL (import external issue/doc)

• 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:

Check for existing plans:

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

If plans exist, use AskUserTool to prompt:

Found plans in ~/.claude/plans/:

• moonlit-brewing-lynx.md

• swift-falcon-auth.md

• [Create new plan instead]

Which plan would you like to import?

Parse the selected plan:

• Extract title from first # heading

• Strip "Plan: " prefix if present

• Identify numbered lists or ## sections as potential subtasks

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"