start¶
Start work: an issue by number, a title that files one, or a plain branch.
REF is an issue number (a leading # is accepted), a quoted
title, which files the issue first, or <kind>/<slug> (docs/
the-plan) for a branch that belongs to no issue: a note, a small
fix. An issue is assigned, and assignment is documentation: at the
workspace's assignee limit, or when the forge refuses the write,
the start proceeds with a warning that others will not see you on
the issue. An issue's branch is <kind>/<number>-<slug> and
fm submit closes the issue on merge; a plain branch is named
as given and closes nothing. Every branch starts from a fetched
origin/main, so a stale base is impossible; --from=<branch>
starts on a pushed, unmerged parent instead and records the parent
with the commit the branch starts from. fm submit targets the
parent until it has merged, and fm sync and fm submit move
the branch's own commits when the parent moves or merges. A worktree under
the runner's home is the default, entered in a shell when a
person is at the terminal (--open=code opens the editor
instead, --open=none prints the path); --no-worktree
reuses this checkout, where a dirty tree refuses naming --wip
(park the tree as a commit; squash-only merging evaporates it) as
the escape. --agent launches the named agent in the worktree
with a minimal briefing; the worktree's own instructions are the
real ones. Re-running on started work re-enters it, in whichever
tree holds the branch. A local branch no tree holds is re-entered
on its own tip, unless its pull request merged and took that tip:
the branch is finished work, so it goes and the start begins fresh.
fm start <ref> [--type=VALUE] [--from=VALUE] [--body=VALUE] [--wip] [--no-worktree] [--agent=VALUE] [--prompt=VALUE] [--open=VALUE]
| Parameter | Type | Default | Description |
|---|---|---|---|
<ref> |
required | ||
--type=VALUE |
"" |
kind override: feat, fix, chore, docs, refactor | |
--from=VALUE |
"" |
start on this pushed, unmerged branch instead of main; submit targets it | |
--body=VALUE |
"" |
the issue body when the title form files one | |
--wip |
flag | false |
park the dirty tree as a commit and reuse this checkout |
--worktree |
flag | true |
open the work in a linked worktree |
--agent=VALUE |
"" |
hand the work to a coding agent (implies a worktree) | |
--prompt=VALUE |
"" |
an initial prompt appended to the agent's briefing | |
--open=VALUE |
"" |
how to open a worktree: shell, code, or none |