TenantAtlas/docs/AGENTS-draft.md

AGENTS.md Draft Addendum

This draft is intentionally short. It is meant to be merged into the root AGENTS.md after review, not to replace the existing Spec Kit workflow and multi-agent coordination rules.

Enterprise Rule Sources

Agents must treat these files as project rules:

• docs/stack-overview.md
• docs/architecture-guidelines.md
• docs/filament-guidelines.md
• docs/security-guidelines.md
• docs/testing-guidelines.md
• docs/performance-guidelines.md
• docs/deployment-checklist.md
• docs/package-governance.md
• docs/ai-coding-rules.md

Version Rules

• Laravel 12, Filament 5, Livewire 4, Tailwind CSS 4, Pest 4, PHPUnit 12, PostgreSQL 16.
• Do not use Filament v3/v4 or Livewire v3 APIs.
• Laravel 12 panel providers are registered in bootstrap/providers.php.
• Search official version-specific docs before changing Laravel, Filament, Livewire, Pest, Tailwind, or PostgreSQL behavior.

Code Rules

• Keep Filament resources/pages thin. Extract non-trivial business logic into actions/services/jobs.
• All Graph calls go through GraphClientInterface.
• No Graph calls during UI rendering.
• Every tenant-owned query is workspace- and tenant-scoped.
• Every new resource-backed model has a policy or a documented exception.
• Every destructive/high-impact Filament action has confirmation, authorization, audit logging, notification, and tests.
• New JSON payload storage defaults to PostgreSQL JSONB when it is retained or queryable.
• Jobs must be idempotent, observable, retry-aware, and safe to re-run.

Security and Testing Rules

• Run composer audit and corepack pnpm audit --audit-level moderate for dependency work and before release.
• Use Pest 4 and Filament action testing helpers.
• Use the PostgreSQL test lane for migrations, JSONB, partial indexes, locks, and tenant-isolation constraints.
• Never log secrets, tokens, credential payloads, or raw sensitive Graph payloads.

Deployment Rules

• Sail-first locally; Dokploy-first for staging/production.
• Production must set APP_DEBUG=false.
• Production workers use supervised queue:work, not queue:listen.
• Deployments that use Filament registered assets must run php artisan filament:assets.
• Staging validation is required before production promotion.