| name | git-flow |
| description | Project git flow (branches, PR/MR, position check before dev). Use when starting or finishing a dev, branching, opening a PR/MR, merging, or to know which branch to work from. |
Git flow
Simplified vanilla git flow. This documents project usage, not git itself.
Business / technical backlogs: see docs/agents/business-backlog.md and
docs/agents/issue-tracker.md (source of truth for the tooling).
What we keep
main: prod, protected; no direct merge (hotfix excepted).develop: global integration; every dev branches from it and merges back into it.integration/<business-ref>-<slug>: integration branch for one business user story, from up-to-date develop. Named after the business user story (its reference + a slug), because grill-with-docs creates it during grilling — before /to-prd generates the PRD on the technical backlog (so NOT the PRD number). The session writes its grilling output (CONTEXT.md, ADRs) here; the integration branch then accumulates the sub-issues. ready-for-agent sub-issues auto-merge into it after a green local check (build + tests + green Feature Path (FP)); integration -> develop stays a human decision (where the HP suite is run).feature/<issue-ref>-<slug>: one dev = one branch, from up-to-date develop — or from the integration/* of the business story when the dev implements a sub-issue of a grilled story.hotfix/<slug>: from main, on explicit request, PR + manual validation, then ported back onto develop.- No
release branch until there's a pre-prod.
Workflow
We speak of MR/PR (depending on the technical backlog, see docs/agents/issue-tracker.md). On the git side:
-
New dev: from up-to-date develop -> feature/<issue-ref>-<slug>; or, if the dev implements a sub-issue of a grilled business story, from integration/* -> feature/<issue-ref>-<slug>. Unless stated otherwise, it ties to one or more business stories (-> technical issues); if none is known, ask.
-
Business story (integration branch): grill-with-docs creates integration/<business-ref>-<slug> from up-to-date develop (named after the business story, before /to-prd) and writes its grilling output there. /to-prd then creates the PRD, then /to-issues pushes the integration branch and creates the sub-issues based on it. ready-for-agent sub-issues PR -> integration/* and auto-merge once the local check is green (project build + tests + the FP green via /agentic-tests, no blocking finding). Keep the integration branch in sync with develop (it is long-lived).
No CI wired by default in the skeleton: the auto-merge gate is the agent running build + tests + the FP locally and merging only if everything is green. An agentic test needs an agent to drive the app: the day a CI exists, it doesn't run the test itself, it triggers an agent — and then it holds the gate.
-
End of dev: PR toward the branch the dev started from (--base develop, or --base <integration/*> for a sub-issue), assigning the responsible reviewer (<reviewer to define>); comment the PR link on the business story (moved to "in review"). The agent never merges into develop/main: the responsible human validates and merges. Only exception: the auto-merge of a ready-for-agent sub-issue into its integration/* (green local check).
-
integration/* -> develop: human decision. Before the PR, the agent runs the HP suite (/agentic-tests HP) and pastes the result into the PR (pass/fail + findings); if the feature warrants it, it proposes co-creating an HP — at most 3 HP (otherwise: merge two journeys, drop a non-critical one, or graft drive-by). The PR lists the included issues for a readable batch review. The agent opens the PR and gives the link; never merges.
-
develop -> main: human decision. On request, the agent opens the PR and gives the link; never merges.
Before coding — check your position
On the 1st act of dev (code meant to be committed):
git rev-parse --abbrev-ref HEAD
git branch --merged develop
git status -sb
On main, on a stale branch, or on a feature/* unrelated to the requested dev: don't pile on. Explain the cleanest placement (back to up-to-date develop + a new branch) and why, then ask for approval before acting (especially if there are uncommitted changes).
