git-workflow

Implements a dev-first branching model with worktrees and multi-repo coordination for Git workflows.

Updated Jun 2, 2026
One-click install
npx skills add https://github.com/codebytes/btt --skill git-workflow-codebytes
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: git-workflow
Source: https://github.com/codebytes/btt/tree/main/.copilot/skills/git-workflow
Command: npx skills add https://github.com/codebytes/btt --skill git-workflow-codebytes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams working on multiple issues simultaneously often struggle with branch chaos, PRs targeting the wrong base branch, and filesystem collisions between parallel workstreams. This Skill enforces a consistent three-branch model (main, dev, insiders) with clear rules for branching, PRs, and cleanup. ## Core Features & Use Cases - Dev-First Branching: All feature branches follow the squad/{issue-number}-{slug} convention, branch from dev, and open draft PRs targeting dev with issue linkage. - Parallel Work with Git Worktrees: Run multiple agents on separate issues simultaneously using isolated worktrees, avoiding branch-switching and filesystem conflicts. - Multi-Repo Coordination: Coordinate dependent PRs across sibling repositories with local linking (npm link, go replace, pip install -e) for pre-merge testing. - Use Case: A coordinator assigns three bugs to three agents at once. Each agent creates a worktree from dev, commits fixes, pushes a branch, and opens a draft PR to dev — all without interfering with each other. ## Quick Start Create a new issue branch from dev following the squad naming convention and open a draft PR targeting dev.

Frequently Asked Questions about git-workflow

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up git worktrees for parallel issue work?

Run git fetch origin dev, then git worktree add ../repo-{issue-number} -b squad/{issue-number}-{slug} origin/dev for each issue. Each worktree gets its own directory and branch while sharing the same .git object store.

How to create a draft PR targeting a dev branch with GitHub CLI?

Use gh pr create --base dev --title "description" --body "Closes #{issue-number}" --draft after pushing your branch. Mark it ready for review later with gh pr ready.

When should I use git worktrees vs separate clones?

Use worktrees for parallel issues within the same repository since they share the object store and avoid branch switching. Use separate sibling clones when work spans multiple repositories, such as a CLI depending on an SDK.

Can I test changes across multiple repos before merging PRs?

Yes, use npm link for Node.js, a replace directive in go.mod for Go, or pip install -e for Python to link local repos. Remove these links before committing since CI must use published packages.

What happens to .squad state files when using worktrees?

Each worktree has its own copy of .squad/ files, which is safe because .gitattributes declares merge=union on append-only files. Never rewrite or reorder these files in a worktree — append only.

Why should feature branches not target main directly?

The workflow reserves main for released, tagged code published to npm. All feature work integrates through dev first, which publishes preview builds, and only merges to main for stable releases.