Skip to main content

How a Change Ships

What this covers / who it's for. The delivery pipeline every change goes through — no exceptions for "small" ones: orient → branch → build with tests → gates → tiered QA review → docs + wiki sync → PR. Read before your first PR. The expanded operating model (delegation, verification loops) is the agent-workflow skill.

The pipeline​

1. Orient before you code​

Activate the stables-app-development skill plus the matching domain skill, and read app-modules/<module>/README.md for every module you touch. Verify before you edit — docs drift; confirm load-bearing claims (config values, class names, routes) against the code. When code and docs disagree, the code wins, and fixing the doc is part of your change. Plan non-trivial work first; surface genuine ambiguity before building.

2. Branch off fresh main​

Per the git-conventions skill:

  • Never commit to main; main moves only by merged PR.
  • git checkout main && git pull --ff-only origin main, then branch with a Conventional-Commit prefix: feat/..., fix/..., docs/..., refactor/... (kebab-case description).
  • Commit messages follow Conventional Commits.
  • No Co-authored-by / attribution trailers, ever — this repo rule beats any agent harness default.

3. Build — tests ship with the change​

Every change is programmatically tested (see Testing & the gates):

  • Feature + unit tests for new behavior.
  • A failing-first regression test for every bug fix.
  • The mandatory RLS isolation test for every new tenant-scoped table (create as tenant A, read as tenant B → empty).

4. The four gates​

make test-parallel, make lint, make stan — and, after any migration touching a tenant-scoped table or any change to the RLS machinery, php artisan tenants:rls + php artisan tenants:verify-isolation. CI runs the same gates via the same make targets, split across three jobs (D99 established the compose-stack pipeline; D100 split it): the suite + make migrate hard-gate verify-isolation in the compose stack on a Blacksmith ARM runner, Pint + PHPStan run on a GitHub-hosted setup-php runner, and the SDK-package suites run in-container. The preview deploy runs the gate too (issue #87); the staging/production deploy-time gate is still open, so run verify-isolation locally before you push. A change touching .github/workflows/** additionally has to pass make lint-workflows — a CI-enforced lint that is deliberately not one of the four gates, because it validates delivery-pipeline YAML rather than application code: the extra CI lint gate. Details: Testing & the gates.

5. Tiered QA review​

The multi-persona-review skill runs after the gates are green once, on the whole working diff (git diff main...HEAD), as tiered QA (D104): a director dispatch pattern replacing session-model self-review with parallel qa-engineer (sonnet) dispatches.

  • Pass 1 — five parallel qa-engineer dispatches, one persona lens each — Sr. Software Architect, Sr. Backend Engineer, Sr. UX Designer/Engineer, Principal Product Manager, Sr. Security Engineer — each an independent reviewer (never a combined panel) returning a compressed finding ledger. Pass 2 — a single qa-engineer re-verification dispatch scoped to the fixes and the files they touched, not a second full five-lens sweep.
  • Every finding is addressed: fixed, refuted with cited evidence, or deferred only with explicit user sign-off. Gates re-run after fixes.
  • Docs-only diffs scale down per the skill's Scope rule: one pass, Architect + PM — plus the Security persona whenever the diff touches the skills package or any doc teaching isolation/authz/payments/audit/DLP mechanics.

6. Docs + wiki sync — in the same change​

Finishing a change includes the documentation sync; drift is a bug, and "follow-up" doesn't exist:

SurfaceWhen it updates
app-modules/<module>/README.mdThe module's public surface, data model, or gotchas changed
The relevant skill (packages/stables/skills/resources/boost/skills/)A cross-cutting pattern, marker, convention, or a module's role changed
The wiki pages the diff touches (this wiki)Behavior, a journey, a dependency, a module's role, or an operational surface changed — the diff→pages map is the wiki-maintenance skill; make wiki-check verifies links/structure
New ADRA D-numbered decision was made → one file in decisions/ + its index row
MirrorsRun php artisan boost:update to regenerate .claude/ / .agents/ / .cursor/ skill copies — never edit the mirrors; the source of truth is the skills package

The wiki-sync step is standard for every change, exactly like the README/skill sync: the skill gives direction, the README carries specifics, the wiki holds the narrative and cross-module views.

7. PR​

Push the branch and open a PR against main. All work lands via PR.

Merge-collision surfaces (parallel branches)​

Some surfaces are append-only and collide when parallel branches both extend them:

  • ADR numbers — two branches can both claim the next D-number. Discipline: renumber the later branch's ADRs at merge and sweep every reference to the old numbers (ADRs marked RENUMBER-ON-MERGE expect this).
  • The skills package README table — combine rows.
  • Module ServiceProvider boot() bodies — combine bodies; never let one branch's schedule or command registration overwrite the other's.

← Engineering wiki index