Write Better AGENTS.md Files for Your AI Coding Agents

# CRM Application

## Build & Test
- Install: `pip install -r requirements.txt`
- Migrate: `python manage.py migrate`
- Run: `python manage.py runserver`
- Test: `pytest -x --tb=short`

## Database & ORM Rules
CRITICAL: Django ORM exclusively. No raw SQL ever.
- `select_related()` on every ForeignKey access
- `prefetch_related()` for M2M & reverse FK
- Chain `only()` or `defer()` on large models
- Target: <5 queries per view. N+1 = rejected PR
- Monetary fields: `DecimalField(max_digits=12, decimal_places=2)`
- Run `django-debug-toolbar` to verify query count

## Views & Code Style
- Class-based views only — no function views
- Every feature gets a dedicated method in the view
- Mixins for shared auth/permission logic
- Each method does ONE thing — no god-methods

## Naming (Strictly Enforced)
Kebab-case for everything:
- Files: `deal-stage-view.py` not `DealStageView.py`
- Templates: `contact-detail.html`
- URLs: `/deal-stages/` not `/dealStages/`
- Names must be self-explanatory without opening file

## Architecture
- `apps/contacts/` — Lead & customer models
- `apps/deals/` — Pipeline stages & tracking
- `apps/emails/` — IMAP sync via Celery
- `apps/reports/` — Dashboard aggregations

## Gotchas
- Deal stages are ordered — never skip a stage
- Contact merge = soft-delete; old record preserved
- Ask before guessing any business logic

# Online Store

## Build & Test
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm vitest run`
- Lint: `pnpm eslint . --fix`

## Frontend Rules
- Tailwind CSS v4+ (latest) — via CDN or Vite plugin
- No React. Plain HTML templates only.
- Semantic HTML is mandatory:
  Use `<header>`, `<main>`, `<nav>`, `<section>`, `<article>`, `<footer>`
- Favicon: 96x96 PNG per Google guidelines

## Accessibility (MANDATORY on every page)
- Every `<label>` must have `for=` matching its input `id=`
- Every `<section>` needs `aria-labelledby` → heading `id`
- All images: descriptive `alt` text, never empty
- Keyboard nav must work on all interactive elements
- Colour contrast minimum: 4.5:1 ratio
- Skip-to-content link on every page

## SEO Requirements
- Action-oriented H1 per page:
  ✔ "Shop Handmade Leather Bags Online"
  ✘ "Products" or "Home"
- Intro paragraph must ask the user to take action
- `itemscope`/`itemprop` Product schema on every product
- Unique `id` attrs namespaced by slug:
  `id="product-{{ slug }}-title"`
- No two pages share identical element identifiers

## Architecture
- `src/cart/` — Cart logic, pricing, discount calc
- `src/catalog/` — Product & category templates
- `src/checkout/` — Stripe payment flow
- Prices stored in cents (integer). Display = cents / 100
- Stripe webhook signature verified on every callback

# Task & Project Tracker

## Build & Test
- Install: `npm install`
- Dev: `npm run dev`
- Test: `npm run test`
- DB seed: `npm run db:seed`

## Naming Rules (Strictly Enforced)
Kebab-case for EVERYTHING. No exceptions.
- Files: `board-kanban-view.ts` ✔
         `BoardKanbanView.ts` ✘
- URLs: `/task-assignments/` ✔
        `/taskAssignments/` ✘
- DB tables: `task-comments` ✔
             `task_comments` ✘
- CSS classes: shared across pages
- IDs: namespaced per page slug
- File names must be descriptive enough that
  any developer understands without opening:
  ✔ `board-column-drag-handler.ts`
  ✘ `handler.ts` or `utils.ts`

## Code Style
- Class-based architecture — dedicated method per feature
- Each method does ONE thing. No 200-line methods.
- `src/boards/` — Kanban rendering & drag/drop
- `src/tasks/` — CRUD, assignments, status flow
- `src/teams/` — Workspace, roles, invitations
- `src/timeline/` — Gantt chart & activity feed

## Agent Behaviour Rules
IMPORTANT — read before writing any code:
- If business logic is unclear — ASK, don't assume
- Do NOT rename existing classes/methods/functions
- Do NOT change file names without approval
- Always specify exact file path when sharing code
- No summary docs, implementation guides, or READMEs
- No comparison docs showing before/after changes

# Invoicing Platform

## Build & Test
- Install: `pip install -r requirements.txt`
- Run: `python manage.py runserver`
- Test: `pytest --cov=apps`
- Lint: `ruff check . --fix`

## Performance Rules (NON-NEGOTIABLE)
Optimize every view for minimal SQL queries.
- `select_related()` on every FK access
- `prefetch_related()` for reverse/M2M relations
- Aggregate in queryset, NOT in Python loops:
  ✔ `.annotate(total=Sum('line_items__amount'))`
  ✘ `sum([i.amount for i in inv.items.all()])`
- Use `Subquery` + `OuterRef` for correlated lookups
- Pagination mandatory: 25 items per page
- `db_index=True` on fields used in filter/order_by
- requirements.txt: package names only, no versions

## HTML & JavaScript Rules
- Every interactive element: `data-*` attributes
  Example: `data-invoice-id="{{ inv.id }}"`
- JS selectors match namespaced IDs:
  `document.querySelector('[data-invoice-id]')`
- No inline `onclick` — use event delegation
- `for=` on every `<label>`, matching input `id=`

## Architecture
- `apps/invoices/` — Create, send, track, PDF
- `apps/clients/` — Profiles & address book
- `apps/payments/` — Stripe webhooks & bank
- `apps/recurring/` — Celery beat scheduling

## Gotchas
- Sent invoices: immutable — credit notes only
- Invoice numbers: sequential, never reuse/skip
- All amounts: `DecimalField`, never `FloatField`
- Tax rules by country — see `tax-config.py`

# Content Management System

## Build & Test
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm vitest run`

