# 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.