Development workflow

Basic Git workflow for maintaining a2c-workflow. Aligned with LibESys practice: develop for day-to-day work, master for stable consumption, Conventional Commits enforced by pre-commit.

Branches

Branch	Role
develop	Working branch — all day-to-day commits and merge requests
master	Stable branch — fast-forwarded from develop when work is ready and CI is green

Protected branches: develop, master (and release/*, hotfix/* if used).

Day-to-day flow

develop (commit, push) → CI green → fast-forward master → consumers adopt tagged release

1. Clone and setup

git clone git@gitlab.com:libesys/ai-workflows/a2c-workflow.git
cd a2c-workflow
git checkout develop
./scripts/setup-dev.sh

2. Work on develop

git checkout develop
git pull origin develop
# edit docs, rules, templates, prompts
git add <files>
git commit -m "docs: Add commit planning guidance"
git push origin develop

Do not commit routine work directly to master.

3. Land on master

Untagged integration (normal development): when Development CI is green on your feature branch or develop:

git checkout master
git pull origin master
git merge --ff-only origin/<your-branch>
git push origin master

Tagged release (after green Release CI on vX.Y.Z): ff-merge from release/X.Y.Z — see release-pipeline.md and ADR-0009.

No merge commits on master — --ff-only only.

4. Catch up develop with master

git checkout develop
git fetch origin
git rebase origin/master
git push origin develop

Never git merge master into develop — rebase to keep history linear.

Commits

• Format: commit-messages.md (Conventional Commits + adr type + optional AI: footer)
• Checklist: commit-checklist.md
• Prefer one coherent commit per logical change set
• ADR decisions use adr(<category>): ... — one ADR per commit
• Curate root CHANGELOG.md [Unreleased] when landing release-relevant work — workflow/changelog-policy.md, workflow/ci-release-flow.md, release-pipeline.md

Pre-commit hooks

Installed by scripts/setup-dev.sh (Linux/macOS/Git Bash) or scripts/setup-dev.ps1 (Windows):

Hook	When	Purpose
trailing-whitespace, end-of-file-fixer, etc.	pre-commit	File hygiene on Markdown/YAML (staged files)
gitlint	commit-msg	Enforce commit message format

Changed files by default

Local hooks run on staged files at commit time. That is the normal day-to-day path.

CI runs pre-commit on changed files for the merge request or commit — not the entire repository. See workflow/pre-commit-policy.md and adr/0001-shared-pre-commit-policy.md.

Deliberate full-tree runs

The team may run pre-commit run --all-files manually when explicitly cleaning up the repository — for example after adding hooks, tightening rules, or onboarding legacy files. Commit the cleanup, then resume normal changed-file enforcement.

CI

.gitlab-ci.yml runs Development CI on feature branches (MRs), develop, and release/X.Y.Z; Release CI on tags; optional light Master CI on master (non-gating per ADR-0009).

A green develop pipeline requires all of these jobs to pass:

Stage	Job	When
lint	pre-commit	Changed files on every develop push and MR
lint	workflow-docs:contract	Every develop push and MR
trigger	trigger:docs-portal	Every develop push and merge request (after lint jobs pass)
release	release:verify	Tags v*.*.* only

workflow-docs:contract and trigger:docs-portal are not limited to commits that touch docs/**. A chore-only push must still validate the portal contract and run the downstream sync gate.

workflow-docs:contract also runs scripts/check_web_source_tags.py (ADR-0011): every [web:NNN] in scoped docs must exist in docs/web-source-mapping.md, and every mapping entry must be referenced. Run locally before doc commits: python scripts/check_web_source_tags.py.

On merge requests, trigger:docs-portal runs with PORTAL_SYNC_COMMIT=false so the portal syncs and builds from the MR commit without pushing mirror commits to docs-portal develop.

Do not fast-forward master with a tagged release commit until the Release CI on that tag is green.

Agents

• Commit on develop unless explicitly asked otherwise
• Do not push, ff-merge to master, or amend without explicit user request
• Follow commit-messages.md; include AI: footer when assisted
• See AGENTS.md and .cursor/rules/00-governance.mdc

Related

• commit-messages.md
• workflow/ci-release-flow.md
• release-pipeline.md