Imported from OCCLUSA/HS-CLINIC (.agent/AGENTS.md). Install upstream with npx skills add OCCLUSA/HS-CLINIC --skill .agent. Copyright stays with the author.

HS Clinic — Agent Operating Manual

⚠️ STOP. READ THIS ENTIRE FILE BEFORE DOING ANYTHING. Every agent session MUST start by reading this file. No exceptions.

Who You Are

You are an AI agent working on the HS Clinic website for Dr. Haitham Sharshar. This is a production medical website serving international patients. Mistakes have real consequences — broken pages lose patients, wrong medical info violates YMYL.

Agent Roster

MANDATORY Pre-Work Readings

Before writing ANY code, you MUST read and internalize these files in this order:

1. Debugging Lessons (CRITICAL — Read First)

File: .agent/skills/debugging-lessons/SKILL.md

This contains 10 hard-won lessons from production incidents. Each lesson cost hours of debugging. If you skip this, you WILL repeat the same mistakes. Read every lesson, understand the root cause, and apply the prevention rules to your work.

Key rules you MUST know before writing code:

• CORS: Always verify production domain is whitelisted in Sanity
• Slugs: Always query API directly, never trust what the UI shows
• Silent fallbacks: Never assume "page looks fine" means CMS data is flowing
• Field pipeline: Trace Schema → GROQ → Type → Hook → JSX (all 5 links)
• Hover dropdowns: NEVER use margin between trigger and panel — use padding
• Nav highlighting: Use startsWith() for items with child routes
• Duplicate docs: Check for multiple documents of same singleton type
• GROQ syntax: NEVER use order() with boolean expressions — use coalesce()
• CMS overrides: CMS data overrides code defaults — use canonical overrides for critical URLs
• CSS filters: Remove brightness/contrast filters when swapping image assets

2. Safety Protocol (MANDATORY for every code change)

File: .agent/workflows/safety-protocol.md

The 6-step process every task must follow. Skipping steps is not allowed.

3. Coding Rules (MANDATORY before writing any code)

File: .agent/workflows/coding-rules.md

Tech stack constraints, forbidden packages, image rules, Vite config rules.

4. Coordination Rules (MANDATORY for multi-agent work)

File: _AGENT_COORD/COORDINATION_RULES.md

5. Anti-Destruction Policy (ABSOLUTE — No Exceptions)

File: _AGENT_COORD/ANTI_DESTRUCTION_POLICY.md

Key rules you MUST follow:

• NEVER delete any source file without explicit user command
• NEVER rewrite an entire file — only patch/edit specific sections
• NEVER remove any existing feature, route, or component
• ALWAYS run npm run build before AND after changes
• If build breaks → immediately revert and report
• Protected files (require PROPOSAL): vite.config.ts, netlify.toml, tsconfig.json

6. Contextual Skills (Read based on task type)

The Three Laws of HS Clinic Development

Law 1: Read Before You Build

Every bug in the debugging-lessons file was caused by an agent who didn't know the context. The 5 minutes you spend reading saves 2 hours of debugging.

Law 2: Build Must Pass

npm run build with 0 errors is a non-negotiable gate. If it fails, you do NOT proceed. You fix it first.

Law 3: Never Break What Works

This is a live production website. The worst outcome is a regression. When in doubt, add a new component — don't modify an existing one.

Quick Architecture Reference

F:\HS CLINIC\
├── src/
│   ├── app/pages/services/     ← 4 service pillar pages (CMS-powered)
│   ├── hooks/useCmsData.ts     ← ALL Sanity hooks live here (SHARED: see OWNER_MAP)
│   ├── lib/sanityClient.ts     ← Sanity client + urlFor helper
│   └── lib/seo.ts              ← JSON-LD constants
├── studio/                     ← Sanity Studio (schemas, config)
├── _AGENT_COORD/               ← Multi-agent coordination hub
├── .agent/skills/              ← Agent memory (you are reading one now)
└── .agent/workflows/           ← Mandatory processes

CMS Data Pipeline (Memorize This)

Sanity Schema → GROQ Query → TypeScript Interface → Hook Return → JSX Rendering
     1              2              3                    4             5

If ANY link is missing, the data silently disappears and fallback content shows. This is the #1 source of "it's not working" bugs in this project.