Skip to content

AGENTS.md

Latest commit

 

History

History
254 lines (189 loc) · 12.9 KB

AGENTS.md

File metadata and controls

254 lines (189 loc) · 12.9 KB

AGENTS.md

A comprehensive guide for AI agents working on the modAI-chat project, providing context and instructions for effective development assistance.

AI WAY OF WORKING (MANDATORY)

This project is designed for AI-first development. All agents MUST follow these protocols:

0. Context Loading (ALWAYS FIRST)

  • RULE: ALWAYS read project context before starting ANY task.
  • PROCESS:
    1. Read {frontend/omni|backend/omni}/docs/architecture/*.md to understand frontend system design.
    2. Read {frontend/omni|backend/omni}/docs/learnings/*.md to learn from past corrections.
    3. Check .agents/skills/ for relevant technology skills.
  • WHY: These files contain critical knowledge from past work. Skipping them leads to repeated mistakes and inconsistent code.

1. Technology Skill Acquisition

  • RULE: NEVER work on a technology without verified skills.
  • PROCESS:
    1. If a task involves a new technology/library: STOP.
    2. Perform a web search or use the dedicated task agent to investigate best practices, common pitfalls, and API usage.
    3. Document findings in .agents/skills/<tech-name>/SKILL.md.
    4. Only proceed with implementation once the skill file exists and is reviewed.

2. Architecture First

  • RULE: Architecture MUST be adapted/reviewed before coding starts.
  • PROCESS:
    1. For any new feature/package, update {frontend/omni|backend/omni}/docs/DECISIONS.md.
    2. Ensure the architecture aligns with the overall project goals.

3. Learning from Corrections

  • RULE: If the user corrects a mistake, update the instructions immediately.
  • PROCESS:
    1. Identify the root cause of the mistake.
    2. Update {frontend/omni|backend/omni}/docs/learnings/INSTRUCTION_UPDATES.md with a new rule to prevent recurrence.
    3. Append relevant rules to AGENTS.md if they are project-wide.

4. Test-Driven Completion

  • RULE: A task is NOT done until tests pass.
  • PROCESS:
    1. Every work package MUST include tests.
    2. Tests MUST pass before the task is marked completed in the todo list.
    3. NO WHITEBOX TESTING: Tests MUST only test the public interface / observable behavior. NEVER test private/internal functions directly. Private helpers are covered indirectly through the public API. This applies to every layer: backend modules, API endpoints, frontend components, and utility files.

5. Code Quality Gate (MANDATORY)

  • RULE: ALWAYS run linting and formatting before completing any code task.
  • PROCESS:
    1. Run code formatters and code linters
    2. Fix any issues before marking task as complete.

6. Documentation Updates for API Changes (MANDATORY)

  • RULE: When adding, modifying, or deleting API endpoints, ALWAYS update documentation.
  • PROCESS:
    1. Check {frontend/omni|backend/omni}/README.md for endpoint references and usage examples.
    2. Check {frontend/omni|backend/omni}/docs/architecture/*.md for endpoint documentation.
    3. Check any other docs that reference API endpoints.
    4. Update all affected documentation before marking task as complete.

7. Changelog Updates (MANDATORY)

  • RULE: After completing any code change, update the CHANGELOG.md in the affected sub-project root if one exists.
  • PROCESS:
    1. Check whether frontend/omni/CHANGELOG.md or backend/omni/CHANGELOG.md exists for the changed sub-project.
    2. Add a concise entry under the Unreleased section (or the latest version block if no Unreleased section is present) describing what was added, changed, or fixed.
    3. Follow the existing format of the file (typically Keep a Changelog style).
    4. Update the changelog before marking the task as complete.

Project Overview

modAI-chat is a full-stack application with separate backend and frontend components:

  • Backend: Python FastAPI REST API with SQLModel persistence
  • Frontend: Svelte TypeScript SPA with modular architecture
  • E2E Tests: Tests covering all different frontends with the (if needed) backend

General Guidelines

  • KISS Principle: Always strive for simple and easy solutions
  • No Unasked Refactoring: Don't refactor existing code unless directly related to the task
  • Library Reuse: Prefer existing libraries over custom implementations
  • Documentation: Keep documentation concise; don't create additional docs unless requested
  • Task Planning: Create TODO items before starting work, prioritizing document reading first
  • Function Order: Public functions first, then protected, then private
  • Top down functions: The more specific functions get the further down in a file they should be. The entry point of a file (e.g. a Svelte Compnent) should be on the top, subfunctions then underneeth.
  • Read Architecture first: Determine if you the work is frontend or backend related and then read the corresponding arch document first.

Coding Standards

Python

  • Type Hints: Use type hints whenever possible
  • Avoid Any: Minimize use of Any type hint (except in dicts like dict[str, Any])
  • List Comprehensions: Prefer [x for x in items] over traditional loops for simple expressions
  • Functional Approach: Avoid mutating class variables; return new instances
  • Pydantic: Use v2+ and follow migration guide https://docs.pydantic.dev/latest/migration/
  • Optional Types: Use pipe operator str | None instead of Optional[str]
  • Web Error Exposure: Log full stack traces internally, return generic messages to Web responses to not leak details

Svelte TypeScript

  • Language: Use TypeScript over JavaScript
  • File Naming:
    • Use camelCase for utility files: userProfile.ts, dataService.ts
    • Use PascalCase for component files: UserProfileComponent.tsx
  • Folder Naming: Use kebab-case: user-profile, data-services
  • Imports: Import directly from source modules; avoid re-exports
  • Context Providers: Use <Context value={value}>{children}</Context> pattern over <Context.Provider>

Shell

  • Local Variables: Make new variables in functions local to avoid conflicts with global variables

modAI Backend Development

Environment Setup

  • Location: Work in backend/omni/ directory. When executing commands, switch to the backend dir.
  • Package Manager: Use UV for dependency management
  • Start Server: uv run uvicorn modai.main:app
  • Install Dependencies: uv add <package-name>

Architecture Reading Requirements

Before any backend work, read relevant architecture documents:

  • Always read: backend/omni/docs/architecture/core.md
  • Authentication work: backend/omni/docs/architecture/auth.md
  • Chat/AI features: backend/omni/docs/architecture/chat.md
  • Database work: backend/omni/docs/architecture/persistence.md
  • SQLModel work: https://fastapi.tiangolo.com/tutorial/sql-databases/

Testing

  • Framework: pytest
  • Command: uv run pytest
  • Location: Tests live alongside source code in __tests__/ directories under backend/omni/src/modai/ and backend/omni/src/modai/modules/*/
  • Test Coverage: Always add unit tests for new features or bug fixes
  • Test Isolation: Use mocking for external dependencies
  • Atomic Tests: Each test function should test one specific behavior
  • NO WHITEBOX TESTING — Behavior Testing Only: Only test the public interface of a module/class/endpoint. NEVER import or directly call functions prefixed with _. NEVER assert on internal instance attributes or private state. Private/internal logic is tested indirectly through the public API. If you feel the need to test a private function directly, it is a signal that the public API test coverage is insufficient — fix the public tests instead.
  • Coverage targets: Happy paths (e.g. streaming, non-streaming, tool calling) AND error paths (e.g. connection errors, timeouts, invalid input, unavailable dependencies) — all exercised through the public API only.

