git-workflow

name	git-workflow
description	Standard unified VCS workflow — every code change must go through a branch, PR, and merge for traceability.

Unified VCS Workflow

Every code change must be traceable via a branch and Pull Request. No direct commits to `master`.

<tools_required>

• vcs_create_work_item
• vcs_create_pr
• vcs_merge_pr
• vcs_add_comment
• Terminal (for git commands) </tools_required>

NEVER use the `gh` CLI. Use MCP tools and local `git` only. NEVER use legacy `github_*` MCP tools. Use `vcs_*` equivalents. NEVER commit directly to `master` or `main`. Every change MUST have a PR — this is the traceability guarantee. ALWAYS switch back to `master` after pushing a feature branch. ALWAYS use `git pull --rebase origin master` instead of `git pull origin master`. This prevents merge commit noise. NEVER run `git push origin master` or `git push origin main` directly. ALL code MUST enter master/main through `vcs_create_pr` + `vcs_merge_pr`. Direct push to protected branches is a violation of Issue-First SDLC. First, check if a Tracking Issue already exists: - Look for a "## Tracking Issue" section in your prompt header — it contains the pre-created Issue number - Check the `OPTIMUS_TRACKING_ISSUE` environment variable If a Tracking Issue exists, use it. Do NOT create a duplicate. If none exists, create one via `vcs_create_work_item`. Capture the Issue ID (e.g., `#113`). Do not proceed without one. Using local terminal commands: 1. `git checkout -b feature/issue--` 2. Stage and commit: `git commit -m "feat: , fixes #"` 3. Push: `git push -u origin ` Before creating a PR, you MUST verify your changes: 1. If the project has a build step (e.g., `npm run build`, `dotnet build`), run it and confirm zero errors. 2. If test scripts exist (e.g., `npm test`), run them and confirm all pass. 3. If neither exists, at minimum review the diff (`git diff HEAD~1`) to sanity-check your changes.

Hypothesis-Driven Verification: Before running verification commands, explicitly state your expectations:

1. Expected build result (success/failure and why)
2. Expected files in the diff (list them)
3. Expected scope boundary (files that should NOT be changed)

After running, compare actual results to expectations. Report discrepancies in your output under ## Expected vs Actual. Unexpected results indicate either a bug in the implementation or a gap in understanding.

Do NOT create a PR with broken builds or failing tests.

Invoke `vcs_create_pr` with `title`, `head`, `base` (master), and `body` containing `Fixes #`. Invoke `vcs_merge_pr` to merge the PR into master. Use `merge_method: "squash"` for clean history. Run `git checkout master && git pull --rebase` to sync the merged changes locally.

<error_handling>

• 401/403 Credential Error: Halt and instruct user to verify GITHUB_TOKEN or ADO_PAT.
• Comment Type Error: vcs_add_comment requires item_type: "workitem" or "pullrequest".
• Merge Conflict: DO NOT force push. Halt and request intervention. </error_handling>