How we go from 3 to 7+ developers without breaking the codebase.

Adopted, and rolling out in phases.

This is no longer a hypothetical. The model below is the team's operating system, ratified across docs/adr/ (ADR-0083–0096). Most of the foundation is live; the rest is rolling out. Here's the honest split, so you can tell the vision from what works today.

Twelve terms · so the rest reads fast.

If you've worked on small teams, some of these will be new. The full definitions live in docs/GLOSSARY.md.

Coherence is what we lose first when we grow.

QIIUB today is unusually coherent — every endpoint follows the same pattern, every screen uses the same components, every ADR is consistent. This is the project's biggest asset. It's also the one most easily lost when the team expands.

Any multi-developer system must answer three questions.

Knowledge, Ownership, Flow. Each one fits into ~30 seconds of explanation. Together they form the operating model.

One guide, four levels, every Claude reads it.

When seven developers each work with their own Claude, every Claude reads only the code it can see and infers its own conventions. The result: seven implicit styles. The fix: a cascade of guides everyone (human and AI) reads first.

Eight gated paths. Everything else flows freely.

The biggest mistake a growing team makes is reviewing everything as if it were equally dangerous. We don't. Only eight paths in the repo carry permanent consequences if a wrong change merges — those need owner approval. Everything else needs one teammate's eyes, no more.

The 8 paths that need owner approval

The live .github/CODEOWNERS is the authoritative list and has grown beyond these eight as the repo matured — it also gates DESIGN-SYSTEM.md, the design-token assets, the doctor / smoke-test scripts, and the Auth / Identity / Invitations feature folders. Schema (Entities/, Migrations/) and auth stay Mike-only; everywhere else Mike and JJ co-own.

Everything else · the 95%

How it's enforced (this matters)

The gates are server-side: the cascade-guards.yml CI workflow runs on every PR and checks the gated paths against the manifest (live); CODEOWNERS auto-requests the right reviewer (live); branch protection on main — the final activation step — hard-blocks the merge button until both pass. No client-side pre-commit hook controls governance. Hooks can be bypassed with --no-verify, so they're not trustworthy as gates. CI is the trust boundary.

How it scales

As the project grows, more paths join the gated set — but only at real business milestones, not arbitrarily. First pilot live? Add Sync Engine + Payments + Auth. Three merchants in production? Move to a primary+secondary owner model per area. Multi-region rollout? Full release management. The model tightens with the stakes, never ahead of them.

Seven stages. Same path for every piece of work.

From "someone has an idea" to "it's merged in main" — seven concrete steps with clear tooling at each. No mystery about where work is or who owns the next move.

Day-to-day · the actual mechanics

The trivial-fix exception

Some changes are so small they don't need an issue or a manifest. Six criteria: 1 sentence describable, 1 file, < 50 lines, not in src/QIIUB.*, not in docs/adr/, not in CODEOWNERS gated paths. Examples: locale key typo, missing aria-label, hardcoded hex → token, missing test. Title prefix qa-fix:. The PR is the tracking. CI validates the criteria — you can't lie your way past them.

Merge strategy · squash and merge (only)

Every PR squashes to one commit on main. The PR title + body becomes the commit message. Clean linear history. Easy reverts. The full PR history (every individual commit) is preserved in GHES for context. No merge commits, no rebase merges — one button, one rule.

QA Phase first · 2-3 weeks of validating what already exists.

Before development with the full team starts, the three available developers (Manager + 2 new hires) spend 2-3 weeks mechanically validating the existing codebase. The point: build shared mental model, find gaps, and exit the phase with a triaged backlog — not to "do new work."

The decision rule for QA findings · all six must be true

For each role · the practical impact.

If you're a PM, dev, or QA, here's the day-to-day reality with this system. Skip to your row.

Monday morning · a developer's actual workflow.

No process matters until you can describe it as a normal day. Here's yours:

The system tightens at business milestones, not by calendar.

Today we're at "dev iteration" — no paying customers yet, so the gates are minimal. As QIIUB acquires real customers, more paths join the gated list. The triggers are business events, not arbitrary dates.

Note the inversion: today Mike is on every gated path. At scale he's on almost nothing day-to-day — area owners do it. The system was designed from day one so this scaling works without re-architecting.

Phase 0 · the load-bearing minimum.

Phase 0 lays the load-bearing minimum before the team builds new features. Most of it is live: ✓ shipped — root CLAUDE.md updates, .github/CODEOWNERS, cascade-guards.yml, the 4 issue templates + PR template, and the T1–T5 cascade tests. ◷ still rolling out — branch protection on main, the Lookbook seed, the onboarding-ritual doc, and the label taxonomy. After this, QA Phase runs with the cascade already operational, and full Flow kicks in at QA's Definition of Done.

The objections you'd raise (and the answers).