Skip to content

03-naming-conventions.md

Latest commit

 

History

History
95 lines (66 loc) · 2.17 KB

03-naming-conventions.md

File metadata and controls

95 lines (66 loc) · 2.17 KB

Naming Conventions

Predictable names reduce ambiguity for humans, agents, CI systems, and search tools.

Branch Names

<type>/<scope-slug>

Optional issue or ticket IDs may be included when the team uses them:

<type>/<ticket>-<scope-slug>

Examples:

  • feat/gate31-builder-skeleton
  • fix/GH-42-null-check-on-login
  • docs/pr-workflow-hardening

Rules:

  • lowercase kebab-case after the slash
  • describe one logical slice of work
  • avoid wip, misc, update, or other low-signal names

Commit Messages

Use Conventional Commit style unless the repo defines a stricter variant.

<type>(<optional-scope>): <imperative summary>

Examples:

  • feat(screening): add dry-run mode
  • fix(inventory): preserve existing ops state
  • docs(workflow): clarify worktree rule

Rules:

  • imperative mood
  • no trailing period
  • keep the subject line short enough to scan in logs
  • use the body for why, constraints, or trade-offs

PR Titles

PR titles should usually match the intended squash commit message.

Examples:

  • feat(builder): create application directory skeleton
  • fix(validation): avoid mutating tracked run logs during dry-run

Handoff Files

If the repo uses delegated workers, name handoffs:

YYYY-MM-DD-<scope-slug>.md

Examples:

  • 2026-03-09-pr04-gate31-builder-skeleton.md
  • 2026-03-10-fix-validation-side-effects.md

Durable Artifacts

Use date-first names for closeout notes, retrospectives, and other operator artifacts.

YYYY-MM-DD-<topic>.md

Examples:

  • 2026-03-09-gate30-reflection.md
  • 2026-03-10-pr-review-retrospective.md

Labels and Status Names

Use stable, explicit labels such as:

  • type:*
  • priority:*
  • status:*
  • scope:*

Prefer names that encode behavior, not mood. status:blocked is better than needs-help.

File and Directory Names

  • docs: kebab-case markdown files
  • scripts: kebab-case or the dominant repo convention
  • generated outputs: named by product or run, not by vague adjectives
  • temp outputs: obviously disposable names such as scratch/, tmp/, or .worktrees/

See Repo Structure and PR Flow for how names connect to workflow.