Skip to content

FullFran/nyxterm / .agents/skills/commit-convention

commit-convention

Unverified

Conventional Commits, work-unit commits, NO Co-Authored-By. Load before creating any commit.

Commit convention

Format

Conventional Commits. Scope optional but encouraged.

<type>(<scope>): <subject in present imperative>

<optional body explaining WHY, not what>

<optional footer with BREAKING CHANGE: ... or Refs #N>

Allowed types

TypeUse for
featnew user-visible capability
fixbug fix
chorebuild, deps, tooling, non-functional
docsdocs only (README, CONTRIBUTING, skills, code comments-only changes)
refactorrestructure without behavior change
perfperformance improvement (measured)
testtests only
styleformatting, whitespace, no logic change
ciGitHub Actions, CI config
buildbuild system, packaging (Nix flake, Cargo.toml, etc.)
revertrevert a previous commit

Examples

feat(pty): add SIGWINCH propagation for tmux-less resize
fix(theme): emit theme to webgl renderer after context restore
chore: bump portable-pty to 0.9.1
docs(agents): document OSC 7 trust window
refactor(multiplex): extract pane grid into dedicated module
perf(buffer): coalesce 4ms PTY flushes — 40% fewer IPC calls
test(pty): cover backpressure overflow path
build(nix): switch to pnpm.fetchDeps for frontend deps
ci: add cargo clippy gate

Subject rules

  • Present imperative: "add", not "added" or "adds". Like you're completing the sentence "If applied, this commit will ...".
  • No period at the end.
  • ≤72 chars ideally.
  • Lowercase first letter (after the colon).

Body (when needed)

  • Explain WHY, not what. The diff shows what.
  • Wrap at 72 chars.
  • Reference the issue: Refs #42 or Closes #42 in the footer.

Forbidden

  • ❌ Co-Authored-By: anyone@anywhere
  • ❌ 🤖 Generated with [Claude Code]
  • ❌ Any AI attribution footer

The human owns the commit. The agent assisted. Attribution is via the PR review trail, not the commit message.

Work-unit commits

One commit = one coherent change. Tests + docs + code of that change go together, not in separate commits.

Examples:

  • ✅ feat(pty): add SIGWINCH propagation includes the implementation, the test, and the relevant docs/skill update.
  • ❌ Three commits: "add code", "add test", "update docs". That's three artificial commits for one change.

Exception: when a sequence has internal milestones that each compile and pass tests independently, splitting can aid review. Then the boundary is "each commit is a green build", not "files of type X".

Amend vs new commit

  • Amend before push, when the previous commit is yours and the change is a typo or trivial fixup.
  • Never amend a published commit without coordinating. New commits preferred.
  • Never amend after a hook failure — the commit didn't happen; create a new one.

Pre-commit hooks

Don't skip with --no-verify. If a hook fails, fix the underlying issue (lint, format, test). The hook is there because the team decided it should pass.

If a hook is broken or wrong, fix the hook in a separate PR; don't bypass.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall