David
efeeb164b8
- plan.md: overview now lists English, French & Danish; status header tracks the remediation work; date-formatting note updated to Intl - AGENTS.md: Build & Run section now lists lint, lint:fix, the test/ test:* scripts and the site scripts - technical docs (EN/FR): date formatting section rewritten for the Intl-based formatter (incl. Danish column), streak definition notes only completed logs count - user guide (EN/FR): delete sections mention the new usage counts in the confirmation dialogs - decision log entries for F1/F3/F4 landed with their fixes - npm run format over the touched markdown/code Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
130 lines
6.4 KiB
Markdown
130 lines
6.4 KiB
Markdown
# 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
|