Skip to content

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

Example

$ fm start <ref> --wip