This guide walks through the core fp workflow: creating issues, building a hierarchy, tracking progress, and reviewing changes.

## Create Issues

```bash
fp issue create --title "Add authentication"
```

fp generates a unique ID (e.g., `FP-abcd`) and creates the issue with `todo` status.

## Build a Hierarchy

Break work into smaller tasks with `--parent`:

```bash
fp issue create --title "Design auth flow" --parent FP-abcd
fp issue create --title "Implement OAuth provider" --parent FP-abcd
fp issue create --title "Add session management" --parent FP-abcd
fp issue create --title "Write tests" --parent FP-abcd
```

View the tree:

```bash
fp tree
```

```
FP-abcd [todo] Add authentication
├── FP-efgh [todo] Design auth flow
├── FP-ijkl [todo] Implement OAuth provider
├── FP-mnop [todo] Add session management
└── FP-qrst [todo] Write tests
```

## Work on an Issue

Start working — this captures the current commit as the base:

```bash
fp issue update --status in-progress FP-ijkl
```

Log progress as you go:

```bash
fp comment FP-ijkl "Implemented Google OAuth provider"
fp comment FP-ijkl "Added token refresh logic"
```

Attach commits to the issue:

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

Mark complete — this captures the tip commit:

```bash
fp issue update --status done FP-ijkl
```

## Review Changes

See the diff for a specific issue:

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

See which files changed:

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

Parent issues aggregate diffs from all children:

```bash
fp issue diff FP-abcd    # Shows combined changes from all subtasks
```

## The Agent Workflow

When Claude Code (or another agent) is configured, you can simply ask:

> "Plan out the authentication feature"

The agent creates a hierarchy of issues automatically using fp.

> "Work on FP-ijkl"

The agent claims the issue, works on it, logs progress with comments, and marks it done — all through fp commands.

## Next Steps

- [CLI Overview](/docs/cli/overview) — Full command reference
- [Issue Tracking](/docs/cli/issue-tracking) — Deep dive into issues, comments, and diffs
- [Claude Code Workflow](/docs/guides/claude-code-workflow) — Agent workflow best practices