GIT-OS — Automation-First Git Workflow

Trigger

Load this skill before any of the following actions — do not proceed without reading it first:

• Creating a branch
• Writing a commit message
• Running git commit
• Running git push
• Creating or updating a PR title

Do NOT use this skill for: reviewing PR comments (use pr-review), creating a PR (use pr-create), planning a project (use greenfield).

---

My Git history powers automation. Commits drive version bumps, changelogs, release notes, deployments, and CI behavior. If commits are wrong → automation breaks.

1. Branching Model

Branch	From	PR target	Purpose
feat/<name>	<target>	<target>	New feature
fix/<name>	<target>	<target>	Bug fix
chore/<name>	<target>	<target>	Tooling / config
test/<name>	<target>	<target>	Test additions
hotfix/<name>	<target>	<target>	Urgent prod fix

<target> is project-specific (main, develop, etc.). Never commit directly to target. All changes enter via PR.

Stacked PRs: When PRs depend on each other, stack them bottom-up. feat/b branches from feat/a, targets feat/a. Merge order: a → b → c.

2. Commit Format

type(scope?): Description

(optional body)

(optional footer)

Allowed types

feat | fix | refactor | perf | docs | style | test | chore

Do NOT invent types. Do NOT skip colon. Do NOT capitalize the type. Do NOT add emoji.

Subject line rules

• Imperative mood: "Add login" not "Added login"
• Under 50 characters
• No trailing period
• Lowercase type, capitalized description

Body rules (when needed)

• Blank line after subject
• Wrap at 72 characters
• Explain WHY first, then WHAT changed

Breaking changes

refactor: Remove legacy user endpoint

BREAKING CHANGE: /v1/users removed. Use /v2/users

3. Atomic Commit Rule

One logical change per commit. If unsure → split it.

# Good
feat: Add login endpoint
test: Add login integration tests

# Bad
feat: Add login and fix navbar and update readme

4. Pre-Push Checklist

Before pushing any branch, all must pass:

1. npm run lint
2. npm run format:check
3. npm run test
4. npm run build

CI is a safety net, not the first line of defense.

5. Pull Request Rules

• Max 5–6 files per PR
• PR title follows the same conventional commit format
• Use this PR description template:

### Ticket Link
---
### Description
---
### Steps to Test
---
### GIFs
---

6. Tool Usage

Action	Tool	Notes
Run git commands	Bash	git commit, git push, git log, etc.
Read a file before editing	Read	Always read first — never edit blind
Edit a file	Edit	Never use Bash with sed or awk to modify files
Search file contents	Grep	Never use Bash grep
Find files	Glob	Never use Bash find

7. What Never To Do

• Commit without a type
• Bundle multiple concerns in one commit
• Force push the target branch
• Rewrite shared history
• Include AI attribution — no Co-Authored-By lines, no AI tool mentions

Commits should look human-authored. No fingerprints.

8. Agent Commit Format

When an agent generates a commit for a fix from a review comment:

fix(scope): description from review comment

Resolves review comment #N

9. Commit-Lint Hook (Claude Code)

Add this to .claude/settings.json in the project to enforce commit format automatically before every git commit:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -q '\"git commit' && npx --no-install commitlint --edit || true"
          }
        ]
      }
    ]
  }
}

This intercepts any Bash tool call containing git commit and runs commitlint against the message before the commit lands. Requires .commitlintrc.json to be present (copied automatically by ws-skills install).