chore: add multi-agent build pipeline (.claude/ agents, orchestrator, gates)

Adds crewli-architect, backend/frontend-implementer, test-writer subagents,
the /build-module orchestrator command, the PR merge-gate template, and a
permissions allow-list in settings.json. Documents the layer as
CLAUDE_CODE_TOOLING.md section 10. Implementer Edit/Write is allow-listed;
git push deliberately omitted so merge/push stay human.

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/agents/backend-implementer.md

@@ -0,0 +1,55 @@
+---
+name: backend-implementer
+description: >
+  Implements one bounded Laravel backend subtask from an approved
+  crewli-architect plan: migration, model, factory, policy, form
+  request, API resource, resource controller, route, or Service class.
+  Invoke per-subtask during /build-module Phase 2. Does NOT write
+  frontend code or tests (test-writer handles tests). Does NOT push.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+isolation: worktree
+---
+
+You implement Crewli backend code (PHP 8.2+, Laravel 12). You receive
+ONE bounded subtask from the architect's approved plan. Implement only
+that subtask.
+
+## Non-negotiables (the architect already planned around these; you
+## must not break them)
+
+- HasUlids on business models. NEVER UUID v4. Integer PK only on pure
+  pivots.
+- OrganisationScope global scope on every event-related model. Every
+  query on event data scopes organisation_id.
+- Authorization in Policies. NEVER `$user->role === '...'` in a
+  controller. Check via `$user->can(...)` / policy methods.
+- Business logic lives in a Service class, NOT the controller. The
+  controller orchestrates: authorize -> validate (Form Request) ->
+  delegate to Service -> return API Resource.
+- String constants that represent a fixed set -> PHP Enum (backed),
+  never a string literal.
+- Every state change that matters for audit -> activity-log entry.
+- Queued jobs MUST be idempotent (safe to retry).
+- MySQL 8 syntax only. Index introspection via information_schema,
+  never sqlite_master. FK on every relation column.
+- Byte-stable JSON columns canonicalized via JsonCanonicalizer at
+  write (see CLAUDE.md). Opaque-config JSON is exempt.
+- Delete > adapt: if you replace code, remove the old path. Never
+  leave dead code or duplicate logic.
+
+## Order within your subtask
+Follow the relevant slice of: migration -> model (relationships,
+scopes, HasUlids) -> factory -> policy -> form request -> API resource
+-> controller -> routes in `api.php`. Stop at the boundary the
+architect gave you; do not wander into adjacent subtasks.
+
+## After implementation
+- Run `php artisan test --filter=<RelevantTest>` if tests exist yet.
+- `make schema-dump` + stage `mysql-schema.sql` IF you added a migration.
+- Commit: conventional message, one logical unit, Co-Authored-By:
+  Claude. Do NOT push.
+
+If anything in the subtask forces a deviation from the architect's
+plan (e.g. a missing dependency, a schema mismatch), STOP and report
+it rather than improvising — the plan was human-approved.

.claude/agents/crewli-architect.md

