4. Trunk-Based Branching Model

← Back to Table of Contents | Previous: Git Repo Organization | Next: Kiro Configuration →

4.1 Why Trunk-Based Development for AI-Assisted Teams

AI assistants generate code fast. Traditional Git Flow with long-lived branches creates: - Massive merge conflicts when multiple Kiro agents work in parallel - Stale branches that drift from trunk - Integration pain at merge time

Trunk-Based Development (TBD) solves this by enforcing: - A single stable trunk (main) - Short-lived feature branches (hours, not days) - Frequent integration (multiple merges per day)

4.2 Branch Model

main (always deployable)
 │
 ├── kiro/auth/add-jwt-refresh          (lives < 24h)
 ├── kiro/billing/stripe-webhook        (lives < 24h)
 ├── kiro/orders/validate-quantity       (lives < 24h)
 ├── kiro/infra/add-rds-module          (lives < 24h)
 └── release/v1.2.0                     (optional, for release cuts)

Branch Naming Convention

kiro/<module>/<short-task-description>

Examples:

kiro/auth/add-refresh-token
kiro/billing/fix-invoice-rounding
kiro/orders/add-order-validation
kiro/gateway/rate-limiting
kiro/infra/ecs-autoscaling

Release Branches (Optional)

For teams that need release stabilization:

release/v1.2.0

Created from main when preparing a release
Only hotfixes are cherry-picked into release branches
Release branches are short-lived (1–3 days max)

4.3 Branch Rules

Rule	Value
Branch lifespan	< 24 hours
Max lines changed per branch	< 400 lines
Merge frequency	Multiple times per day
Rebase before PR	Always
Direct commits to main	Never
Force push to main	Never

4.4 Commit Convention

Follow Conventional Commits with module prefix:

<type>(<module>): <description>

Allowed types:

Type	Usage
`feat`	New feature
`fix`	Bug fix
`test`	Adding or updating tests
`refactor`	Code restructuring without behavior change
`docs`	Documentation only
`chore`	Build, CI, tooling changes

Examples:

feat(auth): add JWT refresh token endpoint
test(auth): add refresh token rotation tests
fix(billing): correct decimal rounding on invoices
refactor(orders): extract validation into service
chore(ci): add security scan stage

4.5 Merge Strategy

For Feature Branches → Main

Use squash merge or rebase merge:

Squash merge: collapses all branch commits into one clean commit on main
Rebase merge: replays commits linearly on top of main

Recommended: squash merge for AI-generated branches (cleaner history).

Merge Requirements (CI Gate)

Before a branch can merge to main, it must pass:

PR opened
    ↓
lint check ✓
    ↓
type check ✓
    ↓
unit tests ✓
    ↓
integration tests ✓
    ↓
security scan ✓
    ↓
code review approved ✓
    ↓
merge allowed

4.6 Conflict Prevention

Technique	How It Helps
Module isolation	Each Kiro only touches its own module
Frequent rebasing	Developers rebase against main before opening PR
Small branches	Less code changed = fewer conflicts
CODEOWNERS	Prevents unauthorized cross-module changes
Shared types are human-maintained	AI agents don't modify the shared layer

4.7 Feature Flags for Large Features

When a feature spans multiple sprints or requires gradual rollout:

if (featureFlags.newBillingFlow) {
  useNewBillingService();
} else {
  useLegacyBillingService();
}

Benefits: - Trunk remains stable even with incomplete features - Safe incremental AI commits - Progressive deployment to production

4.8 Trunk-Based Development Checklist

[ ] main compiles at all times
[ ] All tests pass on main at all times
[ ] No branch lives longer than 24 hours
[ ] Every PR is reviewed before merge (team mode)
[ ] CI pipeline is the gatekeeper — no bypassing
[ ] Feature flags used for incomplete features
[ ] Rebase before opening PR

← Back to Table of Contents | Previous: Git Repo Organization | Next: Kiro Configuration →