Configuration

Project Structure

After fp init, your project contains:

your-project/
└── .fp/
    └── extensions/           # Scaffolding for authoring fp extensions

If you ran fp init --agent standard or fp init --agent codex (or chose Standard AGENTS.md at the prompt), the project also has the standard agent instruction pair:

your-project/
├── FP_AGENTS.md              # Agent workflow instructions (fp-managed)
└── AGENTS.md                 # `@`-includes FP_AGENTS.md (yours to edit)

If you ran fp init --agent claude (or chose Claude Code at the prompt), the project has the Claude-specific pair:

your-project/
├── FP_CLAUDE.md              # Claude Code workflow rules (fp-managed)
└── CLAUDE.md                 # `@`-includes FP_CLAUDE.md (yours to edit)

The FP_* files are managed by fp. The cli may overwrite them whenever they drift from the bundled templates. The AGENTS.md / CLAUDE.md files are yours; fp only ensures the @FP_AGENTS.md / @FP_CLAUDE.md include lines are present and never touches user-authored content otherwise.

Project registration and issue prefix

fp init registers the project in the global registry at ~/.fiberplane/projects.toml. The issue prefix you choose during fp init lives on the registry entry, and can be updated with fp project update --prefix NEWPFX.

Issue data, comments, and sync configuration live outside the repo at ~/.fiberplane/projects/<storage-dir>/.

Onboarding issues

The first time fp init runs on a machine, it seeds an onboarding issue tree so there are issues to explore from the start. Subsequent fp init runs in other repos skip the seed.

Agent Workflow Files

fp init --agent standard writes FP_AGENTS.md with the workflow rules that AI agents follow:

• Use fp issue for task tracking instead of built-in todo tools.
• Log progress with fp comment at each milestone.
• Commit early and often.

AGENTS.md is created (or updated) so it @-includes FP_AGENTS.md. Agents that read the standard AGENTS.md pick up the fp rules automatically.

Choosing the agent surface

In interactive mode, fp init prompts you to pick the agent instructions to add. You can answer ahead of time with --agent:

Flag	What it writes
--agent claude	FP_CLAUDE.md and ensures CLAUDE.md @-includes it
--agent standard	FP_AGENTS.md and ensures AGENTS.md @-includes it
--agent codex	alias for standard
--agent skip	no agent instruction files

With --yes and no --agent, the default is skip.

Adding or refreshing agent files later

fp agent setup <target> runs the agent-instruction step on its own, without re-running fp init. It is idempotent, so files are only rewritten when they’ve drifted from the bundled template, and the @-include is only inserted when missing.

fp agent setup claude     # FP_CLAUDE.md + ensure CLAUDE.md @-includes it
fp agent setup standard   # FP_AGENTS.md + ensure AGENTS.md @-includes it
fp agent setup codex      # alias for `standard`

fp does not install Claude skills, hooks, settings, or permissions; the integration is entirely through these instruction files.

Workflow Primers

fp guide <skill> prints bundled workflow primers as markdown. Available skills:

Skill	Aliases	Purpose
plan	planning	Break a feature into a hierarchy of scoped issues
implement	—	Claim issue, do work, log progress, mark done
brainstorm	bs	Author a brainstorm plan
extension	extensions, ext	Author an fp extension

Add --references <name> to print companion material (for example fp guide brainstorm --references mermaid).

What to Commit

fp init manages a single line to your gitignore: .fp/.

It is also generally safe to commit this folder, though you may want to add local, user-specific extension configuration to it in the future.