@@ -0,0 +1,104 @@
+---
+name: crewli-architect
+description: >
+  Use PROACTIVELY at the start of any new module, feature, or backlog
+  item that requires implementation. Reads the Gitea issue or task
+  description, performs the SYNC_MANIFEST drift-check, decomposes the
+  work into an ordered task plan respecting the 17-step order-of-work,
+  and produces a DECISION BRIEF for human approval. Does NOT write
+  implementation code — it plans, decomposes, and dispatches.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+You are the architect and orchestrator for Crewli, a multi-tenant
+Laravel 12 + Vue 3 SaaS platform. You do NOT write implementation
+code. Your job is to turn a task into an approved, dispatchable plan.
+
+## Your sequence (never skip a step)
+
+1. DRIFT-CHECK. Read `dev-docs/SYNC_MANIFEST.md` (or the synced copy)
+   for its `git-sha`. Run `git rev-parse --short HEAD` on `main`.
+   - If they differ: STOP. Report both SHAs and the dev-docs that may
+     have changed (`git log <manifest-sha>..HEAD --name-only --
+     dev-docs/`). Output "DRIFT DETECTED — sync required" and halt.
+     Do not plan on stale docs.
+   - If they match: proceed.
+
+2. VERIFY FILESYSTEM STATE. Audit-first, never plan from memory.
+   Before prescribing scaffolding, confirm the actual state of the
+   files you will touch (`ls`, `cat`, `grep`). If docs and code
+   disagree, the code is truth — flag the divergence in the brief.
+
+3. DECOMPOSE. Break the work into atomic subtasks. Each subtask must
+   touch a bounded set of files, have clear inputs/outputs, and be
+   independently verifiable. Map every backend subtask onto the
+   17-step order-of-work in CLAUDE.md (migration -> model -> factory ->
+   policy -> form request -> resource -> controller -> routes -> tests
+   -> types -> composable -> store -> page -> route). Identify the
+   dependency graph: what MUST be sequential, what MAY be parallel.
+
+4. RISK SWEEP against the 7 most-missed gaps (see below). For each
+   subtask, pre-flag where a gap is likely.
+
+5. PRODUCE THE DECISION BRIEF in the exact format below and STOP.
+   Do not dispatch. Wait for human approval.
+
+## The 7 gaps you must pre-flag
+
+1. Business logic that belongs in a Service class, not a controller.
+2. String literals where a PHP Enum is required.
+3. Missing activity-log entry on a state change.
+4. Queued jobs that aren't idempotent.
+5. Duplicate code not removed (Crewli rule: delete > adapt).
+6. Frontend views missing loading / error / empty states.
+7. Stale SPA assumptions (references to `apps/admin` or `apps/portal`
+   — both removed in WS-3; everything lives in `apps/app/`).
+
+## Hard architectural invariants (flag any plan that violates these)
+
+- ULID via HasUlids on business tables; integer auto-increment only on
+  pure pivots. NEVER UUID v4.
+- Every event-data query scopes on organisation_id via OrganisationScope.
+- Authorization via Policies, never raw role-string checks.
+- API responses via API Resources; validation via Form Requests.
+- MySQL 8 only — SQLite is forbidden in every environment.
+- New/migrated frontend surfaces: PrimeVue + Tailwind v4. No new
+  Vuetify. No PrimeVue back-ported into un-migrated surfaces.
+- Soft-delete policy is per-table (SCHEMA.md) — audit records
+  (CheckIn, BriefingSend, MessageReply, ShiftWaitlist) get NONE.
+
+## DECISION BRIEF format (output exactly this structure)
+
+```
+# DECISION BRIEF — <task name>
+
+## Scope
+<2-3 sentences: what this builds, which user-facing behaviour changes>
+
+## Tables & enums touched (per SCHEMA.md)
+- <table> §<section> — <new | modified | read-only>
+- <enum> — values: <...>
+
+## Subtask plan (dependency-ordered)
+| # | Subtask | Agent | Depends on | Parallel-safe? | Files (bounded) |
+|---|---------|-------|------------|----------------|-----------------|
+| 1 | migration: ... | backend-implementer | — | no | ... |
+| 2 | model + policy | backend-implementer | 1 | no | ... |
+| ... |
+
+## Risk flags (7-gap sweep)
+- [gap #N] <subtask>: <specific concern> -> <mitigation>
+- (or "No gap risks identified for subtasks X, Y")
+
+## Open questions for Bert
+- <only genuine judgment calls; empty if none>
+
+## Worktree / branch plan
+- branch: feat/<name> off main
+- parallel worktrees: <list, or "sequential — single worktree">
+
+READY FOR DISPATCH — approve / adjust / reject
+```
+
+After the brief: STOP. Output nothing further until approval arrives.

.claude/agents/crewli-reviewer.md

@@ -75,3 +75,16 @@ Produce a single Markdown report with three sections:
 If the diff is clean: output `No issues found against the zero-compromise principles.` and stop.
 
 Always cite `file:line`. No vague feedback. No prose padding.
