solo-flow

Files (2)

• SKILL.md
• two-branch-variant.md · references/

SKILL.md (first lines)

# Solo Flow

GitFlow's branches (`develop`, long-lived `feature/*`, `release/*`, `hotfix/*`)
exist to coordinate humans who would otherwise step on each other. A repo
with exactly one writer — one agent, one loop, nobody else committing —
has no one to coordinate with. Every branch that isn't earning its keep
against that fact is state the loop has to track for no return: one more
thing to fast-forward, one more thing that can drift from its sibling, one
more question ("which branch am I on, and is it in sync?") a tick has to
answer before it can start.

Solo Flow is trunk-based development named for this specific case: one
branch (`main`), short-lived local work branches, CI as the only
independent check, and releases as tags cut directly off `main` instead of
a `develop`/`release` branch dance. It is not a novel workflow — it is
2026's mainstream recommendation for CI/CD-heavy teams, applied to the
narrower and more clear-cut case of a single automated committer.

## When a second branch would be justified — and it usually isn't

Before prescribing this, check for the one thing that would justify keeping
a `develop`/integration branch separate from `main`: **does anything outside
the loop consume in-progress state before a release tag exists** — another
agent, another repo, a staging deploy that reads ahead of what's tagged?

- If nothing does — the common case — collapse to one branch. `main` only
  ever holds commits that passed the full check suite, so there is no
  "unstable" state a second branch would need to shield anyone from.
- If something genuinely does — say, a deploy pipeline that must see
  integration state before a human signs off on a release — keep a
  `develop`/`main` split. That's GitLab Flow, a legitimate pattern; don't
  force trunk-based onto a repo that has a real second audience. Point that
  case to `references/two-branch-variant.md` instead of the model below.

Don't take the requester's word that a second branch is needed — ask what,
specifically, reads `develop` today. "We might want it later" is not a
consumer.

## The model

| Branch | Where it lives | Purpose | Who merges into it |
|---|---|---|---|
| `main` | remote, default | the only shared state; every commit on it has already passed the full check suite | the agent, automatically, once checks pass |
| `feat/*`, `fix/*`, `chore/*` | local only, each in its own worktree | one unit of work (one roadmap item, one bug, one cleanup) | never pushed — merged locally into `main`, then the worktree and branch are deleted |
| `release/x.y.z` | local, ephemeral (minutes, not days), in its own worktree — only needed if the version bump + notes take more than one commit, or the owner wants to review notes before they're permanent | holds the version bump and release notes until the owner signs off | fast-forwarded into `main`, then discarded — nothing merges back out of it |

The permission boundary is intentionally short, because there's only one
writer to grant permissions to:

- **Automatic:** local branches and commits, merging a work branch into
  `main` once checks pass, deleting merged local branches, cutting and
  merging `release/*`.
- **Needs the owner:** tags and GitHub releases, CI configuration changes,
  repository settings.
- **Never:** force-pushing `main`, deleting `main`, committing to `main`
  without the check suite having run on that commit.

## Worktrees: the primary checkout never leaves `main`

Doing every work branch by `git switch` in the one checkout means the
answer to "which branch am I on, and is it clean?" changes under the loop
all day — and a tick that dies mid-item leaves the next one a checkout on
the wrong branch with a dirty tree. Worktrees make the answer structural:

- **The primary checkout stays on `main`, always.** Nothing switches
  branches there. It is where merges land and where `git push` runs.
- **Every unit of work gets its own worktree**, created off `main` and
  placed *outside* the repo directory (a sibling like `../<repo>.wt/<slug>`),
  so linters, test runners, and graph tools scanning the repo never trip
  over a nested copy of it and nothing needs `.gitignore`ing:
  ```bash
  git worktree add ../<repo>.wt/<slug> -b feat/<slug> main
  ```
- **Its lifetime is the branch's lifetime.** Landing the work removes both:
  `git worktree remove ../<repo>.wt/<slug> && git branch -d feat/<slug>`.
- **So "where am I" has one answer:** the primary is `main`; anything else
  is a worktree, and `git worktree list` is the complete inventory of work
  in flight. At the start of a tick, anything on that list that isn't the
  item being worked is an orphan from a crashed tick — resume it if it
  holds commits or changes worth keeping, otherwise remove it. Run
  `git worktree prune` for entries whose directory is gone. Look at a
  dirty worktree before removing it; don't reach for `--force`.

Two side benefits come free. The full check suite runs in a clean worktree,
so it verifies exactly what's committed on the branch rather than whatever
untracked leftovers the primary has accumulated. And several worktrees can
exist at once: a loop may build independent items concurrently (for example
subagents each given their own worktree) without it becoming a second
writer, because everything still lands serially through the primary's
`main`. Only parallelise items that don't touch the same files; sequence
the rest, since the second one to land pays the rebase.

What worktrees cost, so the loop plans for it:
- A branch can be checked out in only one worktree, so `main` lives in the
  primary and the merge into `main` happens there (`git -C <primary> …`),
  never from inside a work worktree.
- Each worktree is a fresh checkout: dependencies must be installed again
  (use a shared package store or cache), and gitignored files — `.env`,
  the loop's own state — don't exist in it. Keep loop state in the primary
  and reference it by absolute path.
- Submodules behave poorly across worktrees; if the repo has them, keep
  one worktree at a time.

## Day-to-day flow

1. `git fetch`, fast-forward local `main` (in the primary) to
   `origin/main`; reconcile any orphaned worktrees (see above).
2. Create a work branch in a new worktree off `main`; one commit per item.
3. While building, run only the fast checks (typecheck + lint) — save the
   full suite for step 4, it's too slow to run on every save.
4. Before merging: the full check suite, once per batch, run in the work
   worktree, plus one independent fresh-context review of the whole diff
   (a different agent or persona than the one that wrote it — the review
   is worth nothing if it's the same context grading its own work).
5. Merge: in the worktree, rebase onto `origin/main` if it moved; then in
   the primary, merge (fast-forward or `--no-ff`, pick one convention and
   keep it) into local `main` and push `main`; then remove the worktree
   and delete the local work branch.
6. The merge commit message is the record: items closed, net line change,

From Busy-Office/ai-skills, MIT.

More from Busy-Office/ai-skills