Skip to content

docs: update branch creation to recommend worktrees for parallel sessions #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
marcusquinn wants to merge 1 commit into from
Closed

docs: update branch creation to recommend worktrees for parallel sessions #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions .agent/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,15 @@ If the script outputs "STOP - ON PROTECTED BRANCH", you MUST NOT proceed with ed

> On `main`. Suggested branch: `{type}/{suggested-name}`
>
> 1. Create suggested branch (recommended)
> 2. Use different branch name
> 3. Stay on `main` (not recommended)

3. **Do NOT proceed until user replies with 1, 2, or 3**
4. After creating branch, call `session-rename_sync_branch` tool
> 1. Create worktree for suggested branch (recommended for parallel sessions)
> 2. Create branch with checkout (switches current directory's branch)
> 3. Use different branch name
> 4. Stay on `main` (not recommended)

3. **Do NOT proceed until user replies with 1, 2, 3, or 4**
4. If worktree (option 1): `~/.aidevops/agents/scripts/worktree-helper.sh add {type}/{name}`
5. If checkout (option 2): `git checkout -b {type}/{name}`
6. After creating branch, call `session-rename_sync_branch` tool
Comment on lines +36 to +39
Copy link

@gemini-code-assist gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This new set of instructions has a couple of areas for improvement:

  1. The sequential numbering of steps 4, 5, and 6 can be confusing, as steps 4 and 5 are mutually exclusive. It would be clearer to restructure this to show that creating a branch is a single step with different options.
  2. The placeholder {name} is used here, but pre-edit-check.sh uses {description}. To maintain consistency across the documentation and scripts, it's better to use a single placeholder. {description} seems more descriptive.

Here is a suggested revision that addresses both points:

Suggested change
3. **Do NOT proceed until user replies with 1, 2, 3, or 4**
4. If worktree (option 1): `~/.aidevops/agents/scripts/worktree-helper.sh add {type}/{name}`
5. If checkout (option 2): `git checkout -b {type}/{name}`
6. After creating branch, call `session-rename_sync_branch` tool
3. **Do NOT proceed until user replies with 1, 2, 3, or 4**
4. After user reply, create the branch:
- If option 1 (worktree): `~/.aidevops/agents/scripts/worktree-helper.sh add {type}/{description}`
- If option 2 (checkout): `git checkout -b {type}/{description}`
5. After creating branch, call `session-rename_sync_branch` tool


**Why this matters**: Skipping this check causes direct commits to `main`, bypassing PR review.

Expand Down
8 changes: 7 additions & 1 deletion .agent/scripts/pre-edit-check.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,13 @@ if [[ "$current_branch" == "main" || "$current_branch" == "master" ]]; then
echo " refactor/description - Code restructuring"
echo ""
echo "To create a branch:"
echo " git checkout -b chore/your-description"
echo ""
echo " Option A - Worktree (recommended for parallel sessions):"
echo " ~/.aidevops/agents/scripts/worktree-helper.sh add {type}/{description}"
echo " cd ../{repo}-{type}-{description}"
Copy link

@gemini-code-assist gemini-code-assist bot Jan 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This line hardcodes the directory naming convention for the new worktree (../{repo}-{type}-{description}). This is brittle because if the worktree-helper.sh script changes its directory naming logic, this instruction will become incorrect. A more robust approach would be for worktree-helper.sh to print the path of the created worktree, and the instructions here would guide the user to cd into that printed path. This would decouple the instruction from the implementation details of the helper script.

echo ""
echo " Option B - Traditional checkout:"
echo " git checkout -b {type}/{description}"
echo ""
echo -e "${RED}DO NOT proceed with edits until on a feature branch.${NC}"
echo ""
Expand Down