TenantAtlas/docs/ai-coding-rules.md

TenantPilot AI Coding Rules

Status: 2026-05-15 Use for: Codex, Claude, Cursor, Windsurf, and other AI coding agents.

Stack

• PHP 8.4.15 runtime; Composer constraint currently ^8.2.
• Laravel 12.52.
• Filament 5.2.1 with required upgrade target >=5.3.5 because of advisory.
• Livewire 4.1.4. Never propose Livewire v3 APIs.
• Tailwind CSS 4.2.2 with Vite 7.3.2.
• PostgreSQL 16 via Sail/Dokploy.
• Pest 4.3 and PHPUnit 12.
• Queue/cache default to database locally; Redis is available.

Mandatory First Reads

• AGENTS.md
• .specify/memory/constitution.md
• Relevant specs/<NNN>-<slug>/spec.md, plan.md, tasks.md
• docs/research/filament-v5-notes.md for Filament uncertainty
• Relevant guideline file in docs/*-guidelines.md

Forbidden APIs and Patterns

• No Filament v3/v4 APIs.
• No Livewire v3 references.
• No panel providers in bootstrap/app.php; Laravel 12 panel providers belong in bootstrap/providers.php.
• No Graph calls outside GraphClientInterface.
• No Graph calls during UI render.
• No destructive action without ->action(...), ->requiresConfirmation(), authorization, audit, and test.
• No business-critical logic buried in Filament closures.
• No public/local uploaded filenames from preserveFilenames() without approved mitigation.
• No new persisted entity, enum/status family, abstraction, or taxonomy without constitution proportionality review.
• No new package without package-governance review.

Architecture Rules

• Filament is UI composition.
• Services/actions own business behavior.
• Jobs own remote/long-running work.
• Policies/gates own authorization.
• Models own persistence relationships, casts, scopes, and small invariants.
• Migrations own integrity through constraints and indexes.
• Tenant-owned data must always be workspace- and tenant-scoped.

Filament Rules

• Every globally searchable resource needs a View or Edit page and $recordTitleAttribute; otherwise disable global search.
• Tables need default sort, domain-specific empty state, and query-safe columns.
• Relationship columns require eager loading or query optimization.
• Use UiEnforcement or WorkspaceUiEnforcement for capability-aware action state.
• Prefer render hooks and CSS hook classes over publishing Filament internals.
• Add php artisan filament:assets to deployment when Filament assets are registered.

Testing Rules

• Use Pest 4.
• Test pages/relation managers/widgets as Livewire components.
• Use Filament action helpers for action tests.
• Add policy tests for new policies.
• Add tenant isolation tests for tenant-owned models.
• Use PostgreSQL lane for JSONB, partial indexes, locks, composite FKs, and migrations.
• Browser tests are for critical workflows and JS/visual smoke, not every CRUD page.

Security Rules

• Deny unauthorized workspace/tenant access as not found.
• Never log secrets, tokens, raw credential payloads, or raw sensitive Graph payloads.
• Provider credentials use encrypted storage.
• File uploads default to private disks, random names, MIME/size validation, and tamper prevention when applicable.
• Production requires APP_DEBUG=false.
• Dependency audits must be clean or explicitly accepted.

Performance Rules

• Use JSONB for queryable snapshot, backup, restore, evidence, and audit payloads.
• Add indexes for proven query paths only.
• Move Graph, restore, backup, export, and report work to queues.
• Make jobs idempotent and observable through OperationRun.
• Honor Microsoft Graph Retry-After; use exponential backoff with jitter when missing.

Response Format for AI Code Changes

Every implementation response must state:

1. Livewire v4 compliance.
2. Panel provider location if Filament panel code changed.
3. Global search status for changed resources.
4. Destructive/high-impact actions and how confirmation + authorization + audit are handled.
5. Asset strategy and whether filament:assets is required.
6. Tests run and tests added/updated.
7. Deployment impact: env, migrations, queues, scheduler, storage.