Git Hygiene

Git Hygiene — Phoenix Agentic Engine Interface

CLI tool policy (mandatory)

• NEVER use gh CLI — it is not installed and must not be used.
• Always prefer GitHub MCP tools (mcp_github_*) for all GitHub operations.
• Fall back to terminal git commands only for local worktree operations or when MCP tools fail.
• Do NOT suggest or attempt any gh subcommand.

Mandatory first step: terminal scope check

1. Set-Location "C:\Users\rivie\vsCodeProjects\Phoenix-Agentic-Engine-Interface"
2. Get-Location
3. git rev-parse --show-toplevel
4. git branch --show-current

Branch workflow

1. Sync base branch:

git checkout main
git pull --ff-only

2. Create focused branch:

git checkout -b feature/<short-topic>

3. Keep PR scope single-purpose and small.

PR size discipline (mandatory)

• Keep PRs small and focused — one logical change per PR.
• Use the three-tier branch hierarchy to keep PRs reviewable:
  1. Create subfeature/<type>/<description> branches off the parent feature/<topic> branch for discrete pieces of work.
  2. Open PRs from each subfeature branch into the feature branch (small, reviewable).
  3. Once subfeature PRs are merged, open a single PR from the feature branch into main (large, expected).
• Target: Subfeature PRs should ideally be under ~400 lines of meaningful change.
• If a PR exceeds this, strongly consider splitting into additional subfeature branches before requesting review.

Pre-commit quality gate (required)

Run all:

npm run lint
npm run typecheck
npm test

If any command fails, fix before committing.

Commit workflow

git status
git add <focused file set>
git commit -m "feat: <short summary>"

Recommended prefixes: feat, fix, chore, docs, test.

PR workflow (use GitHub MCP tools — never gh CLI)

1. Create PR:

mcp_github_github_create_pull_request(owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", title="...", body="...", head="<branch>", base="main")

2. Check whether Copilot review already exists for the latest commits:

mcp_github_github_pull_request_read(method="get_reviews", owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", pullNumber=<PR_NUMBER>)

If Copilot review is missing for the latest commit set, request it:

mcp_github_github_request_copilot_review(owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", pullNumber=<PR_NUMBER>)

3. Read and handle reviews/comments:

mcp_github_github_pull_request_read(method="get_reviews", owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", pullNumber=<PR_NUMBER>)
mcp_github_github_pull_request_read(method="get_review_comments", owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", pullNumber=<PR_NUMBER>)

4. Check PR workflow status and fix failures before merge readiness:

mcp_github_github_actions_list(method="list_workflow_runs", owner="rivie13", repo="Phoenix-Agentic-Engine-Interface")
mcp_github_github_actions_list(method="list_workflow_jobs", owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", resource_id="<RUN_ID>")

If any job fails, use the GitHub Actions Debug skill flow to inspect logs, fix root causes, and re-run/recheck.

5. Apply fixes and re-run quality gate.

Interface-specific checks for PR readiness

• npm run lint passes
• npm run typecheck passes
• npm test passes
• PR workflow/status checks are green
• Contract changes include fixture + schema + tests
• No backend-only logic added (prompts/orchestration/policy)

Issue creation (public repo — never use gh CLI)

• Create issues using mcp_github_github_issue_write.
• For non-sensitive, public-facing work: assign to Copilot (cloud agent) using mcp_github_github_assign_copilot_to_issue.
• Do NOT create public issues for private/sensitive matters.
• Search for existing issues before creating duplicates using mcp_github_github_search_issues.

Issue–branch alignment

• Epic issues map to feature/* branches; close the epic when the feature branch merges to main.
• Sub-issues map to subfeature/<type>/<description> branches; reference with Closes #N in the subfeature PR and close explicitly via MCP tools after merge.
• Create sub-issues via mcp_github_github_sub_issue_write.

Project board field management (mandatory)

Labels ≠ project fields. The project board (rivie13/projects/3) has separate single-select fields (Priority, Size, Work mode, Status) that are NOT GitHub labels. Never create labels named after field values.

MCP tools cannot set project fields directly. Use signal labels (set:<field>:<value>) as a bridge:

mcp_github_github_issue_write(method="update", ..., labels=["task", "set:priority:p1", "set:size:m"])

The sync-project-fields.yml workflow detects signal labels, sets the project field via GraphQL, and removes the signal label. The issue keeps only its real labels.

Available signal labels:

When to set fields: On issue creation or when triaging. For cloud-agent labeled issues, the cloud-agent-assign.yml workflow already sets Work mode and Status — only add set:priority:*, set:size:*, and set:area:* signal labels.

Post-merge issue completion (mandatory)

After any PR is merged, always close linked issues explicitly. Do NOT rely solely on Closes #N in the PR body — GitHub only auto-closes issues when merging into the repo's default branch. Subfeature PRs that merge into feature/* branches will NOT auto-close linked issues.

1. Close the linked issue:

   mcp_github_github_issue_write(method="update", owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", issueNumber=<N>, state="closed", stateReason="completed")
   

2. Close completed sub-issues — if this was a parent issue with sub-issues, verify each merged sub-issue is closed.

3. Close parent epic if all children are done — if this was a sub-issue, check whether all sibling sub-issues are now closed. If so, close the parent epic too.

4. Set Status → Done on the project board using a signal label:

   mcp_github_github_issue_write(method="update", owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", issueNumber=<N>, labels=["task", "set:status:done"])
   

Rule: A PR is not "fully done" until all linked issues are verified closed.