old.cms.fellies.org/docs/product-engineering/code-handover-playbook.md

Code Handover Playbook

This is the minimum runbook for a new engineer to continue delivery safely.

Local Setup

1. Install Bun matching repo policy.
2. Copy .env.example to .env and fill required values.
3. Generate Prisma client: bun run db:generate
4. Apply migrations: bun run db:migrate:deploy (or local named migration flow)
5. Seed data: bun run db:seed
6. Start apps: bun run dev

Daily Development Loop

1. Create branch by task type: todo/*, refactor/*, code/*.
2. Implement smallest vertical slice for one TODO item.
3. Run quality gates: bun run check bun run typecheck bun run test
4. Update TODO.md status and discovery log.
5. Commit with Conventional Commit message and GPG signing.

Database Workflow

• Schema source is: packages/db/prisma/schema.prisma
• Use named dev migrations for schema changes.
• Avoid manual SQL unless migration tooling is blocked.
• Always regenerate client after schema change.

Testing Strategy

• Unit/service tests: packages/* and logic helpers.
• App-boundary integration tests: auth flow and route-level behavior.
• E2E tests: full admin/public happy paths through Playwright.

Common Failure Recovery

• DATABASE_URL not set: ensure root .env is loaded for Bun/Prisma scripts.
• Prisma client import errors: run bun run db:generate.
• Migration drift: run deploy/reset flow in dev and reseed.
• Playwright host deps missing: install browser dependencies on host before running e2e.

Ownership Expectations

• Keep invariants explicit and tested before changing auth/media pipelines.
• Treat TODO.md as delivery source of truth.
• If changing branch/release workflow, update docs in same branch.