Quick Start

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

Create Issues

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:

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:

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:

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

Log progress as you go:

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

Attach commits to the issue:

fp issue assign FP-ijkl --rev HEAD

Mark complete — this captures the tip commit:

fp issue update --status done FP-ijkl

Review Changes

See the diff for a specific issue:

fp issue diff FP-ijkl

See which files changed:

fp issue files FP-ijkl

Parent issues aggregate diffs from all children:

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 — Full command reference
• Issue Tracking — Deep dive into issues, comments, and diffs
• Claude Code Workflow — Agent workflow best practices