/flowforge:session:start

/flowforge:session:start is the mandatory entry point for every FlowForge work session. It detects (or accepts) a ticket id, places the working tree on the correct feature branch, starts time tracking, and runs pre-flight environment checks. No FlowForge work begins until this command has run.

Synopsis

/flowforge:session:start [ticket-id]

From the command line outside Claude Code, the equivalent invocation is:

flowforge run flowforge:session:start [ticket-id]

Description

This command is the surface of FlowForge’s “time = money” guarantee. The framework refuses to count work that was not preceded by a session start: the timer must be running, the branch must be the ticket’s feature branch, and the session manifest in .flowforge/local/session.json must exist. /flowforge:session:start produces all three side effects atomically.

When invoked without an argument the command auto-detects the ticket using a deterministic priority order:

The current session manifest (.flowforge/local/session.json) — used to resume if a session is mid-flight.
The next ticket from the configured provider’s task order.
In-progress tickets from the provider system.
Position tracking, when the project uses it.
Provider-assigned tickets (GitHub, Linear, Jira, Local, and other configured providers).

When invoked with an explicit ticket id, the command jumps straight to that ticket and skips auto-detection. Ticket ids are interpreted by the configured provider — 123 for GitHub issues, LIN-456 for Linear, task-789 for the local provider, and so on.

After the ticket is resolved, the command verifies the working tree is in a git repository, switches to (or creates) the corresponding feature branch, records the session manifest, and starts the time tracker. The branch is enforced by Rule #18 — work on main or develop is rejected at this stage.

Arguments

Position	Name	Required	Description
1	`ticket-id`	no	Provider-specific ticket identifier. When omitted, the command auto-detects via the priority order above. The literal values `?` and `help` print an in-terminal usage block and exit `0`.

Options

This command has no flags. Behavior is controlled by environment variables and the positional ticket id.

Environment variables

Variable	Direction	Purpose
`ARGUMENTS`	read	Receives the ticket id when invoked through `flowforge run` or the Claude Code hook runtime.
`DEBUG`	read	When set to `1`, the command turns on `set -x` for full bash tracing. Useful when an auto-detect step is opaque.

Examples

Start with an auto-detected ticket:

/flowforge:session:start

Start work on GitHub issue 123:

/flowforge:session:start 123

Start work on Linear ticket LIN-456:

/flowforge:session:start LIN-456

Start with full debug tracing:

DEBUG=1 /flowforge:session:start 123

Print in-terminal help and exit:

/flowforge:session:start ?

The output of a successful session start follows this shape:

Starting FlowForge Session...
Detected ticket: #123 ("Add CLI reference page")
Switched to branch: feature/123-add-cli-reference-page
Time tracking active.

Exit codes

Code	Meaning
`0`	Session started, timer running, branch set.
Non-zero	A precondition failed. Common causes: not in a git repository, no provider configured, ticket lookup failed, or branch creation rejected. The error message names the failure mode and prints the `DEBUG=1` recovery hint.

/flowforge:session:pause — pause without ending the session.
/flowforge:session:end — close the session and stop the timer.
/flowforge:dev:status — confirm the timer and branch state.
/flowforge:dev:checkrules — verify Rule #5 and Rule #18 compliance.
Sessions — the conceptual model for what a “session” means.
First Session — end-to-end walkthrough.