Intelligent Commit Workflow

--help Handler

If the user passes --help as an argument, display this help and stop:

/coconut-commit-work:commit-work - Intelligent Git Commits

DESCRIPTION
  Analyzes all changes and commits them in smallest logical groups with:
  - Semantic grouping by feature, layer, or concern
  - Conventional commit format with emoji prefixes
  - Scrum-like user story sections
  - Auto-generated acceptance criteria
  - Auto-push to remote (default behavior)

USAGE
  /coconut-commit-work:commit-work [options]
  /coconut-commit-work:commit-work --help

OPTIONS
  --dry-run              Preview commits without executing
  --no-push              Skip auto-push after commits (default: auto-push enabled)
  --help                 Show this help message

EXECUTION MODEL
  - Analysis: Parallel (multiple commit-analyzer agents for large changesets)
  - Staging & Commit: Sequential (avoids git staging race conditions)
  This provides fast analysis while ensuring reliable atomic commits.

COMMIT FORMAT
  ✨ feat(scope): Subject line (max 50 chars)

  ## Why (User Story)
  As a [role], I want [goal] so that [benefit].

  ## What Changed
  - Specific change 1
  - Specific change 2

  ## Acceptance Criteria
  - [ ] Testable criterion 1
  - [ ] Testable criterion 2

  ## Notes
  Technical context if needed.

EMOJI TYPES
  ✨ feat      New feature
  🐛 fix       Bug fix
  📝 docs      Documentation
  💄 style     Formatting only
  ♻️ refactor  Code restructure
  ✅ test      Tests
  🔧 chore     Maintenance
  ⚡ perf      Performance
  👷 ci        CI/CD
  📦 build     Build system

GROUPING STRATEGY
  1. Feature cohesion - Related functionality together
  2. Layer separation - Frontend/backend/config separate
  3. Test pairing - Implementation + tests together
  4. Config isolation - Config changes standalone
  5. Documentation - Docs usually separate

EXAMPLES
  # Analyze, commit, and push all changes (default)
  /coconut-commit-work:commit-work

  # Preview what would be committed
  /coconut-commit-work:commit-work --dry-run

  # Commit without pushing
  /coconut-commit-work:commit-work --no-push

COMMIT TEMPLATE
  Creates .github/COMMIT_TEMPLATE if missing for team consistency.
  Includes git user.name and user.email from git config.

Execute an intelligent commit workflow that:

1. Groups changes semantically into smallest logical commits
2. Creates detailed conventional commit messages with emoji prefixes
3. Includes user story sections in each commit
4. Auto-pushes to remote (unless --no-push is specified)

Step 1: Check/Create Commit Template

First, check if .github/COMMIT_TEMPLATE exists:

test -f .github/COMMIT_TEMPLATE && echo "EXISTS" || echo "MISSING"

If MISSING, create the directory and template:

mkdir -p .github

Get git user info from config:

git config user.name
git config user.email

Then write this commit template to .github/COMMIT_TEMPLATE, replacing [GIT_USER_NAME] and [GIT_USER_EMAIL] with the actual values from git config:

# [emoji] [type](scope): Subject (max 50 chars)

## Why (User Story)
As a [role], I want [goal] so that [benefit].

## What Changed
-

## Acceptance Criteria
- [ ]

## Notes

# ---
# Author: [GIT_USER_NAME] <[GIT_USER_EMAIL]>
#
# Emoji Reference:
# ✨ feat     = New feature
# 🐛 fix      = Bug fix
# 📝 docs     = Documentation
# 💄 style    = Formatting (no code change)
# ♻️ refactor = Code restructure
# ✅ test     = Tests
# 🔧 chore    = Maintenance
# ⚡ perf     = Performance
# 👷 ci       = CI/CD
# 📦 build    = Build system

Step 2: Gather All Changes

Get the current git status to see all changes (staged and unstaged):

git status --porcelain

Also get a detailed diff to understand what changed:

git diff HEAD --stat

For new/untracked files, list them:

git ls-files --others --exclude-standard

Step 3: Semantic Analysis & Grouping

