Repository Standards

Every client project follows the same conventions. The reason is handover: a consistent structure means the client's next developer can navigate it, and so can you in eighteen months.

Required in every repository#

• README.md — what this is, how to run it locally, how to deploy
• .env.example — every variable listed with a description and no real values
• .gitignore — verified to exclude .env, build output, and editor files
• docs/architecture.md — the pieces and how they connect
• docs/deployment.md — deploy and rollback steps

Commits#

Conventional commits. feat:, fix:, chore:, docs:, refactor:.

Commit messages describe why, not what. The diff already says what.

Branches#

• main — always deployable
• feat/[description] — feature work
• fix/[description] — bug fixes

Merge to main when a milestone is demo-ready.

Secrets#

Never commit a secret. Ever.

If one is committed, rotating the key is required — removing the file is not sufficient, because git history retains it. Before any handover, scan git history, not just the current tree.

Code standards#

• Typecheck and lint must pass with zero errors before any milestone demo
• No any in TypeScript without an accompanying comment explaining why
• No commented-out code in main — that is what git history is for
• Environment-dependent values in environment variables, never hardcoded

Before handover#

• Squash or document experimental branches
• Remove unused dependencies
• Verify a clean clone runs from the README instructions alone, on a machine with nothing pre-configured

That last check catches the majority of handover failures.