Module README (MANDATORY)

Every module folder under backend/omni/src/modai/modules/<module>/ MUST contain a README.md. Keep it up to date whenever you:

  • Add a new module folder
  • Add a new implementation file to an existing module
  • Change config options of any implementation

Required content:

  1. Interface section — briefly describe the abstract module (module.py): module type, endpoints it registers, and the public contract for callers.
  2. One section per implementation — class name used in config.yaml, one-sentence purpose, and the full config.yaml snippet with every supported key (required and optional), including module_dependencies.

Persistence

  • Dictionary Storage: Use SQLAlchemy's JSON type for dictionary fields
  • Timestamps: All HTTP API timestamps in UTC ISO 8601 format

modAI Frontend Development

Environment Setup

  • Location: Work in frontend/omni/ directory. When executing commands, switch to the frontend dir.
  • Package Manager: Use pnpm (not npm)
  • Start Dev Server: pnpm dev
  • Build: pnpm build
  • Install Dependencies: pnpm add <package-name>

Architecture Reading Requirements

  • Always read first: frontend/omni/architecture/core.md

Technology Stack

  • Framework: Svelte with TypeScript
  • Styling: TailwindCSS
  • Build Tool: Vite
  • UI Components: shadcn/ui (https://ui.shadcn.com/docs/components)
  • Install UI Components: pnpm dlx shadcn@latest add <component-name>

UI/UX Guidelines

  • Component Library: Leverage shadcn/ui components for consistency
  • i18n: Always translate texts in the Frontend with i18next
  • English: English is always the fallback language in the code. No need for a own en.json
  • Imports: When you import something from another module group, never use relative imports but always full like import { foo } from "@/modules/some-module". Imports within the same module group should be relative.
  • Svelte Compnents Functions: Create function ProviderItem({provider: Provider}) { over const renderProviderItem = (provider: Provider) => {
  • JSX Functions: JSX should never have a render.. function, but always a proper component function. Compnent functions should never be nested in other functions but on top level
  • pnpm dev: You should never run pnpm dev because this is blocking. Use pnpm build instead always.

Unit Testing

cd frontend/omni
pnpm test            # Run javascript unit tests (vitest)
pnpm check           # Run linter
  • NO WHITEBOX TESTING — Behavior Testing Only: Only test public component behavior and exported functions. NEVER directly test internal/private helpers or assert on internal component state. Internal logic is tested indirectly through the public API. Tests should cover happy paths and error paths. If you feel the need to test an unexported helper, improve the public-API test coverage instead.

Frontend

E2E Testing

Note: Only read this section when working with e2e tests.

For comprehensive e2e testing best practices and patterns, refer to e2e_tests/BEST_PRACTICES.md.

Git Hooks (prek)

Pre-commit hooks use prek's workspace mode. Each sub-project has its own .pre-commit-config.yaml (with orphan: true), discovered automatically from the root .pre-commit-config.yaml.

Layout:

  • .pre-commit-config.yaml — workspace root (empty, enables discovery)
  • backend/omni/.pre-commit-config.yaml — ruff format + ruff check
  • backend/tools/dice-roller/.pre-commit-config.yaml — ruff format + ruff check
  • frontend/omni/.pre-commit-config.yaml — biome check
  • e2e_tests/tests_omni_full/.pre-commit-config.yaml — biome check
  • e2e_tests/tests_omni_light/.pre-commit-config.yaml — biome check

Hooks check (but do not auto-fix) on every commit and fail if issues remain.

One-time setup after cloning:

uv tool install prek   # Install prek binary (skip if already installed)
prek install           # Wire hooks into .git/hooks/pre-commit

Manual run:

prek run               # Run on staged files only
prek run --all-files   # Run on all files
prek run backend/omni/ # Run hooks for a specific project
prek run ruff-check    # Run a single hook by id

Development Workflow

  1. Read Architecture: Always read relevant architecture docs first
  2. Create TODOs: Plan work with structured todo items
  3. Write Tests: Add tests for new functionality
  4. Build & Verify: Run build commands to verify changes
  5. No Summaries: Don't provide task summaries unless requested

Security Considerations

  • Backend: Never expose internal error details to users
  • Frontend: Validate all user inputs
  • Authentication: Follow architecture guidelines in backend/omni/docs/architecture/auth.md

This guide provides AI agents with the essential context needed to work effectively on both backend and frontend components while maintaining project standards and architectural integrity.