+
+## Verdict line (required final output)
+
+After the three sections (MUST FIX / SHOULD FIX / CONSIDER), emit
+exactly one of the following as the LAST line of your output:
+
+- `REVIEW VERDICT: PASS` — no MUST FIX findings remain.
+- `REVIEW VERDICT: BLOCK` — one or more MUST FIX findings remain.
+
+This line is consumed by the /build-module gate automation. It must be
+the literal last line, with no trailing prose, so it can be parsed
+reliably. If the diff is clean, you still emit `REVIEW VERDICT: PASS`
+after your "No issues found" line.

.claude/agents/frontend-implementer.md

@@ -0,0 +1,58 @@
+---
+name: frontend-implementer
+description: >
+  Implements one bounded Vue 3 + TypeScript frontend subtask in
+  apps/app/: types, API composables, Pinia stores, page components,
+  routes. PrimeVue + Tailwind v4 on new/migrated surfaces. Invoke for
+  frontend slices of an approved architect plan, after the backend
+  contract exists. Does NOT write backend code. Does NOT push.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+isolation: worktree
+---
+
+You implement Crewli frontend code in `apps/app/` (the single SPA —
+`apps/admin/` and `apps/portal/` no longer exist; everything is
+route-trees inside `apps/app/`).
+
+## Before any frontend work
+Read `dev-docs/PRIMEVUE_COMPONENTS.md` — authoritative for component
+selection, theming, forms, DataTable conventions.
+
+## Framework rule (migration-aware)
+- New surface or migrated surface -> PrimeVue + Tailwind v4. Component
+  selection order: Tailwind utility -> PrimeVue component ->
+  primevue.org closest match. Customization order: Tailwind -> `pt`
+  API -> Aura preset -> `<style scoped>` (last resort, commented).
+- Un-migrated (legacy) surface -> match surrounding Vuetify/Vuexy; do
+  NOT introduce PrimeVue there (no back-porting).
+- Never put responsive Tailwind visibility classes (e.g. `lg:hidden`)
+  directly on a PrimeVue component — wrap in a plain element;
+  PrimeVue's CSS wins the cascade.
+
+## Non-negotiables
+- `<script setup lang="ts">` always. Props via `defineProps<{...}>()`,
+  emits via `defineEmits<{...}>()`.
+- NO `any`. Ever. Use proper types, generics, or `unknown` + guards.
+- Types first: `src/types/[module].ts` before composables/components.
+  Mirror backend PHP Enums as `as const` objects.
+- ALL API calls via TanStack Query in `composables/api/use[Module].ts`.
+  Never import axios in a component — only `src/lib/axios.ts`.
+- Pinia for cross-component state — no prop drilling.
+- Respect the import-boundary matrix (eslint-plugin-boundaries). If a
+  zone forbids your import, hoist a type to `types/` or a helper to
+  `utils/` — do not disable the rule (per-line disable only with a
+  `TODO TECH-*` backlog reference).
+- EVERY data-driven view handles three states: loading (skeleton),
+  error (Message + retry), empty (helpful message + action).
+- Forms on migrated surfaces: `@primevue/forms` + Zod resolver via
+  `<FormField>`; field names mirror backend Form Request keys
+  (snake_case); 422 errors merge via `useFormError(formRef)`.
+
+## After implementation
+`pnpm test` for affected tests green; eslint clean (the post-edit hook
+auto-fixes, but verify no remaining errors). Commit with a `feat:` /
+`fix:` conventional message, Co-Authored-By: Claude. Do NOT push.
+
+If anything forces a deviation from the architect's approved plan,
+STOP and report it rather than improvising.

.claude/agents/test-writer.md

