AGENTS.md

1# Repository Guidelines
2 
3Halo is a full-stack monorepo: Java 21 / Spring Boot WebFlux + R2DBC backend and a Vue 3 + TypeScript + TailwindCSS frontend. Work from the repo root and load **every relevant module guide** for the areas you touch.
4 
5## Modules
6 
7|       Module        |                           Path                            |                              Guide                               |
8|---------------------|-----------------------------------------------------------|------------------------------------------------------------------|
9| API library         | `api/` (extension model, contracts, security)             | [api/AGENTS.md](api/AGENTS.md)                                   |
10| Backend application | `application/` (services, routers, migrations, packaging) | [application/AGENTS.md](application/AGENTS.md)                   |
11| Frontend            | `ui/` (console, user center, workspace packages)          | [ui/AGENTS.md](ui/AGENTS.md)                                     |
12| Application BOM     | `platform/application/` (shared dependency constraints)   | [platform/application/AGENTS.md](platform/application/AGENTS.md) |
13| Plugin BOM          | `platform/plugin/` (plugin-facing constraints)            | [platform/plugin/AGENTS.md](platform/plugin/AGENTS.md)           |
14 
15## Quick Commands
16 
17Run from the repo root:
18 
19- `./gradlew build` — full backend build and tests.
20- `./gradlew spotlessApply` — format Java, Markdown, JSON, and properties.
21- `./gradlew :application:test` — backend tests.
22- `pnpm -C ui typecheck && pnpm -C ui lint` — frontend validation.
23- `pnpm -C ui test:unit` — frontend unit tests.
24- `./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen` — regenerate the UI client after contract changes.
25 
26## Cross-Module Rules
27 
28- Keep API contracts, backend handlers, and UI usage in sync; never hand-edit `ui/packages/api-client/src/` — regenerate it after contract changes.
29- Versions live in `gradle/libs.versions.toml`, `gradle.properties`, or `ui/package.json`; never hard-code them.
30- Branch naming: `feat/`, `fix/`, `improvement/`, `upgrade/`; PRs target `upstream` and follow `.github/pull_request_template.md`.
31- Stage specific files only; never `git add -A` (H2 artifacts and build outputs appear under `application/`).
32- Add tests for changed behavior; keep CI green.
33- Ask before public API changes, new dependencies, database migrations, security configuration, or CI workflow changes.
34- Never commit secrets or introduce blocking I/O into reactive flows.
35 
36