Flow is a CLI tool that manages multi-repo development workspaces using git worktrees. Written in Go.
cmd/flow/main.go— entry pointinternal/cmd/— cobra command definitions (root, init, list, render, state, exec, delete)internal/config/— path resolution (~/.flow/structure) and global config (config.yaml)internal/state/— workspace state file schema, load/save/validateinternal/workspace/— core business logic (create, list, find, resolve, render, delete)internal/git/— git CLI wrapper withRunnerinterface for testabilityinternal/agents/— AI agent file management (Claude instructions per workspace)internal/ui/— styled terminal output (lipgloss), spinners (bubbletea), prompts (huh)internal/iterm/— iTerm2 tab color/title escape sequencesdocs/prd/— product requirement documents
- Dependency injection:
workspace.Serviceaccepts agit.Runnerinterface. Tests use a mock runner — no real git calls. - ID vs Name: workspaces have a stable random ID (directory name like
calm-delta) and an optional human-friendly name in metadata. - State-driven: everything flows from
state.yaml. Render is idempotent. - Bare clone caching: repos are bare-cloned once to
~/.flow/repos/, shared across workspaces via worktrees. - Embedded defaults:
internal/agents/defaults/contains default Claude instructions, embedded viago:embedand written only if missing (preserves user edits).
make build # build binary
make test # run tests
make lint # run golangci-lintAll three must pass before committing. The linter config (.golangci.yml) enforces forbidigo (no fmt.Print* outside ui//cmd/) and err113 (wrapped errors).
Tests use t.TempDir() for isolation. The workspace tests use a mockRunner that implements git.Runner and creates directories to simulate worktrees. No real git operations in tests.
- Git: never force push. Create new commits instead of amending pushed commits.
- Commit messages: single line, no co-authored-by
- Errors: use sentinel errors with
fmt.Errorf("context: %w", err)wrapping - Output: all user-facing output goes through
internal/ui/— never usefmt.Print*directly - YAML:
gopkg.in/yaml.v3with struct tags - No over-engineering: only build what's needed now