Git & GitHub Workflow (Monorepo + Split Repos)

This playbook defines the Flow Create Solutions default Git/GitHub workflow across projects, with explicit guidance for:

Internal developers + AI agents working in the canonical monorepo
Outside contractors working in split repos (module repos) without monorepo access

If a specific project deviates (different branch names, different release flow, no split repos), that project must document the deviation in its repo-level docs and/or AGENTS.md.

Canonical branches (default)

main is production (only receives changes by merging from development)
development is the pre-production deployed branch (one step before production)
local is a local-only staging branch for unreviewed work (agents PR here; humans decide what gets PR’d into development)

“PR to main” meaning

If someone says “PR to main”, they mean a release PR that merges development → main.

Definitions

Monorepo: the canonical repository containing multiple modules (e.g., backend/, frontend/, infra/).
Split repos: separate repositories per module (e.g., one repo per backend, frontend, etc.).
Internal contributors: employees/owners/agents working directly in the monorepo.
Contractors: outside contributors who should only be granted access to split repos (never the monorepo).

Internal workflow (humans + AI agents)

Isolation: worktrees first

Each agent (or parallel stream of work) should use an isolated git worktree.
Treat each worktree like a separate checkout (install deps, run scripts/tests, etc. per worktree as needed).
Keep work scoped per agent to avoid conflicts (e.g. one agent on frontend/, another on backend/).

Keep your worktree up to date (required at start of task)

Because development is deployed and may receive approved changes over time, your local worktree can become stale quickly.

At the start of any task, refresh remote refs:

git fetch origin development

Then ensure your base branch is local:

Prefer working from local (local-only staging). Do not do feature work directly on development.
If local doesn’t exist yet, create it from origin/development:

git checkout -b local origin/development

Safe update rule for local (only when safe):

If you are on local, your working tree is clean, and local can fast-forward to origin/development:

git merge --ff-only origin/development

If it’s not safe to fast-forward (local changes, detached HEAD, local commits, divergence), do not auto-update mid-task. Reconcile intentionally when you’re ready (commit first, then rebase/merge as appropriate).

Default branching rule (agents)

Work on a feature branch by default, based on local:

Create a feature branch off local for the task.
When the task is complete, open a PR into local (do not merge directly).

Only keep working directly on local when the change is trivial and explicitly low-risk (e.g., a one-line docs fix).

If you’re continuing the same job across multiple sessions, keep using the same branch.

Branch naming convention (recommended)

Use a consistent, sortable prefix and keep names short:

Format: <area>/<type>/<slug>
type: feat, fix, chore, refactor, docs
area: choose a stable project module name (examples: frontend, backend, infra, ops, docs, repo)

Examples:

frontend/feat/beads-1234-lead-export-page
backend/fix/rate-limit-headers
docs/chore/git-playbook

GitHub behavior standards (agents)

Commit / push / PR behavior

Commit: if instructed “commit”, create a commit on the current branch/worktree (no push).
Push: never push unless explicitly requested.
PR: never open a PR (especially into development) unless explicitly requested.

PR-to-`local` behavior (default completion path)

When you finish a task (and are asked to open a PR):

open a PR from your feature branch into local
do not merge directly into local
do not push local unless explicitly requested

“Push those changes” meaning

Treat “push those changes” as:

push commits to the current branch

Do not open a PR unless explicitly requested.

If you are asked to open a PR and a prior PR for that branch is already merged/closed, open a new PR (merged PRs cannot be “updated” later).

Always verify PR state before claiming it is open.

Required pre-flight before pushing / PR

Before pushing or opening a PR:

verify the diff matches intent (no accidental files)
verify there are no secrets staged or untracked (never commit .env files or credentials)
if (and only if) asked to open a PR, ensure the PR target is explicitly correct:
- default target: local
- integration/deploy target: development (only when explicitly requested)
- release PR target: main (merging development → main)

Contractors: split repo workflow (required)

Outside contractors should never get access to the monorepo. They work only in split repos:

branch off split repo development
PR back into split repo development
internal owner tests locally (in the split repo), merges into split repo development, then imports into the monorepo

Sync rule: monorepo ↔ split repos (git subtree)

Sync between monorepo and split repos is not automatic. Split repos only reflect monorepo changes when you explicitly publish them.

Rules:

Never try to “merge repos”.
Use git subtree sync only.
Run subtree sync commands from the monorepo root.
Ensure your monorepo development is up to date before syncing.

Publish monorepo → split repos (prepare contractor work)

From monorepo development:

git checkout development
git pull --ff-only

git subtree push --prefix=<module_dir> <split_remote_name> development

Example (replace with your project’s module names/remotes):

git subtree push --prefix=frontend split-frontend development
git subtree push --prefix=backend split-backend development

Import split repos → monorepo (after split repo `development` contains the change)

From monorepo development:

git checkout development
git pull --ff-only

git fetch <split_remote_name> development
git subtree pull --prefix=<module_dir> <split_remote_name> development

Example (replace with your project’s module names/remotes):

git fetch split-frontend development
git subtree pull --prefix=frontend split-frontend development

git fetch split-backend development
git subtree pull --prefix=backend split-backend development

Project adoption & overrides

Each project should:

reference this playbook from its root AGENTS.md
document any deviations (different branch names, different release model, no split repos) in project docs and/or AGENTS.md
keep project docs focused on project-specific truth (commands, ports, env vars), and link here for the workflow baseline