Creates commits with conventional format and validation. Use when committing changes or generating commit messages.

Command low

Primary Agent: git-operations-engineer

Smart Commit

Simple, validated commit creation. Run checks locally, no agents needed for standard commits.

Quick Start

/ork:commit

Workflow

Phase 1: Pre-Commit Safety Check

# CRITICAL: Verify we're not on dev/main
BRANCH=$(git branch --show-current)
if [[ "$BRANCH" == "dev" || "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  echo "STOP! Cannot commit directly to $BRANCH"
  echo "Create a feature branch: git checkout -b issue/<number>-<description>"
  exit 1
fi

Phase 2: Run Validation Locally

Run every check that CI runs:

# Backend (Python)
poetry run ruff format --check app/
poetry run ruff check app/
poetry run mypy app/

# Frontend (Node.js)
npm run format:check
npm run lint
npm run typecheck

Fix any failures before proceeding.

Phase 3: Review Changes

git status
git diff --staged   # What will be committed
git diff            # Unstaged changes

Phase 4: Stage and Commit

# Stage files
git add <files>
# Or all: git add .

# Commit with conventional format
git commit -m "<type>(#<issue>): <brief description>

- [Change 1]
- [Change 2]

Co-Authored-By: Claude <noreply@anthropic.com>"

# Verify
git log -1 --stat

Commit Types

Type	Use For
`feat`	New feature
`fix`	Bug fix
`refactor`	Code improvement
`docs`	Documentation
`test`	Tests only
`chore`	Build/deps/CI

Rules

Run validation locally - Don't spawn agents to run lint/test
NO file creation - Don't create MD files or documentation
One logical change per commit - Keep commits focused
Reference issues - Use #123 format in commit message
Subject line < 72 chars - Keep it concise

Quick Commit

For trivial changes (typos, single-line fixes):

git add . && git commit -m "fix(#123): Fix typo in error message

Co-Authored-By: Claude <noreply@anthropic.com>"

ork:create-pr: Create pull requests from commits
ork:review-pr: Review changes before committing
ork:fix-issue: Fix issues and commit the fixes
ork:issue-progress-tracking: Auto-updates GitHub issues with commit progress

Rules

Each category has individual rule files in rules/ loaded on-demand:

Category	Rule	Impact	Key Pattern
Atomic Commits	`rules/atomic-commit.md`	CRITICAL	One logical change per commit, atomicity test
Commit Splitting	`rules/commit-splitting.md`	HIGH	`git add -p`, interactive staging, separation strategies
Conventional Format	`rules/conventional-format.md`	HIGH	type(scope): description, breaking changes
Issue Reference	`rules/issue-reference-required.md`	HIGH	Reference issue `#N` in commits on issue branches

Total: 4 rules across 4 categories

References

Rules (4)

Create atomic commits that bundle one logical change for safe revert and bisect — CRITICAL

Atomic Commit Rules

A commit is atomic when it contains exactly ONE logical change that can be understood, reviewed, and reverted independently.

The Atomicity Test

A commit is atomic if ALL of these are true:

[x] Does ONE logical thing
[x] Leaves the codebase in a working state (tests pass)
[x] Commit message doesn't need "and" in the title
[x] Can be reverted independently without breaking other features
[x] A reviewer can understand the full change without external context

Detection Heuristics

Directory Spread — Changes spanning unrelated directories signal mixed concerns:

# ATOMIC: Related files in same domain
src/auth/login.ts
src/auth/login.test.ts
src/auth/types.ts

# NOT ATOMIC: Unrelated directories
src/auth/login.ts        ← auth feature
src/billing/invoice.ts   ← billing feature
config/webpack.config.js ← build config

Commit Type Mixing — A single commit shouldn't mix types:

# NOT ATOMIC: feat + fix in one commit
feat: Add user dashboard
fix: Resolve login timeout     ← separate commit

# NOT ATOMIC: feat + chore in one commit
feat: Add API caching
chore: Update eslint config     ← separate commit

File Count Threshold — More than 10 staged files warrants inspection. Not always wrong, but should be verified:

# OK: 15 files, all test fixtures for one feature
tests/fixtures/user-*.json (15 files)

# NOT OK: 12 files across 6 unrelated modules

"And" Test — If describing the commit requires "and", it's two commits:

# Fails "and" test → split it
"Add user authentication AND fix logging format"

# Passes "and" test → atomic
"Add JWT token validation for login endpoint"

Common Atomic Patterns

Pattern	Files	Why Atomic
Feature + its tests	`feature.ts` + `feature.test.ts`	Tests validate the feature
Migration + model update	`migration.sql` + `model.ts`	Schema change is one concern
Refactor across files	Multiple files, same pattern	One refactoring decision
Config change	`.env.example` + `config.ts`	One configuration concern
Dependency update	`package.json` + `package-lock.json`	One dependency decision

Common Non-Atomic Patterns

Pattern	Problem	Fix
Feature + unrelated fix	Two concerns	Two separate commits
Code change + formatting	Formatting is noise	Format first, then change
Multiple features	Can't revert independently	One commit per feature
Feature + config change	Different review concerns	Separate unless config IS the feature

Incorrect — non-atomic commit mixing concerns:

# Mixed commit spanning unrelated areas
git add src/auth/login.ts \
        src/billing/invoice.ts \
        config/webpack.config.js
git commit -m "feat: Add login AND fix invoice AND update webpack"
# Three unrelated changes - can't revert independently!

Correct — atomic commits with single concerns:

# Commit 1: Auth feature + its tests (related)
git add src/auth/login.ts src/auth/login.test.ts
git commit -m "feat(#123): Add JWT token validation for login endpoint"

# Commit 2: Billing feature + its tests (related)
git add src/billing/invoice.ts src/billing/invoice.test.ts
git commit -m "feat(#124): Add invoice generation service"

# Commit 3: Config change (separate concern)
git add config/webpack.config.js
git commit -m "chore: Update webpack for tree shaking"

Key Rules

One logical change per commit — if you say "and", split it
Tests belong with the code they test — same commit
Formatting/linting changes are separate commits
Database migrations go with the code that uses them
Never mix feature work with unrelated refactoring

Split large mixed commits into focused, reviewable units with clean boundaries — HIGH

Commit Splitting Strategies

When you have mixed changes in your working directory, use these strategies to create atomic commits.

Strategy 1: Interactive Staging (`git add -p`)

Stage changes hunk-by-hunk to separate concerns:

# Stage changes interactively
git add -p

# Options at each hunk:
# y - stage this hunk
# n - skip this hunk
# s - split into smaller hunks (if hunk has gaps)
# e - manually edit the hunk boundaries
# q - quit, leave remaining unstaged

# Review what's staged vs unstaged
git diff --staged    # Will be committed
git diff             # Won't be committed

# Commit the staged portion
git commit -m "feat(#123): Add user validation"

# Repeat for next logical change
git add -p
git commit -m "fix(#456): Resolve timeout in auth"

Strategy 2: File-Based Splitting

When changes are in separate files, stage by file:

# Stage only auth-related files
git add src/auth/login.ts src/auth/login.test.ts
git commit -m "feat(#123): Add login validation"

# Stage only billing-related files
git add src/billing/invoice.ts src/billing/invoice.test.ts
git commit -m "feat(#124): Add invoice generation"

Strategy 3: Stash-Based Splitting

For complex mixed changes, use stash to isolate:

# Stash everything
git stash

# Apply and stage only what you need
git stash pop
git add -p  # Stage only feature A
git stash   # Re-stash the rest
git commit -m "feat: Feature A"

# Recover remaining changes
git stash pop
git add -p  # Stage feature B
git commit -m "feat: Feature B"

Strategy 4: Pre-Commit Formatting Split

Always format BEFORE making logical changes:

# Step 1: Format first (separate commit)
npx prettier --write src/
git add -A
git commit -m "style: Format files with prettier"

# Step 2: Now make your logical changes
# ... edit files ...
git add -p
git commit -m "feat(#123): Add user dashboard"

When to Split

Signal	Action
`git diff --staged` shows > 10 files	Review if all related
Commit message needs "and"	Split into separate commits
Changes span > 3 unrelated directories	Split by directory/concern
Mix of feat + fix + chore	One commit per type
Formatting mixed with logic changes	Format first, then logic

Incorrect — staging everything at once, mixed concerns:

# Staging all files including mixed changes
git add .
git commit -m "feat: Add login and fix billing and update config"
# Unreviewable, can't revert parts!

Correct — interactive staging for separate atomic commits:

# Stage auth changes interactively
git add -p src/auth/login.ts
# y - stage login validation hunks
# n - skip other hunks
git add src/auth/login.test.ts
git commit -m "feat(#123): Add login validation"

# Stage billing changes interactively
git add -p src/billing/invoice.ts
git add src/billing/invoice.test.ts
git commit -m "fix(#456): Resolve invoice calculation bug"

# Stage config separately
git add config/webpack.config.js
git commit -m "chore: Update webpack config"

Key Rules

Use git add -p as the default — stage interactively, not git add .
Format changes always go in their own commit
Test files go with the code they test, not in separate commits
When in doubt, split — smaller commits are always safer
Each commit should pass tests independently

Format commit messages with conventional commit prefixes for automated changelogs — HIGH

Conventional Commit Format

All commits must follow the Conventional Commits specification for automated tooling.

Format

<type>(<scope>): <description>

[optional body]

[optional footer]
Co-Authored-By: Claude <noreply@anthropic.com>

Types

Type	When	Bumps
`feat`	New feature or capability	MINOR
`fix`	Bug fix	PATCH
`refactor`	Code restructuring, no behavior change	—
`docs`	Documentation only	—
`test`	Adding or fixing tests	—
`chore`	Build, deps, CI, tooling	—
`style`	Formatting, whitespace, semicolons	—
`perf`	Performance improvement	PATCH
`ci`	CI/CD configuration	—
`build`	Build system changes	—

Scope

Optional, identifies the area of change:

# Issue reference (preferred)
feat(#123): Add user authentication

# Module name
fix(auth): Resolve token expiration

# No scope (acceptable for small changes)
chore: Update dependencies

Breaking Changes

Use ! after type/scope OR BREAKING CHANGE: footer:

# With ! marker (bumps MAJOR)
feat(api)!: Change authentication endpoint structure

# With footer
feat(api): Change auth endpoints

BREAKING CHANGE: /api/auth/login now requires email instead of username

Title Rules

[x] Imperative mood ("Add feature" not "Added feature")
[x] No period at end
[x] < 72 characters (< 50 preferred)
[x] Lowercase after colon
[x] Meaningful — describes WHY, not just WHAT

Incorrect:

Fixed the bug.                          # Past tense, period, no type
feat: stuff                             # Vague
feat: Add user authentication and fix billing  # Two concerns
FEAT: Add Auth                          # Uppercase

Correct:

feat(#123): Add JWT token validation for login
fix(#456): Resolve race condition in payment processing
refactor: Extract database connection pool to shared module

Body (Optional)

Use for context that doesn't fit in the title:

git commit -m "$(cat <<'EOF'
feat(#123): Add rate limiting to API endpoints

Applied token bucket algorithm with 100 req/min per user.
Redis-backed for distributed deployments.

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Key Rules

Type is mandatory — no untyped commits
Scope with issue number when available (#123)
Title < 72 chars, imperative mood, no period
One type per commit — if you need feat AND fix, make two commits
Always include Co-Authored-By when Claude assists
Breaking changes must use ! or BREAKING CHANGE: footer

Include issue references in commits to maintain traceability to GitHub issues — HIGH

Issue Reference Required

When on an issue branch (issue/*, fix/*, feat/*), commit messages MUST reference the issue number using #N format.

Why

Links commits to issues automatically in GitHub
Enables automated issue closing via Closes #N or Fixes #N
Provides traceability for code review and auditing

Good Examples

# Issue number in scope
git commit -m "fix(#42): resolve null pointer in auth handler"

# Issue number in body
git commit -m "feat(auth): add OAuth2 support

Implements #42"

# Closing reference
git commit -m "fix(api): validate input length

Closes #42"

Bad Examples

# No issue reference on an issue branch
git commit -m "fix: resolve null pointer in auth handler"

# Issue number without # prefix
git commit -m "fix(42): resolve null pointer"

When to Apply

Always when the branch name contains an issue number (e.g., issue/42-fix-auth, fix/42-null-pointer)
Recommended for any branch linked to a known GitHub issue
Skip for branches unrelated to issues (e.g., chore/update-deps)

Incorrect — missing issue reference on issue branch:

# On branch: issue/42-fix-auth
# No issue reference - breaks traceability!
git commit -m "fix: resolve null pointer in auth handler"

Correct — issue reference in commit message:

# On branch: issue/42-fix-auth
# Issue number in scope
git commit -m "fix(#42): resolve null pointer in auth handler"

# Or in body
git commit -m "fix(auth): resolve null pointer in auth handler

Fixes #42"

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Type	Description	Bumps
`feat`	New feature for users	MINOR
`fix`	Bug fix for users	PATCH
`docs`	Documentation only	-
`style`	Formatting, no code change	-
`refactor`	Code change, no feature/fix	-
`perf`	Performance improvement	PATCH
`test`	Adding/fixing tests	-
`chore`	Build process, deps	-
`ci`	CI configuration	-
`revert`	Revert previous commit	-

Breaking Changes

Add ! after type or BREAKING CHANGE: in footer:

feat!: drop support for Node 14

BREAKING CHANGE: Node 14 is no longer supported

Scope Examples

feat(auth): add OAuth2 support
fix(api): handle null response
docs(readme): update install steps
refactor(core): extract helper functions

Good Examples

feat(#123): add user profile page

- Create ProfilePage component
- Add profile API endpoint
- Include unit tests

Co-Authored-By: Claude <noreply@anthropic.com>

fix(#456): prevent XSS in comment display

Sanitize HTML in user comments before rendering.

Co-Authored-By: Claude <noreply@anthropic.com>

Recovery

Git Recovery

Committed to Wrong Branch

# Save work to new branch
git checkout -b issue/<number>-<description>

# Reset original branch
git checkout dev
git reset --hard origin/dev

# Return to feature branch
git checkout issue/<number>-<description>

Undo Last Commit (Keep Changes)

git reset --soft HEAD~1

Undo Last Commit (Discard Changes)

git reset --hard HEAD~1

Amend Last Commit

# Fix message only
git commit --amend -m "new message"

# Add forgotten files
git add forgotten-file.txt
git commit --amend --no-edit

Revert Published Commit

git revert <commit-hash>
git push

Unstage Files

git restore --staged <file>

Discard Local Changes

# Single file
git restore <file>

# All files
git restore .

Commit

On this page