Git Workflow

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

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:

   bashCopy

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

2. Mark issue in-progress:

   bashCopy

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

3. Create draft PR targeting dev:

   bashCopy

   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:

   bashCopy

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

6. After merge to dev:

   bashCopy

   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

Setup

From the main clone (must be on dev or any branch):

Naming convention: ../{repo-name}-{issue-number} (e.g., ../squad-195, ../squad-pr-42).

Each worktree:

• Has its own working directory and index
• Is on its own squad/{issue-number}-{slug} branch from dev
• Shares the same .git object store (disk-efficient)

Per-Worktree Agent Workflow

Each agent operates inside its worktree exactly like the single-issue workflow:

All PRs target dev independently. Agents never interfere with each other’s filesystem.

.squad/ State in Worktrees

The .squad/ directory exists in each worktree as a copy. This is safe because:

• .gitattributes declares merge=union on append-only files (history.md, decisions.md, logs)
• Each agent appends to its own section; union merge reconciles on PR merge to dev
• Rule: Never rewrite or reorder .squad/ files in a worktree — append only

Cleanup After Merge

After a worktree’s PR is merged to dev:

If a worktree was deleted manually (rm -rf), git worktree prune recovers the state.

Multi-Repo Downstream Scenarios

When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user’s app depends on squad):

Setup

Clone downstream repos as siblings to the main repo:

Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Squad conventions, use squad/{issue-number}-{slug}.

Coordinated PRs

• Create PRs in each repo independently
• Link them in PR descriptions:

  Copy

  Closes #42
  
  **Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature)

• Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli)

Local Linking for Testing

Before pushing, verify cross-repo changes work together:

Important: Remove local links before committing. npm link and go replace are dev-only — CI must use published packages or PR-specific refs.

Worktrees + Multi-Repo

These compose naturally. You can have:

• Multiple worktrees in the main repo (parallel issues)
• Separate clones for downstream repos
• Each combination operates independently

Anti-Patterns

• ❌ Branching from main (branch from dev)
• ❌ PR targeting main directly (target dev)
• ❌ Non-conforming branch names (must be squad/{number}-{slug})
• ❌ Committing directly to main or dev (use PRs)
• ❌ Switching branches in the main clone while worktrees are active (use worktrees instead)
• ❌ Using worktrees for cross-repo work (use separate clones)
• ❌ Leaving stale worktrees after PR merge (clean up immediately)

Promotion Pipeline

• dev → insiders: Automated sync on green build
• dev → main: Manual merge when ready for stable release, then tag
• Hotfixes: Branch from main as hotfix/{slug}, PR to dev, cherry-pick to main if urgent