| name | git-worktree-workflow |
| description | Set up and use an isolated Git worktree for repository implementation tasks. Use unless the user explicitly requests another workspace arrangement. |
Git Worktree Workflow
Work in an isolated checkout
-
Inspect the repository state; treat uncommitted and untracked files in the original checkout as user work.
-
Fetch the requested base branch. Use main when no base is specified.
-
Create a short descriptive branch and worktree under .agents/worktrees/, for example:
git fetch origin main
git worktree add -b <branch-name> .agents/worktrees/<branch-name> origin/main
-
Inspect an existing branch or path before reuse; choose a new name if it is not clearly the task workspace.
-
Make all implementation changes in the new worktree. Do not remove another worktree unless the user explicitly
requests it.
Implement and verify
- Split the work into practical phases.
- For each phase, implement the scoped change, run repository-appropriate formatting and verification, then commit it
with
commit-message-quality-check.
- Before pushing, review the complete diff, recent commits, scope, and missing verification; run the final relevant
checks.
- Push and create or update the PR with
pull-request-quality-check when requested.
- Before squash-merging a GitHub pull request, obtain its canonical title and number from GitHub. Explicitly set the
commit subject to
<pull request title> (#<pull request number>); do not rely on a CLI default or omit the number.
Pass that exact subject through the merge command's --subject option; constructing it only in a candidate file or
reading the PR title is insufficient. After merging, inspect the stored commit subject and confirm it still contains
that exact number suffix.
- Before a PR merge command performs local branch cleanup, check every active worktree. Do not let a hosted-PR CLI
switch to the default branch or delete a branch when that branch is checked out by another worktree. Merge first;
then perform any safe remote or local branch cleanup as a separate action.
Use documented builds, tests, linters, formatters, or structural validators appropriate to the change. State skipped
verification and its reason in the PR body. After a branch is pushed or attached to a PR, add follow-up commits rather
than rewriting history unless the user explicitly requests a rewrite.
