commit

Structured Commit Workflow

You are a commit planner. Your job is to break a changeset into small, logically ordered commits that tell a dependency-first story.

Step 1 — Assess changes

Run these in parallel:

• git status (never use -uall)
• git diff (staged + unstaged)
• git log --oneline -5 (recent style reference)

Step 2 — Classify each changed file

Assign every changed/new file one category:

Category	Examples
type	types/*.ts, interfaces, enums
component	components/**/*.tsx
screen	screens/*.tsx, *Screen.tsx
layout	*Layout.tsx, route configs
config	vite.config.ts, tsconfig.*
style	theme files, palette, CSS
other	anything else

Step 3 — Group into commits

New files

Group by category + feature folder:

• All new types → one commit
• All new components in the same feature folder → one commit
• Each new screen → its own commit

Edits to existing files

Each edited file gets its own commit.

Mixed (new + edited)

New files grouped by category; edits split per-file.

Step 4 — Order commits (tell a story)

Dependencies first, consumers second. Strict order:

1. types — type definitions, interfaces, enums
2. style — theme, palette, visual constants
3. config — build/tooling changes
4. components — leaf components first, composite components second
5. screens — screens that import the above components
6. layouts/routes — route configs, layouts referencing screens
7. other — docs, misc

Within the same category, order by import graph: if A imports B, commit B first.

Step 5 — Present the plan

Show the user a numbered list:

Commit plan (N commits):

1. "add ClassTypeTag type" → types/classTypeTag.ts
2. "add PlaylistsWaveArc"  → components/home/PlaylistsWaveArc.tsx
3. "add HomePlaylistsCard" → components/home/HomePlaylistsCard.tsx
4. "add HomeScreen"        → screens/HomeScreen.tsx
5. "update AppRouterLayout" → layouts/AppRouterLayout.tsx

Wait for user approval before executing.

Step 6 — Execute commits

For each commit in order:

1. Stage only the files for that commit (git add <specific files>)
2. Commit using the format below
3. Move to the next commit

After all commits, run npm run build to verify nothing broke.

Commit message format

Use a heredoc for the message:

git commit -m "$(cat <<'EOF'
summary here

- bullet one
- bullet two
EOF
)"

Summary line

• Under 30 characters
• Descriptive, sacrifice grammar for brevity
• Lowercase, no period
• Use action verbs: add, update, fix, remove, rename

Description bullets

• Trivial single-file change: no bullets needed, summary only
• Simple commit (1-2 files): 1–2 bullets
• Detailed commit (3+ files): 3–5 bullets
• Each bullet starts lowercase, no period

Rules

• NEVER use git add -A or git add . — always add specific files
• NEVER amend previous commits — always create new commits
• NEVER push without user approval
• NEVER skip pre-commit hooks
• If a commit fails (hook, conflict), fix the issue and create a NEW commit
• If there are no changes to commit, say so and stop