Add project documentation and update workflow plan
Adds AGENTS.md, DESIGN.md, and docs/* covering architecture, conventions, decisions, checklists, branching, release process, and prompts. Updates README and workflow-feedback-plan to reflect the decoupled GroupName nomination model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
AzuTear
@@ -0,0 +1,256 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user