Analyze ALL changes and group them into the SMALLEST logical commits. Use semantic understanding to group related changes together.

Grouping Strategy:

1. Feature boundaries - Related functionality across files goes together
2. Layer separation - Frontend vs backend vs config separated
3. Test pairing - Implementation files + their tests together
4. Config isolation - Config/build changes separate from code
5. Documentation - Docs changes separate unless directly related to code change

Emoji Mapping:

Type	Emoji	When to use
feat	✨	New feature or capability
fix	🐛	Bug fix
docs	📝	Documentation only
style	💄	Formatting, whitespace, no logic change
refactor	♻️	Code restructure without behavior change
test	✅	Adding or updating tests
chore	🔧	Maintenance, deps, tooling
perf	⚡	Performance improvement
ci	👷	CI/CD configuration
build	📦	Build system, packaging

Step 4: Execute Commits

If $ARGUMENTS contains --dry-run:

• Show the proposed commit groups and messages
• Do NOT actually commit
• End workflow here

Execution Strategy: Parallel Analysis → Sequential Commits

Why this approach? Git's staging area (.git/index) is shared. Parallel git add and git commit operations create race conditions where one commit may accidentally include files intended for another. Sequential execution for staging/committing ensures reliable atomic commits.

Where parallelization IS safe:

• Analyzing and grouping changes (reading files, determining groupings)
• Generating commit messages (no git state modification)

Where parallelization is NOT safe:

• Staging files (git add) - modifies shared .git/index
• Creating commits (git commit) - reads from shared staging area

Phase 1: Parallel Analysis (Fast)

For large changesets (10+ changed files), spawn parallel commit-analyzer agents to:

1. Analyze different file groups concurrently
2. Generate commit messages in parallel
3. Determine semantic groupings simultaneously

This can analyze 50+ files in the time it takes to analyze 10 sequentially.

Phase 2: Sequential Execution (Safe)

Execute commits one by one to avoid race conditions:

For EACH logical group (in dependency order):

1. Stage the files for that group:

   git add <file1> <file2> ...
   

2. Verify staging (only expected files staged):

   git diff --cached --name-only
   

3. Commit with the pre-generated message:

   git commit -m "$(cat <<'EOF'
   [emoji] [type](scope): Brief subject line
   
   ## Why (User Story)
   As a [specific role], I want [specific goal] so that [specific benefit].
   
   ## What Changed
   - Specific change 1
   - Specific change 2
   
   ## Acceptance Criteria
   - [ ] Criterion 1
   - [ ] Criterion 2
   
   ## Notes
   Any additional context or technical notes.
   EOF
   )"
   

4. Verify commit before proceeding to next:

   git log -1 --oneline
   

5. Report what was committed

Execution Order

Commits are executed in dependency order:

1. Infrastructure/config changes first
2. Database migrations
3. Backend/API changes
4. Frontend changes
5. Tests
6. Documentation last

This ensures clean git bisect and rollback capability.

Step 5: Push to Remote (Default)

Unless $ARGUMENTS contains --no-push, push all commits to remote:

1. Check if remote exists:

   git remote -v
   

2. Get current branch:

   git branch --show-current
   

3. Push to remote:

   git push origin <current-branch>
   

4. If push fails (e.g., no upstream):

   git push -u origin <current-branch>
   

5. Report push status:

   • ✅ Successfully pushed to origin/<branch>
   • ❌ Push failed: <reason>

If --no-push is specified:

• Skip this step
• Report: "Commits created locally. Use git push to publish."

Step 6: Summary

After all commits (and push if enabled), provide a summary:

• Number of commits created
• List of commit subjects
• Push status (pushed to origin/<branch> or skipped)
• Any files that were skipped and why

Important Rules

• Atomic commits: Each commit should be a single logical change
• Meaningful scopes: Derive scope from directory or feature (e.g., auth, api, ui)
• Real user stories: Write genuine user stories, not generic placeholders
• Specific changes: List actual changes, not "updated files"
• Testable criteria: Acceptance criteria should be verifiable
• No WIP commits: Every commit must be complete and meaningful