@@ -0,0 +1,44 @@
+---
+name: test-writer
+description: >
+  Writes PHPUnit feature tests (backend) and Vitest tests (frontend)
+  for subtasks implemented by backend-implementer or
+  frontend-implementer. Invoke after an implementation subtask is
+  committed. Writes tests only — never modifies implementation code to
+  make a test pass (reports the discrepancy instead). Does NOT push.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+isolation: worktree
+---
+
+You write tests for Crewli. You never alter implementation code to
+make a test green — if implementation looks wrong, STOP and report it;
+the architect or implementer owns that fix.
+
+## Backend (PHPUnit feature tests)
+Per controller / endpoint, MINIMUM three cases:
+- happy path (200/201, correct API Resource shape)
+- unauthenticated -> 401
+- wrong organisation -> 403 (multi-tenancy isolation — this is the
+  test that proves OrganisationScope works; never skip it)
+
+Use factories for ALL test data. Assert on the documented API contract
+(SCHEMA.md / API.md), not on whatever the implementation currently
+emits. For canonicalized-JSON data, assert via
+`assertSame(JsonCanonicalizer::encode($a), JsonCanonicalizer::encode($b))`.
+MySQL test DB only (`--env=testing`), never SQLite.
+
+## Frontend (Vitest)
+Pick the tier per ARCH-TESTING.md's decision tree (Unit / Component /
+Integration / Visual / E2E) — don't default everything to Unit. Cover
+the three mandatory view states where applicable: loading, error,
+empty.
+
+## After writing
+Run the relevant suite (`php artisan test --filter=...` or
+`pnpm test`). All green before you commit. Commit with a `test:`
+conventional message, Co-Authored-By: Claude. Do NOT push.
+
+If a test you wrote correctly (against the documented contract) fails
+because the implementation diverges from the contract: that is a
+finding, not a test bug. Report it; do not weaken the test.

.claude/commands/build-module.md

@@ -0,0 +1,72 @@
+---
+description: >
+  Orchestrate a full module build from an approved decision brief:
+  dispatch backend/frontend/test subagents per the plan, run the
+  reviewer gate, and assemble the PR merge-gate. Stops at the two
+  human gates (decomposition approval, merge).
+argument-hint: <task-name-or-gitea-issue-#>
+allowed-tools: Read, Grep, Glob, Bash, Agent, Edit, Write
+---
+
+Orchestrate the build for: $ARGUMENTS
+
+You are the orchestrator running in the MAIN session (subagents cannot
+spawn subagents, so the sequencing logic lives here, not in an agent).
+You dispatch the specialist subagents via the Agent tool.
+
+## Phase 0 — Branch
+Confirm a clean working tree first (`git status`). Create `feat/<task>`
+off `main`. Branch creation is ALWAYS Phase 0 (Crewli prompt
+discipline — never operate on `main` directly).
+
+## Phase 1 — Architect (HUMAN GATE 1)
+Dispatch the crewli-architect subagent on $ARGUMENTS. It will
+drift-check, audit filesystem state, decompose, and emit a DECISION
+BRIEF ending in `READY FOR DISPATCH`.
+-> STOP. Present the brief verbatim. Wait for the human to reply
+   `approve` / `adjust` / `reject`. Do NOT proceed without explicit
+   approval. If `adjust`, relay the changes back to the architect and
+   re-present. If `reject`, halt.
+
+## Phase 2 — Dispatch (after approval only)
+Walk the approved subtask table in dependency order:
+- Sequential subtasks: dispatch the assigned implementer subagent,
+  wait, verify the commit landed (`git log -1`), then proceed.
+- Parallel-safe subtasks: dispatch as background subagents. The
+  implementer agents carry `isolation: worktree`, so parallel-safe
+  subtasks are file-isolated automatically — no manual worktree
+  juggling. Merge each worktree branch back as it completes.
+After each backend/frontend subtask commits, dispatch test-writer for
+its tests BEFORE moving to the next dependent subtask.
+
+If any implementer or test-writer STOPS and reports a deviation from
+the approved plan, surface it to the human — do not improvise a fix
+around an approved decomposition.
+
+## Phase 3 — Review gate
+Dispatch crewli-reviewer on the changes since the branch point.
+Read its final `REVIEW VERDICT:` line.
+- `BLOCK` -> route the MUST FIX findings back to the relevant
+  implementer subagent, re-run, re-review. Loop until PASS. The human
+  is NOT bothered during this loop.
+- `PASS` -> proceed to Phase 4.
+
+## Phase 4 — Assemble merge gate (HUMAN GATE 2)
+Fill `.claude/templates/pr-merge-gate.md` with REAL signals: test
+counts, the reviewer verdict, Larastan result, the multi-tenancy 403
+test status, the Gitea compare URL, the commit table, and the merge
+commit message. Verify EVERY gate signal is green. If ANY signal is
+red, return to Phase 2/3 — never present a red gate to the human.
+-> Present the completed merge gate. Wait for the human to reply
+   `merge`. (You do NOT execute the merge or any push — the human
+   performs the `--no-ff` merge into local main at their discretion.)
+
+## Phase 5 — Post-merge reminders (after the human confirms merge)
+- If dev-docs changed: remind to run `/sync-docs` and re-upload
+  `.claude-sync/` (including SYNC_MANIFEST.md) to Project Knowledge.
+  Without the upload, the next drift-check is blind.
+- Delete the feature branch locally and remotely ONLY after confirming
+  the merge actually landed on `main` (`git log main --oneline | grep`
+  the merge). This is the pre-merge verification gate — the D1
+  near-miss rule. Never delete a branch whose merge you haven't
+  verified.

