Git Practices

These are the conventions for all git operations in this project. Every branch, commit, and pull request follows these rules without exception.

Branch Naming

Format: <type>/<ticket-id>

Types:

• feat — New feature or capability
• fix — Bug fix
• refactor — Code restructuring without behavior change
• chore — Maintenance, tooling, config, dependencies

Examples:

feat/CTR-12
fix/CTR-45
refactor/CTR-78
chore/CTR-99

Rules:

• Ticket ID matches the project tracker (JIRA, Linear, etc.)
• Lowercase everything
• No descriptions in branch name — the ticket ID is the reference
• One branch per ticket — don't combine work from multiple tickets

Commit Messages

Format:

<type>(<scope>): <short message> [<ticket-id>]

<description>

Line 1 (subject):

• type — Same as branch types, plus: docs (documentation), test (tests only)
• scope — One word indicating the module or layer affected (e.g., auth, api, database, ui, config)
• short message — Imperative mood, lowercase, no period, under 50 characters after the scope
• ticket-id — In square brackets at the end

Line 2: Blank line (always)

Line 3+ (description):

• What was done and why, in plain sentences
• Reference related files or decisions if helpful
• Keep it concise — enough context for someone reading git log, not a full essay

Examples:

feat(document): implement search by text [CTR-12]

Added full-text search to the document module using the existing
search index. Follows the pattern established in the user search
feature.

fix(auth): prevent token refresh race condition [CTR-45]

Two concurrent requests could both trigger a token refresh,
causing one to fail with an invalid token error. Added a mutex
to ensure only one refresh happens at a time.

refactor(api): extract validation middleware [CTR-78]

Moved request validation logic from individual route handlers
into a shared middleware. Reduces duplication across 12 endpoints.

chore(config): update dependencies to latest stable [CTR-99]

Bumped all non-major dependencies. No breaking changes detected.

test(billing): add edge cases for prorated charges [CTR-33]

Covers: mid-cycle upgrade, downgrade on last day, zero-usage
month, and negative balance scenarios.

docs(api): update endpoint documentation for v2 routes [CTR-55]

Reflects the new response format introduced in the API v2 migration.

Rules:

• Subject line is mandatory, description is mandatory for anything beyond trivial changes
• No co-author or AI attribution lines
• One logical change per commit — if you have to use "and" in the subject, consider splitting
• The type in the commit matches the branch type (a feat/ branch should have feat() commits, with occasional test() or docs() commits for supporting work)

Pull Requests

Title format: Same as commit subject line:

<type>(<scope>): <short message> [<ticket-id>]

Body format:

## Summary
[2-4 sentences: what this PR does and why. Written for a reviewer
who hasn't read the ticket — they should understand the change
from this summary alone.]

## Changes
- [Concrete change 1 — what file/module and what was done]
- [Concrete change 2]
- [Concrete change 3]

## Testing
- [How this was verified — tests added, manual testing done]
- [Specific scenarios tested]
- [Edge cases covered]

## Ticket
[TICKET-ID](link to ticket if available)

Examples:

Title: feat(document): implement search by text [CTR-12]

Body:

## Summary
Adds full-text search to the document module, allowing users to
search documents by content rather than just title. Uses the existing
search index infrastructure established in user search.

## Changes
- Added search endpoint `GET /api/documents/search` with query parameter
- Created `DocumentSearchService` following the `UserSearchService` pattern
- Added search result highlighting in the response
- Added 8 unit tests covering: exact match, partial match, no results,
  special characters, pagination, and sorting

## Testing
- Unit tests pass: `npm run test -- documents`
- Manual testing: verified search returns expected results with 500+ documents
- Tested edge cases: empty query, very long query, special characters

## Ticket
[CTR-12](https://tracker.example.com/CTR-12)

Rules:

• PR title follows the exact same format as commit messages
• Summary explains the WHY, changes list the WHAT
• Testing section is mandatory — no PRs without describing how it was verified
• One ticket per PR — don't bundle unrelated work
• Link the ticket if possible
• No screenshots unless the change is visual (then they're encouraged)

Tool

Pull requests are created with the GitHub CLI (gh):

gh pr create --title "<title>" --body "<body>"

For drafts:

gh pr create --draft --title "<title>" --body "<body>"

Determining the Type

When in doubt about the commit/branch type:

If a commit includes both a feature and its tests, use feat — the tests support the feature. If a commit is purely adding missing tests for existing code, use test.

Determining the Scope

The scope should be a single word identifying the affected module or layer. Use names that match your project's directory structure or domain concepts:

Examples of good scopes:

• auth, api, database, ui, config, billing, search, notifications
• user, document, task, project, team

Avoid:

• Generic scopes: app, code, misc, stuff
• Multi-word scopes: user-profile (use user or profile)
• File names as scopes: userService (use user)

Git Worktrees

We use git worktrees instead of switching branches. Each branch lives in its own directory inside the repo, allowing parallel work across multiple features.

Folder convention:

my-repo/                    ← main checkout, always on the default branch
  .claude/worktrees/        ← worktree directory (git-ignored)
    feat-CTR-12/            ← one worktree per branch: branch name with "/" → "-"
    fix-CTR-45/

• Directory name: the branch name with / replaced by - (feat/CTR-12 → feat-CTR-12). Only letters, digits, ., _ and -; max 64 chars.
• Branch name: unchanged, <type>/<ticket-id> (see Branch Naming).
• Ignored: .claude/worktrees/ must be in the repo's .gitignore, or the main checkout sees every worktree as untracked files.
• Local files: untracked files a worktree needs to run (e.g. .env) are listed in stack.md under worktree_copy: and copied from the main checkout when the worktree is created:

  worktree_copy:
    - .env

Creating, removing, listing, migrating: use /virtual-team:worktree — it owns the exact steps for each host.

Rules:

• Always create worktrees from the main checkout (not from inside another worktree)
• Branch name follows the Branch Naming convention above: <type>/<ticket-id>
• One worktree per ticket — matches one-branch-per-ticket rule
• Remove worktrees after the PR is merged to keep the directory clean
• The main checkout always stays on the default branch (main/master) — never switch branches, stash, pull or edit there while working in a worktree

Story Groups

Stories within a feature can be grouped into execution tracks using backlog tags.

Backlog format with groups:

- [ ] S-010: Create user model | feature:FEAT-005 | group:1 | order:1 | service:be
- [ ] S-011: Add user API endpoints | feature:FEAT-005 | group:1 | order:2 | service:be
- [ ] S-012: Add user validation | feature:FEAT-005 | group:1 | order:3 | service:be
- [ ] S-013: User profile page | feature:FEAT-005 | group:2 | order:1 | service:fe
- [ ] S-014: User settings page | feature:FEAT-005 | group:2 | order:2 | service:fe

Tags:

• feature:FEAT-NNN — parent feature
• group:N — execution group. Stories in the same group are sequential and go on one branch.
• order:N — execution order within the group. Processed in ascending order.
• service:xx — which service/repo

Branch naming for groups:

• Feature with multiple stories → branch: feat/FEAT-005 (feature ID, not story ID)
• Single-story work → branch: feat/S-010 (story ID)

Group flow:

1. /virtual-team:implement FEAT-005 picks the first ready story, implements all stories sequentially
2. /virtual-team:pr marks all stories as Done in one commit