Menu
Flow workspace management — commands, state format, rendering, and PRs. Load this skill at the start of every session.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | flow |
| description | Flow workspace management — commands, state format, rendering, and PRs. Load this skill at the start of every session. |
| user-invocable | false |
When launched into a fresh workspace with no repos:
Edit state.yaml with the task details:
metadata.name — short kebab-case name (e.g., vpc-ipv6)metadata.description — one-line summaryspec.repos — repos needed (see State Format below)Run flow render <workspace> — clones repos and creates branches. No flags needed.
Start working in the repo directories.
apiVersion: flow/v1
kind: State
metadata:
name: my-project
description: What this workspace is for
created: "2026-01-01T00:00:00Z"
spec:
repos:
- url: github.com/org/repo # git remote URL
branch: feat/my-feature # branch to work on
base: staging # optional — create branch from this (default: repo's default branch)
path: ./repo # optional — local directory name (derived from URL)
branch is the branch you work on. base is where it's created from. Omit base to branch from the repo's default (e.g., main).
spec:
repos:
- url: github.com/acme/apps
branch: qa-1
base: staging
| Command | Description |
|---|---|
flow render <ws> | Create fresh branches from base |
flow render <ws> --reset=false | Use existing remote branches (errors if missing) |
flow list | List all workspaces |
flow edit state <ws> | Open state file in editor |
flow open <ws> | Open shell in workspace |
flow exec <ws> -- <cmd> | Run command in workspace |
flow delete <ws> | Delete workspace and worktrees |
origin/{base}, resetting if it already exists.--reset=false: uses an existing remote branch as-is. Errors if branch doesn't exist.Push before creating a PR — flow branches are local until pushed.
git push -u origin HEAD
In worktrees, gh can't auto-detect the repo. Always pass --repo and --head:
gh pr create --repo <owner>/<repo> --head <branch> --title "..." --body "..."
~/.flow/
├── config.yaml # global config
├── agents/claude/ # shared Claude instructions
├── repos/ # bare clone cache (shared across workspaces)
└── workspaces/<id>/
├── state.yaml # workspace manifest (source of truth)
├── CLAUDE.md # auto-generated context
├── .claude/ → shared # symlinks to agents/claude/
├── repo-a/ # git worktree
└── repo-b/ # git worktree
Workspaces are referenced by ID (e.g., calm-delta) or by metadata.name.
How to create pull requests for this project. Use when opening a PR on GitHub.
How to add new CLI commands to flow. Use when creating a new subcommand, adding flags, or modifying the command tree.
How to create Claude Code skills for this project. Use when adding new skills, creating SKILL.md files, or setting up skill directories.
Testing conventions and patterns for this project. Use when writing tests, creating mocks, or understanding the test infrastructure.
How to update documentation for this project. Covers updating the root README, creating and updating VHS tape recordings, running gendocs, and the make commands that tie it together.
How to write PRDs for this project. Use when creating a new product requirement document, planning a feature, or adding to docs/prd/.