# GIT Workflow

Squad branching model: dev-first workflow with insiders preview channel

- Repository: https://github.com/microsoft/waza (1496 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add microsoft/waza --skill git-workflow -g -a claude-code -y`
Codex: `npx skills add microsoft/waza --skill git-workflow -g -a codex -y`
Cursor: `npx skills add microsoft/waza --skill git-workflow -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/waza --skill git-workflow -g -a gemini-cli -y`

## Description

Squad branching model: dev-first workflow with insiders preview channel

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## Context

Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.**

| Branch | Purpose | Publishes |
|--------|---------|-----------|
| `main` | Released, tagged, in-npm code only | `npm publish` on tag |
| `dev` | Integration branch, all feature work lands here | `npm publish --tag preview` on merge |
| `insiders` | Early-access channel, synced from dev | `npm publish --tag insiders` on sync |

## Branch Naming Convention

Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}`

Examples:
- `squad/195-fix-version-stamp-bug`
- `squad/42-add-profile-api`

## Workflow for Issue Work

1. **Branch from dev:**
   ```bash
   git checkout dev
   git pull origin dev
   git checkout -b squad/{issue-number}-{slug}
   ```

2. **Mark issue in-progress:**
   ```bash
   gh issue edit {number} --add-label "status:in-progress"
   ```

3. **Create draft PR targeting dev:**
   ```bash
   gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft
   ```

4. **Do the work.** Make changes, write tests, commit with issue reference.

5. **Push and mark ready:**
   ```bash
   git push -u origin squad/{issue-number}-{slug}
   gh pr ready
   ```

6. **After merge to dev:**
   ```bash
   git checkout dev
   git pull origin dev
   git branch -d squad/{issue-number}-{slug}
   git push origin --delete squad/{issue-number}-{slug}
   ```

## Parallel Multi-Issue Work (Worktrees)

When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead.

### When to Use Worktrees vs Sequential

| Scenario | Strategy |
|----------|----------|
| Single issue | Standard workflow above, no worktree needed |
| 2+ simultaneous issues in same repo | Worktrees, one per issue |
| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) |

### Setup

The rest: https://github.com/microsoft/waza/blob/HEAD/.github/skills/git-workflow/SKILL.md