Issue Tracking

Creating Issues

Create a top-level issue:

fp issue create --title "Add user dashboard"

Create a sub-issue under a parent:

fp issue create --title "Design dashboard layout" --parent FP-abcd

Add a description:

fp issue create --title "Fix login bug" --description "Users can't log in with GitHub OAuth"

Set priority:

fp issue create --title "Critical fix" --priority high

Custom Properties

Extensions can register custom properties on issues. Use --property to set them:

fp issue create --title "Fix auth" --property labels=frontend,backend
fp issue create --title "Deploy" --property labels=infra --property env=staging

Update properties on existing issues (replace semantics):

fp issue update FP-abcd --property labels=frontend
fp issue update FP-abcd --property labels=            # clear the property

View properties with fp issue show:

fp issue show FP-abcd

Issue: FP-abcd
Title: Fix auth
Status: todo
Priority: medium

Fields:
  labels: frontend, backend

Description:
...

Multiple --property flags can be combined in a single command. Multiselect properties (like labels) split on commas; text properties preserve commas literally.

The default labels extension is auto-seeded on fp init with options: frontend, backend, infra, design, security, perf. See Labels Extension for details.

Listing and Filtering

List all issues:

fp issue list

Filter by status:

fp issue list --status todo
fp issue list --status in-progress
fp issue list --status done

The Issue Tree

fp tree shows the full hierarchy with status indicators:

fp tree

FP-abcd [in-progress] [high] Add user dashboard
├── FP-efgh [done] Design dashboard layout
├── FP-ijkl [in-progress] Implement dashboard API
├── FP-mnop [todo] Add dashboard widgets
└── FP-qrst [todo] Write dashboard tests

Comments

Add progress comments at any time:

fp comment FP-ijkl "Finished the REST endpoints, moving to GraphQL"

Comments are timestamped and attributed to the current agent or user.

VCS Integration

Assigning Commits

Attach one or more commits to an issue:

fp issue assign FP-ijkl --rev HEAD
fp issue assign FP-ijkl --rev abc1234

Viewing Diffs

See what changed for an issue:

fp issue diff FP-ijkl

See changed files:

fp issue files FP-ijkl

Parent Aggregation

Parent issues automatically aggregate diffs from all their descendants:

fp issue diff FP-abcd    # Combined diff from all child issues
fp issue files FP-abcd   # All files changed across subtasks

This makes it easy to review an entire feature by looking at the parent issue.

Loading Context

Load the full context of an issue (useful for agents switching tasks):

fp context FP-ijkl

This outputs the issue details, comments, and related context in a format optimized for AI agents.

Storage

Issue data is stored locally at:

~/.fiberplane/projects/<project-name>/
├── activity.jsonl   # Append-only event log
├── issues/          # Issue data files
├── comments/        # Comment data files
└── sync-state.toml  # Sync state

Project configuration (.fp/) should be committed to git. Issue data is per-machine.