a2host/.agents/skills/github-flow/SKILL.md

8.5 KiB

name description
github-flow Guides git and GitHub workflow using GitHub Flow: branch creation off main, atomic conventional commits, pull requests, automated CI checks, code reviews, merge strategies, and branch cleanup. Use when creating branches, preparing commits, managing PRs, resolving merge conflicts, or integrating changes into main.

GitHub Flow: Branching, Commits, and Pull Requests

A lightweight, branch-based workflow optimized for continuous delivery, code quality, and rapid iteration. Under GitHub Flow, the main branch is always stable and deployable, and all new features, bugfixes, or refactors are developed in dedicated, short-lived branches integrated via Pull Requests (PRs).


1. Core Principles of GitHub Flow

 main (deployable) ───────────────────●──────────────────────●───────►
                         \           /                      /
  feat/chat-export        ●───●─────● (PR #42: Merged)     /
                               \                          /
  fix/socket-reconnect          ●──────●─────────────────● (PR #43: Merged)
  1. main is always deployable: No untested or half-finished code is committed directly to main.
  2. Branch from main: Always create descriptive branches directly from the latest updated main.
  3. Commit early and atomically: Small, logical commits following the Conventional Commits specification.
  4. Open a Pull Request early: Open a PR as soon as work is ready (or draft PR for early feedback).
  5. Review and discuss: Solicit feedback, pass CI tests, and address comments.
  6. Merge and delete branch: Integrate into main (Squash & Merge or Rebase & Merge) and immediately delete the feature branch.

2. Step-by-Step Workflow Guide

Step 1: Synchronize main & Create Feature Branch

Before starting any new task, ensure your local main matches the remote repository:

# Switch to main and pull latest changes
git checkout main
git pull --ff-only origin main

# Create a new branch with a semantic prefix
git checkout -b <type>/<short-description>

Branch Naming Conventions:

Prefix Purpose Example
feat/ New feature or capability feat/speech-to-text
fix/ Bugfix or patch fix/admin-session-timeout
refactor/ Code refactoring without behavior change refactor/websocket-handler
perf/ Performance improvement perf/vector-search-indexing
docs/ Documentation only docs/api-endpoints-guide
test/ Adding or correcting unit/integration tests test/faq-repository-suite
chore/ Maintenance, dependencies, build configs chore/upgrade-vite

Step 2: Atomic Commits with Conventional Commits

Keep each commit focused on a single logical change. Follow the Conventional Commits format:

<type>(<scope>): <short imperative summary>

[optional body explaining WHY and WHAT changed]

[optional footer: Closes #123, BREAKING CHANGE: ...]

Commit Types:

  • feat: A new feature for the user or system.
  • fix: A bug fix.
  • refactor: Code change that neither fixes a bug nor adds a feature.
  • style: Formatting, missing semicolons, whitespace (no code logic change).
  • perf: Performance optimization.
  • test: Adding missing tests or refactoring test suites.
  • docs: Documentation updates.
  • chore: Build process, package updates, tooling config.

Good vs. Bad Commits:

  • ✅ feat(chat): add auto-reconnect backoff on WebSocket disconnect
  • ✅ fix(auth): prevent token leakage in error response payloads
  • ❌ changes
  • ❌ fixed stuff and updated tests and ui

Step 3: Local Verification & Pre-Push Validation

Before pushing, verify code quality, syntax, and test suites locally:

  1. Check status & modified files:
    git status
    git diff
    
  2. Run tests & linters (project specific):
    # Run frontend build / lint if applicable
    npm run build
    # Run backend tests / static analysis if applicable
    composer test
    
  3. Verify no sensitive secrets or temporary files are staged: Ensure .env, credentials, local cache files, or .system_generated/ are ignored in .gitignore.

Step 4: Push to Remote & Open Pull Request

Push the branch to origin setting the upstream tracking:

git push -u origin <branch-name>

Creating the PR:

  • Using GitHub CLI (gh):
    gh pr create --title "feat(chat): implement speech-to-text integration" --body-file .agents/skills/github-flow/references/pull-request-template.md
    
  • Using GitHub Web: Navigate to repository URL, click Compare & pull request, and fill in the PR template.

Step 5: Keep Branch Synchronized with main

If other PRs were merged into main while working on your branch, rebase your branch on top of latest main to maintain clean history:

# Fetch latest main without switching branches
git fetch origin main

# Rebase feature branch on origin/main
git rebase origin/main

# If conflicts occur:
# 1. Edit conflicting files and resolve markers (<<<<<<< / ======= / >>>>>>>)
# 2. Stage resolved files: git add <resolved-file>
# 3. Continue rebase: git rebase --continue
# 4. Force-push with lease:
git push --force-with-lease origin <branch-name>

Important

Always use --force-with-lease instead of --force when pushing rebased branches to prevent overwriting team member commits.


Step 6: Code Review, Approval, & Merge

  1. Review: Team members and automated CI pipelines review the PR.
  2. Address Feedback: Push additional commits to the same branch; GitHub updates the PR automatically.
  3. Merge Method:
    • Squash and Merge (Recommended for feature branches): Combines all branch commits into one clean commit on main.
    • Rebase and Merge: Retains individual commits in a flat linear history.
  4. Branch Cleanup:
    # Delete remote branch (GitHub web does this via button or gh)
    gh pr merge --squash --delete-branch
    
    # Or locally clean up:
    git checkout main
    git pull --ff-only origin main
    git branch -d <branch-name>
    git remote prune origin
    

3. Pull Request Template Standard

When opening a PR, structure the description with the following markdown format:

## Description
Provide a concise overview of what this PR does and why it was created.

## Type of Change
- [ ] 🚀 New feature (non-breaking change adding functionality)
- [ ] 🐛 Bug fix (non-breaking change fixing an issue)
- [ ] ♻️ Refactoring (clean code, structure improvement)
- [ ] ⚡ Performance optimization
- [ ] 📝 Documentation update
- [ ] 🔒 Security patch

## Key Changes
- Detailed bullet points of main changes
- Touched components, models, or endpoints

## How Has This Been Tested?
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual test in local browser/environment

## Checklist
- [ ] Code follows project style guidelines and naming conventions.
- [ ] Self-review conducted; no console.logs or dead debug code left behind.
- [ ] No sensitive credentials, secrets, or .env files included.
- [ ] Documentation updated where relevant.

4. Git Emergency & Utility Cheatsheet

Task Command
Discard unstaged changes in a file git restore <file>
Unstage a file without losing changes git restore --staged <file>
Undo last commit keeping changes staged git reset --soft HEAD~1
Temporarily stash work in progress git stash save "wip: message"
Restore stashed work git stash pop
Clean untracked files & directories git clean -fd (Use with caution!)
View pretty one-line git log graph git log --oneline --graph --decorate -n 15
Show diff of staged changes git diff --cached

5. Integration with Scrum Multi-Agent Framework

When working with scrum-multi-agent-orchestration:

  1. Developer Agents (Frontend / Backend): Create branches named feat/<ticket-id>-description or fix/<ticket-id>-description.
  2. QA Agent: Checks out the branch, executes verification test suites, and posts results to the PR.
  3. Code Reviewer Agent: Audits the PR diff against security, clean code, accessibility (WCAG), and Definition of Done (DoD).
  4. Scrum Master / Tech Lead: Approves and triggers Squash & Merge into main.