init
This commit is contained in:
Tom Trappmann
245
AGENTS.md
Normal file
245
AGENTS.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# Agent Instructions — Codex (Nuxt 3 + FastAPI, Greenfield, Mock-First)
|
||||
|
||||
This repository contains a **Nuxt 3 frontend**.
|
||||
A **FastAPI** backend will be developed in parallel (may be in a separate repo/service).
|
||||
|
||||
You are an automated coding agent (Codex).
|
||||
|
||||
Your job is to make **precise, minimal, correct changes** while strictly following these rules.
|
||||
Do not guess. If required information is missing, stop and ask one clear question.
|
||||
|
||||
This is an early-stage project. Prefer **simple, explicit patterns**.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
- Root directory:
|
||||
- Deployment artifacts: `Dockerfile`, `deploy/docker-compose.yml`
|
||||
- Nuxt application lives in `NautilusDeskTimeFrontend/`
|
||||
|
||||
- `NautilusDeskTimeFrontend/app/`
|
||||
- Nuxt application source (pages, layouts, components, composables)
|
||||
|
||||
- `NautilusDeskTimeFrontend/server/`
|
||||
- Nuxt/Nitro server code may exist
|
||||
- Backend business logic belongs in FastAPI, not here
|
||||
|
||||
- `NautilusDeskTimeFrontend/public/`
|
||||
- Static assets served as-is
|
||||
|
||||
- Generated output (DO NOT EDIT):
|
||||
- `NautilusDeskTimeFrontend/.nuxt/`
|
||||
- `NautilusDeskTimeFrontend/.output/`
|
||||
|
||||
---
|
||||
|
||||
## Commands (Frontend)
|
||||
|
||||
Run all frontend commands from `NautilusDeskTimeFrontend/`.
|
||||
|
||||
- `npm install`
|
||||
- `npm run dev` (`http://localhost:3000`)
|
||||
- `npm run build`
|
||||
- `npm run preview`
|
||||
- `npm run generate` (if used)
|
||||
|
||||
Do not modify build scripts unless explicitly instructed.
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack
|
||||
|
||||
Frontend:
|
||||
- Nuxt 3
|
||||
- Vue 3 (Composition API only)
|
||||
- TypeScript
|
||||
- Vite
|
||||
- Tailwind CSS
|
||||
- Plain CSS is allowed when needed
|
||||
|
||||
Backend (separate service):
|
||||
- FastAPI
|
||||
- JWT authentication
|
||||
|
||||
Do not introduce new dependencies unless explicitly requested.
|
||||
|
||||
---
|
||||
|
||||
## Global Coding Rules (Strict)
|
||||
|
||||
- Prefer clarity over abstraction
|
||||
- Keep diffs small and scoped
|
||||
- Do not refactor unless asked
|
||||
- Do not change behavior unless asked
|
||||
- Do not remove code unless instructed
|
||||
- Avoid speculative features
|
||||
- Do not add comments explaining obvious code
|
||||
|
||||
When no established pattern exists yet:
|
||||
- introduce a simple, conventional pattern
|
||||
- apply it consistently
|
||||
- do not over-engineer
|
||||
|
||||
---
|
||||
|
||||
## Vue & Nuxt Conventions
|
||||
|
||||
### Components
|
||||
- Use `<script setup lang="ts">`
|
||||
- No Options API
|
||||
- No class-based components
|
||||
- Props and emits must be typed
|
||||
- Avoid `any` and unsafe casts
|
||||
- Components must do one job
|
||||
|
||||
### Pages & Routing
|
||||
- Use Nuxt file-based routing
|
||||
- Page files in `app/pages/` use lowercase filenames
|
||||
- Use `definePageMeta` for layout, middleware, SEO
|
||||
- Do not manually configure routes
|
||||
|
||||
### Composables
|
||||
- Prefix composables with `use`
|
||||
- No side effects at import time
|
||||
- Return only what is required
|
||||
- Keep UI concerns out of composables
|
||||
|
||||
---
|
||||
|
||||
## Backend Integration (FastAPI)
|
||||
|
||||
### Source of Truth
|
||||
- Backend business logic will live in FastAPI
|
||||
- Do not create new `/server/api/*` endpoints in Nuxt unless explicitly instructed
|
||||
- Nuxt server code is infrastructure only (optional proxy/SSR helpers)
|
||||
|
||||
### API Contract & Mocking (IMPORTANT)
|
||||
- The FastAPI API may not exist yet.
|
||||
- If OpenAPI schema is not available, use **mock data** to build the frontend.
|
||||
|
||||
Rules for mock data:
|
||||
- Mock data must be centralized in a single place (e.g. `app/mocks/`).
|
||||
- Mocks should match likely real shapes (typed interfaces).
|
||||
- Switching from mock to real API must be easy:
|
||||
- Use a single API layer (e.g. `app/composables/useApi.ts` or `app/services/api/`).
|
||||
- Pages/components must not directly embed mock fixtures.
|
||||
- Prefer feature flags via runtime config (e.g. `useMockApi`) only if needed.
|
||||
- Do not invent endpoints; if endpoints are unknown, create placeholders and document assumptions in code only when necessary.
|
||||
|
||||
### API Access
|
||||
- Use `$fetch` for HTTP calls from composables/stores.
|
||||
- Use `useFetch` / `useAsyncData` in pages/components when SSR-friendly loading is needed.
|
||||
- Do not hardcode hostnames/ports.
|
||||
|
||||
### Configuration
|
||||
- FastAPI base URL must come from runtime config or environment variables.
|
||||
- If config keys do not exist yet, create them in `nuxt.config` using conventional names:
|
||||
- `runtimeConfig.public.apiBaseUrl`
|
||||
- Keep client-only values in `runtimeConfig.public`.
|
||||
|
||||
---
|
||||
|
||||
## Authentication (JWT)
|
||||
|
||||
JWT will be used for authentication.
|
||||
|
||||
Rules:
|
||||
- Do not assume token storage strategy unless specified.
|
||||
- Default strategy (if not otherwise specified):
|
||||
- Store JWT in memory (Pinia) and optionally persist using existing project preference when defined.
|
||||
- Do not implement auth flows that require backend behavior not defined yet.
|
||||
- If backend endpoints for auth are unknown, build UI using mock auth responses and typed models.
|
||||
|
||||
When adding auth:
|
||||
- Centralize token attach logic in the API layer (single place).
|
||||
- Do not sprinkle Authorization header logic across components.
|
||||
- Use `Authorization: Bearer <token>` when making authenticated requests.
|
||||
|
||||
If any auth detail is unclear (login endpoint, refresh tokens, expiry behavior):
|
||||
- Stop and ask one question.
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
- Use Pinia only if needed and keep it minimal
|
||||
- One store per domain
|
||||
- Setup-style stores only
|
||||
- Handle async errors explicitly
|
||||
- Stores must not manipulate the DOM
|
||||
|
||||
---
|
||||
|
||||
## Styling
|
||||
|
||||
- Use Tailwind by default
|
||||
- Plain CSS is allowed when needed
|
||||
- Avoid inline styles unless unavoidable
|
||||
- Keep `.vue` indentation at **4 spaces**
|
||||
|
||||
---
|
||||
|
||||
## TypeScript Rules
|
||||
|
||||
- Be explicit with types
|
||||
- Prefer narrowing over casting
|
||||
- Avoid `any`
|
||||
- Avoid `as unknown as`
|
||||
|
||||
---
|
||||
|
||||
## Testing & Validation
|
||||
|
||||
- No test framework is configured yet
|
||||
- Validate changes by running `npm run dev`
|
||||
- Manually exercise affected routes/features
|
||||
- If tests are added, document how to run them
|
||||
|
||||
---
|
||||
|
||||
## Git Rules (MANDATORY)
|
||||
|
||||
For every logical change:
|
||||
1. Make the change
|
||||
2. `git status` must be clean after commit
|
||||
3. Commit with a concise imperative message
|
||||
4. Push the commit
|
||||
|
||||
Rules:
|
||||
- One logical change per commit
|
||||
- Do not mix unrelated changes
|
||||
- Do not leave uncommitted changes
|
||||
|
||||
If commit or push cannot be completed:
|
||||
- Stop
|
||||
- Explain why
|
||||
- Ask one concise question
|
||||
|
||||
---
|
||||
|
||||
## Output Requirements
|
||||
|
||||
When responding with code changes:
|
||||
- Modify only relevant files
|
||||
- Do not include unchanged files
|
||||
- Do not include explanations unless explicitly requested
|
||||
- Do not include emojis or conversational text
|
||||
- Prefer minimal diffs
|
||||
|
||||
---
|
||||
|
||||
## Failure Handling
|
||||
|
||||
If a task cannot be completed safely:
|
||||
- Stop
|
||||
- State what is missing
|
||||
- Ask one clear question
|
||||
|
||||
---
|
||||
|
||||
You are a deterministic Nuxt 3 frontend coding agent.
|
||||
Build against mock data when the API is not available.
|
||||
Integrate with FastAPI via runtime-configured base URLs.
|
||||
Use JWT auth via Bearer tokens when endpoints are defined.
|
||||
Maintain clean git history with commit+push for each change.
|
||||
Reference in New Issue
Block a user