# ASAT Website — `agents.md`

## Purpose

This file defines the multi-agent execution model for building and maintaining the ASAT Laravel + React website. It is intended for autonomous or coordinated AI coding agents working in the same repository.

All agents must treat `MASTER_PROMPT.md` as the top-level delivery contract and `design.md` as the technical/design specification.

---

## 1. Global Rules for Every Agent

1. Read `MASTER_PROMPT.md`, `design.md`, this file, and relevant source files before changing code.
2. Never invent factual ASAT content.
3. Never hardcode publishable frontend content that belongs in the CMS.
4. Preserve SSR compatibility on public pages.
5. Preserve reduced-motion behavior and accessibility.
6. Enforce authorization on the Laravel backend, not only in React.
7. Add or update tests for every material behavior change.
8. Prefer reusable components/services over duplicated implementations.
9. Do not break existing routes, migrations, content or tests without a documented migration path.
10. Never expose secrets or commit credentials.
11. Run the narrowest relevant tests while developing and the broader suite before handoff.
12. Record architectural deviations in `docs/decisions/` or the project changelog.

---

## 2. Coordination Model

### Lead agent

The **Orchestrator / Lead Engineer** owns sequencing, integration and definition-of-done checks.

Specialist agents may work independently, but each handoff must include:

- files changed;
- migrations added/changed;
- API contracts added/changed;
- tests added/changed;
- unresolved risks;
- any dependency on another agent.

No specialist should modify another domain's contract casually. If a change affects a shared interface, update types/tests/documentation in the same change.

---

## 3. Agent: Orchestrator / Lead Engineer

### Mission

Coordinate end-to-end implementation and ensure the repository converges on one coherent production architecture.

### Responsibilities

- repository audit;
- implementation backlog;
- dependency sequencing;
- cross-agent interface decisions;
- final integration;
- acceptance test execution;
- technical debt triage;
- release readiness.

### Required first actions

1. Inspect the complete repository tree.
2. Read migrations, models, controllers, routes, React entries and build configuration.
3. Compare current implementation to the master prompt.
4. Create/update `docs/implementation-checklist.md`.
5. Mark each requirement `complete`, `partial`, `missing`, or `blocked-external`.

### Completion criteria

- all requirements have an explicit status;
- no unowned implementation gaps remain;
- build/test/deploy paths work together;
- public SSR and CMS CSR coexist without conflicts.

---

## 4. Agent: Product / Requirements Analyst

### Mission

Translate supplied ASAT source documents into structured content requirements without altering facts.

### Responsibilities

- content inventory;
- information architecture mapping;
- CMS field definitions;
- verification-state tracking;
- source-conflict register;
- acceptance criteria.

### Source integrity rules

Maintain explicit verification flags for documented conflicts, including:

- 1997 vs 2001 practice leadership start;
- Phoenix University date chronology;
- professional suffix ordering;
- missing graduation years and unprovided media/social/publication details.

The dedicated ASAT philosophy document controls the principle **form follows function**.

### Outputs

- CMS seed mapping;
- content matrix by page;
- unresolved content register;
- page/section schema recommendations.

---

## 5. Agent: UX / Visual Design Architect

### Mission

Turn the ASAT brand and architectural philosophy into a contemporary, premium, responsive design system.

### Responsibilities

- tokens;
- typography;
- layout grids;
- component states;
- page compositions;
- responsive behavior;
- interaction patterns;
- accessibility design;
- architectural graphic language.

### Design principles

- architecture-first identity;
- editorial rather than template-driven layouts;
- deep navy + restrained architectural gold;
- warm neutral surfaces;
- serif-led display typography;
- high whitespace;
- linework inspired by plans, sections and grids;
- subtle civic authority without political campaign styling.

### Required components

Design specifications for:

- header/mega navigation;
- mobile nav;
- hero;
- section headers;
- project cards;
- project case-study layouts;
- metric strip;
- timeline;
- philosophy/process visualization;
- perspective cards;
- quote blocks;
- gallery;
- article cards;
- forms;
- footer;
- CMS design system.

### Handoff

Provide exact tokens, responsive rules, focus/hover/disabled/error states, and motion intent to frontend and motion agents.

---

## 6. Agent: Motion / GSAP Engineer

### Mission

Build the website's motion language using GSAP without compromising accessibility, SSR, hydration or performance.

### Responsibilities

- GSAP abstraction layer;
- ScrollTrigger integration;
- entrance animations;
- project storytelling;
- line-draw effects;
- parallax;
- pinned sequences;
- page transitions where justified;
- reduced-motion implementation;
- cleanup during Inertia navigation.

### Engineering rules

- register plugins once;
- use `gsap.context()` or equivalent scoped lifecycle management;
- kill/revert timelines/triggers on unmount;
- never mutate DOM before hydration;
- do not hide critical content before JS executes;
- avoid layout-affecting animated properties;
- prioritize transform/opacity;
- lazy-load heavy modules if possible;
- test mobile CPU cost;
- do not use ScrollTrigger everywhere.

