Branching And Initiative Work

Use this page before changing code or docs. The goal is to keep initiative work reviewable and keep integration branches clean.

Core Rules

• Do not commit directly to dev or main.
• dev is the default integration branch for day-to-day work.
• main is not the default base unless a human explicitly says the task targets it.
• Local commits belong on initiative, initiative-slice, or fix branches. PRs and merges update dev and main.
• Create the top-level initiative/<slug> branch once per initiative. Do not run bun run initiative:start <slug> again for follow-up slices inside the same initiative.
• If you are already on a human-provided branch, preserve that context instead of switching branches automatically.
• For new independent coding-agent tasks, prefer Git Worktrees For Agent Tasks when you want dev to stay clean and parallel tasks to stay isolated.

Starting An Initiative

Start new initiative work from a clean dev branch. Run this once for the durable workstream:

git checkout dev
bun run initiative:start <slug>

bun run initiative:start <slug> creates initiative/<slug> and scaffolds canonical planning artifacts under docs/features/<slug>/. The slug names the initiative, not necessarily a brand-new product feature.

The command fails if the working tree is dirty, if you are not on dev, if local dev is missing, or if initiative/<slug> already exists. Fix that branch state first rather than bypassing the script.

If docs/features/<slug>/ already exists and initiative/<slug> does not, this command can still create the top-level branch for renewed work on that existing initiative. It writes only missing scaffold files and does not overwrite existing docs.

Working Inside An Initiative

Once an initiative branch exists, related work branches must branch from that initiative branch only. Do not branch related initiative slices from dev or main.

Do not run bun run initiative:start <slug> for these related slices. That command is only for creating the one top-level initiative branch and canonical docs directory.

git checkout initiative/<slug>
git checkout -b initiative/<slug>--<slice-slug>

Use -- between the initiative slug and slice slug. Do not use initiative/<slug>/<slice-slug> because that branch name cannot coexist with the top-level initiative/<slug> branch in Git.

Use initiative-slice branches for UI, API, docs, tests, or refactor work that belongs to the same initiative. This keeps the initiative’s canonical docs, implementation, and follow-up slices together.

Keep Initiative Slices Isolated

Prefer small initiative-slice branches with clear ownership, especially when multiple developers or agents may work on the same initiative. Good slices usually have a narrow write area, such as one app, one package, one workflow, or one docs surface.

Before starting a slice, update from the top-level initiative branch:

git checkout initiative/<slug>
git pull
git checkout -b initiative/<slug>--<slice-slug>

Avoid broad mixed-purpose branches that touch unrelated UI, API, docs, and test surfaces at the same time. If a slice starts crossing too many boundaries, split the next piece into a separate branch from initiative/<slug>.

Merge Slices Back Often

Treat initiative/<slug> as the integration branch for that initiative. After a slice is reviewed and its focused verification passes, merge it back to the initiative branch promptly:

git checkout initiative/<slug>
git merge initiative/<slug>--<slice-slug>

Merging small verified slices back frequently keeps conflicts close to the work that caused them and gives the next slice a current base. If a slice is still in review or failing verification, keep it separate until it is ready.

Existing Features And Docs

Not every branch needs a new docs/features/<slug>/ directory.

• New product feature, repository initiative, or cross-cutting workstream with durable planning needs: create or reuse one canonical docs/features/<slug>/ and one top-level initiative/<slug> branch.
• Existing documented feature: reuse the existing docs directory and branch from the active initiative/<slug> branch for that work.
• Bug fix: use fix/<bug-slug> from dev unless the bug is contained inside active initiative work.
• Docs-only support, tooling, or repository hygiene: use a branch name that describes the work and update support-dev or owning docs only when they are the durable source.

If the work is organized around a sprint, milestone, or upcoming release theme, prefer a non-release initiative name such as initiative/<cycle-or-theme-slug>. Avoid release/<slug> unless the branch is the actual release branch, because release-like names can imply a shipping state that has not happened yet. Slice branches from an initiative should follow the same separator pattern, such as initiative/<cycle-or-theme-slug>--<slice-slug>.

Bug Fix Exception

Standalone bug fixes branch from dev, not from an unrelated initiative branch:

git checkout dev
git checkout -b fix/<bug-slug>

A bug found only inside active initiative work can stay in that initiative’s branch tree. If the bug affects current dev behavior outside the initiative, split it into a fix/<bug-slug> branch from dev unless the human explicitly keeps it in the initiative scope.

Before Opening A PR

Before opening a PR:

1. Confirm the base branch makes sense for the branch type.
2. Run the relevant verification for the changed surface.
3. Use PR Readiness for the final branch audit, diff review, Codex review expectations, and PR handoff.

Canonical Sources

• AGENTS.md
• scripts/startInitiative.ts
• docs/AGENTS.md
• apps/support-dev/src/content/docs/workflows/pr-readiness.md