Conventions
Coding standards, commit rules, naming patterns, ticket scoping, and debt management -- the human side of how we work.
Conventions are the shared agreements that keep the codebase consistent when multiple AI agents and a solo founder are writing code in parallel. This topic covers process -- the decisions humans and agents make about how to work. The automated enforcement of these conventions lives in the Delivery domain.
Why Conventions Matter Here
Trovella is built by a solo founder dispatching AI agents to work on parallel features. Without shared conventions, each agent invents its own patterns. The result is a codebase that works but is impossible to reason about. These conventions exist so that:
- Code written by different agents in different sessions reads like it was written by one person
- The founder can review PRs by scanning for convention violations, not re-reading every line
- Automated tooling (linters, type checkers, architecture tests) can enforce the mechanical parts
Pages in This Topic
Commit Workflow
The pre-commit checklist, staging discipline, commit message conventions, and the full ci:check pipeline that runs before every commit. Covers the path from code change to merged PR.
Code Documentation
TSDoc conventions including the summary-first philosophy, optional standard tags, and the three custom intent tags (@invariant, @intent, @contract) required on critical modules like RLS, auth, and state machines.
Technical Debt
The TODO/FIXME/HACK convention with mandatory expiration dates, the four-quadrant debt classification system, and hotspot analysis for identifying the most dangerous files in the codebase.
Naming Patterns
Naming conventions for branches, files, database objects, and identifiers -- and why they are the way they are.
Ticket Scoping
How Linear tickets are structured, estimated, and related. Covers the mandatory admin logging scope, the Fibonacci point scale, and one-week feature scope rule.
Automated vs Human
| Convention | Human responsibility | Automated enforcement |
|---|---|---|
| Commit message quality | Write meaningful "why" messages | None (intentionally) |
| TODO expiration dates | Choose realistic dates, extend with context | ESLint unicorn/expiring-todo-comments (Quality Gates) |
| TSDoc on exports | Write the summary and intent tags | ESLint jsdoc/require-jsdoc + tsdoc/syntax (Quality Gates) |
| Naming conventions | Follow the patterns in new code | ESLint @typescript-eslint/naming-convention (Complexity and Naming) |
| File staging | Stage specific files, check for secrets | Pre-commit hook formats staged files (Pre-commit Hooks) |
| Ticket structure | Include admin logging scope, set estimates | None (manual discipline) |
| Import sorting | None (auto-fixed) | ESLint simple-import-sort + pre-commit hook |
The pattern is deliberate: automate what can be checked mechanically, document what requires judgment.
Cross-Domain References
- Delivery -- Quality Gates -- the ESLint/TypeScript rules that enforce coding standards at editor-time and in CI
- Delivery -- Architecture Enforcement -- complexity limits, dependency graph rules, dead code detection
- Delivery -- Pipeline -- Local CI Parity -- running the same checks locally that CI runs
- Delivery -- Dependency Management -- catalog pattern, Renovate, version strategy