commit

name	commit
license	MIT
compatibility	Claude Code 2.1.183+.
description	Creates commits with Conventional Commits format (feat/fix/docs/refactor/test/chore), automatic scope detection, co-author attribution, and pre-commit hook compliance. Validates staged changes, generates descriptive messages focusing on the 'why', and prevents secrets or generated-only files from being committed. Use when committing changes or generating commit messages.
argument-hint	[message]
context	inherit
version	1.2.0
author	OrchestKit
tags	["git","commit","version-control","conventional-commits"]
user-invocable	true
disable-model-invocation	true
allowed-tools	["Bash"]
skills	["chain-patterns"]
complexity	low
persuasion-type	discipline
effort	low
hooks	{"PreToolUse":[{"matcher":"Bash","command":"${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/commit-convention-loader","once":true},{"matcher":"Bash(git *)","command":"${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs pretool/bash/git-validator"}]}
metadata	{"category":"workflow-automation"}
triggers	{"keywords":["commit","comit","commit message","stage and commit","save progress","save my progress","wrap it up","conventional commit"],"examples":["commit my changes","create a conventional commit for these files","stage and commit the new tests"],"anti-triggers":["push","pr","pull request","review","rebase","merge"]}
invocation_hooks	["git rev-parse --is-inside-work-tree >/dev/null 2>&1 || echo 'Warning: not inside a git repository'"]

Smart Commit

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

Note: If disableSkillShellExecution is enabled (CC 2.1.91), the git repository check won't run. This skill requires a git repository.

Quick Start

/ork:commit
/ork:commit fix typo in auth module

Argument Resolution

COMMIT_MSG = "$ARGUMENTS"  # Optional commit message, e.g., "fix typo in auth module"
# If provided, use as commit message. If empty, generate from staged changes.
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)

STEP 0: Choose Commit Mode (AskUserQuestion — M118 #1465)

Default is "new commit", but voice-flow needs explicit choice when amend / push / stash is wanted:

# Skip when a flag in the invocation makes the mode unambiguous:
#   /ork:commit --amend  → skip, mode=amend
#   /ork:commit --push   → skip, mode=new+push
#   /ork:commit --stash  → skip, mode=stash-first
#   ORK_COMMIT_DEFAULT_MODE=new (or amend|push|stash) → skip, use env value
#
# Otherwise, ask:
AskUserQuestion(questions=[{
  "question": "How should this commit land?",
  "header": "Commit mode",
  "options": [
    {"label": "New commit (default)", "description": "Create a new commit, leave HEAD intact"},
    {"label": "Amend HEAD", "description": "Fold staged changes into the last commit (LOCAL ONLY — refuses if HEAD is published)"},
    {"label": "New commit + push", "description": "Commit then `git push` (refuses on protected branches)"},
    {"label": "Stash first", "description": "Stash unrelated working-tree changes, then commit only what was already staged"}
  ]
}])

Mode-specific guards:

• Amend HEAD — verify HEAD is not on origin (git rev-list HEAD..origin/<branch> empty); if it is published, refuse and recommend "New commit" instead.
• New commit + push — re-check the protected-branch rule from Phase 1 before pushing; if HEAD's branch is main/master/dev, abort.
• Stash first — git stash push -k -m "ork:commit autostash" (keep-index), commit, then git stash pop after push success.

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 3b: Agent Attribution (automatic)

Before committing, check for the branch activity ledger at .claude/agents/activity/{branch}.jsonl. If it exists and has entries since the last commit, include them in the commit message:

1. Read .claude/agents/activity/{branch}.jsonl (one JSON object per line)
2. Filter entries where ts is after the last commit timestamp (git log -1 --format=%cI)
3. Skip agents with duration_ms < 5000 (advisory-only agents go in PR, not commits)
4. Add an "Agents Involved:" section between the commit body and the Co-Authored-By trailer
5. Add per-agent Co-Authored-By trailers: Co-Authored-By: ork:{agent} <[e-mail]>

If the ledger doesn't exist or is empty, skip this step — commit normally.

Phase 4: Stage and Commit

CC 2.1.113 idiom: Multi-line Bash with leading # intent: comments now shows the full command in the transcript — prefix complex scripts with a one-line intent comment so future readers (and /recap scans) can grep the transcript for what happened without re-reading the diff.

# intent: stage the hook change + its test + built artifacts
# Stage files
git add <files>
# Or all: git add .

# Commit with conventional format (with agent attribution if ledger exists)
git commit -m "<type>(#<issue>): <brief description>

- [Change 1]
- [Change 2]

Agents Involved:
  backend-system-architect — API design + data models (2m14s)
  security-auditor — Dependency audit (0m42s)

Co-Authored-By: Claude <[e-mail]>
Co-Authored-By: ork:backend-system-architect <[e-mail]>
Co-Authored-By: ork:security-auditor <[e-mail]>"

# Verify
git log -1 --stat

CC 2.1.183 — attribution.sessionUrl: In web and Remote Control sessions, CC appends a claude.ai session link to commit/PR attribution. Set attribution.sessionUrl: false (/config attribution.sessionUrl=false) to omit it — useful for public repos where the session link should not leak. The Co-Authored-By trailers above are unaffected.

Handoff File

After successful commit, write handoff:

Write(".claude/chain/committed.json", JSON.stringify({
  "phase": "commit", "sha": "<commit-sha>",
  "message": "<commit-message>", "branch": "<branch>",
  "files": [<staged-files>]
}))

Commit Types

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

Quick Rules

1. Run validation locally - Don't spawn agents to run lint/test
2. NO file creation - Don't create MD files or documentation
3. One logical change per commit - Keep commits focused
4. Reference issues - Use #123 format in commit message
5. 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 <[e-mail]>"

Verification Gate

Before committing, apply the 5-step gate: Read("${CLAUDE_PLUGIN_ROOT}/skills/shared/rules/verification-gate.md"). Run tests fresh. Read the output. Only commit if tests pass. "Should be fine" is not evidence.

Related Skills

• 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	${CLAUDE_SKILL_DIR}/rules/atomic-commit.md	CRITICAL	One logical change per commit, atomicity test
Branch Protection	${CLAUDE_SKILL_DIR}/rules/branch-protection.md	CRITICAL	Protected branches, required PR workflow
Commit Splitting	${CLAUDE_SKILL_DIR}/rules/commit-splitting.md	HIGH	git add -p, interactive staging, separation strategies
Conventional Format	${CLAUDE_SKILL_DIR}/rules/conventional-format.md	HIGH	type(scope): description, breaking changes
History Hygiene	${CLAUDE_SKILL_DIR}/rules/history-hygiene.md	HIGH	Squash WIP, fixup commits, clean history
Issue Reference	${CLAUDE_SKILL_DIR}/rules/issue-reference-required.md	HIGH	Reference issue #N in commits on issue branches
Merge Strategy	${CLAUDE_SKILL_DIR}/rules/merge-strategy.md	HIGH	Rebase-first, conflict resolution, force-with-lease
Stacked PRs	${CLAUDE_SKILL_DIR}/rules/stacked-pr-workflow.md	HIGH	Stack planning, PR creation, dependency tracking
Stacked PRs	${CLAUDE_SKILL_DIR}/rules/stacked-pr-rebase.md	HIGH	Rebase management, force-with-lease, retargeting

Total: 9 rules across 8 categories

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

File	Content
references/conventional-commits.md	Conventional commits specification
references/recovery.md	Recovery procedures