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

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.