Pr Management

PR Management — 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.

Repo Context

• Owner: rivie13
• Repo: Phoenix-Agentic-Engine-Interface
• Default branch: main

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.

Branch hierarchy

Create a Pull Request

Step 1: Check for PR template

mcp_github_github_get_file_contents(owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", path=".github/PULL_REQUEST_TEMPLATE.md")

Step 2: Create the PR

mcp_github_github_create_pull_request(
  owner="rivie13",
  repo="Phoenix-Agentic-Engine-Interface",
  title="<descriptive title>",
  body="<description>",
  head="<feature-branch>",
  base="<parent branch>"  # main for feature branches; feature/<topic> for subfeature branches
)

PR description should include (use MCP tools to set):

• Summary: What changed and why
• Changes: Bullet list of key changes
• Testing: What was tested and how, with pass/fail results
• Breaking changes: Backward compatibility assessment for any contract changes
• Related issues: Link related issues with Closes #N or Relates to #N
• Test results (npm test output)
• If fixtures changed: confirmation that backend golden tests also pass

List Open PRs

mcp_github_github_list_pull_requests(owner="rivie13", repo="Phoenix-Agentic-Engine-Interface", state="open")

Request Copilot Review

Copilot review is often auto-triggered. Before requesting manually, check whether a Copilot review already exists for the latest commit set on the PR.

Use:

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

Only request Copilot review if it is missing for the latest commits:

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

Verify PR workflow checks

Before marking a PR ready/mergeable:

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 workflow/job failed, fetch logs, fix root causes, and re-check until required checks are green.

Branch conventions

• feature/<name> — large deliverables (epic-level), branches from main, PR targets main
• subfeature/task/<name> — new functionality within a feature
• subfeature/bugfix/<name> — bug fixes within a feature
• subfeature/refactor/<name> — refactoring within a feature
• subfeature/test/<name> — test additions/fixes within a feature
• subfeature/docs/<name> — documentation within a feature
• subfeature/chore/<name> — maintenance/tooling within a feature
• contract/<name> — contract/schema changes (legacy, prefer subfeature pattern)

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 (secrets, auth, proprietary logic, security vulnerabilities).
• Search for existing issues before creating duplicates using mcp_github_github_search_issues.
• Use issues to break large features into smaller, trackable units of work.

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. Priority, Size, Work mode, and Status are project board fields (rivie13/projects/3), NOT GitHub labels.

To set project fields, add signal labels (set:<field>:<value>) when updating an issue:

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

The sync-project-fields.yml workflow sets the field via GraphQL and removes the signal label automatically.

Signal labels: set:priority:p0–p3, set:size:xs/s/m/l, set:workmode:cloud-agent/local-ide/cli-agent, set:status:backlog/ready/in-progress/in-review/done, set:area:<area-name>.

For cloud-agent labeled issues, cloud-agent-assign.yml already handles Work mode + Status — only add priority, size, and area signal labels.

Post-merge issue completion (mandatory)

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

Step 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")

Step 2: Close any completed sub-issues

Read the parent issue to list sub-issues. For each sub-issue whose work is merged, close it if still open.

Step 3: Check if parent epic should be closed

If the closed issue was a sub-issue of an epic, check whether all sibling sub-issues are now closed. If so, close the epic.

Step 4: Set Status → Done on project board

Add a signal label to move the issue to Done:

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

The sync-project-fields.yml workflow will set the Status field and remove the signal label.

Rule: Never consider a PR "fully done" until all linked issues are verified closed and moved to Done. This is as important as passing CI.