Command index

The following commands will run the processes below:

• update: Stage, commit, and push all changes to the remote repository. See "### Update" below.
• merge to main: Merge the current branch into the main branch. See "### Merge to main" below.
• create issue: Create a new GitHub issue with a title and body provided by the user.
• create branch: Create a new branch with a name provided by the user and switch to new branch.
• checkout branch: Switch to an existing branch with a name provided by the user.
• list branches: List all branches in the repository.
• status: Show current git status. See "### Status" below.
• log: Show recent git commit history. See "### Log" below.
• branch: Show current branch name. See "### Branch" below.
• revert: Revert a specific commit by its hash, provided by the user.

Environment

Virtual environment: If the Python virtual environment becomes deactivated during this process, reactivate it using

./activate

(or the project-specific activation script) in the terminal. Use terminal window: This is Windows PowerShell within

VS Code

; using

SSH

.

Keep responses concise

• Do not share what your to-do list or plan is. Just do it.
• No need for anything like, "Now I need to..." or "Now I will..."
• Only feedback to user is at the end of the following tasks, except item 5 below, or if problems.
• For successful runs, respond with one short summary line plus essential details (for example, branch name, commit hash, and remote synchronization status).
• For failed runs, respond with one short summary line plus a key error message snippet and one or two concrete suggested next steps.
• Example success summary:

  • Update complete: 3 files committed on branch feature/x, pushed to origin/feature/x; local and remote are in sync.

Command workflows

All workflows

For every command workflow below:

• Error handling: if any step encounters an error, stop, capture the error output, and provide troubleshooting ideas and choices to user, instead of continuing.
• Prohibited operations:
  • Never use

    git push --force

    or

    --force-with-lease

    on main.
  • Do not use

    git rebase

    on main.
• Default remote: Default remote is assumed to be

  origin

  . If multiple remotes exist, prefer

  origin

  unless the user specifies otherwise.
• Do not ask the user for permission to run git commands. Just run them and report the result.
• Run each git command separately (never chain with

  ;

  or

  &&

  in the command string).

Update

• Stage, Commit, and Push Git Changes Carefully follow all of the following steps in order:

1. Examine repository's current status, showing all modified, untracked, and staged files
2. Research: Determine what was changed. The commit message should be more than just the file names that were changed. Use:

   • codebase_search

   • read_file

   • search_files

3. Stage all changes: Handle special cases as needed.
4. Commit message: Craft a meaningful commit message that follows best practices:
   • Concise subject line.
   • Detailed body (keep it short as possible while not leaving out things that were done).
   • Using a Windows PowerShell terminal.
   • Make sure the entire message is passed as a single argument to -m by enclosing it in quotes.
   • Include file paths for all changed files.
   • Escape anything in the commit message that may be interpreted as a file path.
5. Commit: Do not ask the user for permission to commit. Just do the commit. Commit permission: You have full permission to run all commit commands, including ones using the "-m" flag with accompanying message. You have permission to run any variation of

   git commit

   , including, but not limited to

   git commit -m "[commit message here]"

   . Do not ask the user for permission to run git commands. Just run them.
6. Verify the commit was successful and show its hash/details.
7. Push changes to the remote repository on current branch. Pay attention to the terminal where it may ask you for a password. If so, get that password using your project knowledge; it may be referenced via the

   Critical Resources

   section in

   .roo/rules/01-general.md

   .
8. Confirm the synchronization status between local and remote repositories.

Create branch

• Create a new branch with a name provided by the user and switch to new branch. Carefully follow all of the following steps in order:

1. Branch name:
   • If the user did not provide a branch name, STOP and ask for it.
   • Prefer names like

     feature/<short-name>

     or

     fix/<short-name>

     .
2. Examine repository's current status and current branch:
   • Run each git command separately (never chain with

     ;

     or

     &&

     in the command string).
   • Get current branch:

     git branch --show-current

   • Get status:

     git status -sb

   • If there are uncommitted changes, note that they will carry over to the new branch.
3. Validate branch name:
   • Validate the requested name using

     git check-ref-format --branch "<branch_name>"

     .
   • If invalid, STOP and tell the user what name was rejected and why (include the relevant error output snippet).
4. Verify branch does not already exist:
   • Check for an existing local branch with that exact name.
   • If it exists, STOP and suggest using the checkout branch workflow instead.
5. Create and switch:
   • Create the branch and switch to it (prefer

     git switch -c <branch_name>

     ).
6. Verify:
   • Confirm the new current branch name.
   • Show a short status summary to confirm expected state.

Merge to main

• Merge the current branch into the main branch. Carefully follow all of the following steps in order:

1. Identify current branch:
   • Show the current branch name.
   • Store it for later use when merging into

     main

     and optionally switching back.
2. Verify clean working tree on current branch:
   • Show the status to confirm there are no unstaged or uncommitted changes.
   • If there are uncommitted changes, STOP:
     • Do not auto-commit, auto-stash, or discard changes.
     • Inform the user that they must either:
       • Run the update workflow to commit/push changes, or
       • Manually commit/stash/reset before retrying merge to main.
3. Fetch latest from remote:
   • Fetch from the default remote (usually

     origin

     ) to ensure

     main

     is up-to-date before merging.
4. Switch to main branch:
   • Checkout the local

     main

     branch.
   • If

     main

     does not exist locally, create it to track

     origin/main

     (fast-forward only).
5. Update local main from remote:
   • Pull the latest changes into

     main

     from

     origin/main

     .
   • Confirm that

     main

     is now synchronized with its remote counterpart.
6. Merge feature branch into main:
   • Merge the previously identified branch into

     main

     using a standard merge (no rebase).
   • Prefer

     --no-ff

     where appropriate so the merge is explicit in history.
   • If there are merge conflicts:
     • Show the list of conflicting files.
     • Do not attempt complex or destructive auto-resolution.
     • Stop and summarize the conflicts so the user can resolve them manually or via another mode.
7. Verify merge on main:
   • Show the new commit graph or recent log entries on

     main

     , including the merged branch commits.
   • Confirm that the merge commit (or equivalent fast-forward) is present.
8. Push main to remote:
   • Push the updated

     main

     branch to the remote (usually

     origin

     ).
   • Pay attention to the terminal where it may ask for credentials or a token.
     • If so, obtain that information using project knowledge; it may be referenced via the

       Critical Resources

       section in

       .roo/rules/01-general.md

       .
9. Post-merge verification:
   • Confirm that local

     main

     and remote

     main

     are in sync.
   • Optionally, verify that the feature branch is fully merged into

     main

     (e.g., using a merged-branches check).
10. Restore previous context:
    • Optionally switch back to the original working branch so the user can continue work where they left off.

Status

Purpose: Show working tree and staging state. Steps: Errors → run git status -sb → briefly interpret high-level state.

Log

Purpose: Show recent history. Steps: Errors → run a concise log (git log --oneline -n 10 or similar) → avoid over-long output.

Branch

Purpose: Show current branch. Steps: Errors → run git branch --show-current → state the branch name plainly in the summary.