# Repository Guidelines ## Read First Before changing code or durable documentation, inspect the current repository state and read the docs that match the task: - `docs/PROJECT.md` for project intent, runtime facts, environments and docs map. - `docs/ARCHITECTURE.md` for system boundaries, source-of-truth and deployment flow. - `docs/CONVENTIONS.md` for coding, validation, review and documentation standards. - `docs/DECISIONS.md` for accepted architecture and operations trade-offs. - `docs/CHECKLISTS.md` for task-specific quality gates. - `DESIGN.md` for UI, visual language, admin/public layout and responsive rules. Treat these files as the durable starter-kit structure for this existing project. Preserve existing project-specific docs and merge improvements instead of replacing them with generic templates. ## Confidence Gate If requirements are below roughly 95% clear, ask concise clarifying questions before implementing. If ambiguity affects data loss, security, authentication, authorization, public behavior, migrations, deployment or irreversible changes, stop and ask. If ambiguity is isolated and low risk, make the smallest reasonable assumption and state it in the final summary. ## Execution Philosophy Your objective is not to generate code as quickly as possible. Your objective is to solve engineering problems with the judgment of an experienced senior software engineer. Always determine the most appropriate execution strategy before writing code. For every task, first decide: - Does this require deeper reasoning? - Can the work be decomposed? - Can independent parts be executed in parallel? - Would delegated agents improve efficiency? - Is additional clarification required? Choose the execution strategy that maximizes correctness, maintainability, and cost efficiency. Treat delegation, planning, and implementation as engineering decisions rather than fixed rules. ## Project Structure & Module Organization - `frontend/` contains the Vue 3/Vite app. Main source lives in `frontend/src/`, with views in `views/`, reusable UI in `components/`, stores in `stores/`, API helpers in `lib/` and `lib/api/`, and static assets in `assets/` or `public/`. - `Backend/` contains the ASP.NET Core 8 API. Domain models are in `Domain/`, EF Core setup and migrations in `Data/` and `Migrations/`, HTTP endpoints in `Endpoints/`, contracts in `Contracts/`, and shared services/repositories in `Services/` and `Repositories/`. - `.gitea/workflows/ci.yaml` defines build, hygiene, deploy, and live verification. - `docs/` holds planning and workflow notes. Do not commit generated output such as `frontend/dist`, `Backend/bin`, `Backend/obj`, archives, prototype exports, or handoff documents. ## Build, Test, and Development Commands Start the local database: ```bash docker compose -f docker-compose.dev.yml up -d ``` Run the backend: ```bash cd Backend dotnet restore dotnet ef database update ASPNETCORE_ENVIRONMENT=Development dotnet run --urls http://127.0.0.1:5084 ``` Run the frontend: ```bash cd frontend npm ci cp .env.example .env npm run dev ``` Validate before pushing: ```bash cd frontend && npm run build cd .. && dotnet build Backend/Backend.csproj --configuration Release git diff --check ``` `npm run build` runs `vue-tsc -b` and `vite build`. ## Coding Style & Naming Conventions Use TypeScript with Vue single-file components. Keep `.vue` files focused; split large admin or workflow screens into smaller components/composables. Name Vue components in `PascalCase.vue`, composables as `useThing.ts`, and API helpers by feature. Backend code uses nullable-enabled C# with implicit usings; align endpoint, contract, service, and repository names by feature. ## Testing Guidelines There is no dedicated test project checked in yet. Treat the frontend build, backend Release build, CI hygiene checks, and relevant manual endpoint/browser verification as required validation. Add future .NET tests in a separate test project and frontend tests near the feature they cover. ## Commit & Pull Request Guidelines Recent history uses short imperative subjects, for example `Fix team profile auth recovery` or `Refine admin risk workspace`. Keep commits scoped and describe the user-visible behavior or operational change. Pull requests should include a summary, validation commands run, linked issue or context when available, screenshots for UI changes, and notes for database migrations, deployment risk, or configuration changes. ## Security & Configuration Tips Use `Backend/appsettings.Development.json` only for local defaults. Non-local environments should provide `VTSA_POSTGRES` or `ConnectionStrings__Postgres`. Never hardcode secrets, tokens, API keys, or production credentials in `Backend/` or `frontend/src/`; CI scans these paths. ## Task Execution Strategy ## Task Classification Before beginning any work, classify the request based on the amount of reasoning required. ### Simple Small, isolated tasks with minimal reasoning. Examples: - formatting - typo fixes - documentation - repository searches - updating comments - locating references - simple bug fixes - small refactorings - straightforward unit tests - boilerplate generation - dependency lookups Prefer delegation to faster, lower-cost agents when available. --- ### Moderate Tasks requiring understanding of multiple files or components. Examples: - implementing a feature - extending existing functionality - API endpoints - service implementations - medium-sized refactoring Delegate independent supporting work where beneficial while keeping overall coordination in the primary reasoning process. --- ### Complex Tasks requiring significant reasoning or architectural understanding. Examples: - architecture - authentication - authorization - security - database design - distributed systems - major refactoring - performance-critical systems - cross-module changes The primary reasoning process should remain responsible. Delegate only isolated supporting tasks. --- ## Intelligent Task Delegation Continuously evaluate whether the current task should be handled entirely by the primary reasoning process or decomposed into smaller independent tasks. When delegated agents are available: - automatically identify independent subtasks - delegate low-risk work to faster and lower-cost agents - keep architectural decisions within the primary reasoning process - merge delegated work only after validating correctness Do not ask for permission before delegating unless delegation could affect correctness, security, or architecture. Suitable delegated work includes: - searching the repository - finding references - documentation updates - dependency analysis - duplicate code detection - code formatting - renaming symbols - generating boilerplate - simple implementations - isolated unit tests - isolated bug fixes Keep these tasks in the primary reasoning process: - architecture decisions - business logic - security-sensitive code - API design - database design - system integration - cross-module refactoring - final implementation review --- ## Parallel Execution Whenever independent work can safely execute in parallel: - identify parallelizable subtasks - execute them concurrently using delegated agents when available - validate all results before integration - ensure consistency before presenting the final solution Prefer parallel execution whenever it improves efficiency without compromising correctness. --- ## Delegation Principles Optimize for the following priorities: 1. Correctness 2. Engineering quality 3. Maintainability 4. Cost efficiency 5. Execution speed Use delegated agents only when they improve efficiency without reducing solution quality. Always keep final responsibility, integration, validation, and architectural reasoning within the primary reasoning process. ## Definition of Done A task is complete when: - the requested behavior or documentation exists; - changes are consistent with `docs/ARCHITECTURE.md` and `docs/CONVENTIONS.md`; - relevant builds, checks or manual validation have been run; - documentation is updated when setup, architecture, operations or public behavior changed; - the diff is reviewed for unrelated changes, secrets, generated output and accidental overwrites; - remaining risks or skipped validation are clearly communicated.