trainUs/AGENTS.md

Agents Rules

Project Overview

TrainUs is a fitness tracking progressive web application built with:

• Frontend: Vue 3 (Composition API) + Vue Router
• Database: SQLite WASM (client-side, in-browser)
• Build tool: Vite 7
• Styling: Custom CSS + Bootstrap Icons
• i18n: i18next + i18next-vue (English, French & Danish)
• Tests: Playwright (Python) with pytest
• Formatting: Prettier

Project Structure

src/                  # All application source code
  components/         # Reusable Vue components
  composables/        # Vue composables (shared logic)
  db/                 # SQLite WASM database layer
  i18n/               # Internationalization config and translations
  router/             # Vue Router configuration
  styles/             # CSS styles
  utils/              # Utility functions
  views/              # Page-level Vue components
  App.vue             # Root component
  main.js             # Application entry point
public/               # Static assets served as-is
tests/                # Playwright (Python) test suite
  conftest.py         # Pytest fixtures (Vite dev server, browser config)
  test_step*.py       # Test files per feature step
docs/                 # Non-website documentation
  tutorials/          # Step tutorials (EN & FR)
  tutorials/codelabs/ # Google Codelabs format (EN & FR)
  decisions-log.md    # Decision log
  plan.md             # Feature plan and progress tracking
  specification.md    # Project specification
website/              # Hugo project site (docs + blog), two separate sections
                       # by audience, each with its own nav entry
  content/docs/       # User docs ("Documentation" in nav). Diataxis split,
                       # both languages: demarrage-rapide/ (tutorial),
                       # guides-pratiques.{en,fr}.md (how-to), user-guide/
                       # (reference), comprendre.{en,fr}.md (explanation).
  content/developers/ # Contributor docs ("Developers"/"Développeurs" in nav):
                       # technical.en.md, technical.fr.md
  content/blog/       # Blog posts (news, release announcements)

Build & Run Commands

• npm run dev -- Start Vite dev server
• npm run build -- Production build to dist/
• npm run preview -- Preview production build
• npm run format -- Format code with Prettier
• npm run format:check -- Check formatting
• npm run lint -- Lint src/ with ESLint (CI runs this)
• npm run lint:fix -- Lint and auto-fix
• npm run test -- Playwright suite on Firefox (tests/.venv must exist)
• npm run test:chromium -- Playwright suite on Chromium
• npm run test:parallel -- Both browsers in parallel (xdist, per-file distribution)
• npm run test:parallel:firefox / test:parallel:chromium -- One browser in parallel
• npm run test:parallel:n -- Both browsers, worker count from WORKERS (default 4)
• npm run site:dev / site:build -- Hugo website dev server / minified build

Plan

• Prepare a step-by-step plan to implement one feature at a time (do not rush the full application in one shot)
• Validate the plan with me before doing anything
• Validation is required between each step

Code

Respect these principles:

• KISS (Keep It Simple, Stupid)
• SOLID (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion)
• DRY (Don't Repeat Yourself)
• Minimal impact: prefer small, focused changes over large refactors
• All application source code goes in src/
• All new Vue components use Composition API with <script setup>
• Use existing composables and utilities before creating new ones

Documentation

• Keep the decision log updated in docs/decisions-log.md with date, decision, and rationale
• Use Mermaid diagrams to illustrate architecture and flows (prefer: flowchart, sequence diagram, state diagram)
• README.md at project root presents an overview of the application and how to get started
• All documentation files go in docs/
• Technical Documentation (website/content/developers/, "Developers"/"Développeurs" nav entry):
  • Technical overview (technical.en.md): what the app does, tech stack, global architecture
  • Description of each feature with rationale (why this approach, what was considered and rejected)
• User Documentation (website/content/docs/, "Documentation" nav entry):
  • Diataxis-style split, in both English and French: demarrage-rapide/ (tutorial), guides-pratiques.{en,fr}.md (how-to), user-guide/ (reference — kept this name across languages so the bundle pairs as a Hugo translation), comprendre.{en,fr}.md (explanation). Text-based preferred, screenshots where they clarify a screen or flow.
• Tutorials & Codelabs (for each step):
  • A tutorial in docs/tutorials/ explaining what was done (commands, key files, code snippets)
  • Both in English (_en suffix) and French (_fr suffix)
  • Tutorials and codelabs are optional — only generate when explicitly requested

Tests

• Tests are written using Playwright in Python (see tests/requirements.txt for dependencies)
• The Vite dev server starts automatically via the app_url fixture in tests/conftest.py on port 5199
• Test files follow the naming convention test_step<N>_<feature_name>.py
• Tests are documented with a short description per test function
• Browser targets: Firefox (primary), Chromium (must also pass)
• Test both "green" paths (happy flow) and "red" paths (bad inputs, edge cases, error states)
• All test files go in tests/
• The dev server is stopped automatically by the pytest fixture after tests complete

Schema Version

• Do NOT increment SCHEMA_VERSION without asking first.
• In-place schema changes (adding columns directly in SCHEMA_SQL) are acceptable as long as the app has not been released to users.
• A version bump is only needed once a schema has been deployed — at that point, a migration script must accompany the bump. Ask before doing either.

Definition of Done

Before a step is considered complete, all of the following must be true:

• Code implemented in src/
• docs/plan.md updated to track what is done and what remains
• Documentation updated (website/content/developers/technical.en.md, website/content/docs/user-guide/index.en.md, docs/decisions-log.md)
• Tests written and passing on both Firefox and Chromium
• Manual validation by the user before moving to the next step