fp-plan

FP Plan Skill

計画を作成し、追跡可能な課題に分割します。

前提条件

fp コマンドを使う前に、セットアップを確認してください。

# Check if fp is installed
fp --version

fp がインストールされていない場合は、ユーザーに次のように伝えてください。

fp CLI がインストールされていません。次のコマンドでインストールしてください。

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

# Check if project is initialized
fp tree

プロジェクトが初期化されていない場合は、初期化するかどうかをユーザーに尋ねてください。

このプロジェクトは fp で初期化されていません。初期化しますか？

「はい」の場合：

fp init

---

このスキルが起動する条件

1. ユーザーが「計画を作成」「機能を分割」「実装を設計」と依頼した場合
2. ユーザーが Linear、GitHub、Notion の URL を貼り付けた場合（外部の課題やドキュメントをインポート）
3. ユーザーが引数なしで /plan を実行した場合（~/.claude/plans/ から対話形式で計画をインポート）

---

外部ソースからのインポート

URL の検出

ユーザーが URL を貼り付けたら、ソースを検出してコンテンツを取得します。

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）： URL から課題 ID（例：TEAM-123）を抽出し、Linear サーバーの get_issue MCP ツールを使用します。

Notion Pages（notion.so/...）： Notion サーバーの notion-fetch MCP ツールを使用し、完全な URL またはページ ID を指定します。

取得後

抽出したコンテンツから FP の課題を作成します。

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

次に、サブタスクへの分割を提案します（以下の「計画ワークフロー」を参照）。

---

対話形式での計画のインポート（/plan のみを実行した場合）

ユーザーが追加のテキストなしで /plan を実行した場合：

1. 既存の計画を確認します：

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

2. 計画が存在する場合は、AskUserTool を使って次のように尋ねます。

   ~/.claude/plans/ に計画が見つかりました：

   1. moonlit-brewing-lynx.md
   2. swift-falcon-auth.md
   3. [代わりに新しい計画を作成]

   どの計画をインポートしますか？

3. 選択した計画を解析します：

   • 最初の # 見出しからタイトルを抽出します
   • 「Plan: 」の接頭辞があれば削除します
   • 番号付きリストや ## セクションをサブタスク候補として特定します

4. 課題を作成します：

   • 計画全体の内容を説明に含む親課題
   • 特定した各セクション／手順に対応するサブタスク

---

計画ワークフロー

基本概念：計画は課題です

FP では、計画は次の要素を持つ課題です。

• 包括的な説明（計画ドキュメント）
• 子課題（タスク／サブタスク）
• 子課題間の依存関係（任意）

課題の階層

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)

一般的な深さは 2～3 階層です（計画 → タスク → サブタスク）。

依存関係のモデル化

• 順次：タスク B はタスク A に依存します（--depends）
• 並列：依存関係なし（同時に実行可能）
• ファンアウト／ファンイン：複数の依存関係

---

計画の手順

ステップ 1：計画の課題を作成する

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"

これにより <PREFIX>-1 が作成されます。

ステップ 2：タスクに分割する

# 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"

<PREFIX>-1 の子として <PREFIX>-2 が作成されます。

# 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)"

<PREFIX>-2 に依存する <PREFIX>-3 が作成されます。

# 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)"

<PREFIX>-2 と <PREFIX>-3 の両方に依存する <PREFIX>-4 が作成されます。

# 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)"

<PREFIX>-4 に依存する <PREFIX>-5 が作成されます。

# 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"

<PREFIX>-4 と <PREFIX>-5 の両方に依存する <PREFIX>-6 が作成されます。

ステップ 3：可視化して確認する

fp tree

階層全体が表示されます。想定される出力：

<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

作成した計画だけに絞り込むには：

fp tree <PREFIX>-1

残作業だけを表示するには：

fp tree --status todo

ステップ 4：反復して改善する

# 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"

---

ベストプラクティス

タスクを細分化する

各タスクは次の条件を満たす必要があります。

• 1 回の作業セッション（1～3 時間）で完了できる
• 「完了」の定義が明確である
• 対象となるファイルの範囲が小さく、明確である

説明を明確に書く

次の項目を含めます。

• 内容：タスクの簡潔な概要
• 理由：背景や根拠
• 方法：技術的なアプローチや主な手順
• ファイル：作業対象の場所
• 完了：完了の定義

タスク作成テンプレート

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]
"

---

実行中の計画の更新

タスクの追加

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

依存関係の調整

# 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

大きなタスクの分割

# 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"

---

アンチパターン

❌ サブイシューの代わりに Markdown のタスクリストを使用する

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

チェックボックスでは追跡できません。適切なサブイシューを作成してください：

# 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"

❌ 親のないタスクを作成する

# 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"

❌ 依存関係を無視する

# 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"

❌ タスクを一枚岩にする

# 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

---

クイックリファレンス

計画チェックリスト

• 明確な目標を設定した親イシューを作成する
• 原子的なサブタスクに分割する（--parent）
• 依存関係をモデル化する（--depends）
• 明確な説明を書く
• fp tree で可視化する
• - [ ] のチェックボックスリストは使用しない

主なコマンド

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"