Commit Workflow

Every commit follows the same workflow regardless of who (or what) wrote the code. This page covers the human decisions in the commit process -- when to commit, what to include, how to write the message. For the automated checks that run during this process, see Delivery -- Quality Gates and Delivery -- Pipeline.

Pre-Commit Checklist

Before every commit, run the full monorepo checks:

pnpm ci:check

This runs eight steps in sequence. If any step fails, the rest do not run:

1. pnpm format:check -- Prettier formatting
2. pnpm lint -- ESLint across all packages
3. pnpm dep-cruise -- dependency graph validation
4. pnpm lint:dead-code -- Knip dead code detection
5. pnpm lint:duplication -- jscpd copy-paste detection
6. pnpm typecheck -- TypeScript strict mode
7. pnpm test -- Vitest test suites
8. pnpm docs:update-detection -- flags stale user-facing docs

Fix all errors before committing. Warnings (complexity, max-lines) are acceptable; errors must be zero.

Why full monorepo, not per-package

The web app has stricter lint rules than individual packages, and per-package checks miss cross-package issues. Common problems caught only by full-monorepo lint:

• Import/export sorting -- shadcn vendor components and new files often need simple-import-sort auto-fix
• restrict-template-expressions -- the web app forbids numbers in template literals
• no-unsafe-* rules -- the web app's TypeScript-ESLint config is stricter about any types than library packages
• Unused imports -- accumulate during refactoring, caught across all files

Before pushing

Run the full CI simulation including build:

pnpm ci:full

This runs ci:check plus pnpm build, catching Next.js config conflicts and other build-time errors that type checking alone misses.

Staging Discipline

Stage specific files by name. Do not use git add -A or git add . -- these risk including secrets, large binaries, or unrelated changes.

Before staging, verify:

• No .env files are staged (they are gitignored, but check .env.example files for real keys)
• No unrelated changes are bundled into the commit
• Generated files (migrations, seed data) are included when they should be

Commit Messages

Write a concise message focused on why, not what. The diff shows what changed; the message explains the intent.

Co-authorship

When Claude Code authored the changes, include the co-author trailer:

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Branch naming

Branch names come from Linear. When creating a branch for a ticket, use Linear's suggested format:

kyleolson512/tro-14-phase-0-gate-review

This ties every branch to a ticket, making it easy to trace commits back to requirements.

Doc Update Detection

The final step of pnpm ci:check runs pnpm docs:update-detection. This script compares changed files against the sources frontmatter globs in user-facing doc pages. When it flags a page:

1. Read the flagged doc page and the changed source files
2. Determine whether the code changes affect user-visible behavior described in the doc
3. If no (internal refactor, performance, test-only) -- ignore the flag
4. If yes -- either update the doc page in the same commit (if small) or create a Linear issue in the "Document Update Requests" milestone with label doc-update-request

The detection is mechanical glob matching. Your judgment about whether the change is user-visible is the intelligent filter.

Architecture Review

Before pushing a branch, run the /arch-review skill scoped to the code you changed and any code impacted by those changes. Focus on affected packages and their downstream consumers, not the full codebase. Full-codebase sweeps happen on a schedule (TRO-97).

PR Merge Checklist

Before merging a PR to main:

• CI is green on the PR branch
• If new environment variables were added:
  • Added to apps/web/.env.example
  • Secret name added to Terraform (infra/environments/prod/main.tf and staging/main.tf)
  • Secret added to infra/sync-secrets-vm.sh and scripts/sync-secrets.sh
  • CI placeholder added to .github/workflows/ci.yml
  • Secret created in GCP Secret Manager with its value set
  • If NEXT_PUBLIC_*, added as a build arg in apps/web/Dockerfile and the build-push CI job
• If database schema changes are included, the migration SQL has been reviewed

After merging, watch the main branch CI run: gh run list --branch main --limit 1. The full pipeline (CI, build, deploy) takes 5-10 minutes.

Related Pages

• Delivery -- Quality Gates -- the automated checks behind pnpm ci:check
• Delivery -- Pre-commit Hooks -- Husky + lint-staged configuration
• Delivery -- Pipeline -- Local CI Parity -- ensuring local and CI checks match
• Infrastructure -- Deployment -- what happens after merge (build, push, deploy)