vtuber-awards/AGENTS.md

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:

docker compose -f docker-compose.dev.yml up -d

Run the backend:

cd Backend
dotnet restore
dotnet ef database update
ASPNETCORE_ENVIRONMENT=Development dotnet run --urls http://127.0.0.1:5084

Run the frontend:

cd frontend
npm ci
cp .env.example .env
npm run dev

Validate before pushing:

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.