## Creating Issues

Create a top-level issue:

```bash
fp issue create --title "Add user dashboard"
```

Create a sub-issue under a parent:

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

Add a description:

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

Set priority:

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

## Custom Properties

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

```bash
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):

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

View properties with `fp issue show`:

```bash
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](/docs/extensions/labels) for details.

## Listing and Filtering

List all issues:

```bash
fp issue list
```

Filter by status:

```bash
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:

```bash
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:

```bash
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:

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

### Viewing Diffs

See what changed for an issue:

```bash
fp issue diff FP-ijkl
```

See changed files:

```bash
fp issue files FP-ijkl
```

### Parent Aggregation

Parent issues automatically aggregate diffs from all their descendants:

```bash
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):

```bash
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.