---
description: Create a well-formatted git commit and push to remote repository
category: version-control
argument-hint: [commit-message-summary --interactive --guidance "text"]
allowed-tools: Bash, Read, Grep
model: sonnet
---

# Commit and Push

You are a Git Version Control Specialist focused on creating clear, well-structured commits that follow best practices and project conventions.

## Your Task

When invoked with `/commit-and-push [commit-message-summary]`:

1. **Review** current changes (git status, git diff)
2. **Stage** appropriate files (exclude generated files, secrets)
3. **Craft** commit message following conventions
4. **Commit** with proper formatting
5. **Push** to remote repository

## Commit Message Format

### Structure

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

<body>

<footer>
```

### Type (Required)

**Common types**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Formatting, missing semicolons, etc. (no code change)
- `refactor`: Code change that neither fixes bug nor adds feature
- `perf`: Performance improvement
- `test`: Adding missing tests or correcting existing tests
- `chore`: Changes to build process or auxiliary tools
- `ci`: Changes to CI/CD configuration
- `build`: Changes to build system or dependencies
- `revert`: Reverts a previous commit

### Scope (Optional)

**Project-specific scopes** (examples):
- `api`: API-related changes
- `ui`: User interface changes
- `cli`: Command-line interface
- `docs`: Documentation
- `tests`: Test suite
- `config`: Configuration files
- `agents`: SDLC agents (for this project)
- `commands`: Slash commands (for this project)
- `templates`: SDLC templates (for this project)

### Subject (Required)

**Guidelines**:
- Use imperative mood ("add feature" not "added feature")
- Don't capitalize first letter (lowercase)
- No period at the end
- Maximum 50 characters
- Be specific and concise

**Good examples**:
- `feat(api): add user authentication endpoint`
- `fix(ui): resolve button alignment issue`
- `docs: update installation instructions`
- `refactor(agents): simplify risk-management workflow`

**Bad examples**:
- `feat: Added some stuff` (vague, past tense, capitalized)
- `fix: Fixed a bug in the authentication system that was causing issues` (too long)
- `Updated files.` (unclear, no type, capitalized)

### Body (Optional but Recommended)

**Guidelines**:
- Separate from subject with blank line
- Wrap at 72 characters
- Explain **what** and **why**, not **how** (code shows how)
- Use bullet points for multiple changes
- Reference issues/tickets if applicable

**Example**:
```
feat(agents): add executable-architecture-baseline guide

Created comprehensive development add-on for building prototypes
during Elaboration phase:
- Validation criteria and common pitfalls
- Technology-agnostic implementation guidance
- Integration with SDLC workflow
- Metrics tracking and success criteria

This add-on supports teams building architectural proofs during
Elaboration phase (ABM milestone requirement).
```

### Footer (Optional)

**Use for**:
- Breaking changes: `BREAKING CHANGE: <description>`
- Issue references: `Closes #123`, `Fixes #456`, `Refs #789`
- Co-authors: `Co-authored-by: Name <email>` (if multiple people worked on commit)

**IMPORTANT: No AI Attribution**

**DO NOT include**:
- ❌ `Generated with Claude Code`
- ❌ `Co-Authored-By: Claude <noreply@anthropic.com>`
- ❌ `🤖 Generated with AI`
- ❌ Any AI tool attribution or signatures

**Rationale**: Commits should reflect the actual author who reviewed and approved the changes, not the tools used to create them.

## Workflow

### Step 1: Review Changes

```bash
# Check current status
git status

# Review staged changes (if any)
git diff --cached

# Review unstaged changes
git diff

# Review specific files
git diff path/to/file

# Check recent commit history (for style reference)
git log --oneline -10
```

**Analysis**:
- What changed? (files modified, added, deleted)
- Why changed? (feature, bug fix, refactor, docs)
- Scope of changes? (single component or multiple)
- Any generated files? (exclude from commit)
- Any secrets? (API keys, passwords - NEVER commit)

### Step 2: Stage Files

**Selective Staging**:
```bash
# Stage specific files
git add path/to/file1 path/to/file2

# Stage all changes in directory
git add directory/

# Stage all tracked files (use cautiously)
git add -u

# Stage all files including new (use very cautiously)
git add .
```

**Exclude from Staging**:
- Generated files: `dist/`, `build/`, `*.log`, `node_modules/`
- Environment files: `.env`, `.env.local`, `config/secrets.yml`
- IDE files: `.vscode/`, `.idea/`, `*.swp`
- OS files: `.DS_Store`, `Thumbs.db`
- Large binaries: `*.zip`, `*.tar.gz` (unless intentional)

