Local-first issue tracking and code review for humans and AI agents.
- version
- 0.11.2
- GitHub stars
- 40
Install
/plugin install fp@fiberplane-claude-code-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add fiberplane/claude-code-plugins.
Contents
Discovered from sourceSkills 3
FP Implement Skill
Find, claim, and complete work on issues.
Prerequisites
Before using fp commands, check setup:
# Check if fp is installed
fp --version
If fp is not installed, tell the user:
The
fpCLI 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
Core Workflow
1. Find work → fp tree, fp issue list --status todo
2. Claim work → fp issue update --status in-progress <PREFIX>-X
3. Do work → implement the task
4. Comment often → fp comment <PREFIX>-X "progress update"
5. Complete → fp issue update --status done <PREFIX>-X
Finding Work
See the Full Picture
fp tree
Shows all issues with hierarchy, status, and dependencies.
fp tree --status todo
Shows only todo items (filters out done work).
fp tree <PREFIX>-X
Shows a specific issue and its children - useful for focusing on one feature/epic.
List by Status
fp issue list --status todo # Available to pick up
fp issue list --status in-progress # Currently active
fp issue list --status done # Completed
fp issue list # All issues
Pick the Right Task
Look for tasks that:
- Have status
todo - Have no dependencies, OR all dependencies are
done - Match your current focus/expertise
Claiming Work
Mark as In-Progress
fp issue update --status in-progress <PREFIX>-2
This captures the current VCS state as the starting point for tracking changes.
Log That You're Starting
fp comment <PREFIX>-2 "Starting work. First step: implement the User model schema"
Load Context
fp context <PREFIX>-2
Shows issue details, description, and related information.
During Work
Comment Frequently
Log progress at key milestones:
fp comment <PREFIX>-2 "Completed schema design. Added User, Session, Token models to src/models/"
fp comment <PREFIX>-2 "Hit a snag: OAuth library doesn't support refresh tokens out of the box. Investigating alternatives."
fp comment <PREFIX>-2 "Resolved: using custom refresh logic. Proceeding with implementation."
When to comment:
- When you start a task
- When you complete a significant milestone
- When you discover important information
- When you encounter problems
- When you finish work
Check Progress
fp issue diff <PREFIX>-2 --stat # Quick view of changed files
fp issue files <PREFIX>-2 # List files changed
fp issue diff <PREFIX>-2 # Full diff
Completing Work
Mark as Done
fp issue update --status done <PREFIX>-2
This captures the current VCS state as the endpoint.
Add Completion Comment
fp comment <PREFIX>-2 "Task completed. Implemented User, Session, and Token models with Drizzle ORM. All tests passing."
Continuing Previous Work
Find In-Progress Work
fp issue list --status in-progress
Load Context
fp context <PREFIX>-5
Review Recent Activity
fp log <PREFIX>-5 --limit 5
See What's Changed
fp issue diff <PREFIX>-5 --stat
Resume
fp comment <PREFIX>-5 "Resuming work. Current focus: finishing the error handling logic"
Breaking Down Work
If a task is too large, break it down:
# Create sub-tasks
fp issue create --title "Part 1: Setup" --parent <PREFIX>-4
fp issue create --title "Part 2: Implementation" --parent <PREFIX>-4 --depends "<PREFIX>-10"
fp issue create --title "Part 3: Tests" --parent <PREFIX>-4 --depends "<PREFIX>-11"
# Document
fp comment <PREFIX>-4 "Broke down into sub-tasks: <PREFIX>-10, <PREFIX>-11, <PREFIX>-12. Working on <PREFIX>-10 first."
# Work on sub-tasks
fp issue update --status in-progress <PREFIX>-10
Viewing Changes
For a Single Issue
fp issue diff <PREFIX>-2 # Full diff since task started
fp issue diff <PREFIX>-2 --stat # Just file stats
fp issue files <PREFIX>-2 # List of changed files
For Parent Issues
For parent issues with children, these commands aggregate changes from all descendants:
fp issue diff <PREFIX>-1 --stat # All changes across child tasks
fp issue files <PREFIX>-1 # All files changed by descendants
Quick Reference
Essential Commands
# Find work
fp tree # Full hierarchy
fp tree --status todo # Only todo items
fp tree <PREFIX>-X # Focus on one issue
fp issue list --status todo # List available tasks
# Claim work
fp issue update --status in-progress <PREFIX>-X
fp context <PREFIX>-X
# Log progress
fp comment <PREFIX>-X "message"
# View changes
fp issue diff <PREFIX>-X --stat
fp issue files <PREFIX>-X
# Complete
fp issue update --status done <PREFIX>-X
# Activity
fp log --limit 10
fp log <PREFIX>-X
Status Values
todo- Not startedin-progress- Actively being worked ondone- Completed
Priority Values (optional)
critical- Blocking other workhigh- Important, do soonmedium- Normal prioritylow- Nice to have
fp issue update --priority high <PREFIX>-X
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
fpCLI 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
/planwith 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
AskUserToolto 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
- Extract title from first
-
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"
FP Review Skill
Ensure commits are properly linked to issues and provide review feedback.
Prerequisites
Before using fp commands, check setup:
# Check if fp is installed
fp --version
If fp is not installed, tell the user:
The
fpCLI 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
Core Purpose
- Verify commits are assigned to the correct issues
- Leave review comments on issues
- Open interactive review in the desktop app
- Create stories — narrative documents that walk through code changes
Assigning Commits to Issues
Check Current Assignments
fp issue files <PREFIX>-X
If empty, the issue has no commits assigned.
Find Relevant Commits
jj log --limit 20 # Jujutsu
git log --oneline -20 # Git
View Commit Details
jj show <commit-id> # Jujutsu
git show <hash> --stat # Git
Match Commits to Issues
Compare:
- Files changed in commit vs issue description
- Commit message content vs issue title
- Code changes vs issue requirements
Assign Commits
Before assigning commits, confirm with the user. Some users prefer to work without committing until they're done, or may not want commits linked to issues.
Use AskUserTool to ask:
I found these commits that appear related to
<PREFIX>-X:
abc123- Add user modeldef456- Implement auth middlewareWould you like me to assign them to the issue? (If you prefer to review uncommitted changes instead, you can run
fp reviewfor the working copy.)
If confirmed:
# Single commit
fp issue assign <PREFIX>-X --rev abc123
# Multiple commits
fp issue assign <PREFIX>-X --rev abc123,def456,ghi789
# Current HEAD
fp issue assign <PREFIX>-X
# Reset and reassign
fp issue assign <PREFIX>-X --reset
fp issue assign <PREFIX>-X --rev abc123,def456
Verify Assignment
fp issue files <PREFIX>-X
fp issue diff <PREFIX>-X --stat
Leaving Review Comments
Use fp comment for review feedback. Reference files and lines for specificity.
File-Specific Comments
fp comment <PREFIX>-X "**src/utils/parser.ts**: Consider extracting the validation logic into a separate function for testability."
fp comment <PREFIX>-X "**src/api/handler.ts:45-60**: This error handling could swallow important exceptions. Suggest re-throwing after logging."
Severity Prefixes
Use prefixes to indicate importance:
fp comment <PREFIX>-X "[blocker] **src/auth.ts**: Missing input sanitization creates SQL injection risk."
fp comment <PREFIX>-X "[suggestion] **src/utils.ts:23**: Could use optional chaining here for cleaner code."
fp comment <PREFIX>-X "[nit] **README.md**: Typo in setup instructions."
[blocker]- Must fix before merging[suggestion]- Recommended improvement[nit]- Minor/cosmetic issue
General Comments
fp comment <PREFIX>-X "Overall looks good. Main concern is the error handling in the API layer - see specific comments above."
Interactive Review (Desktop App)
fp review opens the Fiberplane desktop app for interactive diff review.
Requires the desktop app. If not installed: https://setup.fp.dev/desktop/latest/
Review Working Copy (No Commits Needed)
If the user hasn't committed yet (or prefers not to commit while work is in progress):
fp review
This shows all uncommitted changes in the working directory. No commit assignment required.
Review by Issue
fp review <PREFIX>-X
Note: For issue-based review to work, the issue must have commits assigned. If no commits are assigned, either:
- Assign commits first with
fp issue assign, OR - Use
fp reviewto review the working copy instead
Review with Story
fp review <PREFIX>-X --with-story
Opens the review with the story panel visible alongside the diff. The issue must have a story created for it.
Other Review Targets
fp review git:abc123 # Specific git commit
fp review jj:abc123 # Specific jj revision
fp review git:abc123..def456 # Range of commits
Review Workflow
Step 1: Check Assignments
fp issue files <PREFIX>-X
Step 2: Assign Missing Commits
jj log --limit 20
fp issue assign <PREFIX>-X --rev abc,def
Step 3: View the Diff
fp issue diff <PREFIX>-X --stat # Overview
fp issue diff <PREFIX>-X # Full diff
fp review <PREFIX>-X # Open in desktop app
Step 4: Leave Comments
fp comment <PREFIX>-X "**file.ts:line**: feedback"
Stories
Stories are narrative documents that walk a reviewer through code changes. They combine markdown prose with embedded diffs, file excerpts, and chat transcripts.
Requires the experimental_story feature flag:
fp feature enable experimental_story
Creating a Story
# From a file
fp story create <PREFIX>-X --file story.md
# From stdin
cat story.md | fp story create <PREFIX>-X
The first ## heading in the markdown becomes the story title.
Story Format
Stories are markdown documents that use directives to embed code artifacts:
Diff Directive
Shows file changes from the issue's assigned commits:
## Moved validation to a shared module
The old approach duplicated validation in each handler.
:::diff{file="src/validation.ts"}
Extracted from handler.ts and api.ts into a single module.
:::
file(required): relative path to the changed file- The text between
:::diffand:::is the annotation — keep it to 1-2 sentences
File Directive
Shows file content (or a slice of it):
:::file{path="src/config.ts" lines="10-25"}
The new defaults that drive the behavior change.
:::
path(required): relative path to filelines(optional): line range, e.g."10-25"
Chat Directive
Embeds excerpts from an AI coding session:
:::chat{source="claude" session="/path/to/session.jsonl" messages="msg1,msg2"}
The key design discussion that led to this approach.
:::
source:"claude","pi", or"opencode"session: full path to session filemessages: comma-separated message IDs
Writing Guidelines
- Headings are past-tense verbs — describe what was done, not what to do (e.g. "Moved validation to a shared module")
- Start with the user problem — the opening prose should explain why the change exists
- Show diff, then explain — lead with the
:::diffdirective, follow with the annotation - Annotations are 1-2 sentences — brief context, not a full explanation
UI Support
Only :::diff is fully rendered in the desktop app right now. :::file works but the collapsed attribute is ignored. The hunks attribute on :::diff is also ignored.
Managing Stories
fp story list # List all stories in the project
fp story get <story-id> # Get story details (supports ID prefix)
fp story get <PREFIX>-X # Get story by issue ID
fp story delete <story-id> # Delete a story (supports ID prefix)
fp story delete <story-id> --yes # Skip confirmation
One story per issue. Creating a new story for an issue replaces the previous one.
Quick Reference
Commands
# Check assignments
fp issue files <PREFIX>-X
# Assign commits
fp issue assign <PREFIX>-X --rev <commits>
# View changes
fp issue diff <PREFIX>-X --stat
fp issue diff <PREFIX>-X
# Leave comments
fp comment <PREFIX>-X "message"
# Interactive review (desktop app)
fp review <PREFIX>-X
# Stories
fp story create <PREFIX>-X --file story.md
fp story list
fp story get <PREFIX>-X
fp story delete <story-id>
fp review <PREFIX>-X --with-story
Comment Format
**filepath**: general comment about file
**filepath:line**: comment about specific line
**filepath:start-end**: comment about line range
[severity] **filepath**: prefixed comment
Severity Levels
[blocker]- Must fix[suggestion]- Should consider[nit]- Minor issue
Sponsors
Details
- Marketplace
- fiberplane/claude-code-plugins
- Source
- fp
- Author
- Fiberplane
- Category
- Productivity
