| name | campusforge-git-commit |
| description | Generate and review Git commits for CampusForge. Use when preparing, splitting, naming, or validating commits in this repository. |
CampusForge Git Commit Skill
Use this skill to create small, auditable commits for the CampusForge monorepo. The goal is to keep history useful for review, release notes, rollback, and incident analysis.
Commit Contract
Every commit MUST satisfy all of the following:
- Contains one logical change only.
- Builds on top of existing project conventions instead of introducing parallel patterns.
- Includes directly affected tests, docs, schemas, migrations, or generated artifacts when applicable.
- Uses Conventional Commits format accepted by
commitlint.config.js.
- Avoids secrets, local machine paths, debug leftovers, generated caches, and unrelated formatting churn.
Message Format
<type>(<scope>): <subject>
[body]
[footer]
The scope is optional only when no project area is clearly dominant.
Types
Use exactly one type:
| Type | Use for |
|---|
feat | User-visible product capability or API behavior. |
fix | Bug fix, broken behavior, regression, data correctness issue. |
docs | Documentation-only change. |
style | Formatting-only change with no runtime or type behavior change. |
refactor | Internal code change that does not add behavior or fix a bug. |
perf | Measurable performance improvement. |
test | Test-only change or test infrastructure. |
chore | Tooling, dependency, repository maintenance. |
ci | GitHub Actions, release automation, CI configuration. |
revert | Revert of a previous commit. |
If a change both fixes a bug and refactors code, use fix when the user-visible behavior changes. If it only improves structure, use refactor.
Scopes
Prefer these repository scopes because they match commitlint.config.js:
| Scope | Use for |
|---|
web | Next.js frontend app, routing, pages, client/server components. |
ui | Reusable UI components, CSS tokens, layout primitives, visual system. |
api | Fastify backend, REST endpoints, request lifecycle. |
db | Prisma schema, migrations, seed data, database client. |
shared | Shared DTOs, Zod schemas, cross-package constants. |
auth | Authentication, identity integration, session handling. |
rbac | Roles, permissions, access-control decisions. |
core | Cross-cutting business logic not owned by one app/package. |
config | TypeScript, ESLint, Prettier, Turbo, package configuration. |
deps | Dependency updates and lockfile-only dependency maintenance. |
ci | Workflows and CI-only scripts. |
docs | Documentation files. |
For mature frontend work, split large UI changes by stable review boundary:
feat(web) for new route-level capability.feat(ui) for new reusable component behavior.fix(ui) for visual or interaction defects in shared components.style(ui) only when output behavior is unchanged.perf(web) only when the commit directly improves rendering, loading, or bundle behavior.
Subject Rules
The subject MUST:
- Be imperative and present tense:
add, prevent, normalize; not added, adds, updated.
- Start lowercase.
- Have no trailing period.
- Be 72 characters or fewer.
- Describe the behavior or repository effect, not the implementation detail.
Good subjects:
feat(web): add invitation review dashboard
fix(ui): preserve focus when closing command menu
refactor(shared): centralize invitation status schema
perf(web): defer loading member graph visualization
Bad subjects:
fix: fixed stuff
chore: update
feat(web): Add New Page.
refactor: changed files
Body Rules
Add a body when the subject alone cannot explain risk or intent. The body SHOULD explain what changed and why; avoid narrating obvious code mechanics.
Use a body for:
- Non-trivial frontend state, routing, caching, accessibility, or rendering changes.
- API, schema, permission, or data model behavior changes.
- Tradeoffs, migration notes, rollback notes, or compatibility constraints.
Wrap body lines at 100 characters to match repository commitlint warnings.
Example:
fix(web): keep invitation filters in sync with URL state
Store the selected status in search params so shared links preserve the same
review queue and browser navigation does not reset the filter.
Footer Rules
Use footers for issue links, breaking changes, and revert metadata.
Closes #42
Fixes #89
Refs #104
BREAKING CHANGE: invitation status values now use shared enum names.
Breaking changes MUST use BREAKING CHANGE: in the footer and describe the migration impact.
Commit Splitting Standard
Before committing, split changes until each commit can be reviewed and reverted independently.
Keep together:
- Component change plus its directly affected styles and tests.
- API contract change plus shared schema update and tests proving the contract.
- Prisma schema change plus required migration and generated client updates.
- Dependency version update plus lockfile change.
Split apart:
- Feature work and opportunistic refactors.
- Formatting-only churn and behavior changes.
- Frontend UI changes and unrelated backend changes.
- Dependency upgrades and product code changes, unless the product code is required by the upgrade.
- Generated artifacts that belong to different logical changes.
Frontend-Specific Quality Gate
For frontend commits, verify the affected behavior before committing:
- UI follows
docs/04-design-system.md tokens, spacing, states, and visual tone.
- Interactive controls preserve keyboard access, focus behavior, labels, and disabled/loading states.
- Client/server boundaries are intentional; avoid unnecessary client components.
- Data-fetching, loading, empty, error, and permission states are covered when affected.
- Tests or manual verification notes cover the changed user behavior.
Repository Commands
Local hooks run through Husky:
pre-commit: pnpm lint and pnpm typecheckcommit-msg: npx --no -- commitlint --edit <message-file>
Useful manual checks:
pnpm lint
pnpm typecheck
printf '%s\n' 'feat(web): add invitation status tracking' | pnpm exec commitlint
Do not bypass hooks with --no-verify unless an emergency process explicitly allows it.
Workflow
- Inspect the diff and remove unrelated edits before staging.
- Stage by logical unit with
git add -p when needed.
- Choose type by externally observable intent.
- Choose scope by primary owner of the changed files.
- Write the shortest subject that still identifies the behavior.
- Add a body or footer when risk, issue linkage, migration, or rollback context matters.
- Run the relevant verification before committing.
Review Checklist
Before accepting a commit message, confirm:
- Type and scope match the actual diff.
- Subject is lowercase, imperative, concise, and has no period.
- Body explains why for non-trivial behavior or architecture changes.
- Breaking changes and issue links are in footers.
- The commit contains no unrelated formatting, debug output, secrets, local files, or generated noise.
- Verification matches the changed behavior rather than only proving the project can start.
