The redacted handbook every RG INSYS engineer follows: how we branch, review, test, ship, and document. If your team has its own standards, we adopt yours; this is the floor, not the ceiling.
We use trunk-based development on every project: one always-deployable main, feature branches under 48 hours, squash-merged after review. No parallel develop or release branches; they produce drift and merge pain.
Branch names are namespaced (feat/, fix/, chore/) and commit messages follow Conventional Commits, keeping history readable and changelog-friendly.
Feature flags cover anything user-visible that is not ready: merge daily without releasing daily.
Every pull request requires at least one senior reviewer approval; two for authentication, payments, schema, or anything labelled security. Self-merging is disabled on every repo.
Our Claude Code reviewer agent auto-posts the first comment on every PR: diff summary, risk level, obvious smells. A starting point for the human reviewer, not a replacement.
A PR cannot merge until:
PRs stay under 400 lines of diff; larger changes are split or feature-flagged.
Enforced in CI: ≥80% line coverage on new and changed code, tuned by risk:
The gate lives in the test runner (vitest --coverage --coverage.thresholds.lines=80, or the Jest, Pytest, or Go equivalent), with a coverage summary posted on every PR.
We pair coverage with mutation testing on critical paths (Stryker for JS/TS) at least once per release.
Every repo runs the same pipeline; a failing stage stops it.
| Stage | What runs | Trigger | Blocks merge? |
|---|---|---|---|
| 1. Lint | ESLint, Prettier, Stylelint, ruff/black, gofmt | Every push | Yes |
| 2. Typecheck | tsc --noEmit, mypy, go vet | Every push | Yes |
| 3. Unit tests | Vitest / Jest / Pytest / go test | Every push | Yes |
| 4. Integration tests | API tests against ephemeral DB, contract tests | Every push | Yes |
| 5. Security scans | Semgrep (SAST), Snyk (dependencies), Trivy (containers), gitleaks (secrets) | Every push | Yes |
| 6. Build | Production build, Docker image, artefact upload | Every push | Yes |
| 7. Deploy preview | Ephemeral preview environment per PR | On PR open / update | No (informational) |
| 8. Deploy staging | Staging environment, smoke tests | On merge to main | No (post-merge) |
| 9. Manual approval | Production deploy gate | Triggered by release manager | Yes (for prod) |
| 10. Deploy production | Rolling deploy, health checks, auto-rollback | On approval | -- |
VoIP and FreeSWITCH work adds a containerised SIP test rig running SIPp scenarios; data-heavy work adds migration apply-and-rollback against a staging snapshot.
AI-native, not "vibe coding": every engineer uses prompt patterns with Claude Code and Cursor built on tight context, explicit file references, and test-first thinking.
Read @services/jobs.ts. Add `archiveJob` mirroring the soft-delete pattern used by `deleteJob`. Write vitest tests first with table-driven cases for: missing job, already archived, archived by non-owner, success. Then implement.
Read @routes/auth.ts and @middleware/rbac.ts. Extract role-check logic into a single `requireRole(role)` middleware. Do not change behaviour. Add tests asserting old call sites return identical responses for: admin, user, anon. No edits outside these two files.
Read @prisma/schema.prisma. Add `Invoice.voidedAt` (nullable timestamp). Generate the migration AND its `down` reversal. Update @services/invoices.ts to filter voided invoices from the default list query. Tests must cover: list excludes voided, explicit `?includeVoided=true` includes them.
Read @services/billing.ts. Bug: pro-rated refund double-counts taxes when subscription changed mid-cycle. First, write a failing vitest test that reproduces the bug at the exact boundary. Show me the failing test output. Only then fix.
Open-ended prompts ("build a payments module") produce slop; bounded prompts produce reviewable diffs.
We never paste customer data, secrets, or production logs into an AI tool. Every AI-touched file is human reviewed before merge.
Posted as a PR template comment; every reviewer walks it before approving.
catch (e) {}.any or as unknown as T.console.log, print, or debug breakpoints.up has a working down.One non-negotiable Definition of Done across all client projects. A change ships to production only when:
Anything missing, the ticket goes back. There is no "we'll add the tests later."
Default floor on new and changed code. Higher for billing, auth, and payments.
Feature branches are short. Trunk-based development keeps the team integrated, not stranded.
No PR merges with a critical Semgrep, Snyk, or Trivy finding open against the changed code.
Every user-visible change has a changeset entry. Release notes write themselves.
Tell us your stack; we will share the relevant handbook section and how we would apply it.