# AGENTS

## Purpose

This repository is developed through agent-assisted workflow. Follow the repository documents first, then implement code.

## Source of truth

Use the documents in this order when there is ambiguity:

1. `docs/architecture.md`
2. `docs/module-decomposition.md`
3. `docs/data-model.md`
4. `docs/database-schema.md`
5. `docs/admin-api.md`
6. `docs/mcp-interface.md`
7. `docs/rust-design.md`
8. `docs/development-rules.md`
9. `docs/rust-code-rules.md`
10. `docs/implementation-plan.md`
11. `docs/product-editions.md`
12. `docs/commercial-boundaries.md`
13. `docs/frontend-roadmap.md`
14. `docs/refactoring-roadmap.md`

If code and docs diverge, update docs first or together with code.

## Workflow

- Follow `Red -> Green -> Refactor -> Commit`.
- Backend changes follow `TDD` strictly. Frontend layout, copy, and UX cleanup do not require strict `TDD`, but working frontend behavior should still be verified before commit.
- Large features use their own branch: `feat/<feature-name>`.
- Commits must be atomic.
- Push periodically after one or more logically complete `RGR + commit` cycles.
- Do not wait for the whole feature to be finished before pushing.
- Delete merged feature branches both locally and in `origin`.
- During the current refactoring and small-fix phase, changes are merged directly into `main` on GitHub without opening PRs by default.

## Language rules

- Commit messages must be in English.
- Code identifiers must be in English.
- Code comments are avoided by default.
- If a code comment is truly unavoidable, it must be in English.

## Code rules

- Prefer self-documenting code.
- Keep domain logic separate from storage, transport, and orchestration.
- Do not create god-structs or giant services.
- Keep `pub` surface minimal.
- Avoid `unwrap`, `expect`, `todo`, `dbg`, and `panic` in production code.
- `unsafe` is forbidden by default.

## Commands

Use the canonical commands from `justfile`:

- `just fmt`
- `just fmt-check`
- `just check`
- `just clippy`
- `just test`
- `just verify`

## Current execution mode

- Build the Rust workspace first.
- Keep the UI as a separate app outside the Cargo workspace.
- Implement one vertical slice at a time.

## Task tracking

- Check `TASKS.md` before starting a new piece of work.
- Update `TASKS.md` when a task starts, finishes, or gets blocked.