Claude Code Workflow

fp is designed to be the task backbone for Claude Code sessions. This guide covers the recommended workflow patterns.

Setup

First, configure Claude Code integration:

fp init
fp setup claude

This installs skills and hooks that teach Claude Code how to use fp automatically.

The Work Session Flow

The standard agent workflow follows this pattern:

1. Find Work

fp issue list --status todo

2. Claim an Issue

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

This captures the current commit as the base reference.

3. Work and Log Progress

# After each milestone
fp comment FP-abcd "Implemented the data model"
fp comment FP-abcd "Added validation layer"

4. Attach Commits

fp issue assign FP-abcd --rev HEAD

5. Complete

fp issue update --status done FP-abcd

This captures the tip commit, enabling fp issue diff to show exactly what changed.

AGENTS.md Integration

Add fp rules to your AGENTS.md so all agents follow the same workflow:

## Issue Tracking

This project uses **fp** for issue tracking. AI agents must follow these rules.

### Task Tracking

- Use `fp issue` for all task tracking — do not use built-in todo tools
- Create subissues with `--parent` flag — never use markdown checklists
- Break work into atomic tasks (1-3 hours each)

### Work Session Flow

1. `fp issue list --status todo` — find available work
2. `fp issue update --status in-progress <id>` — claim before starting
3. Work and commit frequently
4. `fp comment <id> "progress..."` — log at every milestone
5. `fp issue assign <id> --rev <commit>` — attach commits
6. `fp issue update --status done <id>` — mark complete

### Commit Discipline

- Commit early and often with descriptive messages
- Always commit before session ends

Planning with Agents

Ask Claude Code to plan features:

“Plan out the authentication feature”

The agent creates a hierarchy:

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

Each sub-issue is scoped to 1-3 hours of work — small enough for a single agent session.

Reviewing Agent Work

After an agent completes work, review what changed:

fp issue diff FP-ijkl     # Diff for one issue
fp issue files FP-ijkl    # Files changed
fp issue diff FP-abcd     # Parent aggregates all children
fp tree                    # Overview of all progress

Tips

• Always log progress — fp comment creates an audit trail of what the agent did and why
• Use priorities — --priority high helps agents pick the most important work first
• Break work down — Smaller issues = better agent performance and easier review
• Commit before ending — Ensure no work is lost if a session ends unexpectedly