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

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, 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.

Practical Workflow Implementation

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

# 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:

// 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 – Primary definition of trunk-based development, branch strategy, and commit discipline.
• README.md (engineering practices section) – Contextualizes trunk-based development within Google-style engineering practices.
• .github/workflows/test-plugin-install.yml – CI pipeline configuration assuming main is always deployable.
• 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 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.

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, while enforcement occurs through:

• agents/code-reviewer.md (agent instructions for PR reviews)
• .github/workflows/test-plugin-install.yml (CI assuming deployable main)
• README.md (engineering practices context)

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}