Creating Commit

⚠️ CRITICAL CONSTRAINTS

No Claude Code Footer Policy

YOU MUST NEVER add Claude Code attribution to git commits.

• ❌ NO "🤖 Generated with [Claude Code]" in commit messages
• ❌ NO "Co-Authored-By: Claude <noreply@anthropic.com>" in commit messages
• ❌ NO Claude Code attribution, footer, or branding of any kind

Git commits are permanent project history and must remain clean and professional.

---

Git Commit Workflow

Execute intelligent git commit workflows with automatic repository detection, smart pre-commit checks, and conventional commit message generation.

Usage

This skill is invoked when:

• User runs /commit command
• User requests to commit changes
• User asks to create a git commit

How It Works

This skill handles the complete commit workflow:

1. Repository Detection - Automatically detects root repository and submodules 2. Change Analysis - Identifies modified files and determines scope 3. Pre-commit Checks - Runs appropriate checks based on file types 4. Commit Message Generation - Creates conventional commit messages with emojis 5. Submodule Handling - Prompts to update submodule references in root repository

Supported Arguments

Parse arguments from user input:

• No arguments: Interactive mode (auto-detect changes)
• `<scope>`: Direct commit to specific repository (root, submodule-name)
• `--no-verify`: Skip all pre-commit checks
• `--full-verify`: Run full builds (backend + frontend)
• `<scope> --no-verify`: Combine scope with flags

Commit Workflow Steps

Step 1: Parse Arguments

Extract scope and flags from user input:

# Parse arguments
SCOPE=""
FLAG=""

# Example parsing logic (adapt to user input):
# "root --no-verify" → SCOPE="root", FLAG="--no-verify"
# "plan" → SCOPE="plan", FLAG=""
# "--full-verify" → SCOPE="", FLAG="--full-verify"

Step 2: Detect Repositories with Changes

Find monorepo root and detect all repositories with uncommitted changes:

# Find monorepo root (works from submodules too)
if SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null) && [ -n "$SUPERPROJECT" ]; then
    # We're in a submodule
    MONOREPO_ROOT="$SUPERPROJECT"
else
    # We're in root or standalone repo
    MONOREPO_ROOT=$(git rev-parse --show-toplevel)
fi

# Detect repositories with changes
REPOS_WITH_CHANGES=()

# Check root repository
if git -C "$MONOREPO_ROOT" status --porcelain | grep -q .; then
    REPOS_WITH_CHANGES+=("root")
fi

# Check for submodules and their changes
git -C "$MONOREPO_ROOT" submodule foreach --quiet 'echo $name' | while read -r submodule; do
    SUBMODULE_PATH="$MONOREPO_ROOT/$submodule"
    if git -C "$SUBMODULE_PATH" status --porcelain | grep -q .; then
        REPOS_WITH_CHANGES+=("$submodule")
    fi
done

Step 3: Select Target Repository

If no scope specified, select repository interactively or automatically:

