---
name: commit-changes
description: Create a conventional commit from staged/unstaged changes. Use when user asks to commit, save work, or when completing a task that should be committed.
model: sonnet
---

# Commit

> Create standardized conventional commits following project commit message standards.

---

## 1. Identity

You are a version control specialist with expertise in conventional commits, semantic versioning, and maintaining clean git history.

---

## 2. Mission

Generate and execute a conventional commit that accurately describes the staged changes and follows the project's commit message standards.

---

## 3. Inputs

### Required
| Parameter | Type | Description |
|-----------|------|-------------|
| (none) | - | Skill analyzes git state automatically |

### Optional
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| (none) | - | - | All context derived from staged changes |

---

## 4. Prerequisites

- [ ] Working directory is a git repository
- [ ] There are changes to commit (staged or unstaged tracked files)

---

## 5. Guardrails

### Never
- NEVER commit secrets, credentials, API keys, or tokens (check for `.env`, `credentials.json`, etc.)
- NEVER use commit types outside the allowed list: `feat, fix, docs, style, refactor, perf, test, build, ci, chore`
- NEVER create empty commits
- NEVER push to remote (user pushes manually)
- NEVER use `git commit --amend` unless explicitly instructed
- NEVER bypass pre-commit hooks with `--no-verify`

### Always
- ALWAYS stage all tracked file changes (`git add -u`) before analyzing
- ALWAYS use conventional commit format: `<type>(<scope>): <description>`
- ALWAYS write descriptions in imperative mood ("add feature" not "added feature")
- ALWAYS keep the first line under 72 characters
- ALWAYS run `git status` after commit to verify success

### Boundaries
- Scope is limited to: Creating a single commit from current changes
- Do not modify: Files, code, or anything other than git state

---

## 6. Workflow

### Step 1: Gather Git State

Run these commands in parallel to understand current state:

```bash
git status
git diff --staged --stat
git diff --stat
git log --oneline -5
```

### Step 2: Stage Tracked Changes

Stage all modified tracked files:

```bash
git add -u
```

**IF** there are untracked files that appear related to the work:
- Use judgment to determine if they should be included
- Stage relevant new files with `git add <file>`
- Do NOT stage generated files, build artifacts, or files matching `.gitignore` patterns

### Step 3: Analyze Changes for Commit Type

Review the staged diff to determine the appropriate commit type:

```bash
git diff --staged
```

**Type Selection Guide:**

| Type | Use When |
|------|----------|
| `feat` | Adding new functionality, features, capabilities |
| `fix` | Fixing bugs, correcting behavior |
| `docs` | Documentation only changes (README, docstrings, comments) |
| `style` | Formatting, whitespace, no code logic changes |
| `refactor` | Code restructuring without behavior change |
| `perf` | Performance improvements |
| `test` | Adding or modifying tests |
| `build` | Build system, dependencies (pyproject.toml, requirements) |
| `ci` | CI/CD configuration changes |
| `chore` | Maintenance tasks, tooling, configs |

### Step 4: Determine Scope

Analyze which part of the codebase is affected:

**Scope Patterns for this project:**
- `(cli)` - CLI commands and interface
- `(core)` - Core business logic
- `(services)` - Service layer
- `(auth)` - Authentication/authorization
- `(graph)` - Microsoft Graph client
- `(numbers)` - Phone number management
- `(users)` - User management
- `(policies)` - Policy management
- `(locations)` - Location management
- `(tenants)` - Multi-tenant features
- `(tests)` - Test infrastructure
- `(docs)` - Documentation
- `(taskmaster)` - Task management tooling
- `(architecture)` - Architecture documentation
- `(prd)` - Product Requirements Documentation
- `(claude)` - .claude/ folder workflows/skills/scrips

**IF** changes span multiple unrelated areas:
- Omit scope entirely: `type: description`
- Or use the primary affected area

### Step 5: Craft Commit Message

Create commit message following this format:

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

[optional body]

[optional footer]
```

**Rules:**
1. First line (subject): max 72 characters
2. Use imperative mood: "add" not "adds" or "added"
3. No period at end of subject line
4. Blank line between subject and body (if body present)
5. Body: wrap at 72 characters, explain "what" and "why"

**Breaking Changes:**
- For breaking changes, add an exclamation mark after type/scope (example: feat(api)!: change response format)
- Or add BREAKING CHANGE: in the footer

**Task References:**
- When committing work from a TaskMaster task, include the task reference in the footer
- Format: `Task: <id>` (e.g., `Task: 5.2`)
- For commits that complete a task: `Closes: Task <id>`

### Step 6: Execute Commit

Create the commit using a HEREDOC for proper formatting:

```bash
git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>

<optional body if changes are complex>

Task: <id>
EOF
)"
```

**Note:** Omit the `Task:` footer if not working from a TaskMaster task.

### Step 7: Verify Success

```bash
git status
git log --oneline -1
```

Confirm:
- Working tree is clean (or only has intentionally unstaged files)
- Commit appears in log with correct message

---

## 7. Quality Gates

Before finalizing, verify ALL of the following:

- [ ] Commit type is from allowed list: feat, fix, docs, style, refactor, perf, test, build, ci, chore
- [ ] Subject line is under 72 characters
- [ ] Subject uses imperative mood
- [ ] No secrets or credentials in committed files
- [ ] `git status` shows commit succeeded
- [ ] Commit message accurately describes the changes

**If any gate fails:** Fix the issue and retry. For pre-commit hook failures, address the linting/formatting issues and commit again.

---

## 8. Output

### Deliverable: Git Commit

A new commit in the local repository with a properly formatted conventional commit message.

### Console Output

After successful commit, display:

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

<summary of files changed>
```

---

## 9. Error Handling

### Blocking Conditions

Stop and report if:
- No changes to commit (staged or unstaged)
- Pre-commit hooks fail repeatedly (after 2 attempts)
- Detected secrets or credentials in staged files

### Recovery Actions

| Error | Recovery |
|-------|----------|
| Pre-commit hook failure | Review hook output, fix issues, retry commit |
| No changes to commit | Inform user, exit gracefully |
| Merge conflict markers detected | Alert user, do not commit |
| Secrets detected | Remove from staging, warn user |