Commit Workflow

Standard commit workflow for the ai-standards repository.

Before Every Commit

1. Run Markdown Formatter

Format project markdown files using mdformat (excludes opensrc/ which contains external source):

nix develop -c mdformat skills/ .claude/ agents/ templates/ *.md

2. Preview Changes

Show files involved and diff preview:

git status git diff --stat git diff

3. Analyze and Group Changes

Review the changes and determine:

• Single commit: All changes are related to one feature/fix

• Multiple commits: Changes are unrelated and should be separate

Examples:

• Docs update + new skill → 2 commits

• Rename agent + update references → 1 commit

• Bug fix + unrelated refactor → 2 commits

4. Stage and Commit

For single commit:

git add -A git commit -m "commit message"

For multiple commits, stage selectively:

git add <related-files> git commit -m "first commit message"

git add <other-files> git commit -m "second commit message"

Commit Message Guidelines

• Start with uppercase, imperative mood

• Reference skill/agent names in brackets when applicable: [powersync] Add sync pattern docs

• If AI made the changes, include co-author: Co-Authored-By: Claude <noreply@anthropic.com>

Output Format

Always show proposed commits with their files:

Commit 1: commit message here

• file1.md
• file2.ts

Commit 2: another commit message

• file3.md

Then wait for user approval before executing.