# If only one repository has changes, auto-select it
if [ ${#REPOS_WITH_CHANGES[@]} -eq 1 ]; then
    SCOPE="${REPOS_WITH_CHANGES[0]}"
    echo "ℹ️  Auto-selected: $SCOPE (only repository with changes)"
elif [ ${#REPOS_WITH_CHANGES[@]} -gt 1 ]; then
    # Multiple repositories - ask user to select
    echo "Found changes in:"
    for i in "${!REPOS_WITH_CHANGES[@]}"; do
        REPO="${REPOS_WITH_CHANGES[$i]}"
        REPO_PATH=$([ "$REPO" = "root" ] && echo "$MONOREPO_ROOT" || echo "$MONOREPO_ROOT/$REPO")
        CHANGE_COUNT=$(git -C "$REPO_PATH" status --porcelain | wc -l | tr -d ' ')
        echo "$((i+1)). $REPO ($CHANGE_COUNT files modified)"
    done

    # Use AskUserQuestion tool to let user select repository
    # Set SCOPE to selected repository name
fi

Step 4: Resolve Repository Path

Convert scope to absolute path:

# Resolve scope to repository path
if [ "$SCOPE" = "root" ]; then
    REPO_PATH="$MONOREPO_ROOT"
else
    # Submodule or custom scope
    REPO_PATH="$MONOREPO_ROOT/$SCOPE"
fi

# Validate repository exists
if [ ! -d "$REPO_PATH/.git" ]; then
    echo "❌ Error: Not a valid git repository: $REPO_PATH" >&2
    exit 1
fi

Step 5: Check Branch Protection

Validate not on protected branch (main branch for root only):

# Get current branch
CURRENT_BRANCH=$(git -C "$REPO_PATH" rev-parse --abbrev-ref HEAD)

# Check branch protection (only enforce for root repository)
if [ "$CURRENT_BRANCH" = "main" ] && [ "$SCOPE" = "root" ]; then
    echo "❌ Cannot commit to protected branch: main" >&2
    echo "" >&2
    echo "The main branch requires pull requests." >&2
    echo "Please create a feature branch first:" >&2
    echo "" >&2
    echo "  git checkout -b feature/your-feature-name" >&2
    echo "" >&2
    exit 1
fi

Step 6: Stage Files

Stage all unstaged changes or use already-staged files:

# Check if there are already staged files
STAGED_FILES=$(git -C "$REPO_PATH" diff --cached --name-only)

if [ -z "$STAGED_FILES" ]; then
    # No staged files - stage all changes
    echo "Staging all changes..."
    git -C "$REPO_PATH" add -A

    # Verify staging worked
    STAGED_FILES=$(git -C "$REPO_PATH" diff --cached --name-only)
    if [ -z "$STAGED_FILES" ]; then
        echo "❌ No changes to commit" >&2
        exit 1
    fi
else
    echo "ℹ️  Using already staged files"
fi

# Show what will be committed
git -C "$REPO_PATH" status --short

Step 7: Run Pre-commit Checks

Execute pre-commit checks based on changed file types and flags:

# Skip checks if --no-verify flag is set
if [ "$FLAG" = "--no-verify" ]; then
    echo "⚠️  Skipping pre-commit checks (--no-verify flag)"
elif [ "$SCOPE" = "plan" ] || [[ "$SCOPE" == *"doc"* ]]; then
    echo "ℹ️  Skipping checks for documentation repository"
elif [ "$FLAG" = "--full-verify" ]; then
    # Full build verification
    echo "Running full build verification..."

    if [ -d "$MONOREPO_ROOT/backend" ]; then
        echo "Building backend..."
        (cd "$MONOREPO_ROOT/backend" && ./gradlew build test) || {
            echo "❌ Backend build failed" >&2
            exit 1
        }
    fi

    if [ -d "$MONOREPO_ROOT/frontend" ]; then
        echo "Building frontend..."
        (cd "$MONOREPO_ROOT/frontend" && npm run build) || {
            echo "❌ Frontend build failed" >&2
            exit 1
        }
    fi

    echo "✅ Full build verification passed"
else
    # Smart detection - run checks based on file types
    CHANGED_FILES=$(git -C "$REPO_PATH" diff --cached --name-only)

    # Detect Kotlin files
    if echo "$CHANGED_FILES" | grep -q '\.kt$'; then
        echo "Running backend checks (Kotlin files detected)..."
        if [ -f "$MONOREPO_ROOT/backend/gradlew" ]; then
            (cd "$MONOREPO_ROOT/backend" && ./gradlew detekt) || {
                echo "❌ Kotlin checks failed" >&2
                exit 1
            }
        fi
    fi

    # Detect TypeScript/JavaScript files
    if echo "$CHANGED_FILES" | grep -qE '\.(ts|tsx|js|jsx)$'; then
        echo "Running frontend checks (TypeScript files detected)..."
        if [ -f "$MONOREPO_ROOT/frontend/package.json" ]; then
            (cd "$MONOREPO_ROOT/frontend" && npx tsc --noEmit) || {
                echo "❌ TypeScript checks failed" >&2
                exit 1
            }
        fi
    fi

    # Detect Python files
    if echo "$CHANGED_FILES" | grep -q '\.py$'; then
        echo "Running Python checks..."
        # Add Python linting if configured (e.g., pylint, flake8)
    fi

    # Detect Rust files
    if echo "$CHANGED_FILES" | grep -q '\.rs$'; then
        echo "Running Rust checks..."
        if [ -f "$REPO_PATH/Cargo.toml" ]; then
            (cd "$REPO_PATH" && cargo check) || {
                echo "❌ Rust checks failed" >&2
                exit 1
            }
        fi
    fi

    echo "✅ Pre-commit checks passed"
fi

Step 8: Generate Commit Message

Analyze changes and create conventional commit message:

# Detect commit type from changed files
DIFF_STAT=$(git -C "$REPO_PATH" diff --cached --stat)

# Simple heuristic based on file patterns
if echo "$DIFF_STAT" | grep -q "test\|spec"; then
    COMMIT_TYPE="test"
    EMOJI="✅"
elif echo "$DIFF_STAT" | grep -q "\.md\|README\|docs/"; then
    COMMIT_TYPE="docs"
    EMOJI="📝"
elif echo "$DIFF_STAT" | grep -qE "build\.gradle|package\.json|pom\.xml|Cargo\.toml"; then
    COMMIT_TYPE="build"
    EMOJI="🏗️"
elif echo "$DIFF_STAT" | grep -qE "\.github|\.gitlab|Jenkinsfile|\.circleci"; then
    COMMIT_TYPE="ci"
    EMOJI="👷"
elif echo "$DIFF_STAT" | grep -q "refactor"; then
    COMMIT_TYPE="refactor"
    EMOJI="♻️"
elif echo "$DIFF_STAT" | grep -q "fix\|bug"; then
    COMMIT_TYPE="fix"
    EMOJI="🐛"
else
    # Default to feat for most changes
    COMMIT_TYPE="feat"
    EMOJI="✨"
fi

# Analyze the actual changes to generate a meaningful description
CHANGED_FILES_LIST=$(git -C "$REPO_PATH" diff --cached --name-only)
ADDITIONS=$(git -C "$REPO_PATH" diff --cached --numstat | awk '{sum+=$1} END {print sum}')
DELETIONS=$(git -C "$REPO_PATH" diff --cached --numstat | awk '{sum+=$2} END {print sum}')

# Generate commit message based on changes
# You should analyze the diff and create a concise, meaningful message
# For now, this is a template - Claude should intelligently describe the changes
COMMIT_SUBJECT="$COMMIT_TYPE: [brief description of changes]"
COMMIT_BODY="[optional detailed explanation]

Changes:
$CHANGED_FILES_LIST

$ADDITIONS additions, $DELETIONS deletions"

# Present commit message to user for approval
echo ""
echo "Suggested commit message:"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "$EMOJI $COMMIT_SUBJECT"
echo ""
echo "$COMMIT_BODY"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""

# Use AskUserQuestion tool to confirm or let user edit the message

Step 9: Create Commit

Execute git commit with the approved message:

# IMPORTANT: No Claude Code footer in commit messages
# Create commit with clean message only

git -C "$REPO_PATH" commit -m "$COMMIT_SUBJECT" -m "$COMMIT_BODY" || {
    echo "❌ Commit failed" >&2
    exit 1
}

# Get commit hash
COMMIT_HASH=$(git -C "$REPO_PATH" rev-parse --short HEAD)

echo "✅ Commit created: $COMMIT_HASH"
echo ""
git -C "$REPO_PATH" log -1 --oneline

Step 10: Handle Submodule References (if applicable)

If committed to a submodule, prompt to update root repository:

# If we committed to a submodule, check if root needs update
if [ "$SCOPE" != "root" ]; then
    # Check if submodule reference changed in root
    SUBMODULE_REF_CHANGED=$(git -C "$MONOREPO_ROOT" status --porcelain | grep "^ M $SCOPE$")

    if [ -n "$SUBMODULE_REF_CHANGED" ]; then
        echo ""
        echo "ℹ️  Submodule reference changed in root repository"
        echo ""

        # Use AskUserQuestion to ask if they want to commit the submodule reference
        # If yes:
        # git -C "$MONOREPO_ROOT" add "$SCOPE"
        # git -C "$MONOREPO_ROOT" commit -m "build: update $SCOPE submodule reference"
    fi
fi

Commit Type Detection

The skill automatically detects commit types based on file patterns:

Pre-commit Check Matrix

Important Notes

• Multi-repo/Submodule Support: Automatically detects and handles monorepo structures
• Branch Protection: Prevents commits to main branch in root repository
• Smart Checks: Only runs checks relevant to changed file types
• No External Dependencies: All logic uses git commands and Bash tool
• Clean Commit History: No Claude Code attribution in commit messages

Supporting Documentation

For detailed information, see:

• [WORKFLOW.md](WORKFLOW.md) - Step-by-step commit process including repository detection, pre-commit checks, and submodule handling
• [EXAMPLES.md](EXAMPLES.md) - Real-world commit scenarios covering features, bug fixes, submodules, and verification modes
• [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions for pre-commit failures and submodule conflicts

Git Commit Creation: Examples

This document provides real-world examples of commit creation with the creating-commit skill.

For quick start instructions, see SKILL.md. For detailed workflow, see WORKFLOW.md.

---

Example 1: Simple Feature Commit (Root Repository)

Scenario

Adding a new authentication feature in the root repository.

Command

/commit

Execution

Step 1: Repository Detection

Detected repositories:
- Root: myapp
  Changes: src/auth/login.ts, src/auth/oauth.ts

Step 2: Change Analysis

File types: TypeScript (2 files)
Pre-commit check: npx tsc --noEmit

Step 3: Pre-commit Checks

Running TypeScript type checking...
✅ TypeScript compilation successful

Step 4: Commit Message

Suggested commit:
──────────────────────────────────
feat(auth): add OAuth2 login support

Implemented OAuth2 authentication flow with
token refresh and secure session management.
──────────────────────────────────

Proceed? (y/n): y

Output

✅ Committed: [myapp 7f3a8b9] feat(auth): add OAuth2 login support
   2 files changed, 145 insertions(+)

---

Example 2: Bug Fix with Pre-commit Checks

Scenario

Fixing a null pointer exception in Kotlin code.

Command

/commit

Execution

Changes Detected:

Root: backend-service
  M src/main/kotlin/auth/UserService.kt
  M src/main/kotlin/auth/TokenValidator.kt

Pre-commit Check:

Running Detekt...
✅ Detekt analysis passed
   0 issues found

Commit Message:

fix(auth): resolve null pointer in token validation

Added null safety checks in TokenValidator.validateToken()
to prevent NPE when token is expired.

Output

✅ Committed: [backend-service 3e2f1a9] fix(auth): resolve null pointer
   2 files changed, 12 insertions(+), 4 deletions(-)

---

Example 3: Submodule Commit Only

Scenario

Updating documentation in a plugin submodule.

Command

/commit arkhe-claude-plugins

Execution

Scope: Directly commit to arkhe-claude-plugins submodule

Changes:

Submodule: arkhe-claude-plugins
  M git/skills/creating-commit/SKILL.md
  A git/skills/creating-commit/WORKFLOW.md

Pre-commit: None required (documentation)

Commit:

docs(commit): add comprehensive workflow documentation

Added detailed 5-step process covering repository detection,
change analysis, pre-commit checks, message generation, and
submodule handling.

Output

✅ Committed in submodule: [arkhe-claude-plugins def5678]
   2 files changed, 420 insertions(+)

---

Example 4: Submodule Commit with Root Update

Scenario

Commit to submodule, then update the submodule reference in root.

Command

/commit

Execution

Step 1: Detection

Detected changes:
1. arkhe-claude-plugins (submodule)

Select repository: 1

Step 2: Commit to Submodule

✅ Committed: [arkhe-claude-plugins abc1234] feat(git): add commit skill

Step 3: Root Update Prompt

Submodule reference updated in root repository.

Root repository now shows:
  modified: plugins/arkhe-claude-plugins (new commits)

Update submodule reference in root? (y/n): y

Step 4: Root Commit

Committing to root...

chore: update arkhe-claude-plugins submodule

Updated to include:
- feat(git): add commit skill

Output

✅ Submodule committed: [arkhe-claude-plugins abc1234]
✅ Root updated: [myapp 8g4b9c0] chore: update submodule

---

Example 5: Skip Verification (Fast Commit)

Scenario

Documentation-only changes, want to skip all checks for speed.

Command

/commit --no-verify

Execution

Changes:

Root: myapp
  M README.md
  M docs/installation.md

Pre-commit Checks:

--no-verify flag detected
⏭️  Skipping all pre-commit checks

Commit:

docs: update installation guide

Added troubleshooting section and clarified
dependency requirements.

Output

✅ Committed: [myapp 5c7d2e1] docs: update installation guide
   (no checks run)

---

Example 6: Full Verification Mode

Scenario

Before pushing to production, want comprehensive checks.

Command

/commit --full-verify

Execution

Changes:

Root: myapp
  M src/api/endpoints.ts
  M src/ui/components/Dashboard.tsx

Pre-commit Checks:

Running full verification...

Backend checks:
  ✅ TypeScript compilation (API)
  ✅ Unit tests passed

Frontend checks:
  ✅ TypeScript compilation (UI)
  ✅ React component tests passed
  ✅ Lint checks passed

All checks passed ✅

Commit:

feat(dashboard): add real-time analytics

Implemented WebSocket connection for live data
updates on dashboard with automatic reconnection.

Output

✅ Full verification passed
✅ Committed: [myapp 9h5c3f2] feat(dashboard): add real-time analytics

---

Example 7: Pre-commit Check Failure

Scenario

TypeScript compilation error prevents commit.

Command

/commit

Execution

Changes:

Root: myapp
  M src/auth/login.ts

Pre-commit Check:

Running TypeScript check...

❌ TypeScript compilation failed:

src/auth/login.ts:42:15 - error TS2345
  Argument of type 'string' is not assignable to parameter of type 'number'.

  42     authenticate(userId);
                      ~~~~~~

Found 1 error.

Result: Commit aborted

Resolution Options

Option 1: Fix the error

// Before
authenticate(userId);  // userId is string

// After
authenticate(Number(userId));  // Convert to number

Option 2: Skip verification (if confident)

/commit --no-verify

---

Example 8: Rust Project Commit

Scenario

Committing changes to a Rust project.

Command

/commit

Execution

Changes:

Root: rust-cli
  M src/main.rs
  M src/parser.rs

Pre-commit Check:

Running cargo check...

   Compiling rust-cli v0.1.0
   Finished dev [unoptimized + debuginfo] target(s) in 2.34s

✅ Cargo check passed

Commit:

feat(parser): add JSON parsing support

Implemented serde-based JSON parser with
error handling and validation.

Output

✅ Committed: [rust-cli 4f8a2b3] feat(parser): add JSON parsing
   2 files changed, 87 insertions(+)

---

Example 9: Mixed Changes (Interactive Selection)

Scenario

Changes in both root and submodule, need to choose which to commit.

Command

/commit

Execution

Detection:

Multiple repositories with changes detected:

1. myapp (root)
   - src/api/server.ts
   - src/config/database.ts

2. arkhe-claude-plugins (submodule)
   - git/skills/creating-commit/SKILL.md

Select repository to commit (1 or 2): 2

Selected: Commit to submodule first

Submodule Commit:

✅ Committed: [arkhe-claude-plugins xyz7890] docs(commit): update SKILL.md

Root Update Prompt:

Update submodule reference in root? (y/n): n

Result: Submodule committed, root changes remain staged

---

Example 10: Scope-Specific Commit

Scenario

Commit directly to root, ignoring submodule changes.

Command

/commit root

Execution

Scope: root (explicit)

Changes:

Root: myapp
  M package.json
  M src/index.ts

Note: Submodule changes ignored (will remain staged)

Commit:

feat: upgrade to Node.js 20

Updated dependencies and TypeScript target
to support Node.js 20 features.

Output

✅ Committed to root: [myapp 2c9f5a1]
   Submodule changes remain staged

---

Common Workflows

Daily Development

# Morning: Pull latest
git pull

# Work on feature
vim src/feature.ts

# Commit with checks (interactive)
/commit

# Repeat throughout day

Documentation Updates

# Edit docs
vim README.md docs/guide.md

# Fast commit (skip checks)
/commit --no-verify

Pre-Production Checklist

# Final commit before release
/commit --full-verify

# Ensure all tests pass before pushing
git push origin main

Plugin Development

# Work in submodule
cd plugins/arkhe-claude-plugins
vim git/skills/creating-commit/SKILL.md

# Commit submodule
cd ../..
/commit arkhe-claude-plugins

# Update root reference
# (prompted automatically)

---

Tips for Effective Commits

✅ Good Practices

1. Commit frequently: Small, focused commits 2. Run checks: Let pre-commit checks catch errors early 3. Use conventional commits: Script generates proper format 4. Keep submodules in sync: Always update root after submodule commits 5. Review before committing: Check git diff first

❌ Avoid

1. Large, mixed commits: Split into focused commits 2. Skipping checks unnecessarily: Only use --no-verify for docs 3. Committing broken code: Fix pre-commit failures first 4. Forgetting submodule updates: Can cause deployment issues

---

Summary

The creating-commit skill automates:

• ✅ Repository detection (root + submodules)
• ✅ Language-specific pre-commit checks
• ✅ Conventional commit message generation
• ✅ Submodule reference management

Result: Consistent, high-quality commits with minimal manual effort.

For detailed workflow, see WORKFLOW.md. For troubleshooting, see TROUBLESHOOTING.md.

---

Last Updated: 2025-10-27

Git Commit Creation: Troubleshooting

This document provides solutions to common issues when using the creating-commit skill.

For quick start instructions, see SKILL.md. For detailed workflow, see WORKFLOW.md. For examples, see EXAMPLES.md.

---

Common Issues

Issue 1: Pre-commit Checks Failing

Symptom:

❌ Pre-commit checks failed:
  - TypeScript compilation errors
  - Detekt found 3 issues

Causes:

• Code has compilation errors
• Linting violations
• Test failures

Solutions:

Solution A: Fix the Errors (Recommended)

# View detailed error output
npx tsc --noEmit

# Fix errors in your code
vim src/file.ts

# Try committing again
/commit

Solution B: Skip Verification (Use Sparingly)

# Only for documentation or minor changes
/commit --no-verify

Warning: Skipping checks can lead to broken code in repository.

---

Issue 2: TypeScript Compilation Errors

Symptom:

❌ TypeScript errors found:

src/auth/login.ts:42:15 - error TS2345
  Argument of type 'string' is not assignable to parameter of type 'number'.

Cause: Type mismatch or TypeScript configuration issue

Solutions:

Solution A: Fix Type Error

// Before (error)
function authenticate(id: number) { }
authenticate(userId);  // userId is string

// After (fixed)
authenticate(Number(userId));
// or
authenticate(parseInt(userId, 10));

Solution B: Check TypeScript Config

# Verify tsconfig.json exists
cat tsconfig.json

# Test compilation manually
npx tsc --noEmit

Solution C: Install Dependencies

# Missing type definitions
npm install --save-dev @types/node
npm install --save-dev @types/react

---

Issue 3: Detekt Errors (Kotlin)

Symptom:

❌ Detekt found issues:

UserService.kt:15: MagicNumber
  Magic number found: 42

TokenValidator.kt:28: ComplexMethod
  Method complexity is 12, max allowed is 10

Cause: Code style violations in Kotlin files

Solutions:

Solution A: Fix Issues

// Before (magic number)
val timeout = 42

// After (named constant)
private const val DEFAULT_TIMEOUT = 42
val timeout = DEFAULT_TIMEOUT

Solution B: Configure Detekt

# detekt.yml
complexity:
  ComplexMethod:
    threshold: 15  # Increase if needed

style:
  MagicNumber:
    ignoreNumbers: [-1, 0, 1, 2, 42]  # Whitelist specific numbers

Solution C: Skip for This Commit

/commit --no-verify

---

Issue 4: Cargo Check Fails (Rust)

Symptom:

❌ Cargo check failed:

error[E0308]: mismatched types
  --> src/parser.rs:42:5
   |
42 |     "hello"
   |     ^^^^^^^ expected `i32`, found `&str`

Cause: Type error or compilation issue in Rust code

Solutions:

Solution A: Fix Rust Error

// Before (error)
fn get_value() -> i32 {
    "hello"  // Wrong type
}

// After (fixed)
fn get_value() -> i32 {
    42
}

Solution B: Run Cargo Manually

# Get detailed error information
cargo check

# Run with verbose output
cargo check --verbose

# Fix errors then commit
/commit

---

Issue 5: Submodule Conflicts

Symptom:

❌ Submodule has conflicts:

plugins/arkhe-claude-plugins:
  Conflicting changes between local and remote

Cause: Submodule HEAD differs from what root expects

Solutions:

Solution A: Update Submodule

# Navigate to submodule
cd plugins/arkhe-claude-plugins

# Pull latest
git pull origin main

# Return to root
cd ../..

# Try commit again
/commit

Solution B: Reset Submodule

# Reset submodule to commit referenced by root
git submodule update --init --recursive

# Then commit
/commit

Solution C: Commit Submodule First

# Explicitly commit to submodule
/commit arkhe-claude-plugins

# Then update root
# (prompted automatically)

---

Issue 6: Script Not Found

Symptom:

bash: /commit: No such file or directory

Causes:

• Wrong working directory
• Plugin not installed
• File permissions

Solutions:

Solution A: Navigate to Project Root

# Check current directory
pwd

# Find project root
cd /path/to/your/project

# Verify file exists
ls -la /commit

Solution B: Reinstall Plugin

/plugin uninstall git@arkhe-claude-plugins
/plugin install git@arkhe-claude-plugins

Solution C: Fix Permissions

chmod +x /commit
Skills are loaded automatically - no manual setup needed

---

Issue 7: No Changes to Commit

Symptom:

❌ No changes detected in any repository

Cause: All changes are already committed or not staged

Solutions:

Solution A: Stage Changes First

# View unstaged changes
git status

# Stage files
git add src/file.ts

# Then commit
/commit

Solution B: Check for Untracked Files

# View all files including untracked
git status

# Add untracked files
git add .

# Commit
/commit

---

Issue 8: Commit Message Validation Fails

Symptom:

❌ Commit message validation failed:
  - Subject line too long (82 characters, max 72)
  - Missing blank line after subject

Cause: Generated message doesn't meet repository's commit-msg hook requirements

Solutions:

Solution A: Edit Message

# When prompted, choose 'e' to edit
Proceed? (y/n/e): e

# Editor opens, modify message to meet requirements

Solution B: Bypass Hook (If Confident)

/commit --no-verify

Note: This skips all hooks, including commit-msg validation

---

Issue 9: Wrong Repository Selected

Symptom: Committed to root when intended to commit to submodule (or vice versa).

Cause: Interactive mode selected wrong repository

Solutions:

Solution A: Undo Last Commit

# Undo commit but keep changes
git reset --soft HEAD~1

# Re-run with explicit scope
/commit arkhe-claude-plugins

Solution B: Use Explicit Scope

# Always specify scope to avoid selection
/commit root
/commit arkhe-claude-plugins

---

Issue 10: Branch Protection Warning

Symptom:

⚠️  Warning: You are committing to a protected branch (main)
   Consider creating a feature branch instead.

Proceed anyway? (y/n):

Cause: Attempting to commit directly to protected branch

Solutions:

Solution A: Create Feature Branch (Recommended)

# Create and checkout feature branch
/create-branch add my feature

# Then commit
/commit

Solution B: Proceed with Caution

# Only if you have permission
Proceed anyway? y

Best Practice: Always work on feature branches, not directly on main/master

---

Issue 11: Submodule Not Initialized

Symptom:

❌ Submodule directory exists but git repository not initialized:
   plugins/arkhe-claude-plugins

Cause: Submodule cloned but not initialized

Solutions:

Solution A: Initialize Submodule

git submodule update --init --recursive

Solution B: Clone with Submodules

# When first cloning repository
git clone --recursive <repository-url>

---

Issue 12: Multiple Git Instances Detected

Symptom:

⚠️  Warning: Multiple .git directories detected in parent path
   This may cause unexpected behavior

Cause: Nested git repositories (unusual setup)

Solutions:

Solution A: Verify Repository Structure

# Find all .git directories
find . -name ".git" -type d

# Expected:
# ./git (root)
# ./plugins/submodule/.git (submodule)

Solution B: Use Explicit Paths

# Specify exact repository
cd /path/to/intended/repository
../..//commit

---

Quick Reference

Error Messages

Verification Commands

# Check git status
git status

# View staged changes
git diff --cached

# List submodules
git submodule status

# Test TypeScript
npx tsc --noEmit

# Test Kotlin (Detekt)
./gradlew detekt

# Test Rust
cargo check

# Verify script exists
ls -la /commit

Debugging

Enable Verbose Output:

# Run script with bash -x for debugging
bash -x /commit

Check Script Logs:

# If script creates logs
cat /tmp/commit-script.log

---

Prevention Tips

1. Run `git status` before committing: Know what you're committing 2. Stage changes deliberately: Use git add selectively 3. Keep submodules updated: Run git submodule update regularly 4. Fix pre-commit errors: Don't routinely skip checks 5. Use feature branches: Avoid committing directly to main 6. Test locally first: Run checks manually before committing 7. Keep dependencies updated: Ensure build tools are installed

---

Getting Help

If issues persist:

1. Check Skill Documentation: Review SKILL.md for usage 2. Review Examples: See EXAMPLES.md for common patterns 3. Verify Installation:

   /plugin list
   # Ensure git@arkhe-claude-plugins is installed

4. Reinstall Plugin:

   /plugin uninstall git@arkhe-claude-plugins
   /plugin install git@arkhe-claude-plugins

5. Check Git Status:

   git status
   git log --oneline -5
   git submodule status

---

Last Updated: 2025-10-27

Git Commit Creation: Detailed Workflow

This document provides a detailed step-by-step breakdown of the commit creation process.

For quick start instructions, see SKILL.md.

Overview

The commit creation process follows 5 main steps:

1. Repository Detection - Auto-detect root repository and submodules 2. Change Analysis - Identify modified files and determine scope 3. Pre-commit Checks - Run language-specific checks 4. Commit Message Generation - Create conventional commit messages 5. Submodule Handling - Update submodule references in root

---

Step 1: Repository Detection

Automatically detect the repository structure and identify where changes exist.

Root Repository Detection

Process: 1. Find the root .git directory by walking up from current directory 2. Identify repository name from directory or git remote 3. Set root repository path

Example:

Current directory: /Users/you/projects/myapp/src/
Root repository: /Users/you/projects/myapp/
Repository name: myapp

Submodule Detection

Process: 1. Check for .gitmodules file in root 2. Parse submodule paths and names 3. For each submodule:

• Check if directory exists
• Verify .git file/directory
• Add to submodule list

Example `.gitmodules`:

[submodule "plugins/arkhe-claude-plugins"]
	path = plugins/arkhe-claude-plugins
	url = git@github.com:user/arkhe-claude-plugins.git

Detected Structure:

Root: myapp/
Submodules:
  - arkhe-claude-plugins (plugins/arkhe-claude-plugins/)

Change Detection

For Root Repository:

cd /root/path
git status --porcelain

For Each Submodule:

cd /root/path/submodule-path
git status --porcelain

Output Interpretation:

• M = Modified file
• A = Added file
• D = Deleted file
• ?? = Untracked file
• R = Renamed file

Result: List of repositories with changes

---

Step 2: Change Analysis

Analyze the types of changes to determine commit scope and pre-commit checks.

File Type Detection

Scan modified files for patterns:

Scope Determination

Interactive Mode (no arguments):

• If only root has changes → Commit to root
• If only one submodule has changes → Commit to that submodule
• If multiple repositories have changes → Prompt user to select

Direct Mode (with scope argument):

• root → Commit to root repository
• <submodule-name> → Commit to specific submodule
• Skip detection, go directly to specified repository

Example Change Analysis

Scenario: Working on a plugin within a submodule

Changes Detected:

Root repository (myapp):
  - No changes

Submodule (arkhe-claude-plugins):
  M git/skills/creating-commit/SKILL.md
  M git/skills/creating-commit/WORKFLOW.md
  M git/skills/creating-commit/EXAMPLES.md

Analysis:

• Repository: arkhe-claude-plugins (submodule)
• File types: .md (3 files)
• Pre-commit checks: None required (documentation)
• Commit type suggestion: docs

---

Step 3: Pre-commit Checks

Run language-specific checks before allowing commit.

Check Selection Logic

Kotlin Files (.kt):

./gradlew detekt

• Runs static analysis
• Checks code style
• Identifies potential bugs

TypeScript Files (.ts, .tsx):

npx tsc --noEmit

• Type checks all TypeScript code
• Reports compilation errors
• No output files generated

Python Files (.py):

# Configurable - example:
flake8 --max-line-length=100
pylint --disable=C0111

• Linting based on configuration
• PEP 8 compliance

Rust Files (.rs):

cargo check

• Checks code compiles
• Reports errors
• Fast check without building

Check Modes

Standard Mode (default):

/commit

• Runs checks for modified file types only
• Fast feedback loop

Full Verification (--full-verify):

/commit --full-verify

• Runs complete build process
• Backend + Frontend verification
• Slower but comprehensive

Skip Verification (--no-verify):

/commit --no-verify

• Skips all pre-commit checks
• Faster commit process
• Use for documentation-only changes

Check Results

Success:

✅ Pre-commit checks passed

→ Proceed to commit message generation

Failure:

❌ Pre-commit checks failed:
  - Detekt found 3 issues in UserService.kt
  - TypeScript compilation error in auth.ts:42

→ Fix issues before committing (or use --no-verify to bypass)

Example: TypeScript Check

Modified Files:

src/auth/login.ts
src/auth/logout.ts

Check Execution:

npx tsc --noEmit

Success Output:

✅ TypeScript compilation successful

Failure Output:

❌ TypeScript errors found:

src/auth/login.ts:42:15 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

42     login(userId);
               ~~~~~~

→ Fix error before committing

---

Step 4: Commit Message Generation

Generate conventional commit messages with appropriate type and scope.

Conventional Commit Format

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

[optional body]

Commit Type Detection

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• refactor: Code refactoring
• test: Adding tests
• chore: Maintenance tasks
• perf: Performance improvements
• ci: CI/CD changes

Detection Logic: 1. Analyze file paths and types 2. Read git diff for context 3. Suggest appropriate type 4. Allow user to confirm or modify

Scope Detection

Automatic Scope:

• From directory structure (e.g., auth, api, ui)
• From file patterns (e.g., skills/commit → commit)

Example:

Modified: git/skills/creating-commit/SKILL.md
Scope: commit
Type: docs
Message: docs(commit): update skill documentation

Message Construction

Step 1: Generate Description

• Analyze changes from git diff
• Summarize in present tense
• Keep under 72 characters

Step 2: Add Body (if needed)

• Additional context
• Breaking changes
• Related issues

Step 3: Finalize Message

• Review for clarity and completeness
• Ensure it follows conventional commit format

Interactive Approval

Claude Presents:

Suggested commit message:
────────────────────────────────
docs(commit): add comprehensive workflow documentation

Added detailed 5-step process explanation including
repository detection, change analysis, pre-commit checks,
message generation, and submodule handling.
────────────────────────────────

Proceed with this commit? (y/n):

User Options:

• y → Commit with this message
• n → Abort
• Custom message → Provide alternative commit message

---

Step 5: Submodule Handling

Handle submodule reference updates in root repository.

Scenario: Submodule Committed

After committing changes in a submodule:

1. Submodule commit successful:

   [arkhe-claude-plugins abc1234] docs(commit): add workflow doc

2. Root repository now shows:

   cd /root
   git status

   Changes not staged for commit:
     modified:   plugins/arkhe-claude-plugins (new commits)

Update Prompt

Claude Asks:

✅ Committed in submodule: arkhe-claude-plugins

The root repository has new commits in this submodule.
Would you like to update the submodule reference in root? (y/n):

Options:

Yes (y):

# Claude executes:
cd /root
git add plugins/arkhe-claude-plugins
git commit -m "build: update arkhe-claude-plugins submodule

Updated to include latest changes:
- docs(commit): add workflow documentation"

No (n):

• Skip root update
• User can manually update later

Mixed Changes Scenario

Root has changes AND submodule has changes:

Option 1: Commit to submodule first

/commit arkhe-claude-plugins

→ Then prompted to update root

Option 2: Commit to root first

/commit root

→ Submodule changes remain uncommitted

Option 3: Interactive mode

/commit

→ Choose which repository to commit first

---

Complete Example Workflows

Example 1: Simple Feature Commit

Context: Modified authentication logic in root repository

Step 1: Detection

Root repository: myapp
Changes: src/auth/login.ts (modified)
Submodules: No changes

Step 2: Analysis

File type: TypeScript
Pre-commit check: npx tsc --noEmit
Suggested type: feat

Step 3: Pre-commit

Running TypeScript check...
✅ TypeScript compilation successful

Step 4: Message

feat(auth): add OAuth2 login support

Implemented OAuth2 authentication flow with token refresh
and secure session management.

Step 5: Commit

✅ Committed: [myapp 7f3a8b9] feat(auth): add OAuth2 login support

---

Example 2: Submodule Commit with Root Update

Context: Modified plugin skill in submodule

Step 1: Detection

Root repository: myapp
  - No direct changes
  - Submodule has changes

Submodule: arkhe-claude-plugins
  - Modified: git/skills/creating-commit/SKILL.md

Step 2: Interactive Selection

Multiple repositories detected:
1. arkhe-claude-plugins (submodule)

Commit to: arkhe-claude-plugins

Step 3: Pre-commit

No checks required (documentation)
✅ Skipping pre-commit checks

Step 4: Commit to Submodule

docs(commit): update skill documentation

✅ Committed: [arkhe-claude-plugins def5678]

Step 5: Root Update Prompt

Submodule reference updated in root repository.
Update root? (y/n): y

Committing to root:
chore: update arkhe-claude-plugins submodule

✅ Committed: [myapp 8g4b9c0]

---

Example 3: Skip Verification

Context: Documentation-only change, want to skip checks

Command:

/commit --no-verify

Workflow:

Step 1: Detection ✅
Step 2: Analysis ✅
Step 3: Pre-commit → SKIPPED
Step 4: Message generation ✅
Step 5: Commit ✅

Result: Fast commit without waiting for checks

---

Advanced Features

Absolute Path Resolution

The skill works from any directory:

# From root
cd /Users/you/projects/myapp
/commit

# From subdirectory
cd /Users/you/projects/myapp/src/auth
/commit

# From submodule
cd /Users/you/projects/myapp/plugins/arkhe-claude-plugins
/commit

All paths are resolved absolutely using git commands, ensuring consistent behavior.

Branch Protection Awareness

Protected Branches (main, master, production):

• Skill warns before committing
• Suggests creating feature branch
• Prevents accidental commits to protected branches

Emoji Convention

Commit message prefixes (optional):

• 🎨 :art: - Improve structure/format
• ⚡️ :zap: - Improve performance
• 🔥 :fire: - Remove code/files
• 🐛 :bug: - Fix a bug
• ✨ :sparkles: - Introduce new features
• 📝 :memo: - Add/update documentation
• ♻️ :recycle: - Refactor code

Usage: Automatically added based on commit type (configurable)

---

Configuration

Customizing Pre-commit Checks

The skill automatically detects and runs appropriate checks based on file types. To customize:

Edit git/skills/creating-commit/SKILL.md to add custom pre-commit commands:

# Example: Add custom Python linting
if echo "$CHANGED_FILES" | grep -q '\.py$'; then
    echo "Running Python checks..."
    if [ -f "$REPO_PATH/requirements.txt" ]; then
        flake8 --max-line-length=100 || {
            echo "❌ Python linting failed" >&2
            exit 1
        }
    fi
fi

---

Important: No Claude Code Footer Policy

The skill generates clean commit messages without any attribution.

⚠️ CRITICAL CONSTRAINT: Never add Claude Code footers or attribution to commit messages.

Prohibited Content:

• ❌ "🤖 Generated with [Claude Code]"
• ❌ "Co-Authored-By: Claude <noreply@anthropic.com>"
• ❌ Any Claude Code branding or attribution

Why This Matters:

• Git history should reflect actual contributors
• Commit messages should be clean and professional
• Attribution pollutes version control history

Example of Correct Commit:

feat(auth): add OAuth2 login support

Implemented OAuth2 authentication flow with token refresh
and secure session management.

Example of Incorrect Commit (NEVER do this):

feat(auth): add OAuth2 login support

Implemented OAuth2 authentication flow with token refresh
and secure session management.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

---

Best Practices

1. Run checks before committing: Let Claude detect and run appropriate checks 2. Use meaningful commit messages: Claude generates good defaults, but customize if needed 3. Commit frequently: Small, focused commits are easier to review 4. Keep submodules in sync: Always update root when submodule changes 5. Review staged changes: Check git status before running commit 6. Use scoped commits: Commit to specific repository when working on mixed changes

---

Summary

The commit creation workflow automates: 1. ✅ Repository and submodule detection 2. ✅ Language-specific pre-commit checks 3. ✅ Conventional commit message generation 4. ✅ Submodule reference management 5. ✅ Interactive approval process

Result: Consistent, high-quality commits with minimal manual effort.

For examples, see EXAMPLES.md. For troubleshooting, see TROUBLESHOOTING.md.

---

Last Updated: 2025-10-27