Commit Push

• Before any git action, determine whether the current workspace is a single Git repository or a workspace containing multiple independent Git repositories
• If the current workspace matches this multi-repo layout, do not run one combined root-level git workflow:
  • openspec: /Users/d0ublecl1ck/evaluation/openspec
  • evaluation_admin: /Users/d0ublecl1ck/evaluation/evaluation_admin
  • evaluation_server: /Users/d0ublecl1ck/evaluation/evaluation_server
• In that multi-repo layout, run the full Commit&Push workflow separately for each repository
• Treat each repository as an independent unit for pre-checks, staging, commit, hook handling, pull/rebase, push, and failure handling
• Summarize status and outcome per repository

1. Pre-commit checks (must run in parallel)

• Run in parallel: git status, git diff, git log --oneline -5
• Summarize results before proceeding
• If git status --short --branch shows both ahead and behind (e.g., master...origin/master [ahead 1, behind 1]), git diff is empty, git log --oneline -5 is non-empty (not first commit), and git status reports nothing to commit, working tree clean, treat this as a sync-only state
• In sync-only state, run git pull --rebase first, then git push; do not create a new commit

2. First commit special rule

• If git log --oneline -5 is empty or reports no commits (e.g., fatal: your current branch ... does not have any commits yet), treat this as the first commit
• For the first commit, do not ask the user for requirements; inspect current changes and project context and create the initial commit

3. Commit all files without confirmation

• Never ask the user which files to commit
• Always commit all changes, including untracked files (git add -A)
• Before the final staging pass, inspect untracked files and local junk files that should not be versioned, such as __pycache__/, *.pyc, .DS_Store, editor swap files, temporary logs, coverage output, local virtual environments, or build caches
• If such local-only files are present and are not already ignored, add the narrowest appropriate ignore pattern to the repository ignore file before staging
• Prefer updating an existing repo-local ignore file such as .gitignore; use .git/info/exclude only when the ignore rule is intentionally machine-local and should not be committed
• After adding the ignore rule, remove those files from the index if needed, keep them untracked locally, and commit the ignore-rule change as part of the same repository commit
• Do not auto-ignore source files, project assets, fixtures, migrations, lockfiles, or any file whose ownership is ambiguous; when in doubt, stop and ask the user
• Do not create empty commits
• Never commit .env, credentials, secrets, node_modules/, __pycache__/, .venv/, or large binary files without explicit approval

4. Draft the commit message before commit

• Use Conventional Commits format: type(scope): subject
• Scope is required and must be kebab-case
• Subject must use present-tense imperative wording, state what changed, avoid vague phrasing, and end without a period
• Keep the subject concise and preferably within 50 characters after the colon
• Use a HEREDOC for every commit message, including simple commits
• Add a body for non-trivial changes to explain how and why
• Use git trailers when they materially help, such as Fixes #N, Closes #N, or Co-authored-by: Name <email>
• For breaking changes, use type(scope)!: subject or add a BREAKING CHANGE: footer
• Never include signature lines such as Generated with ... or Co-Authored-By: Claude ...

5. Commit

• Draft the message yourself from the diff, not from filenames alone
• Use one focused commit per repository for the current batch of changes
• If the commit includes newly added ignore rules for local-only junk, mention that cleanup intent in the body when it materially affects what was staged
• If commit fails due to large files or policy limits, stop and ask the user for instructions before proceeding

6. Handle pre-commit changes

• If pre-commit hooks modify files, stage the modified files and create a replacement commit that includes those changes
• Reuse the same commit intent while updating the body if the hook materially changed behavior

7. Auto push after successful commit

• Automatically push to the tracked remote branch after a successful commit
• If no upstream is configured, push with -u origin <current-branch>
• If the remote branch is ahead of local, prefer git pull --rebase before retrying push
• If push fails, treat it as an exceptional condition and ask the user for instructions

Commit message conventions

Types

Scope

• Always include a scope in parentheses
• Use concise kebab-case nouns such as auth, api, config, tests, validation, or cookie-service

Subject

• Use imperative verbs such as add, fix, refactor, remove, improve, prevent, or implement
• Describe the concrete change, not a generic intention
• Do not use vague subjects like update code, fix bug, make changes, or add stuff

Body

• Leave one blank line after the subject
• Explain how the change works and why it was made
• Use short bullet points when multiple details need to be grouped
• Wrap lines reasonably, around 72 characters when practical
• Add task, requirement, or review-comment references only when they add useful traceability

Examples

Good:

feat(validation): add URLValidator with domain whitelist
fix(auth): use hmac.compare_digest for key comparison
refactor(template): consolidate filename sanitization
test(security): add path traversal prevention tests

Bad:

update validation code