6a569da3b1
- Add AGENTS.md as the cross-agent entry point (lean; points to .gooserules and docs/AI_* for detail) - Document the Forgejo issue-driven workflow (report → triage → implement → close) and API patterns in .gooserules - Add Forgejo step to the pre-change checklist - Gitignore .forgejo-token
81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# AGENTS.md
|
|
|
|
Entry point for any AI agent working on this repository. Read this first,
|
|
then follow the pointers below for detail.
|
|
|
|
## Project
|
|
|
|
Normogen — open-source health data platform. Monorepo:
|
|
|
|
- `backend/` — Rust (Axum + MongoDB)
|
|
- `web/normogen-web/` — React + TypeScript (Material-UI, Zustand)
|
|
- `docs/` — architecture, product status, testing scripts
|
|
- `shared/` — types/contracts shared across packages
|
|
|
|
Stack detail, architecture, and code patterns: see
|
|
[docs/AI_AGENT_GUIDE.md](docs/AI_AGENT_GUIDE.md) and
|
|
[docs/AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md).
|
|
|
|
## Working directory
|
|
|
|
Absolute paths are preferred. Project root: `/home/asoliver/desarrollo/normogen`.
|
|
|
|
## Issue-driven workflow (source of truth for tasks)
|
|
|
|
Bugs and features are tracked in **Forgejo** at
|
|
`https://gitea.soliverez.com.ar/alvaro/normogen`. This is the canonical
|
|
backlog — do not invent tasks independently; pick up work from open issues or
|
|
discuss before creating new ones.
|
|
|
|
- Report → triage → implement → close, in chunks tied to one issue each.
|
|
- Reference the issue number in branch names (`fix/123-…`, `feat/456-…`) and
|
|
commit messages (`fix(medication): … (#123)`).
|
|
- The Forgejo API token lives in `.forgejo-token` (gitignored). Read it with
|
|
`cat .forgejo-token`; pass it as `Authorization: token $(cat .forgejo-token)`.
|
|
**Never** echo the token value, commit it, or paste it into issue/commit text.
|
|
- Full lifecycle and API call patterns are documented in the
|
|
"Issue-Driven Workflow" section of [`.gooserules`](.gooserules).
|
|
|
|
## Before making changes
|
|
|
|
1. Read [docs/AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md).
|
|
2. Check [docs/product/STATUS.md](docs/product/STATUS.md) for current progress.
|
|
3. Check open Forgejo issues for the task at hand and its prior discussion.
|
|
4. Review existing code patterns before introducing new ones.
|
|
5. Plan the approach and confirm before implementing non-trivial changes.
|
|
|
|
## Essential commands
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend && cargo build
|
|
cd backend && cargo test
|
|
cd backend && cargo clippy
|
|
cd backend && docker compose up -d
|
|
|
|
# Frontend
|
|
cd web/normogen-web && npm install
|
|
cd web/normogen-web && npm start
|
|
cd web/normogen-web && npm test
|
|
|
|
# Integration tests
|
|
./docs/testing/quick-test.sh
|
|
./docs/testing/test-api-endpoints.sh
|
|
```
|
|
|
|
## Commit guidelines
|
|
|
|
Conventional Commits: `feat(scope): …`, `fix(scope): …`, `docs: …`, etc.
|
|
Reference the issue number when the commit closes or advances one:
|
|
`fix(medication): resolve adherence bug (#123)`.
|
|
|
|
## Where things live
|
|
|
|
| Concern | Location |
|
|
|---|---|
|
|
| Backend handlers | `backend/src/handlers/` |
|
|
| Backend models | `backend/src/models/` |
|
|
| Routes | `backend/src/main.rs` |
|
|
| Frontend pages | `web/normogen-web/src/pages/` |
|
|
| Frontend API services | `web/normogen-web/src/services/` |
|
|
| Shared types | `shared/`, `web/normogen-web/src/types/api.ts` |
|