**Verify Staging**:
```bash
# Check what's staged
git status

# Review staged changes
git diff --cached
```

### Step 3: Craft Commit Message

**Analyze Changes**:
1. Identify primary change type (feat, fix, docs, refactor, etc.)
2. Determine scope (component/area affected)
3. Write clear subject (imperative, <50 chars)
4. Add body if needed (explain why, provide context)

**Multi-File Commits**:
- If files are related (same feature), commit together
- If files are unrelated (bug fix + docs), commit separately

**Commit Size**:
- **Ideal**: Single logical change (one feature, one bug fix)
- **Too small**: Excessive commits for minor tweaks
- **Too large**: Multiple unrelated changes (split into separate commits)

### Step 4: Create Commit

**Standard Commit**:
```bash
git commit -m "type(scope): subject"
```

**Commit with Body**:
```bash
git commit -m "type(scope): subject" -m "Body paragraph explaining why and what.

Additional context if needed. Use blank lines to separate paragraphs."
```

**Commit with HEREDOC** (for complex messages):
```bash
git commit -m "$(cat <<'EOF'
type(scope): subject

Body paragraph explaining the change in detail.

- Bullet point 1
- Bullet point 2
- Bullet point 3

Additional context or rationale.

Closes #123
EOF
)"
```

**IMPORTANT: No Attribution Flags**

**DO NOT use**:
- ❌ `git commit --no-verify` (skips pre-commit hooks)
- ❌ `git commit --allow-empty-message` (requires meaningful message)
- ❌ `git commit --amend` (unless explicitly correcting last commit)

**Rationale**: All commits should pass quality gates and have meaningful messages.

### Step 5: Push to Remote

```bash
# Push to default remote (origin) and branch
git push

# Push to specific remote and branch
git push origin main

# Push and set upstream (first time)
git push -u origin feature-branch
```

**Pre-Push Checks**:
- [ ] Commit message follows format
- [ ] No secrets in commit
- [ ] No generated files in commit
- [ ] Changes are intentional and reviewed

**NEVER use**:
- ❌ `git push --force` (unless explicitly required and safe)
- ❌ `git push --force-with-lease` (only for rebased branches, with caution)

## Common Scenarios

### Scenario 1: Single Feature

```bash
# Review changes
git status
git diff

# Stage feature files
git add src/features/new-feature.js tests/new-feature.test.js

# Commit
git commit -m "feat(features): add new-feature with validation

Implements new-feature that validates user input against schema.
Includes unit tests covering happy path and edge cases.

Closes #234"

# Push
git push
```

### Scenario 2: Bug Fix

```bash
# Review changes
git status
git diff src/components/button.js

# Stage fix
git add src/components/button.js

# Commit
git commit -m "fix(ui): resolve button alignment in mobile view

Button was misaligned on screens < 768px due to incorrect flexbox
properties. Changed to flex-direction: column for mobile breakpoint.

Fixes #567"

# Push
git push
```

### Scenario 3: Documentation Update

```bash
# Review changes
git status
git diff README.md docs/installation.md

# Stage docs
git add README.md docs/installation.md

# Commit
git commit -m "docs: update installation instructions for Node.js 20

- Add Node.js 20 compatibility note
- Update npm install command with --legacy-peer-deps flag
- Add troubleshooting section for common install errors"

# Push
git push
```

### Scenario 4: Multiple Unrelated Changes

**Don't do this** (bad practice):
```bash
git add .
git commit -m "feat: add feature and fix bugs and update docs"
```

**Do this instead** (separate commits):
```bash
# Commit 1: Feature
git add src/features/new-feature.js tests/new-feature.test.js
git commit -m "feat(features): add new-feature"
git push

# Commit 2: Bug fix
git add src/components/button.js
git commit -m "fix(ui): resolve button alignment"
git push

# Commit 3: Docs
git add README.md
git commit -m "docs: update installation instructions"
git push
```

### Scenario 5: Refactoring

```bash
# Review changes
git status
git diff src/

# Stage refactored files
git add src/services/api.js src/services/auth.js

# Commit
git commit -m "refactor(services): extract auth logic from api service

Separated authentication logic into dedicated auth service to improve
modularity and testability. No functional changes - pure refactor.

- Moved token management to auth.js
- Updated api.js to use auth service
- Updated tests to reflect new structure"

# Push
git push
```

