Pr Management

PR Management — Phoenix Agentic Website Frontend

CLI tool policy (mandatory)

• Prefer GitHub MCP tools (mcp_github_*) for structured GitHub operations.
• gh CLI is allowed and supported; use it when MCP capability is unavailable/insufficient, and for project/GraphQL-heavy operations.
• Use terminal git commands for local worktree operations.

Repo Context

• Owner: rivie13
• Repo: Phoenix-Agentic-Website-Frontend
• Default branch: main
• Visibility: Public

Branch hygiene (required)

Three-tier branch hierarchy:

1. Start from latest main for new features; start from the parent feature/* branch for subfeature work.
2. Create a focused topic branch following the hierarchy above.
3. Keep scope narrow; avoid unrelated file changes.
4. Run full check (npm run lint; npm run typecheck; npm run test; npm run build) before push.
5. Never force-push shared branches unless explicitly coordinated.

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 (excluding generated files, lock files).
• If a PR exceeds this, strongly consider splitting into additional subfeature branches before requesting review.
• Never let PRs accumulate dozens of unrelated changes.

Create a Pull Request

Step 1: Check for PR template

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

Step 2: Get current branch changes

Use get_changed_files to see what's modified.

Step 3: Create the PR

mcp_github_github_create_pull_request(
  owner="rivie13",
  repo="Phoenix-Agentic-Website-Frontend",
  title="<descriptive title>",
  body="<use template if found>",
  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: Any compatibility concerns
• Related issues: Link related issues with Closes #N or Relates to #N
• Confirmation that full check passes (lint + typecheck + test + build)
• Security boundary notes for auth/API integration changes

List Open PRs

mcp_github_github_list_pull_requests(owner="rivie13", repo="Phoenix-Agentic-Website-Frontend", state="open")

Check PR Status

mcp_github_github_pull_request_read(method="get", owner="rivie13", repo="Phoenix-Agentic-Website-Frontend", pullNumber=<PR_NUMBER>)

PR CI/workflow gate (required)

After PR creation and after each push:

1. Check PR status checks and workflow runs.
2. If any check fails, use the github-actions-debug skill to triage root cause.
3. Fix code/workflow issues, re-run local validation, and push again.
4. Re-check until required checks are green.

Suggested run discovery commands:

mcp_github_github_actions_list(method="list_workflow_runs", owner="rivie13", repo="Phoenix-Agentic-Website-Frontend")
mcp_github_github_actions_list(method="list_workflow_jobs", owner="rivie13", repo="Phoenix-Agentic-Website-Frontend", resource_id="<workflow_run_id>")

Request Copilot Review

Copilot review is often auto-triggered. Before requesting manually, first check whether one already exists.

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

Branch conventions

• feature/<name> / feat/<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

Issue creation (public repo — MCP preferred, gh fallback allowed)

• Prefer creating issues using mcp_github_github_issue_write; gh issue create is acceptable when MCP is unavailable.
• 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-Website-Frontend", 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-Website-Frontend", 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.