# How Trunk-Based Development Functions in the Git-Workflow-and-Versioning Skill

> Learn how trunk-based development works in git-workflow-and-versioning. Maintain a deployable main branch with short-lived feature branches to reduce merge risks and boost performance.

- Repository: [Addy Osmani/agent-skills](https://github.com/addyosmani/agent-skills)
- Tags: how-to-guide
- Published: 2026-04-16

---

**Trunk-based development in the git-workflow-and-versioning skill requires maintaining a continuously deployable `main` branch while using short-lived feature branches that merge back within 1–3 days, reducing merge risk and aligning with DORA research on high-performing engineering teams.**

The `git-workflow-and-versioning` skill in the `addyosmani/agent-skills` repository defines a strict trunk-based development model designed to maintain repository hygiene and accelerate delivery. This approach mandates that the `main` branch remain in a releasable state at all times, with developers integrating changes through brief, focused feature branches.

## Core Principles of Trunk-Based Development

### The Main Branch as the Single Source of Truth

According to [`skills/git-workflow-and-versioning/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/git-workflow-and-versioning/SKILL.md), the `main` branch serves as the sole "trunk" where all stable code resides. Every commit on this branch must be production-ready, ensuring the repository stays in a continuously deployable state.

### Short-Lived Feature Branches

The skill prescribes creating feature branches off `main` that survive for a maximum of 1–3 days. This constraint minimizes divergence and reduces the probability of complex merge conflicts. The documentation includes an ASCII diagram illustrating this flow:

```

main ──●──●──●──●──●──●──●──●──●──  (always deployable)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← short‑lived feature branches (1‑3 days)

```

## Feature Flags and Branch Discipline

### Feature Flags Over Long Branches

When functionality isn't ready for production exposure, the skill recommends using **feature flags** rather than extending branch lifetime. Developers wrap incomplete code in conditional checks (such as environment variables) and merge to `main` immediately, keeping branches short while preventing premature feature activation.

### Commit Discipline

The skill emphasizes **atomic commits** with descriptive messages as the "real safety net." Whether teams use trunk-based development or alternatives like GitFlow, the requirement remains: small, focused changes with clear commit history defined in [`skills/git-workflow-and-versioning/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/git-workflow-and-versioning/SKILL.md).

## Practical Workflow Implementation

The following workflow demonstrates the trunk-based development pattern as defined in the repository:

```bash

# 1. Create a short‑lived feature branch from main

git checkout main
git pull               # ensure main is up‑to‑date

git checkout -b feature/add-login

# 2. Make an atomic change with descriptive commit

git add src/login.ts
git commit -m "feat: add login endpoint with JWT auth"

# 3. Execute pre‑commit hygiene (tests, lint, type‑check)

npm test && npm run lint && npx tsc --noEmit

# 4. Merge back to main within 1–3 days using fast‑forward

git checkout main
git merge --ff-only feature/add-login
git push origin main

# 5. Delete the feature branch after successful merge

git branch -d feature/add-login

```

For features not yet ready for production:

```javascript
// Implement feature flag in code
if (process.env.FEATURE_LOGIN) {
  // login implementation
}

// Merge immediately and control via environment config
// rather than keeping code on a long-lived branch

```

## Key Files and Enforcement

Several files in the `addyosmani/agent-skills` repository collectively define and enforce the trunk-based development model:

- [`skills/git-workflow-and-versioning/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/git-workflow-and-versioning/SKILL.md) – Primary definition of trunk-based development, branch strategy, and commit discipline.
- [`README.md`](https://github.com/addyosmani/agent-skills/blob/main/README.md) (engineering practices section) – Contextualizes trunk-based development within Google-style engineering practices.
- [`.github/workflows/test-plugin-install.yml`](https://github.com/addyosmani/agent-skills/blob/main/.github/workflows/test-plugin-install.yml) – CI pipeline configuration assuming `main` is always deployable.
- [`agents/code-reviewer.md`](https://github.com/addyosmani/agent-skills/blob/main/agents/code-reviewer.md) – Agent instructions enforcing workflow compliance during pull request reviews.

## Summary

- **Trunk-based development** in the `git-workflow-and-versioning` skill mandates a continuously deployable `main` branch and short-lived feature branches merging within 1–3 days.
- The [`skills/git-workflow-and-versioning/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/git-workflow-and-versioning/SKILL.md) file defines this workflow to reduce merge risk and align with DORA research on high-performing engineering teams.
- **Feature flags** replace long-lived branches for incomplete functionality, allowing immediate integration while controlling exposure.
- Enforcement spans agent configurations, CI workflows, and documentation to ensure atomic commits and branch discipline.

## Frequently Asked Questions

### What is the maximum lifetime for feature branches in this trunk-based model?

The `git-workflow-and-versioning` skill specifies that feature branches should merge back to `main` within **1–3 days**. This constraint minimizes code divergence and reduces the complexity of merge conflicts, as documented in [`skills/git-workflow-and-versioning/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/git-workflow-and-versioning/SKILL.md).

### How does the skill handle features that aren't production-ready?

Rather than extending branch lifetime, the skill implements **feature flags**. Developers wrap incomplete functionality in conditional checks (such as environment variable toggles) and merge to `main` immediately. This maintains the trunk-based requirement of short-lived branches while preventing premature feature activation.

### Which branch serves as the source of truth in this workflow?

The **`main` branch** functions as the single "trunk" and sole source of truth. According to the skill documentation, every commit on `main` must remain in a releasable, production-ready state, ensuring the repository is continuously deployable.

### What files enforce the trunk-based development practices?

The primary definition resides in [`skills/git-workflow-and-versioning/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/skills/git-workflow-and-versioning/SKILL.md), while enforcement occurs through:
- [`agents/code-reviewer.md`](https://github.com/addyosmani/agent-skills/blob/main/agents/code-reviewer.md) (agent instructions for PR reviews)
- [`.github/workflows/test-plugin-install.yml`](https://github.com/addyosmani/agent-skills/blob/main/.github/workflows/test-plugin-install.yml) (CI assuming deployable `main`)
- [`README.md`](https://github.com/addyosmani/agent-skills/blob/main/README.md) (engineering practices context)