GitHub Hygiene

Enforce disciplined git workflow. No exceptions. No shortcuts.

Critical Rules

NEVER DO - Hard Stops

# These commands on main/master require EXPLICIT user override
git commit          # on main/master
git push origin main
git push origin master
git merge <branch>  # while on main/master
git push --force    # on ANY protected branch
git reset --hard    # without explicit confirmation

Before ANY git operation: Check current branch first.

branch=$(git branch --show-current)
if [[ "$branch" == "main" || "$branch" == "master" ]]; then
    # STOP - Require explicit user confirmation before proceeding
    echo "⛔ On protected branch: $branch"
fi

ALWAYS DO - Mandatory Workflow

1. •Start work on a branch - Create feature branch BEFORE any code changes
2. •Use GitHub MCP - For all GitHub API operations (issues, PRs, reviews, checks)
3. •Atomic commits - One logical change per commit
4. •PR for everything - All changes reach main via pull request
5. •Delete merged branches - Clean up after merge

Branch Workflow

Starting New Work

# 1. Ensure main is current
git checkout main
git pull origin main

# 2. Create feature branch (REQUIRED before any changes)
git checkout -b <branch-type>/<description>

# Branch naming convention:
# feature/   - New functionality
# fix/       - Bug fixes
# hotfix/    - Urgent production fixes
# refactor/  - Code restructuring
# docs/      - Documentation only
# test/      - Test additions/changes
# chore/     - Maintenance tasks

Branch Naming Rules

Format: <type>/<ticket-or-description>

Good:

• •feature/user-authentication
• •fix/pathmon-timeout-handling
• •hotfix/triton-startup-crash
• •refactor/secflo-rls-policies

Bad:

• •my-changes (no type prefix)
• •feature/stuff (vague description)
• •Feature/Auth (wrong case)

Commit Standards

Conventional Commits (Required)

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• •feat - New feature
• •fix - Bug fix
• •docs - Documentation only
• •style - Formatting, no code change
• •refactor - Code restructuring
• •test - Adding/updating tests
• •chore - Maintenance tasks
• •perf - Performance improvement

Examples:

feat(triton): add dual-core handshake timeout handling

Implements NASA JPL Power of 10 compliant timeout mechanism
for Pico core synchronization during startup sequence.

Closes #42

fix(pathmon): correct SLA evidence timestamp format

FCC complaint export now uses ISO 8601 format consistently.

Commit Hygiene

• •Atomic: One logical change per commit
• •Present tense: "add feature" not "added feature"
• •No period: At end of subject line
• •72 chars: Maximum subject line length
• •Body: Explain what and why, not how

GitHub MCP Usage

ALWAYS use GitHub MCP for these operations:

Why MCP over CLI:

• •Maintains context in conversation
• •Structured data for follow-up operations
• •Audit trail in chat history
• •Enables intelligent automation

MCP Setup Verification

Before GitHub operations, verify MCP is available:

/mcp

If GitHub MCP not configured, alert user:

⚠️ GitHub MCP not configured. 
Add with: claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_PAT"

Pull Request Workflow

Creating PRs

1. •Push branch to origin
2. •Use GitHub MCP create_pull_request
3. •Include in PR body:
   • •Summary of changes
   • •Testing performed
   • •Related issues (Closes #XX)
   • •Breaking changes (if any)

PR Checklist (Verify Before Creating)

• • Branch is up to date with main
• • All tests pass locally
• • No merge conflicts
• • Commit history is clean (squash if needed)
• • Description explains the "why"

After PR Merge

# Switch to main and update
git checkout main
git pull origin main

# Delete local feature branch
git branch -d <branch-name>

# Delete remote feature branch (if not auto-deleted)
git push origin --delete <branch-name>

Safety Checks

Pre-Commit Check

Run before every commit operation:

#!/bin/bash
# Reject commits on protected branches
branch=$(git branch --show-current)
protected=("main" "master" "production" "release")

for p in "${protected[@]}"; do
    if [[ "$branch" == "$p" ]]; then
        echo "❌ Direct commits to '$branch' are not allowed"
        echo "Create a feature branch: git checkout -b feature/your-change"
        exit 1
    fi
done

Pre-Push Check

Verify before pushing:

1. •Correct remote branch target
2. •No force push to protected branches
3. •Branch exists on remote (for updates)

Recovery Procedures

Accidentally Committed to Main

# If not yet pushed - move commit to new branch
git branch feature/rescue-commit
git reset --hard HEAD~1
git checkout feature/rescue-commit

Accidentally Pushed to Main

# STOP - Do not force push
# 1. Create PR to revert
# 2. Or coordinate with team for proper resolution
# Force push to main is NEVER acceptable without explicit team approval

Quick Reference

Red Flags - Stop and Verify

• •About to run git push origin main
• •About to run git commit while on main/master
• •About to run git push --force on any branch
• •About to run git reset --hard anywhere
• •GitHub MCP not responding - do not fall back to CLI without noting

Integration Notes

Pairs with:

• •using-git-worktrees - For isolated development environments
• •test-driven-development - Tests pass before commits
• •finishing-a-development-branch - Proper branch cleanup

Announce at start: "Using github-hygiene skill to ensure proper git workflow."