01 Commit

Commit

Generates atomic git commits with conventional messages, supporting interactive splits and agent-driven auto mode.

Available actions

Default flow

Single action skill. The router dispatches to commit whenever a commit phrase or slash command appears.

Inline arguments

When invoked as a slash command, the trailing argument controls the push behavior:

• /commit → commits only, stays local (push: false)
• /commit push → commits then pushes the branch (push: true)

Transversal rules

• Commits stay atomic and focused on a single concern.
• Messages use imperative mood ("Add feature" not "Added feature").
• Explain "why" not "what" in the body.
• Never --force push. --force-with-lease is acceptable when explicitly required.
• Follow the conventional commit format defined in @assets/commit-template.md.
• Reference issues in the commit body when applicable.
• auto mode never asks for confirmation. interactive mode requires user approval before staging and before committing splits.

References

• None.

Assets

• @assets/commit-template.md: Conventional commit format reference.

External data

• None.

01 - Commit

Stage files, generate or accept a commit message, run the commit, optionally push, and return the resulting sha.

Inputs

mode: interactive | auto       # default: interactive
message: <imposed commit message>   # optional; when set, used as-is, no generation
push: true | false             # default: false
files: [<paths>]               # optional; restrict staging to these paths

When invoked via slash command, parse $ARGUMENTS:

• contains the word push → set push: true
• empty or anything else → leave push: false

Outputs

commit_sha: <full sha>
branch: <branch name>
pushed: true | false

Process

1. Branch resolution. Pick first match:

• branch already checked out -> use it
• mode = auto -> generate a conventional name from the change
• mode = interactive -> propose a name and wait for user approval

2. Staging. Pick first match:

• files set -> git add exactly those paths
• default -> use already-staged changes; do not add unstaged paths implicitly

3. Message resolution. Pick first match:

• message provided -> use it verbatim, skip steps 4 and 5
• mode = auto -> inspect diff and git log -5 --pretty=%B, generate a message per assets/commit-template.md, no approval
• mode = interactive -> draft a message per the template, then proceed to steps 4 and 5

4. Interactive split (when mode = interactive and multiple concerns are present). For each split, show:

• Scope: file list (proposal-only).
• Draft message: conventional subject; body explains "why", never lists files.

Wait for user approval. 5. Interactive stage (when mode = interactive). Run git add -p for each split. 6. Commit. Run git commit with the chosen message via heredoc. 7. Hook recovery. When a pre-commit hook fails, fix the underlying issue, re-stage, and create a new commit (do not amend). Loop until commit succeeds. 8. Capture sha. Read git rev-parse HEAD. 9. Push. When push: true, run git push. Use --force-with-lease only when explicitly required. Never --force. 10. Return the structured Outputs block. In interactive mode, also notify the user.

Test

• Sha match: git rev-parse HEAD returns the new commit sha that matches the commit_sha field in Outputs.
• Format: git log -1 --pretty=%s matches the conventional commit regex ^(feat|fix|docs|style|refactor|perf|test|chore|build|ci)(\([^)]+\))?: .+.
• Push: when push: true, git ls-remote origin <branch> lists a sha equal to commit_sha.

Commit Convention

Format

type(scope): description

[optional body]

[optional footer]

Types

Scope

Component/module affected (optional but recommended):

• auth, api, ui, db, cli

Description

• Use imperative mood: "add" not "added"
• Lowercase, no period
• Max 72 chars
• Clear and concise

Body (Optional)

• Explain why, not what
• Wrap at 72 chars
• Separate from description with blank line

Footer (Optional)

BREAKING CHANGE: describe breaking change
Fixes #123
Closes #456

Examples

Simple

feat(auth): add OAuth2 login

With Body

fix(api): handle null user responses

API was returning 500 when user object was null.
Added null check and return 404 instead.

Breaking Change

feat(api): redesign authentication flow

BREAKING CHANGE: JWT tokens now expire after 1h instead of 24h.
Update client token refresh logic accordingly.

Multi-Issue

fix(db): resolve connection pool leak

Connection pool wasn't releasing connections properly
under high load conditions.

Fixes #123
Closes #456

Tips

• Atomic commits: One logical change per commit
• Test before commit: Ensure code works
• Meaningful messages: Help future you understand why
• Reference issues: Link to tracking system

Bad Examples ❌

fix stuff
WIP
update
fixed bug
changes

Good Examples ✅

feat(search): add fuzzy matching
fix(cart): prevent duplicate items
docs(api): add rate limit examples
refactor(utils): extract validation logic

← aidd-framework / aidd-vcs

01 - Commit

Creates an atomic git commit with a conventional, imperative-mood message, optionally pushing the branch when the caller asks for it.

When to use

• The user says "commit", "git commit", "create a commit", "commit my

changes", or "commit and push".

• The user invokes the /commit slash command.
• An agent has finished a contained change and needs it recorded as a single

atomic commit.

When NOT to use

• To amend an existing commit (this skill always creates a new one).
• To force-push or rebase the current branch.
• To open a pull or merge request → use 02-pull-request.
• To cut a release tag → use 03-release-tag.

How to invoke

Use skill aidd-vcs:01-commit

Or via the slash command:

• /commit - stage, commit, stay local (push: false).
• /commit push - stage, commit, then push the branch (push: true).

The skill runs a single action (commit) that stages, generates or accepts a message, commits, and optionally pushes.

Outputs

• One new git commit on the current branch with a conventional message.
• Optionally, a pushed branch on the remote when push: true.

Prerequisites

• A git repository with at least one staged or unstaged change.
• A configured git identity (user.name, user.email).
• A writable remote when push: true.

Technical details

See `SKILL.md` for the action contract and `assets/commit-template.md` for the conventional commit format reference shipped with the skill.