Command: /flow-start <feature name words>
Example: /flow-start app payment webhooks
This is always the first phase, for every feature without exception. It establishes an isolated workspace, verifies the health of the codebase, configures workspace permissions, and opens the PR before any feature work begins. Framework-specific setup (dependency upgrades, CI fixes) is handled by the framework instructions in the skill.
Steps 1–9 serialize all main-branch work behind a lock. Only one flow-start runs this section at a time. Concurrent starts poll via /loop until the lock is released.
Acquires a queue-based lock (lib/start-lock.py) using a non-blocking --acquire call. Each flow creates an entry in .flow-states/start-queue/ and the oldest entry (by mtime, then feature name) holds the lock. If the lock is already held, invokes /loop 15s /flow:flow-start to poll every 15 seconds until the holder releases. Since nothing has executed yet, re-running the entire skill is safe.
Run bin/flow prime-check to verify /flow-prime has been run with the current plugin version. Also checks GitHub for newer FLOW releases and displays upgrade instructions if one is available.
If the start prompt contains #N issue references, adds the “Flow In-Progress” label immediately. This signals to other engineers (on other machines) that these issues are being worked on. Best-effort — labeling failures do not block the Start phase.
git pull origin main — ensures the worktree starts from the latest code.
bin/flow ci — establish a clean baseline. Main is pristine, so any failure is a flaky test. Retries up to 3 times; if a subsequent attempt passes, files a Flaky Test issue and continues. If all 3 fail, stops and reports to the user.
bin/dependencies — update dependencies on main (not in a worktree). If nothing changed, skip to Step 9.
If dependencies changed, bin/flow ci again — catches dep-induced breakage (rubocop, breaking changes). Retries up to 3 times to detect flaky tests. If all retries fail consistently, launches the ci-fixer sub-agent to diagnose and fix.
If there are any uncommitted changes (dependency updates + CI fixes), commits them to main.
Releases the lock by removing this flow’s entry from the queue so the next waiting flow can proceed.
This ensures every worktree starts from a clean, current main.
A single Python script (lib/start-setup.py) handles all mechanical setup in one process:
.worktrees/app-payment-webhooksgh pr create.flow-states/app-payment-webhooks.json (initial state)By the end of Phase 1:
.worktrees/<feature-name>.claude/settings.jsonbin/flow ci greenPhase 2: Plan (/flow-plan) — explore the codebase, design the approach, and produce an ordered implementation plan.