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-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add fiberplane/claude-code-plugins.

Contents

Discovered from source

Skills 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 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

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 started
  • in-progress - Actively being worked on
  • done - Completed

Priority Values (optional)

  • critical - Blocking other work
  • high - Important, do soon
  • medium - Normal priority
  • low - 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 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"

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

Core Purpose

  1. Verify commits are assigned to the correct issues
  2. Leave review comments on issues
  3. Open interactive review in the desktop app
  4. 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 model
  • def456 - Implement auth middleware

Would you like me to assign them to the issue? (If you prefer to review uncommitted changes instead, you can run fp review for 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:

  1. Assign commits first with fp issue assign, OR
  2. Use fp review to 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 :::diff and ::: 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 file
  • lines (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 file
  • messages: 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 :::diff directive, 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