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

<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

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).