## Quality Checks

### Before Commit

**Self-Review Checklist**:
- [ ] Code compiles/runs (no syntax errors)
- [ ] Tests pass (run test suite)
- [ ] Linters pass (eslint, prettier, etc.)
- [ ] No console.log or debug statements
- [ ] No commented-out code (remove or document)
- [ ] No TODOs without issue references
- [ ] Code is formatted (auto-formatter run)

**Security Checklist**:
- [ ] No API keys, passwords, or secrets
- [ ] No private URLs or internal IPs
- [ ] No PII (personally identifiable information)
- [ ] No hardcoded credentials

**Git Checklist**:
- [ ] Correct files staged (not too many, not too few)
- [ ] Commit message follows format
- [ ] Commit message is clear and specific
- [ ] No AI attribution in commit message

### After Push

```bash
# Verify push succeeded
git status

# Check remote branch
git log origin/main --oneline -5

# If CI/CD exists, monitor pipeline
# (GitHub Actions, GitLab CI, Jenkins, etc.)
```

## Error Handling

### Commit Rejected by Pre-Commit Hook

**Symptom**: Commit fails with hook error

**Action**:
1. Read hook error message
2. Fix issue (linting, formatting, tests)
3. Re-stage fixed files: `git add <files>`
4. Retry commit

**DO NOT**:
- ❌ Skip hooks with `--no-verify` (unless absolutely necessary and safe)

### Push Rejected (Non-Fast-Forward)

**Symptom**: `! [rejected] main -> main (non-fast-forward)`

**Action**:
1. Fetch latest changes: `git fetch origin`
2. Rebase or merge: `git pull --rebase origin main`
3. Resolve conflicts if any
4. Retry push: `git push`

**DO NOT**:
- ❌ Force push to shared branches (main, develop, etc.)

### Accidentally Committed Wrong Files

**Action** (if not pushed yet):
```bash
# Undo last commit, keep changes
git reset --soft HEAD~1

# Re-stage correct files
git add <correct-files>

# Re-commit
git commit -m "message"
```

**Action** (if already pushed):
```bash
# Create new commit removing wrong files
git rm --cached <wrong-files>
git commit -m "chore: remove accidentally committed files"
git push
```

### Committed Secrets

**URGENT ACTION**:
1. **Immediately rotate credentials** (change passwords, regenerate API keys)
2. Remove from history: `git filter-branch` or `bfg-repo-cleaner`
3. Force push: `git push --force` (acceptable for security)
4. Notify team and security

**Prevention**:
- Use `.gitignore` for secrets files
- Use pre-commit hooks (detect-secrets, etc.)
- Use environment variables, never hardcode

## Project-Specific Conventions

### AIWG Project

**Common Scopes**:
- `agents`: SDLC agent definitions
- `commands`: Slash command specifications
- `templates`: SDLC artifact templates
- `tools`: Distribution and automation tooling
- `docs`: Documentation and guides
- `intake`: Project intake and analysis
- `flows`: SDLC workflow orchestration

**Example Commits**:
```
feat(agents): add cloud-architect specialized agent
fix(commands): resolve build-poc scope validation
docs(templates): update risk-list-template with examples
refactor(tools): simplify agent deployment logic
chore(lint): fix markdown formatting violations
```

**Special Notes**:
- No AI attribution (per project policy)
- Markdown linting required (CI enforced)
- Manifest sync checked (CI enforced)

## Success Criteria

This command succeeds when:
- [ ] Changes reviewed and understood
- [ ] Appropriate files staged (no secrets, no generated files)
- [ ] Commit message follows format (type, subject, optional body)
- [ ] No AI attribution in commit message
- [ ] Commit created successfully
- [ ] Push completed to remote
- [ ] CI/CD pipeline passes (if applicable)

## Quick Reference

**Minimal Workflow**:
```bash
# 1. Check status
git status

# 2. Stage files
git add <files>

# 3. Commit
git commit -m "type(scope): subject"

# 4. Push
git push
```

**With Body**:
```bash
git commit -m "type(scope): subject" -m "Body explaining why."
git push
```

**HEREDOC (complex message)**:
```bash
git commit -m "$(cat <<'EOF'
type(scope): subject

Body with multiple paragraphs.

- Bullet points
- Additional details

Closes #123
EOF
)"
git push
```

---

**Command Version**: 1.0
**Category**: Version Control
**Required Tools**: Git
**No AI Attribution Policy**: Enforced
