Git workflow for agents

This document tells how to commit in CepatEdge in a way that matches human maintainer expectations and keeps history useful for bisect, review, and release notes.

Commit message format

Follow Conventional Commits with a scope, consistent with recent history:

<type>(<scope>): <short imperative description>

Types (common):

Type	When
feat	New user-visible behavior or API
fix	Bug fix
docs	Documentation only
chore	Tooling, config, formatting, non-functional refactors
refactor	Code change that is not a fix or feature
test	Tests only

Scopes (examples):

• web — apps/web React SPA
• workers — apps/worker Hono API on Cloudflare Workers
• docs — docs/ tree
• repo — root workspace, .gitignore, pnpm, CI

Subject line rules:

• Use imperative mood: “add”, “fix”, “remove”, not “added” or “adding”.
• ~72 characters or less for the subject when possible.
• No trailing period on the subject.
• Body (optional): explain why if the subject is not obvious; wrap at ~72 cols.

Examples:

feat(web): add RTL-aware language row on settings page
fix(workers): route maintenance security logs through internal logger API
docs(ai-agents): add git workflow notes for automated agents

Before you commit

1. Know what changed — Run git status and skim git diff (or scoped git diff -- path). Untracked files need explicit git add.
2. Group by intent — One commit should represent one logical change (e.g. “workers maintenance fix” separate from “web settings RTL”). Avoid mixing unrelated refactors with feature work in the same commit.
3. Match project patterns — Inspect recent messages: git log --oneline -15. Align tone and scope naming with what is already there.
4. Verify — When the change touches TypeScript, run the relevant pnpm exec tsc --noEmit or tests if the repo standard expects it.

Using history to understand a change

When preparing a commit (or a follow-up fix):

1. Blame / log the file — git log --oneline -5 -- path/to/file shows how that area evolved.
2. See the last good shape — git show <commit>:path/to/file can be used to compare intent if the working tree is messy.
3. Split if needed — If git diff mixes two features, stage with git add -p or path-specific git add so each commit tells one story.

What not to do

• Do not commit secrets, .env files, or large generated artifacts unless the repo already tracks them on purpose.
• Do not force-push to main or shared branches unless project policy says otherwise (default: avoid).
• Do not use vague messages like update or fix stuff; name the area and behavior.

All-in-one vs split commits

• One commit is fine for a tightly coupled change (e.g. one API + one consumer updated together).
• Multiple commits are better when reviewers would otherwise struggle to see: (a) a bug fix, (b) a separate refactor, (c) documentation.

Agents should default to split commits when git diff spans unrelated directories (e.g. apps/worker and apps/web) unless the team explicitly wants a single squash.