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.