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
Parent: -
Dependencies: -
Created: 2026-04-30T10:00:00.000Z
Updated: 2026-04-30T10:00:00.000Z

Properties:
  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.

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

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

Adding a comment

The default form is fp comment add, but you can omit add and use the shorthand:

fp comment add FP-ijkl "Finished the REST endpoints, moving to GraphQL"
fp comment FP-ijkl "Shorthand form, identical to 'add'"

Read the body from a file instead of the command line with --file:

fp comment add FP-ijkl --file ./progress-notes.md

Attach an image (ingested into the project asset store, then referenced as markdown):

fp comment add FP-ijkl "Here's the crash screenshot" --attach ./crash.png

Listing comments

List all comments on an issue:

fp comment list FP-ijkl

Filter and paginate:

fp comment list FP-ijkl --author "alice@example.com"
fp comment list FP-ijkl --limit 5
fp comment list FP-ijkl --reverse          # oldest first
fp comment list FP-ijkl --format json      # machine-readable output

Editing a comment

Edit a comment in place. update and edit are interchangeable — both work:

fp comment update <comment-id> "Updated body text"
fp comment edit   <comment-id> "Same command, friendlier alias"

Read the new body from a file:

fp comment update <comment-id> --file ./revised-body.md

The <comment-id> is the UUID shown in fp comment list. Soft-deleted comments cannot be edited — the command fails with a not-found error.

Deleting a comment

Delete a comment:

fp comment delete <comment-id>

Delete is a soft-delete: the comment is marked with a deletedAt timestamp inside the issue’s Y.Doc, dropped from the full-text search index, and filtered out of fp comment list, fp context, and the desktop app timeline. It stays in the document history so sync peers converge to the same state.

The command is idempotent — calling fp comment delete again on an already-deleted comment returns Comment <id> is already deleted without re-emitting activity entries or extension hooks.

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/<storage-dir>/
├── fp.db            # SQLite database
├── activity.jsonl   # Append-only activity log
├── issues/          # Legacy/materialized issue records
├── comments/        # Legacy/materialized comment records
└── sync-state.toml  # Sync state

The project is registered globally in ~/.fiberplane/projects.toml. Issue data is per-machine.