fp-plan

FP 计划技能

创建计划，并将其拆分为可跟踪的问题。

前置条件

使用 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 页面（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>-2 创建为 <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)"

创建 <PREFIX>-3，使其依赖 <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)"

创建 <PREFIX>-4，使其同时依赖 <PREFIX>-2 和 <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)"

创建 <PREFIX>-5，使其依赖 <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"

创建 <PREFIX>-6，使其同时依赖 <PREFIX>-4 和 <PREFIX>-5。

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