agents.md example

AGENTS.md

REDACTED Rebuild — LLM Agent Guide

These instructions are for LLM agents assisting on this Django rebuild project.

1. Project Context & Role

• Project: Re-platforming a legacy PHP site to Django + HTMX with modern Docker tooling.
• Current Phase: Phases 0-7 are complete. We are now in Phase 8: Frontend & Final Testing. The data migration is structurally complete but requires rigorous validation. The final phase will be deployment.
• Role: Act as a senior Django engineer specializing in HTMX-driven architectures and robust testing.
• Tone: Concise, actionable guidance; cite official docs when helpful.

2. Development Environment

Prerequisites

• Docker & Compose ≥ v25
• Python 3.12 (containerized)
• 4GB+ RAM, 2GB+ disk space

Quick Start Commands

# Setup
cp .env.example .env
docker-compose up -d --build

# Initial setup inside container
docker-compose exec app bash
python manage.py migrate
python manage.py createsuperuser --noinput

Key URLs

• App: http://localhost:8000
• Admin: http://localhost:8000/admin
• Health: http://localhost:8000/healthz
• Metrics: http://localhost:8000/metrics
• Jaeger: http://localhost:16686
• MailHog: http://localhost:8025

3. Workflow Expectations

1. Phase Discipline: Work strictly within the Phase 8 scope: frontend implementation, writing comprehensive tests, and validating the data migration.
2. Development Flow:
   • Use docker-compose exec app bash for all Django commands.
   • Run pytest continuously. All new frontend interactions and business logic must be covered.
   • Check docker-compose logs -f app for real-time debugging.
   • Verify CI passes before suggesting merges.
3. Code Changes:
   • Provide complete, copy-pastable code snippets for views, templates, and tests.
   • Write tests for all new functionality.
   • Follow conventional commit messages (feat:, fix:, test:, chore:).

4. Technical Standards

Topic	Standard
Settings	Split: base.py, dev.py, prod.py, test.py
Testing	pytest, pytest-django, ≥95% coverage, factory_boy for fixtures
Logging	Structured JSON (prod), human-readable (dev)
Observability	OpenTelemetry + Prometheus + Jaeger
Commits	Conventional (feat:, fix:, docs:, etc.)
Python	3.12, full type hints, dataclasses, service layer pattern
Frontend	HTMX for server-rendered partials, Alpine.js for client-side interactivity

5. Core Models

Current Schema

• Site: Multi-tenant support (e.g., lllreptile.com, vistapetsupply.com).
• Store: Business configuration per Site.
• User: Custom user model using email for authentication.
• Contact: One-to-one profile with user details.
• Address: Multiple addresses per Contact.
• AccountMeta: QuickBooks IDs and internal business notes.
• AuditLog: Generic logging for tracking model changes.
• [E-commerce Models]: (Via Django Oscar or custom) Product, Category, Order, Basket, etc. Schema needs verification during testing.
• [CMS Models]: (Via Wagtail) ContentPage, BlogIndexPage, HomePage, etc. Integration with multi-tenant sites needs validation.

Admin Interface

• All core models are registered with the Django admin.
• Custom admin views are in place for Site management.
• AuditLog provides a read-only history of changes.

6. Key Architectural Patterns

Service Layer

Business logic is encapsulated in service functions rather than fat models or views. This improves testability and reusability. Services live in app/services.py files.

• Example: orders.services.place_order(*, user: User, cart: Cart) -> Order

HTMX-driven Views

• Views are designed to return either a full page or an HTML fragment based on the HX-Request header.
• Use render_htmx template tags or decorators to simplify logic.
• Avoid complex state management on the frontend; keep state on the server.

ViewComponents

Reusable template components (e.g., cards, modals, forms) are managed using the django-viewcomponent library. This keeps templates DRY and easier to test.

7. Frontend Workflow

• Django Coomponents: We have django-components and should make the most use out of it. Components go in src/[app]/components/[component].{py,html}. The way django components works with htmx is you register the component at a url and you can get the component directly.
• Tailwind CSS: Use the npm run watch command (via docker-compose exec node) to compile CSS during development.
• HTMX: All dynamic page updates should be handled via HTMX attributes in templates (hx-get, hx-post, etc.).
• Alpine.js: Use for small, localized UI interactions that don't require a server round-trip (e.g., toggling a dropdown, managing modal visibility). Use the x-data, x-show, and @click directives. See docs/frameworks/alpine-js.md.
• Daisy UI: Our primary component library. Use pre-built components whenever possible. See docs/frameworks/daisyui.md.

8. Testing Strategy

The current focus is on integration and end-to-end testing of the frontend and migrated data.

# Run the full test suite
pytest

# Run with coverage report (ensure >=95%)
pytest --cov=src --cov-report=html

# Run tests for a specific app or module
pytest tests/apps/accounts/ -v

# Run frontend-specific tests
pytest tests/frontend/

Testing Priorities

1. Migration Validation: Write data integrity tests that compare critical record counts and field values between the legacy DB dump and the new Django models.
2. User Journeys: Implement end-to-end tests for key flows (e.g., user registration, login, add-to-cart, checkout).
3. HTMX Interactions: Ensure all HTMX-powered UI elements are tested to confirm they render the correct partials and handle user input as expected.

9. Common References

• docs/REBUILD.md: Project phases and decisions
• docs/migration-playbook.md: Data migration validation steps
• docs/deploy.md: Deployment procedures (upcoming)
• docs/frameworks/htmx.md: htmx patterns and pitfalls
• docs/frameworks/alpine-js.md: Alpine.js usage patterns
• Django 5.0 Documentation: https://docs.djangoproject.com/en/5.0/
• pytest-django: https://pytest-django.readthedocs.io/en/latest/
• OpenTelemetry Django: https://opentelemetry.io/docs/instrumentation/python/django/

10. Next Actions

Before implementing new features, confirm:

1. Does the work align with Phase 8 (Frontend & Testing)?
2. Are comprehensive tests included (≥95% coverage)? This is non-negotiable.
3. Have you validated the functionality against the migrated data?
4. Are environment variables for any new services documented in .env.example?

When in doubt, focus on testing. Assume nothing works until a test proves it does.

---

Update this guide when project conventions or requirements change.