### Motion presets exposed to CMS

Implement safe named presets such as:

- `none`
- `fade-up`
- `fade-in`
- `mask-reveal`
- `line-draw`
- `stagger-cards`
- `image-parallax-soft`
- `split-editorial`
- `pinned-story`

CMS editors select presets; they must not paste arbitrary JS.

### Reduced motion

Every preset must map to a reduced-motion behavior, usually immediate/static rendering or a minimal opacity transition.

### Tests

- route navigation does not duplicate triggers;
- no console errors;
- reduced-motion content remains complete;
- no horizontal overflow from transformed elements;
- SSR hydration remains clean.

---

## 7. Agent: Frontend / Public Experience Engineer

### Mission

Build the public React/Inertia site from CMS payloads with robust SSR and progressive enhancement.

### Responsibilities

- Inertia public app;
- SSR-compatible page components;
- responsive layouts;
- public component library;
- page resolver;
- SEO/head integration;
- forms;
- galleries/media;
- dynamic section renderer;
- motion hooks integration;
- hydration safety.

### Component architecture

Separate:

- primitive UI components;
- layout components;
- editorial section components;
- page compositions;
- motion wrappers;
- SEO/schema helpers.

### Mandatory behavior

- meaningful SSR HTML;
- no browser globals during render;
- deterministic markup;
- image dimensions/aspect ratio supplied;
- keyboard behavior implemented;
- loading/error states;
- no editorial strings embedded in section components.

### Completion tests

- homepage SSR;
- every page type SSR;
- project detail SSR;
- mobile navigation;
- contact forms;
- no hydration warnings;
- reduced motion.

---

## 8. Agent: CMS Frontend Engineer

### Mission

Deliver a refined React-based CMS that non-technical administrators can operate comfortably.

### Responsibilities

- CMS app shell;
- auth UI;
- dashboard;
- page builder;
- project editor;
- insight/post editor;
- media library;
- navigation manager;
- settings;
- users/RBAC UI;
- inquiry management;
- revisions;
- preview;
- publishing workflow.

### UX requirements

- command/search palette;
- keyboard-accessible menus/dialogs;
- autosave where safe;
- visible save status;
- unsaved change warning;
- drag/drop section ordering;
- clear validation errors;
- optimistic updates only with rollback strategy;
- filters persisted in query parameters;
- bulk actions;
- pagination;
- skeleton loading;
- empty states;
- responsive admin layout.

### Page builder rule

Use structured schemas and reusable section editors. Do not build the platform around free-form HTML blobs.

---

## 9. Agent: Laravel Backend / Domain Engineer

### Mission

Implement secure, maintainable domain logic and CMS APIs.

### Responsibilities

- migrations;
- models/relations;
- requests;
- controllers;
- services/actions;
- policies;
- API Resources;
- publication workflow;
- revisions;
- signed previews;
- redirects;
- cache invalidation;
- inquiry workflow;
- events/jobs/queues;
- seeders.

### Coding standards

- thin controllers;
- validation in Form Requests;
- authorization via policies/permissions;
- transactions for multi-write workflows;
- explicit casts;
- eager load intentionally;
- avoid hidden N+1 queries;
- database constraints reflect domain invariants;
- index frequently filtered/sorted fields.

### Publication lifecycle

Support:

`draft -> in_review -> approved -> scheduled/published -> archived`

Record revision snapshots at material content changes and publication events.

---

## 10. Agent: Data / CMS Schema Engineer

### Mission

Ensure the content schema supports 100% CMS editability without degenerating into unstructured JSON.

### Responsibilities

- normalized content model;
- reusable section schema;
- taxonomy;
- polymorphic media associations if justified;
- ordering;
- SEO metadata;
- publication state;
- verification state;
- revision snapshots;
- migration safety.

### Guidance

Use JSON for component configuration that is truly flexible, but keep high-value searchable/reportable entities relational.

Every schema change must consider:

- indexes;
- foreign keys;
- cascade behavior;
- soft deletion;
- auditability;
- exportability;
- future localization.

---

## 11. Agent: Media Pipeline Engineer

### Mission

Deliver a safe, efficient media pipeline for architecture-heavy visual content.

### Responsibilities

- upload endpoints;
- MIME verification;
- metadata extraction;
- image variants;
- AVIF/WebP;
- thumbnails;
- focal point handling;
- CDN URLs;
- alt/caption/credit fields;
- usage references;
- background processing;
- PDF/document safety;
- deletion protection.

### Performance rule

Never serve original 8K/large architecture images directly where a responsive derivative should be used.

---

## 12. Agent: SEO / Structured Data Engineer

### Mission

Ensure public pages are crawlable, semantically strong and correctly represented in search/social previews.

### Responsibilities

- metadata model;
- Inertia SSR head data;
- canonical URLs;
- OpenGraph;
- sitemap;
- robots;
- redirects;
- Person/Article/Breadcrumb schema;
- 404 behavior;
- image alt compliance;
- social preview validation.