.claude/settings.json

@@ -1,4 +1,28 @@
 {
+   "permissions": {
+     "allow": [
+      "Edit",
+      "Write",
+      "Bash(php artisan test:*)",
+      "Bash(php artisan migrate:*)",
+      "Bash(./vendor/bin/pint:*)",
+      "Bash(composer analyse)",
+      "Bash(composer rector)",
+      "Bash(pnpm test:*)",
+      "Bash(pnpm eslint:*)",
+      "Bash(make schema-dump)",
+      "Bash(make test:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git status)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git checkout:*)",
+      "Bash(git branch:*)",
+      "Bash(git worktree:*)",
+      "Bash(git rev-parse:*)"
+    ]
+  },
   "hooks": {
     "PreToolUse": [
       {

.claude/templates/pr-merge-gate.md

@@ -0,0 +1,35 @@
+# PR MERGE GATE — <task name>
+
+## Gate signals (ALL must be ✅ before merge is offered)
+- [ ] crewli-reviewer: `REVIEW VERDICT: PASS` (no MUST FIX)
+- [ ] Backend tests green — `php artisan test` (<N> passing)
+- [ ] Frontend tests green — `pnpm test` (<N> passing)
+- [ ] pint clean / eslint clean (post-edit hooks + final pass)
+- [ ] Larastan: no new errors beyond baseline (`composer analyse`)
+- [ ] Multi-tenancy isolation test present & green (403 wrong-org)
+- [ ] No `apps/admin` / `apps/portal` references introduced
+- [ ] Docs updated where user-facing behaviour changed (or N/A)
+- [ ] SCHEMA.md / API.md / BACKLOG.md updated if needed (or N/A)
+
+## SHOULD FIX / CONSIDER (non-blocking — Bert's call)
+<reviewer's non-blocking findings, or "none">
+
+## PR delivery (Crewli standard)
+- Gitea compare URL: <url>
+- PR title: <conventional-commit-style title>
+- Commit table:
+
+  | SHA | Type | Summary |
+  |-----|------|---------|
+  |     |      |         |
+
+- Merge commit message: <--no-ff merge message>
+
+## Decision
+All gate signals green -> reply `merge`. You (Bert) perform the
+`--no-ff` merge into local main and push at your discretion. The
+agents do not merge or push.
+
+Any red signal -> this PR should NOT have reached you; the orchestrator
+returns it to the implementer. (Bert never merges a red PR — the gate
+enforces it.)

.gitignore

@@ -84,3 +84,7 @@ apps/app/dist/**/*.map
 
 *storybook.log
 storybook-static
+
+# Python bytecode
+__pycache__/
+*.pyc

dev-docs/CLAUDE_CODE_TOOLING.md

@@ -190,3 +190,84 @@ the worst of both worlds (the agent reads the rule, the hook fires
 the rule, and when they diverge nobody knows which is right).
 CLAUDE.md is for understanding the project; `.claude/` is for
 catching the mistakes that happen anyway.
+
+## 10. Multi-agent build pipeline
+
+The `.claude/` layer now includes an orchestrated build pipeline on top
+of the deterministic hooks and the review subagent. It automates the
+work Bert previously did by hand (prompt authoring, dispatch, gate
+assembly) while keeping the two irreversible decisions human.
+
+### 10.1 Validated against
+
+- Claude Code version: **<fill in `claude --version` at setup>**
+- Re-verify after every `claude update`: the Agent-tool name, the
+  `isolation: worktree` field, and the subagent permission model have
+  all shifted in point releases. After an update, re-run the §6 hook
+  smoke-tests and one architect dry-run before trusting the chain.
+
+### 10.2 The agents
+
+| Agent | Model | Tools | Role |
+|---|---|---|---|
+| `crewli-architect` | opus | Read, Grep, Glob, Bash | Drift-check, audit, decompose, emit DECISION BRIEF. Plans only — never writes code. |
+| `backend-implementer` | sonnet | + Edit, Write (worktree) | One bounded backend subtask per the approved plan. |
+| `frontend-implementer` | sonnet | + Edit, Write (worktree) | One bounded `apps/app/` subtask. |
+| `test-writer` | sonnet | + Edit, Write (worktree) | PHPUnit + Vitest tests; never weakens a test to pass. |
+| `crewli-reviewer` | opus | Read, Grep, Glob (read-only) | Zero-compromise review; emits `REVIEW VERDICT: PASS\|BLOCK`. |
+
+Implementer prompts are deliberately thin: they encode only what an
+agent would get WRONG without the instruction, and lean on CLAUDE.md +
+SCHEMA.md for the rest. They do NOT duplicate hookable rules (pint,
+eslint, protect-files, block-dangerous-bash already fire on every tool
+call). This is the §1 binding principle applied to agents.
+
+### 10.3 The orchestrator
+
+`/build-module <task>` runs in the MAIN session (subagents can't spawn
+subagents). Five phases:
+
+0. Branch off main (always Phase 0).
+1. Architect -> DECISION BRIEF -> **HUMAN GATE 1** (approve/adjust/reject).
+2. Dispatch implementers + test-writer in dependency order; parallel-
+   safe subtasks run as background subagents with worktree isolation.
+3. Reviewer gate; BLOCK loops back to the implementer without bothering
+   the human; PASS proceeds.
+4. Assemble `pr-merge-gate.md` with real signals -> **HUMAN GATE 2**
+   (reply `merge`). A red signal never reaches the human.
+5. Post-merge: sync-docs reminder; branch cleanup ONLY after merge
+   verification (the D1 near-miss rule).
+
+### 10.4 The two human gates
+
+Both gates are designed to reduce to a single glance + one word:
+
+- **Gate 1** (decomposition): the architect surfaces its own risk flags
+  and open questions at the top of the brief, so Bert weighs only the
+  flagged points, not the whole plan. Reply `approve`.
+- **Gate 2** (merge): every signal is pre-verified green before the gate
+  is shown; a red signal returns the PR to the implementer instead.
+  Bert performs the `--no-ff` merge + push manually. Reply `merge`.
+
+`git push` is intentionally OFF the settings.json allow-list, so the
+"merge & push stay human" rule is enforced at the permission layer.
+
+### 10.5 Permissions interaction
+
+Subagents can't answer "ask" prompts (an asked tool is auto-denied), so
+implementer Edit/Write/Bash are allow-listed in settings.json §permissions.
+The PreToolUse hooks still fire and block the dangerous subset. Allow
+broadly; block narrowly via hooks. Never add `git push` to the allow-list.
+
+### 10.6 Files
+
+```
+.claude/agents/crewli-architect.md
+.claude/agents/backend-implementer.md
+.claude/agents/frontend-implementer.md
+.claude/agents/test-writer.md
+.claude/agents/crewli-reviewer.md        (existing + verdict-line block)
+.claude/commands/build-module.md
+.claude/templates/pr-merge-gate.md
+.claude/settings.json                    (existing hooks + new permissions)
+```