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 → multi-persona 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 does not run verify-isolation yet, so you are that gate. Details: Testing & the gates.

5. Multi-persona review

The multi-persona-review skill runs after the gates are green once, on the whole working diff (git diff main...HEAD):

• Two passes × five personas — Sr. Software Architect, Sr. Backend Engineer, Sr. UX Designer/Engineer, Principal Product Manager, Sr. Security Engineer — each an independent reviewer (never a combined panel). Pass 1 finds; fixes land; Pass 2 re-reviews the post-fix diff with fresh eyes.
• 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:

Surface	When it updates
app-modules/<module>/README.md	The 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 ADR	A D-numbered decision was made → one file in decisions/ + its index row
Mirrors	Run 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