Stacked Git Workflow (-- Sub-Branching) 🌿

An agentic AI workflow skill for managing lightweight, stacked git feature branches using double-dash (--) naming conventions.

Author: Mwila (@swengineermwi)

---

🎯 The Problem

When working on a primary feature in GitFlow, developers frequently discover complementary, auxiliary, or dependent tasks (e.g. database schema migrations, utility helpers, secondary endpoints).

Traditional GitFlow forces a lose-lose choice:

1. Bloated Branches: Mix unrelated changes into a single branch, producing messy, hard-to-review commits.
2. Context Interruption: Stop momentum to run a full GitFlow cycle (PR, CI build, review, merge into develop, re-branching off develop), destroying developer velocity.

---

🚀 The Solution: Double-Dash (--) Sub-Branching

The Stacked Git Workflow allows developers and AI coding agents to spawn lightweight sub-branches directly off active feature branches using double-dashes (--):

feat/payments
  └── feat/payments--account-social-profile-update-endpoint
        └── feat/payments--account-social-profile-update-endpoint--db-doc-copy

• Zero-Friction Context Isolation: Keeps complementary work cleanly modularized.
• Fast Local Collapse: When completed, leaf branches unwind and merge back up layer-by-layer without engaging full PR/CI overhead.
• Clean Cascade Promotion: Fully tested, combined feature stacks promote cleanly into develop and main.

---

📥 Installation in Antigravity

To install this skill in any project using Google Antigravity (AGY CLI / IDE):

mkdir -p .agents/skills/stacked-git-workflow && \
curl -sSL https://raw.githubusercontent.com/swengineermwi/antigravity-stacked-git-skill/main/SKILL.md \
-o .agents/skills/stacked-git-workflow/SKILL.md

---

🔄 How the Unwinding Algorithm Works

When a nested sub-task is completed:

1. Unwind Leaf: Merge ...--subtask into its direct parent branch.
2. Prune: Delete the merged child branch locally (git branch -d) and remotely (git push origin --delete).
3. Cascade Up: Repeat steps 1-2 up the stack to the base feature, develop, and main.

graph TD
    Subchild["Layer 2: feat/...--endpoint--db-doc-copy"] -->|1. Merge & Prune| Child["Layer 1: feat/...--endpoint"]
    Child -->|2. Merge & Prune| Base["Base Feature: feat/payments"]
    Base -->|3. Merge & Prune| Dev["develop"]
    Dev -->|4. Merge| Main["main"]

Loading

---

📜 License

MIT © Mwila