gh-linus-mcmanamey-unify-2-1-plugin/commands/local-commit.md

allowed-tools: Bash(git add:), Bash(git status:), Bash(git commit:), Bash(git diff:), Bash(git log:), Bash(git push:), Bash(git pull:), Bash(git branch:), mcp__ado__repo_list_branches_by_repo, mcp__ado__repo_search_commits, mcp__ado__repo_create_pull_request, mcp__ado__repo_get_pull_request_by_id, mcp__ado__repo_get_repo_by_name_or_id, mcp__ado__wit_add_work_item_comment, mcp__ado__wit_get_work_item argument-hint: [message] | --no-verify | --amend | --pr-s | --pr-d | --pr-m description: Create well-formatted commits with conventional commit format and emoji, integrated with Azure DevOps

Smart Git Commit with Azure DevOps Integration

Create well-formatted commit: $ARGUMENTS

Repository Configuration

• Project: Program Unify
• Repository ID: e030ea00-2f85-4b19-88c3-05a864d7298d
• Repository Name: unify_2_1_dm_synapse_env_d10
• Branch Structure: feature/* → staging → develop → main
• Main Branch: main

Implementation Logic for Claude

When processing this command, Claude should:

1. Detect Repository: Check if current repo is unify_2_1_dm_synapse_env_d10

   • Use git remote -v or check current directory path
   • Can also use mcp__ado__repo_get_repo_by_name_or_id to verify

2. Parse Arguments: Extract flags from $ARGUMENTS

   • PR Flags:
     • --pr-s: Set target = staging
     • --pr-d: Set target = develop
     • --pr-m: Set target = main
     • --pr (no suffix): ERROR if unify_2_1_dm_synapse_env_d10, else target = develop

3. Validate Current Branch (if PR flag provided):

   • Get current branch: git branch --show-current
   • For --pr-s: Require feature/* branch (reject staging, develop, main)
   • For --pr-d: Require staging branch exactly
   • For --pr-m: Require develop branch exactly
   • If validation fails: Show clear error and exit

4. Execute Commit Workflow:

   • Stage changes (git add . )
   • Create commit with emoji conventional format
   • Run pre-commit hooks (unless --no-verify)
   • Push to current branch

5. Create Pull Request (if PR flag):

   • Call mcp__ado__repo_create_pull_request with:
     • repository_id: e030ea00-2f85-4b19-88c3-05a864d7298d
     • source_branch: Current branch from step 3
     • target_branch: Target from step 2
     • title: Extract from commit message
     • description: Generate with summary and test plan
   • Return PR URL to user

6. Add Work Item Comments Automatically (if PR was created in step 5):

   • Condition Check: Only execute if:
     • A PR was created in step 5 (any --pr-* flag was used)
     • PR creation was successful and returned a PR ID
   • Get Work Items from PR:
     • Use mcp__ado__repo_get_pull_request_by_id with:
       • repositoryId: e030ea00-2f85-4b19-88c3-05a864d7298d
       • pullRequestId: PR ID from step 5
       • includeWorkItemRefs: true
     • Extract work item IDs from the PR response
     • If no work items found, log info message and skip to next step
   • Add Comments to Each Work Item:
     • For each work item ID extracted from PR:
       • Use mcp__ado__wit_get_work_item to verify work item exists
       • Generate comment with:
         • PR title and number
         • Commit message and SHA
         • File changes summary from git diff --stat
         • Link to PR in Azure DevOps
         • Link to commit in Azure DevOps
         • IMPORTANT: Do NOT include any footer text like "Automatically added by /local-commit command" or similar attribution
       • Call mcp__ado__wit_add_work_item_comment with:
         • project: "Program Unify"
         • workItemId: Current work item ID
         • comment: Generated comment with HTML formatting
         • format: "html"
     • Log success/failure for each work item
     • If ANY work item fails, warn but don't fail the commit

Current Repository State

• Git status: !git status --short
• Current branch: !git branch --show-current
• Staged changes: !git diff --cached --stat
• Unstaged changes: !git diff --stat
• Recent commits: !git log --oneline -5

What This Command Does

1. Analyzes current git status and changes
2. If no files staged, stages all modified files with git add
3. Reviews changes with git diff
4. Analyzes for multiple logical changes
5. For complex changes, suggests split commits
6. Creates commit with emoji conventional format
7. Automatically runs pre-commit hooks (ruff lint/format, trailing whitespace, etc.)
   • Pre-commit may modify files (auto-fixes)
   • If files are modified, they'll be re-staged automatically
   • Use --no-verify to skip hooks in emergencies only
8. NEW: With PR flags, creates Azure DevOps pull request after push
   • Uses mcp__ado__repo_create_pull_request to create PR
   • Automatically links work items if commit message contains work item IDs
   • IMPORTANT Branch Flow Rules (unify_2_1_dm_synapse_env_d10 ONLY):
     • --pr-s: Feature branch → staging (standard feature PR)
     • --pr-d: staging → develop (promote staging to develop)
     • --pr-m: develop → main (promote develop to production)
     • --pr: NOT ALLOWED - must specify -s, -d, or -m for this repository
   • For OTHER repositories: --pr creates PR to develop branch (legacy behavior)
9. NEW: Automatically adds comments to linked work items after PR creation
   • Retrieves work items linked to the PR using mcp__ado__repo_get_pull_request_by_id
   • Automatically adds comment to each linked work item with:
     • PR title and number
     • Commit message and SHA
     • Summary of file changes
     • Direct link to PR in Azure DevOps
     • Direct link to commit in Azure DevOps
     • IMPORTANT: No footer attribution text (e.g., "Automatically added by /local-commit command")
   • Validates work items exist before commenting
   • Continues even if some work items fail (warns only)

Commit Message Format

Type + Emoji Mapping

• ✨ feat: New feature
• 🐛 fix: Bug fix
• 📝 docs: Documentation
• 💄 style: Formatting/style
• ♻️ refactor: Code refactoring
• ⚡️ perf: Performance improvements
• ✅ test: Tests
• 🔧 chore: Tooling, configuration
• 🚀 ci: CI/CD improvements
• ⏪️ revert: Reverting changes
• 🚨 fix: Compiler/linter warnings
• 🔒️ fix: Security issues
• 🩹 fix: Simple non-critical fix
• 🚑️ fix: Critical hotfix
• 🎨 style: Code structure/format
• 🔥 fix: Remove code/files
• 📦️ chore: Dependencies
• 🌱 chore: Seed files
• 🧑‍💻 chore: Developer experience
• 🏷️ feat: Types
• 💬 feat: Text/literals
• 🌐 feat: i18n/l10n
• 💡 feat: Business logic
• 📱 feat: Responsive design
• 🚸 feat: UX improvements
• ♿️ feat: Accessibility
• 🗃️ db: Database changes
• 🚩 feat: Feature flags
• ⚰️ refactor: Remove dead code
• 🦺 feat: Validation

Commit Strategy

Single Commit (Default)

git add .
git commit -m "✨ feat: implement user auth"

Multiple Commits (Complex Changes)

# Stage and commit separately
git add src/auth.py
git commit -m "✨ feat: add authentication module"

git add tests/test_auth.py
git commit -m "✅ test: add auth unit tests"

git add docs/auth.md
git commit -m "📝 docs: document auth API"

# Push all commits
git push

Pre-Commit Hooks

Your project uses pre-commit with:

• Ruff: Linting with auto-fix + formatting
• Standard hooks: Trailing whitespace, AST check, YAML/JSON/TOML validation
• Security: Private key detection
• Quality: Debug statement detection, merge conflict check

Important: Pre-commit hooks will auto-fix issues and may modify your files. The commit process will:

1. Run pre-commit hooks
2. If hooks modify files, automatically re-stage them
3. Complete the commit with all fixes applied

Command Options

• --no-verify: Skip pre-commit checks (emergency use only)
• --amend: Amend previous commit
• --pr-s: Create PR to staging branch (feature → staging)
• --pr-d: Create PR to develop branch (staging → develop)
• --pr-m: Create PR to main branch (develop → main)
• --pr: Legacy flag for other repositories (creates PR to develop)
  • NOT ALLOWED in unify_2_1_dm_synapse_env_d10 - must use -s, -d, or -m
• Default: Run all pre-commit hooks and create new commit
• Automatic Work Item Comments: When using any PR flag, work items linked to the PR will automatically receive comments with commit details (no footer attribution)

Azure DevOps Integration Features

Pull Request Workflow (PR Flags)

When using PR flags, the command will:

1. Commit changes locally
2. Push to remote branch
3. Validate repository and branch configuration:
   • THIS repo (unify_2_1_dm_synapse_env_d10): Requires explicit flag (--pr-s, --pr-d, or --pr-m)
     • --pr-s: Current feature branch → staging
     • --pr-d: Must be on staging branch → develop
     • --pr-m: Must be on develop branch → main
     • --pr alone: ERROR - must specify target
   • OTHER repos: --pr creates PR to develop (all other flags ignored)
4. Use mcp__ado__repo_create_pull_request to create PR with:
   • Title: Extracted from commit message
   • Description: Full commit details with summary and test plan
   • Source Branch: Current branch
   • Target Branch: Determined by flag and repository
   • Work Items: Auto-linked from commit message (e.g., "fixes #12345")

Viewing Commit History

You can view commit history using:

• mcp__ado__repo_search_commits - Search commits by branch, author, date range
• Traditional git log - For local history

Branch Management

• mcp__ado__repo_list_branches_by_repo - View all Azure DevOps branches
• git branch - View local branches

Branch Validation Rules (unify_2_1_dm_synapse_env_d10)

Before creating a PR, the command validates:

--pr-s (Feature → Staging)

• ✅ ALLOWED: Any feature/* branch
• ❌ BLOCKED: staging, develop, main branches
• Target: staging

--pr-d (Staging → Develop)

• ✅ ALLOWED: Only staging branch
• ❌ BLOCKED: All other branches (including feature/*)
• Target: develop

--pr-m (Develop → Main)

• ✅ ALLOWED: Only develop branch
• ❌ BLOCKED: All other branches (including staging, feature/*)
• Target: main

--pr (Legacy - NOT ALLOWED)

• ❌ BLOCKED: All branches in unify_2_1_dm_synapse_env_d10
• 💡 Error Message: "Must use --pr-s, --pr-d, or --pr-m for this repository"
• ✅ ALLOWED: All other repositories (targets develop)

Best Practices

1. Let pre-commit work - Don't use --no-verify unless absolutely necessary
2. Atomic commits - One logical change per commit
3. Descriptive messages - Emoji + type + clear description
4. Review before commit - Always check git diff
5. Clean history - Split complex changes into multiple commits
6. Trust the hooks - They maintain code quality automatically
7. Use correct PR flag - --pr-s for features, --pr-d for staging promotion, --pr-m for production
8. Link work items - Reference Azure DevOps work items in commit messages (e.g., "#43815") to enable automatic PR linking
9. Validate branch - Ensure you're on the correct branch before using --pr-d or --pr-m
10. Work item linking - Work items linked to PRs will automatically receive comments with commit details
11. Keep stakeholders informed - Use PR flags to ensure work items are automatically updated with progress

Example Workflows

Simple Commit

/commit "fix: resolve enum import error"

Commit with Work Item

/commit "feat: add enum imports for Synapse environment"

Commit and Create PR (Feature to Staging)

/commit --pr-s "feat: refactor commit command with ADO MCP integration"

This will:

1. Create commit locally
2. Push to current branch
3. Create PR: feature/xyz → staging
4. Link work items automatically if mentioned in commit message

Promote Staging to Develop

# First checkout staging branch
git checkout staging
git pull origin staging

# Then commit and create PR
/commit --pr-d "release: promote staging changes to develop"

This will:

1. Create commit on staging branch
2. Push to staging
3. Create PR: staging → develop

Promote Develop to Main (Production)

# First checkout develop branch
git checkout develop
git pull origin develop

# Then commit and create PR
/commit --pr-m "release: promote develop to production"

This will:

1. Create commit on develop branch
2. Push to develop
3. Create PR: develop → main

Error: Using --pr without suffix

/commit --pr "feat: some feature"

Result: ERROR - unify_2_1_dm_synapse_env_d10 requires explicit PR target (--pr-s, --pr-d, or --pr-m)

Feature PR with Automatic Work Item Comments

# On feature/xyz branch
/commit --pr-s "feat(user-auth): implement OAuth2 authentication #12345"

This will:

1. Create commit on feature branch
2. Push to feature branch
3. Create PR: feature/xyz → staging
4. Link work item #12345 to the PR
5. Automatically add comment to work item #12345 with:
   • PR title and number
   • Commit message and SHA
   • File changes summary
   • Link to PR in Azure DevOps
   • Link to commit in Azure DevOps
   • (No footer attribution text)

Staging to Develop PR with Multiple Work Items

# On staging branch
/commit --pr-d "release: promote staging to develop - fixes #12345, #67890"

This will:

1. Create commit on staging branch
2. Push to staging
3. Create PR: staging → develop
4. Link work items #12345 and #67890 to the PR
5. Automatically add comments to both work items with PR and commit details (without footer attribution)

Note: Work items are automatically detected from commit message and linked to PR. Comments are added automatically to all linked work items without any footer text.