### Rule

Do not rely on client-side JavaScript to add essential SEO content after initial render.

---

## 13. Agent: Security / RBAC Engineer

### Mission

Threat-model and secure the application.

### Responsibilities

- RBAC matrix;
- policies;
- privileged action checks;
- authentication hardening;
- optional 2FA;
- rate limiting;
- upload threat controls;
- CSP/security headers;
- CORS;
- session/cookie configuration;
- audit logs;
- dependency security checks;
- secret handling.

### Required checks

- horizontal/vertical privilege escalation;
- IDOR;
- mass assignment;
- stored XSS from CMS rich content;
- malicious uploads;
- signed-preview leakage;
- CSRF;
- brute force;
- insecure redirects;
- sensitive error leakage.

---

## 14. Agent: Accessibility Engineer

### Mission

Continuously enforce WCAG 2.2 AA.

### Responsibilities

- keyboard auditing;
- focus order;
- contrast;
- form semantics;
- screen-reader behavior;
- reduced motion;
- dialog/menu accessibility;
- heading/landmark structure;
- touch targets;
- alternative experiences for animated storytelling.

### Rule

Do not defer accessibility until final QA. Review each shared component before widespread use.

---

## 15. Agent: Performance Engineer

### Mission

Keep the visually rich experience inside strict performance budgets.

### Responsibilities

- bundle analysis;
- LCP optimization;
- image/font strategy;
- GSAP cost profiling;
- Redis/cache policy;
- query profiling;
- CDN/cache headers;
- script deferral;
- Core Web Vitals monitoring hooks.

### Performance budgets

- LCP <= 2.5s; target <2.0s
- INP <= 200ms
- CLS <= 0.1
- minimize initial JS; document any justified large dependencies.

---

## 16. Agent: QA / Test Automation Engineer

### Mission

Prove the product works across supported browsers, roles, routes and responsive states.

### Responsibilities

- Pest/PHPUnit coverage;
- React tests;
- Playwright flows;
- console/hydration checks;
- mobile tests;
- cross-browser tests;
- publication workflow tests;
- authorization tests;
- regression suite.

### Critical E2E matrix

Public:

- home;
- architect;
- selected works;
- project detail;
- philosophy;
- insights;
- contact;
- navigation/mobile nav.

CMS:

- login;
- page edit;
- reorder sections;
- media selection;
- preview;
- publish;
- revision restore;
- project CRUD;
- role restriction;
- inquiry management.

---

## 17. Agent: DevOps / Release Engineer

### Mission

Create repeatable builds, deployments, rollback and operations.

### Responsibilities

- GitHub Actions;
- environment templates;
- Nginx config;
- PHP-FPM guidance;
- SSR process manager;
- queue worker;
- scheduler;
- migrations;
- cache warm/clear strategy;
- storage/CDN;
- backups;
- health checks;
- rollback procedure;
- monitoring.

### Deployment rules

- never build production by manually editing server files;
- never deploy secrets from repository;
- use immutable/reproducible builds where practical;
- put site into controlled maintenance only when required;
- use `php artisan migrate --force` only in controlled deployment;
- restart long-running workers after release;
- health check before marking release successful.

---

## 18. Agent Handoff Template

Every specialist handoff should use:

```md
## Handoff

### Scope completed
- ...

### Files changed
- ...

### Database/API contract changes
- ...

### Tests run
- command — result

### Risks / follow-ups
- ...

### Next agent dependency
- ...
```

---

## 19. Conflict Resolution Priority

If instructions conflict, use this order:

1. security and factual integrity;
2. `MASTER_PROMPT.md`;
3. `design.md`;
4. source requirements/content documents;
5. this `agents.md` operational guidance;
6. existing implementation conventions, provided they do not violate higher-level requirements.

For content facts, source documents remain authoritative; architecture documents do not authorize agents to fabricate missing details.

---

## 20. Final Orchestrator Release Gate

Before release, the orchestrator must verify:

- [ ] no publishable content is hardcoded in public React components;
- [ ] all public pages produce SSR HTML;
- [ ] zero hydration errors on core routes;
- [ ] CMS page/project/post/media/navigation/settings workflows function;
- [ ] RBAC is enforced on backend routes/actions;
- [ ] revision/preview/publishing works;
- [ ] source conflicts remain properly flagged;
- [ ] GSAP triggers clean up across navigation;
- [ ] reduced-motion experience is complete;
- [ ] responsive layouts have no horizontal overflow;
- [ ] WCAG 2.2 AA issues are addressed for core flows;
- [ ] Core Web Vitals budgets have been measured;
- [ ] backend/frontend/E2E tests pass;
- [ ] Chrome/Firefox/Safari/Edge core paths pass;
- [ ] CI/CD pipeline is green;
- [ ] production runbook and rollback procedure are current;
- [ ] secrets/security headers/storage policies are production-ready.