## SEO Rules (EVERY page, NO exceptions)
Google must see every generated page as
structurally unique — no two pages share
identical element identifiers or schema.

Page-specific requirements:
- Unique `id` attributes namespaced by slug:
  `id="post-{{ slug }}-title"`
  `id="post-{{ slug }}-content"`
  `id="post-{{ slug }}-comments"`
- `for=` on every `<label>` matching input `id=`
- `aria-labelledby` on sections → heading `id`
- `itemscope`/`itemprop` schema: Article, BlogPosting
- `data-*` attributes for all JS hooks

## H1 & Content Rules
- Action-oriented H1 per page:
  ✔ "Read Our Guide to Container Security"
  ✘ "Blog Post" or "Article"
- Intro paragraph: ask the user to do something
- No two pages share identical H1 or meta desc

## Dynamic Pages
- Tag archives, author pages: ALL ids, aria refs,
  and schema built from slug at render time
- Sitemap auto-generated on each publish
- Canonical URL on every page
- OG image auto-generated from post title

## Architecture
- `src/editor/` — Rich text editor (TipTap)
- `src/posts/` — CRUD, drafts, scheduling
- `src/media/` — Upload, CDN resize to WebP
- `src/seo/` — Meta tags, structured data

## Gotchas
- Slug changes auto-create 301 redirect records
- Workflow: Draft → Review → Published only
- Never delete media — flag as unused instead

# HR Management System

## Build & Test
- Install: `pip install -r requirements.txt`
- Migrate: `python manage.py migrate`
- Run: `python manage.py runserver`
- Test: `pytest apps/ -x`

## Full-Stack Conventions
Backend:
- Django class-based views, dedicated methods each
- Django ORM exclusively — zero raw SQL
- `select_related`/`prefetch_related` on every queryset
- requirements.txt: package names only, no versions
- Kebab-case file names: `employee-detail-view.py`

Frontend:
- Tailwind CSS latest version via CDN
- Semantic HTML: `<main>`, `<section>`, `<nav>`, `<footer>`
- Favicon: 96x96 PNG per Google guidelines
- No React — server-rendered Django templates only
- `for=`/`id=` on every label/input pair
- `aria-labelledby` on sections → heading `id`

## Security (STRICT)
- PII encrypted at rest (django-encrypted-model-fields)
- RBAC: Admin > HR Manager > Employee
- Payroll: HR Manager+ only, row-level permission
- SSO via SAML — no password-based auth
- Audit log on every `save()` and `delete()`
- Data exports require approval workflow
- Session timeout: 30 min inactivity

## Architecture
- `apps/employees/` — Profiles, org chart, search
- `apps/leave/` — PTO requests, balance calc
- `apps/payroll/` — Salary processing, payslip PDF
- `apps/onboarding/` — Checklists & docs

## Agent Behaviour Rules
READ THIS BEFORE WRITING ANY CODE:
- Do NOT change existing class/method/function names
- Do NOT rename files without explicit approval
- Do NOT guess business logic — ask first
- Do NOT create summary docs or READMEs
- Always specify exact file path in responses
- Performance first: every query counts
- When in doubt about anything — ASK