---

name: git-workflow description: Conventional commits, PR templates, and branch strategy type: semantic user-invocable: true semantic: skillVersion: 1 permissions: graph: [read, write] memory: [recall, remember] assertions: - predicate: "git:commit_created" requireProof: false - predicate: "git:pr_created" requireProof: false - predicate: "git:branch_policy" requireProof: false queries: - predicate: "git:commit_created" scope: agent - predicate: "git:workflow_context" scope: namespace allowedTools: ["*"] metadata: mayros: requires: bins: [git, gh]

git-workflow

Best practices for git workflows: Conventional Commits, pull request templates, branch naming strategy, and safe git operations. Enforces consistency and safety across all git interactions.

Conventional Commits

All commit messages must follow the Conventional Commits specification (v1.0.0):

type(scope): description

[optional body]

[optional footer(s)]

Commit Types

| Type | Purpose | |------|---------| | feat | A new feature | | fix | A bug fix | | docs | Documentation only changes | | style | Formatting, missing semicolons, white-space (no code change) | | refactor | Code change that neither fixes a bug nor adds a feature | | perf | Performance improvement | | test | Adding or correcting tests | | build | Changes to build system or external dependencies | | ci | Changes to CI configuration files and scripts | | chore | Maintenance tasks (no production code change) | | revert | Reverts a previous commit |

Breaking Changes

Breaking changes are indicated in two ways:

1. Append ! after the type/scope: feat!: remove deprecated API
2. Include BREAKING CHANGE: in the commit footer

Rules

• First line (subject) must not exceed 72 characters
• Use imperative mood ("add feature" not "added feature")
• Do not capitalize the first letter of the description
• Do not end the subject with a period
• Focus on "why" not "what" --- the diff shows what changed

Pull Request Templates

Every PR should follow this structure:

## Summary
- 1-3 bullet points describing the change at a high level

## Changes
- File-by-file breakdown of what was modified and why

## Test Plan
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing steps described

## Breaking Changes
- List any breaking changes and migration steps
- Omit this section if there are no breaking changes

PR Title

• Keep under 70 characters
• Follow the same Conventional Commit format: type(scope): description
• Use the description/body for details, not the title

Branch Strategy

Branch names follow a consistent pattern:

| Pattern | Purpose | Example | |---------|---------|---------| | feat/<name> | New features | feat/user-auth | | fix/<name> | Bug fixes | fix/null-pointer-crash | | release/<x.y.z> | Release preparation | release/2.1.0 | | hotfix/<name> | Production hotfixes | hotfix/critical-auth-bypass |

Rules

• Use lowercase with hyphens (no underscores, no camelCase)
• Keep branch names descriptive but concise
• Delete branches after merge
• Never commit directly to main or master

Safe Git Practices

These safety rules are mandatory and must never be overridden:

Never Do (Without Explicit User Confirmation)

• NEVER force push to main/master --- this destroys shared history
• NEVER use --no-verify to skip pre-commit hooks --- hooks exist for a reason
• NEVER run destructive commands without confirmation:
  • git reset --hard --- discards all uncommitted work
  • git clean -f --- deletes untracked files permanently
  • git branch -D --- force-deletes a branch regardless of merge status
  • git checkout . / git restore . --- discards all working tree changes
• NEVER amend published commits --- this rewrites shared history

Always Do

• ALWAYS stage specific files by name (git add src/auth.ts) instead of git add -A or git add . which can accidentally include sensitive files (.env, credentials, large binaries)
• ALWAYS create NEW commits rather than amending. When a pre-commit hook fails, the commit did not happen --- so --amend would modify the PREVIOUS commit, destroying its changes
• ALWAYS write commit messages that explain the "why" not the "what"
• ALWAYS check git status and git diff before committing

Merge Conflicts

• Show both versions of the conflict clearly
• Let the user choose which version to keep
• Never silently resolve conflicts by picking one side
• After resolution, verify the result compiles and tests pass

Semantic Integration

• Use skill_assert with git:commit_created when a commit is successfully created.
• Use skill_assert with git:pr_created when a pull request is created.
• Use skill_assert with git:branch_policy when validating branch naming compliance.
• Consult skill_memory_context for workflow context and previous commit patterns.