| 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_itemvcs_create_prvcs_merge_prvcs_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:
- Expected build result (success/failure and why)
- Expected files in the diff (list them)
- 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>
