Smart Commit - Pro Workflow

Overview

Smart Commit automates quality checks and creates well-crafted conventional commits. It runs lint, typecheck, and tests on affected files, scans for common issues, and drafts meaningful commit messages.

Trigger

Use when:

Saying “commit”, “save changes”, or “ready to commit”
After making changes and ready to persist
Before pushing to remote

/commit
/pro-workflow:commit

Workflow

Check Current State

Identify what files have changed and what to commit

git status
git diff --stat

Run Quality Gates

Lint, typecheck, and test affected files

npm run lint 2>&1 | tail -5
npm run typecheck 2>&1 | tail -5
npm test -- --changed --passWithNoTests 2>&1 | tail -10

Scan Staged Changes

Review code for issues before committing

Draft Commit Message

Generate conventional commit from the diff

Stage and Commit

Stage specific files by name and create the commit

git add <specific files>
git commit -m "<type>(<scope>): <summary>"

Prompt for Learnings

Ask if there are any learnings to capture from this change

Code Review Scan

Before committing, Smart Commit checks staged changes for:

Debug Statements

console.log / console.debug / console.warn
debugger statements
print() / println() in Python/Java
fmt.Println() in Go
dbg!() in Rust

TODO Comments

TODO/FIXME/HACK comments without ticket references
Example: // TODO: fix this ❌
Example: // TODO(#123): fix auth logic ✅

Secrets & Keys

Hardcoded API keys or tokens
Database credentials
Private keys or certificates
AWS/GCP/Azure credentials

Test-Only Code

it.only() / describe.only()
fit() / fdescribe() in Jasmine
test.only() in Jest
Leftover test fixtures in production code

If any issues are found, Smart Commit flags them before proceeding. You must fix or explicitly approve.

Commit Message Format

Smart Commit uses conventional commit format:

<type>(<scope>): <short summary>

<body - what changed and why>

Types

Type	When to Use	Example
`feat`	New feature	`feat(auth): add OAuth2 support`
`fix`	Bug fix	`fix(api): handle null user response`
`refactor`	Code restructuring	`refactor(db): extract query helpers`
`test`	Test changes	`test(auth): add login edge cases`
`docs`	Documentation	`docs(api): update endpoint examples`
`chore`	Maintenance	`chore(deps): upgrade to Next.js 14`
`perf`	Performance	`perf(query): add index on user_id`
`ci`	CI/CD changes	`ci(actions): add deploy workflow`
`style`	Formatting	`style(lint): fix ESLint warnings`

Scope

Optional. Use the affected module or feature area:

(auth), (api), (ui), (db), (payments)
If change affects entire project, omit scope: feat: add health check endpoint

Summary

Under 72 characters
Lowercase, no period at end
Imperative mood: “add” not “added” or “adds”
Focus on what changed, not how

Body

Optional but recommended for non-trivial changes:

Explain why the change was needed
Reference issue numbers: Fixes #123 or Closes #456
Describe trade-offs or alternative approaches considered

feat(auth): add rate limiting to login endpoint

Prevents brute-force attacks by limiting to 5 login attempts
per IP per minute. Uses Redis for distributed rate limiting.

Fixes #234

Guardrails

Never skip quality gates unless user explicitly says to.

Staging Rules

Stage specific files by name. Never git add -A or git add .
Verify each file is intentionally staged
Exclude generated files, lock files, or unrelated changes

Message Rules

Summary under 72 characters
Body explains why, not what
No generic messages: “fix bug”, “update code”, “changes”
Reference issue numbers when applicable

Quality Gates

If quality gates fail:

Show the errors
Ask if you should fix them or commit anyway
Never proceed without acknowledgment

Output

Smart Commit provides:

Quality Gate Results

✓ Lint: passed (0 errors, 2 warnings)
✓ Typecheck: passed
✓ Tests: 15 passed, 0 failed

Issues Found

Issues in staged changes:
⚠️ src/api/auth.ts:42 - console.log left in code
⚠️ src/utils/db.ts:15 - TODO without ticket reference

Suggested Commit Message

Suggested commit:

feat(auth): add OAuth2 provider support

Implements Google and GitHub OAuth2 login flows.
Adds new /auth/oauth/callback endpoint and provider
configuration in environment variables.

Fixes #145

Commit Hash

✓ Committed: a3f5c21 feat(auth): add OAuth2 provider support

Learning Prompt

Any learnings to capture from this change?
(e.g., "Remember to test OAuth flows in incognito mode")

Examples

Example 1: Feature Commit

User: "commit these changes"

Claude:
1. Checking current state...
   Modified: src/api/users.ts, src/types/user.ts, tests/api/users.test.ts

2. Running quality gates...
   ✓ Lint: passed
   ✓ Typecheck: passed
   ✓ Tests: 23 passed

3. Scanning staged changes...
   ✓ No issues found

4. Suggested commit:
   
   feat(api): add user profile update endpoint
   
   Allows users to update their profile information via
   PATCH /api/users/:id. Validates email format and prevents
   username changes.
   
   Fixes #89

