GIT Workflow

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:

   git checkout dev
   git pull origin dev
   git checkout -b squad/{issue-number}-{slug}
   

2. Mark issue in-progress:

   gh issue edit {number} --add-label "status:in-progress"
   

3. Create draft PR targeting dev:

   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:

   git push -u origin squad/{issue-number}-{slug}
   gh pr ready
   

6. After merge to dev:

   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