GitHub Operations

Full contribution lifecycle — from branch creation to PR merge. MCP tools preferred; gh CLI as fallback.

Contribution Lifecycle

1. Create branch (naming convention) →
2. Make changes →
3. Commit (conventional commits) →
4. Push (pre-push hooks validate branch + scope) →
5. Create PR (MCP tools) →
6. Review + Merge

Branch Naming (Mandatory)

Before any commit or PR, validate the branch name:

git rev-parse --abbrev-ref HEAD

If the branch name is invalid, stop and suggest renaming: git branch -m <old-name> feat/<descriptive-name>

For domain-scoped branches, verify changed files are within scope. If files are out of scope, suggest feat/ or fix/ instead.

📋 Full rules: Read references/branch-strategy.md for scope tables, validation commands, and enforcement layers.

Conventional Commits (Mandatory)

Commit messages must follow Conventional Commits format (enforced by commitlint):

<type>[optional scope]: <description>

Scopes: agents, skills, instructions, bicep, terraform, mcp, docs, scripts

📋 Full workflow: Read references/commit-conventions.md for staging, breaking changes, best practices, and safety protocol.

MCP Priority Protocol (Mandatory)

1. Identify required operation (issue, PR, search, Actions, release, etc.)
2. Check whether an MCP tool exists for that operation
3. If MCP exists, use MCP only
4. Use gh CLI only when no equivalent MCP tool is available

Devcontainer Reliability Rule

• Do not run gh auth login in devcontainer workflows
• GH_TOKEN must be set via VS Code User Settings (terminal.integrated.env.linux)
• For PR/issue creation, rely on MCP tool authentication by default
• If MCP write tools are missing, report explicitly and provide fallback

Issues (MCP Tools)

Creating issues — Required: owner, repo, title, body. Title guidelines: prefix with [Bug], [Feature], [Docs]; keep under 72 chars.

Pull Requests (MCP Tools)

Creating PRs

Required: owner, repo, title, head (source branch), base (target branch)

Pre-flight checks (mandatory before creating):

1. Validate branch name (see Branch Naming above)
2. For domain branches, verify files are in scope
3. Search for PR templates in .github/PULL_REQUEST_TEMPLATE/
4. Title must follow conventional commit format

Default merge method: squash unless user specifies otherwise.

📋 Smart PR Flow: Read references/smart-pr-flow.md for PR lifecycle states, auto-labels, and auto-merge conditions.

CLI Commands (gh)

📋 Reference: Read references/detailed-commands.md for complete gh CLI commands covering repos, Actions, releases, secrets, API, and auth.

IMPORTANT: gh api -f does not support object values. Use multiple -f flags with hierarchical keys and string values instead.

Global Flags

DO / DON'T

• DO: Validate branch name before committing or creating PRs
• DO: Use MCP tools first for issues and PRs
• DO: Use gh CLI for Actions, releases, repos, secrets, API
• DO: Confirm repository context before creating issues/PRs
• DO: Search for existing issues/PRs before creating duplicates
• DO: Check for PR templates before creating PRs
• DON'T: Commit on a branch with an invalid name
• DON'T: Create issues/PRs without confirming repo owner and name
• DON'T: Merge PRs without user confirmation
• DON'T: Use gh CLI for issues/PRs when MCP tools are available
• DON'T: Skip hooks (--no-verify) unless user explicitly asks

Reference Index

Smart PR Flow

Automated PR lifecycle for infrastructure deployments. Defines label-based state tracking, auto-label rules on CI pass/fail, and a watchdog pattern for the deploy agent.

For full details: Read references/smart-pr-flow.md

Quick Reference