Claude Code Workflow

fp integrates with Claude Code so issues and progress stay tracked across sessions. Once configured, Claude Code follows the fp workflow automatically.

Setup

fp init --agent claude

fp init will create or update the file FP_CLAUDE.md and ensure CLAUDE.md @-includes it, giving Claude Code a lightweight set of fp-managed instructions that load on every session.

To add the Claude files to an already-initialized project, run:

fp agent setup claude

The command is idempotent. It only rewrites FP_CLAUDE.md if its content drifts from the bundled template, and it only inserts the @FP_CLAUDE.md file-inclusion directive into CLAUDE.md when missing.

Workflow primers

The plan-and-implement primers ship with the CLI. Print them with fp guide:

fp guide plan         # Planning skill
fp guide implement    # Implementation skill

Output is markdown. Ask Claude to read it, or save it to a skill file if you wish. Other available guides are available for writing brainstorm docs or extensions:

fp guide brainstorm   # alias: bs
fp guide extension    # aliases: extensions, ext

Pass --references <name> to print companion material — for example, fp guide brainstorm --references mermaid.

The fp workflow: plan and implement

fp is structured around two phases:

Phase	Primer	Description
Plan	fp guide plan	Break a feature into a hierarchy of scoped issues
Implement	fp guide implement	Claim issue, do work, log progress, mark it done

Plan

Start with a prompt:

Use fp to plan out the authentication feature

Claude Code creates an issue hierarchy in fp:

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

Implement

Work on FP-ijkl

Claude marks the issue in-progress, does the work, comments at milestones, and then marks it done. The full step-by-step is in fp guide implement.

If you prefer a different implementation workflow, just describe it in your CLAUDE.md.

Inspect progress

Use the CLI or the fp Mac app to inspect progress:

fp tree                    # Overview of all progress
fp issue show FP-ijkl      # Details + comments for one issue

Extending the workflow

Plan and implement are the defaults, but fp is highly extensible! Every project’s workflow is different. See the Extensions docs for how to adapt fp to fit specific needs.

How the agent-instruction files work

fp writes agent instruction files for the agent surface you choose:

File	Owner	Purpose
FP_AGENTS.md	fp (managed)	Cross-agent fp workflow rules
AGENTS.md	you	Project rules; @-includes FP_AGENTS.md
FP_CLAUDE.md	fp (managed)	Claude-specific fp rules
CLAUDE.md	you	Project Claude Code preferences; @-includes FP_CLAUDE.md

Run fp init --agent claude (or fp agent setup claude) to write the FP_CLAUDE.md / CLAUDE.md pair. Run fp agent setup standard separately if you also want the standard FP_AGENTS.md / AGENTS.md pair.

The fp-managed files instruct the agent to:

• Use fp issue for task tracking instead of built-in todo tools
• Load context with fp context <id> before starting work
• Mark the issue in-progress on claim and done on completion
• Log progress with fp comment at each milestone
• Commit frequently and before ending a session

AGENTS.md and CLAUDE.md are yours to edit — fp only ensures the matching @FP_* include line exists. fp does not install Claude skills, hooks, settings, or permissions; the integration is entirely through these instruction files.

Tips

• Read fp issue show before marking done — confirm Claude Code’s progress comments match the work you expected
• Use priorities — --priority high helps Claude Code pick the most important work first
• Keep issues small — smaller issues produce more focused sessions