5. Staging and committing...
   git add src/api/users.ts src/types/user.ts tests/api/users.test.ts
   git commit -m "feat(api): add user profile update endpoint..."
   
   ✓ Committed: b7d4e92

Any learnings to capture? (e.g., validation patterns, API design decisions)

Example 2: Quality Gate Failure

User: "commit"

Claude:
1. Checking current state...
   Modified: src/components/Button.tsx

2. Running quality gates...
   ✗ Lint: 3 errors
   
   src/components/Button.tsx:12:5
     Missing semicolon
   
   src/components/Button.tsx:18:3
     'className' is defined but never used

   ✓ Typecheck: passed
   ✓ Tests: 5 passed

Lint errors must be fixed before committing. Should I:
1. Fix the lint errors
2. Commit anyway (not recommended)

Example 3: Issues Found

User: "ready to commit"

Claude:
1-2. [Checking state and quality gates...] ✓

3. Scanning staged changes...
   ⚠️ Issues found:
   
   src/api/auth.ts:42
     console.log('user:', user)
     → Debug statement should be removed
   
   src/utils/helpers.ts:15
     // TODO: refactor this
     → TODO without ticket reference

Would you like me to:
1. Remove the console.log and fix the TODO
2. Commit anyway with these issues
3. Skip these files from the commit

Integration with Pro Workflow

Smart Commit works seamlessly with other skills:

Wrap-Up

Wrap-up calls Smart Commit as part of end-of-session ritual

Learn Rule

Capture lessons after committing (e.g., “Always test edge cases”)

Orchestrate

Multi-phase development ends with Smart Commit

Deslop

Run deslop before Smart Commit to clean up AI bloat

Configuration

Custom Quality Gates

Override default quality commands in your CLAUDE.md:

## Quality Gates

Before commits:
- Lint: `npm run lint -- --max-warnings 0`
- Types: `tsc --noEmit`
- Tests: `npm test -- --coverage --changedSince=origin/main`
- Security: `npm audit --audit-level=moderate`

Skip Specific Checks

Temporarily skip checks (not recommended):

# Skip tests (emergency fixes only)
claude --set SKIP_TESTS=true

# Skip lint (never recommended)
claude --set SKIP_LINT=true

Skipping quality gates should be rare. Capture as a learning if you do it.

Best Practices

Commit Often

Small, focused commits are easier to review and revert. Aim for one logical change per commit.

Feature Branches

Always work on feature branches, never directly on main/master.

git checkout -b feat/add-oauth
# make changes
/commit
git push -u origin feat/add-oauth

Atomic Commits

Each commit should be self-contained:

Builds successfully
Tests pass
Can be deployed independently (when possible)

Meaningful Messages

Future you (and teammates) will thank you:

Good: fix(auth): prevent token refresh race condition
Bad: fix bug

Troubleshooting

Quality Gates Take Too Long

# Run only affected tests
npm test -- --changed --onlyChanged

# Or set a timeout
npm test -- --testTimeout=5000

Lint Errors on Generated Code

Exclude generated files in .gitignore and lint config:

// .eslintrc.json
{
  "ignorePatterns": ["dist/", "*.generated.ts", "node_modules/"]
}

Commit Message Too Long

Move details to the body:

feat(api): add webhook retry logic

Implements exponential backoff with jitter for webhook
delivery failures. Retries up to 5 times with delays:
1s, 2s, 4s, 8s, 16s. Marks webhook as failed after
all retries exhausted.

Fixes #234

Next Steps

Learn Wrap-Up Ritual

End sessions properly with learning capture

Try Deslop

Clean up AI-generated code bloat before committing

Master Orchestrate

Build features through structured phases

View All Skills

Explore the complete skill system

Get Started

Core Concepts

Skills

Agents

Commands

Hooks & Events

Configuration

Guides

​Overview

​Trigger

​Workflow

​Code Review Scan

​Commit Message Format

​Types

​Scope

​Summary

​Body

​Guardrails

​Staging Rules

​Message Rules

​Quality Gates

​Output

​Examples

​Example 1: Feature Commit

​Example 2: Quality Gate Failure

​Example 3: Issues Found

​Integration with Pro Workflow

Wrap-Up

Learn Rule

Orchestrate

Deslop

​Configuration

​Custom Quality Gates

​Skip Specific Checks

​Best Practices

​Troubleshooting

​Quality Gates Take Too Long

​Lint Errors on Generated Code

​Commit Message Too Long

​Next Steps

Learn Wrap-Up Ritual

Try Deslop

Master Orchestrate

View All Skills

Build docs developers (and LLMs) love

Overview

Trigger

Workflow

Code Review Scan

Commit Message Format

Types

Scope

Summary

Body

Guardrails

Staging Rules

Message Rules

Quality Gates

Output

Examples

Example 1: Feature Commit

Example 2: Quality Gate Failure

Example 3: Issues Found

Integration with Pro Workflow

Configuration

Custom Quality Gates

Skip Specific Checks

Best Practices

Troubleshooting

Quality Gates Take Too Long

Lint Errors on Generated Code

Commit Message Too Long

Next Steps