# 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.
