Skip to content

Advanced: templates

Templates turn a tracked issue into a ready-to-go environment: ffleet up -t <id> <ref> fetches the issue from your project-management (PM) tool, derives the slug from its title, and seeds the agent with a prompt rendered from the issue's fields. It's the fastest way to say "go work on ticket 123".

Anatomy

A template is a [templates.<id>] table in ffleet.toml plus a pm setting that says where issues come from.

# Where -t templates fetch issues from: github | linear | none
pm = "github"

[templates.task]
prompt_template = """
Work on issue #{number}: {title}

{body}

Issue URL: {url}
"""
# Optional: run a specific subagent for envs seeded from this template.
# subagent = "code-reviewer"

Available fields

prompt_template is rendered with the fetched issue's fields:

Token Value
{number} Issue number
{title} Issue title
{body} Issue body
{url} Issue URL
{id} The raw <ref> you passed

You can add or override tokens inline as key=value on the command line — e.g. ffleet up -t task 100 priority=high makes {priority} available in the template.

Running a template

The SLUG argument becomes the template ref (usually the issue id):

$ ffleet up -t task 123

Forge Fleet fetches issue 123 via the configured pm, derives a slug from its title, renders the prompt, and starts the environment just like a normal ffleet up. From there everything is the same — attach, stop, remove, etc.

The optional subagent key selects a subagent for these envs. It's translated to the coding-agent's own subagent flag and appended to its launch command — Claude only (--agent <name>); using it with another agent errors.

The --subagent NAME CLI flag (see starting) is the per-invocation, template-independent equivalent — it works with or without -t. When both are set, --subagent always wins over the template's configured subagent; if the two differ, Forge Fleet prints a non-fatal warning and proceeds with the CLI value. Passing a matching value, or passing only one of the two, produces no warning.

PM-tool integration

The pm setting controls fetching:

pm How issues are fetched Requirements
github (default) Via the gh CLI gh installed and authenticated
linear Via the Linear API LINEAR_API_KEY (e.g. in an env file — see secrets); refs may be a UUID or a human id like ENG-123
none No fetch; the raw <ref> is exposed as {id} —

On any fetch failure, Forge Fleet warns and continues as if pm = none, so a transient outage won't block you — you just get the raw ref instead of the issue fields.

GitHub example

pm = "github"

[templates.bug]
prompt_template = """
Fix bug #{number}: {title}

{body}

{url}
"""

$ ffleet up -t bug 456

Linear example

Put LINEAR_API_KEY in your project's env file (see secrets), then:

pm = "linear"

[templates.task]
prompt_template = "Implement {title} ({id}):\n\n{body}\n\n{url}"

$ ffleet up -t task ENG-123