Git Conventions

Git Conventions

You are a senior engineer helping enforce Singleton SD's git conventions. Apply these rules when writing commit messages, naming branches, or reviewing either.

Engineering host

Read consumer .skills/profile / config/tracker-profiles/.

Legacy ClickUp Delivery branches (feature/<clickup-id>-…) may exist on older app work — do not create new ones.

Commit message format

type: TICKET Description in sentence case

Examples:

feat: #284 Add multi-agent skills install
feat: AI-47 Migrate poc skills into categories
feat: SSDOP-42 Add dark mode toggle to settings page

Rules

Commit body: 72-character lines

When the commit has a body (paragraphs or bullet list):

• Every body line must be ≤ 72 characters (count spaces and punctuation).
• That includes lines that start with a bullet (- ): the whole line must stay within the limit; wrap long bullets onto continuation lines if needed.
• Prefer breaking at natural phrase boundaries, not mid-word.

Example (subject obeys 50-character limit; each body line ≤ 72):

chore: SSDOP-42 Add parallel TS build driver

- Parallel: generate-html, manifest icons, and profile pipeline
- Profile: static assets, then animations (PNG cache reuse)
- Run build via ts-node instead of bash for portability

Ticket auto-injection

The prepare-commit-msg hook automatically injects the ticket number from the branch name. If you are on feature/SSDOP-42-dark-mode, writing:

feat: Add dark mode toggle

becomes:

feat: SSDOP-42 Add dark mode toggle

You only need to include the ticket explicitly when:

• You are on a non-feature/hotfix branch (e.g., develop)
• The ticket in your commit differs from the branch (this will error — fix the mismatch)

Allowed types (conventional commits)

Branch naming

App repos (GitHub / GitLab issues):

<type>/<issue-number>-<kebab-title>

Examples: feat/284-skills-multi-agent-install, fix/211-login-redirect, chore/284-skills-install.

Skills repo / ClickUp-custom-id workflows:

feature/TICKET-NUMBER[-optional-slug]
hotfix/TICKET-NUMBER[-optional-slug]
release/vMAJOR.MINOR.PATCH

Also allowed (protected): main, master, develop, design.

Examples:

feature/AI-47-skills-consolidation
feature/SSDOP-42-dark-mode-toggle
hotfix/SSDOP-17-null-pointer-fix
release/v1.3.0

Prefer the target repo's AGENTS.md when it defines a stricter pattern. The skills-repo post-checkout hook validates ClickUp-style names on creation.

Isolated worktrees

Implement and review on a sibling worktree created from the latest origin/<default-branch>. Detect the default branch from origin/HEAD (master or main); do not hardcode it.

• Path sits next to the default checkout, for example <repo>/feature-SSDOP-42-dark-mode beside <repo>/main.
• Never nest .worktrees/ (or any worktree) inside an existing checkout.
• Never edit or push main / master for feature work.
• Parent agents create the worktree before launching a subagent and pass that path as the subagent working directory.
• Subagents already inside a feature worktree must stay there and must not create another worktree.

Full procedure: engineering/isolated-worktree.

TypeScript filename conventions

Staged .ts files must match one of these patterns:

The pre-commit hook blocks commits containing files that don't match.

Versioning

Versions follow semver and are bumped automatically by release-it based on commit types:

Never manually edit the version in package.json. Run yarn release (dry-run) or yarn release:ci (CI/CD) instead.

Validation checklist

Before pushing, verify:

• Work happens in a sibling worktree, not on main / master
• Branch name matches feature/TICKET-NNN or hotfix/TICKET-NNN or an allowed base branch
• Commit subject is ≤ 50 chars, sentence-case, no period
• Ticket number is present (in commit or auto-injected from branch)
• Body lines (if any) are ≤ 72 chars with a blank separator line
• TypeScript filenames follow kebab-case or PascalCase