adrs/053-git-workflow-guidelines.md

ADR-053: Git Workflow Guidelines

Status

Proposed

Created: 2026-01-27

Context

The acsis-core repository is developed by both human developers and AI agents working in parallel. This multi-agent environment creates unique challenges:

Multiple worktrees: Each agent operates in an isolated worktree (worktrees/<agent-name>/)
Parallel development: Multiple agents work simultaneously on different features
Rapid development phase: Currently prioritizing velocity over formal PR review
Context limitations: AI agents have session-based context that may be compacted
Traceability requirements: Need to understand what changed and why

Without clear guidelines, we risk:

Merge conflicts from uncoordinated rebases
Lost context when commits are squashed inappropriately
Inconsistent history that's hard to navigate
Confusion about which workflow applies when

Decision

We establish the following git workflow guidelines for the acsis-core repository.

Branch Naming Conventions

Branch Type	Pattern	Example
Agent working branch	`agent/<agent-name>`	`agent/caliban`
Feature branch	`feature/<short-description>`	`feature/mqtt-retry-logic`
Bugfix branch	`fix/<short-description>`	`fix/null-reference-startup`
Release branch	`release/<version>`	`release/1.0.0`

Agent branches are automatically created by the worktree setup script and are the primary working branches for AI agents.

Merge Strategies

During Rapid Development Phase (Current)

Direct-to-main workflow:

# From agent worktree (can't checkout main directly)
git fetch origin main
git merge origin/main
git push origin agent/<name>:main

When to use:

All current development work
No PR review required
Conflicts resolved locally before push

Production Phase (Future)

PR-based workflow with squash merge:

Feature branches require PR review
Squash merge to keep main history clean
Delete feature branch after merge

Rebase vs Merge Guidelines

Scenario	Strategy	Rationale
Updating agent branch from main	Merge	Preserves commit history; safer for shared branches
Local feature branch (unpushed)	Rebase allowed	Keeps history linear before sharing
Pushed/shared branch	Never rebase	Avoids force-push disasters
Resolving conflicts	Merge	Clearer conflict resolution history

Key rule: If the branch has been pushed, use merge, not rebase. This prevents the need for force pushes which can destroy others' work.

When to Squash Commits

DO squash when:

Multiple "WIP" or "fix typo" commits clutter history
PR contains iterative review-response commits
Commits don't individually represent meaningful work

DO NOT squash when:

Each commit represents a distinct, reviewable change
Commits are from different logical phases of work
History provides valuable context (e.g., "tried X, didn't work, did Y")
Agent sessions where the commit history documents the work progression

Agent work should generally NOT be squashed because:

Each commit represents a distinct work session
The history documents the progression of AI-assisted development
Traceability is more valuable than a "clean" history

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, refactor, test, chore, perf

Scope: Component or area affected (e.g., catalog, orchestration, analyzers)

Footer:

Closes: SWE-XXX for Linear issues
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> for AI-assisted commits

Example:

feat(orchestration): add container name suffix for agent isolation

Add .WithContainerName() to local development containers to use
agent-based names instead of random hex hashes. This makes it easier
to identify which containers belong to which agent.

Closes: SWE-123

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Handling Merge Conflicts

Fetch latest: git fetch origin main
Merge: git merge origin/main
Resolve conflicts in your editor
Test: Ensure the code compiles and tests pass
Commit the merge: git commit (merge commit auto-generated)
Push: git push origin agent/<name>:main

Never use:

git push --force on shared branches
git checkout --theirs . or --ours . without reviewing changes
git reset --hard to "fix" merge issues (destroys work)

Keeping Branches Up to Date

Recommended frequency: Before starting significant new work

# Standard update pattern
git fetch origin main
git merge origin/main

# If conflicts, resolve them, then:
git push origin agent/<name>:main

Do not rebase your agent branch onto main - this rewrites history and will cause problems when pushing.

Multi-Agent Coordination

When multiple agents work on the same codebase:

Use Agent Teams for intra-session coordination between lead and teammate agents
Push frequently to reduce merge conflict window
Pull before significant changes to get others' work
Use Linear to track cross-session work and blockers

Forbidden Operations

These operations are never allowed without explicit user request:

Operation	Why Forbidden
`git push --force`	Destroys remote history, breaks other worktrees
`git reset --hard origin/main`	Loses uncommitted work
`git checkout .` / `git restore .`	Loses uncommitted changes
`git clean -fd`	Deletes untracked files permanently
`git rebase` on pushed branches	Requires force push
`git commit --amend` after push	Requires force push

Consequences

Positive

✅ Clear expectations: Everyone knows which workflow to use when

✅ Preserved history: Avoiding squash/rebase keeps valuable context

✅ Safer collaboration: Merge-based workflow prevents force-push disasters

✅ Traceability: Commit messages link to Linear issues

✅ Agent-friendly: Guidelines account for worktree isolation and session limits

Negative

⚠️ Messier history: Merge commits create non-linear history

⚠️ More commits: Not squashing means more commits to navigate

⚠️ Discipline required: Easy to accidentally rebase or force-push

Trade-offs Accepted

Safety over cleanliness: We accept merge commits for the safety they provide
Traceability over brevity: We keep commits for context even if history is longer
Velocity over review: During rapid development, we skip PRs for speed

Implementation

Phase 1: Documentation (This ADR)

Document current workflow practices
Establish conventions

Phase 2: CLAUDE.md Update

Add git workflow reference to CLAUDE.md
Ensure agents follow these guidelines

Phase 3: Tooling (Future)

Pre-push hooks to prevent force-push to main
Commit message linting
PR templates for production phase

ADR-048: Agent-driven development stack (establishes multi-agent context)
Session management: dplx session new creates agent worktrees, dplx session clean removes them

Documentation