name: git-workflow description: Conventional commits, PR creation, and quality gate verification triggers: [commit, PR, branch, push, conventional commit, create pull request, git] tags: [coding] context_cost: low

Git Workflow Skill

Goal

Create well-structured commits following Conventional Commits spec, pass all quality gates before pushing, and create a descriptive PR for human review.

Steps

1. Verify quality gates (all must pass before committing)

   [test command]       # All tests pass
   [typecheck command]  # No type errors
   [lint command]       # No lint errors
   [security_scan]      # No new critical/high CVEs (on dependency changes)
   

   If any fail: fix them before continuing. Do NOT commit with failing gates.

2. Stage changes

   git status           # Review what's changed
   git diff             # Review the actual changes
   git add [specific files]  # Never: git add -A (risk of including .env or build artifacts)
   

3. Write a Conventional Commit message

   Format: <type>(<scope>): <subject>

   Type	When to use
   feat	New feature
   fix	Bug fix
   docs	Documentation only
   style	Formatting, no logic change
   refactor	Code restructure, no behavior change
   test	Adding or fixing tests
   chore	Build process, tooling, deps
   perf	Performance improvement
   sec	Security fix
   deps	Dependency updates

   Good examples:

   feat(auth): add OAuth2 Google login with refresh tokens
   fix(api): resolve N+1 query in users list endpoint
   sec(deps): update lodash 4.17.20 -> 4.17.21 (CVE-2021-23337)
   test(domain): add unit tests for Order aggregate invariants
   refactor(application): extract CreateOrderUseCase from OrderController
   

   Bad examples (avoid):

   fix stuff            # No scope, no description
   WIP                  # Work in progress should not be committed
   update code          # No context
   temp                 # Never commit temporary code
   

4. Create the commit

   git commit -m "feat(auth): add email verification flow
   
   - Add email_verified_at column to users table
   - Send verification email on registration
   - Add /auth/verify endpoint
   - Block login for unverified accounts
   
   Closes #42"
   

5. Create a feature branch (if working on main without a branch)

   git checkout -b feat/[issue-number]-[brief-description]
   # Example: git checkout -b feat/42-email-verification
   

6. Push and create PR

   git push origin [branch-name]
   
   # Create PR with gh CLI (preferred):
   gh pr create \
     --title "feat(auth): add email verification flow" \
     --body "$(cat <<'EOF'
   ## Summary
   - Add email verification requirement for new user accounts
   - Users must verify email before they can log in
   
   ## Changes
   - Database: adds `email_verified_at` column to users
   - API: adds `POST /auth/verify` endpoint
   - Auth: blocks unverified accounts from login
   
   ## Test Plan
   - [ ] Run unit tests: `[test command]`
   - [ ] Test registration flow end-to-end
   - [ ] Test that unverified users cannot log in
   - [ ] Verify verification email is sent
   
   ## Breaking Changes
   None — existing verified users are not affected.
   
   ## Security Notes
   Verification tokens expire after 24 hours.
   EOF
   )"
   

7. Post-PR checklist

   • Add reviewers if team is set up for it
   • Link to the relevant task in project/TASKS.md or issue tracker
   • Update task status in project/TASKS.md → DONE (or IN_REVIEW)
   • Add entry to AUDIT_LOG.md

Branch Naming Conventions

feat/[issue]-[description]     # New features
fix/[issue]-[description]      # Bug fixes
refactor/[description]         # Refactoring
chore/[description]            # Tooling, deps
sec/[description]              # Security fixes
docs/[description]             # Documentation

Constraints

• NEVER push directly to main/master — always use feature branches
• NEVER commit without all quality gates passing
• NEVER include .env files, credentials, or build artifacts in commits
• PR title must be a valid Conventional Commit message

Output Format

Commit created + PR URL. Report: "Committed: [message]. PR: [URL]. All [N] quality gates passed."

Security & Guardrails

1. Skill Security (Git Workflow)

• Silent Gate Override: Step 1 requires all quality gates to pass. If a test is flaky, the agent might decide to selectively bypass the test suite locally (--no-verify or git commit -n) to push the code and ask for human review. The workflow script MUST intercept and physically block any invocation of git commit or git push that attempts to disable pre-commit hooks or CI validation gates.
• Secret Staging (The git add . Trap): Step 2 explicitly warns against git add -A. An attacker who compromises a sub-module might create a .env.local file containing production secrets. If an LLM agent gets lazy and executes a wildcard add (git add .), those secrets are permanently etched into the repository history. The agent must explicitly define -- path/to/file arguments for every file it stages, categorically rejecting any form of wildcard staging.

2. System Integration Security

• Branch Name Injection: In Step 5, the agent creates a branch using the issue number and description (feat/[issue]-[description]). If the source issue title contains malicious shell characters or path traversal sequences (e.g., Issue #42: Fix ../../../etc/shadow), constructing the git checkout -b command dynamically will lead to command injection. The agent must strictly normalize and strictly sanitize all branch names to alphanumeric and hyphen characters before executing the shell command.
• PR Description XSS / Payload Delivery: In Step 6, the agent constructs a PR description via the gh pr create --body command. If the commit relates to a bug fix for a malicious payload, the agent might blindly copy the payload into the "Summary" section to provide context. When developers open the PR on GitHub/GitLab, the payload might execute in their browser context. The agent must HTML-encode and neutralize all user-provided data included in the PR body string.

3. LLM & Agent Guardrails

• Artificial PR Approval (Sockpuppeting): The agent operates within a swarm. A compromised agent persona might attempt to use the Git workflow to push malicious code, and another compromised persona might automatically approve it. The Git Workflow must strictly define that only authenticated Human identities (via cryptographic signatures or specific GitHub accounts) can review and merge PRs generated by an autonomous agent.
• Hallucinated Semantic Versioning: The LLM generates the Conventional Commit prefix (feat:, fix:). If the LLM incorrectly classifies a breaking change (e.g., changing an API response format) as a simple chore or fix, automated semantic release pipelines will fail to increment the major version, breaking downstream consumers. The agent must run an automated "Breaking Change Detection" AST diff script prior to generating the commit type, vetoing the LLM's classification if a public contract was mutated.