normogen/.gooserules

# Goose-Specific Rules for Normogen

## Agent Configuration
- **Agent Name**: goose
- **Working Directory**: /home/asoliver/desarrollo/normogen
- **Available Tools**: apps, chatrecall, computercontroller, context7, developer, extensionmanager, memory, repomix, skills, todo

## Goose-Specific Behaviors

### Tool Usage
1. **ALWAYS batch multiple tool operations into ONE execute_code call**
   - ❌ WRONG: Separate execute_code calls for read file, then write file
   - ✅ RIGHT: One execute_code with a script that reads AND writes

2. **Use read_module before calling unfamiliar tools**
   - Check tool signatures to understand required vs optional parameters
   - Tool signature format: `toolName({ param1: type, param2?: type }): string`

3. **Provide tool_graph parameter**
   - Describe execution flow for UI
   - Each node has: tool, description, depends_on

### Task Management
1. **Update todo immediately when given a task**
   - Capture all explicit AND implicit requirements
   - Break down into subtasks

2. **Confirm before implementing code changes**
   - Show what you plan to change
   - Wait for user approval

3. **Commit with relevant messages when making changes**
   - Use conventional commit format
   - Reference related issues/phases

### Global Hints to Follow
- Run unit tests before committing any changes
- Prefer functional programming patterns where applicable
- Do not suppress warnings - fix root cause or prompt for correct handling

## Project-Specific Context

### Quick 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

# Testing
./docs/testing/quick-test.sh
./docs/testing/test-api-endpoints.sh
```

### File Locations
- Backend handlers: `backend/src/handlers/`
- Backend models: `backend/src/models/`
- Frontend pages: `web/normogen-web/src/pages/`
- Frontend services: `web/normogen-web/src/services/`

### Current Phase
- Phase 2.8 (Drug Interactions) implemented
- Backend: Phase 2.x feature-complete, security-hardened
- Frontend: early stage (Login/Register + API/store; router not wired)
- Open work: frontend (Phase 3)

### Code Patterns
- Backend: Repository pattern, async/await, Result<_, ApiError>
- Frontend: Functional components, Zustand, Material-UI
- Auth: JWT with middleware on protected routes
- Testing: cargo test, npm test, integration scripts

## Issue-Driven Workflow

The Forgejo issue tracker at `https://gitea.soliverez.com.ar/alvaro/normogen`
is the source of truth for bugs and features. The API token lives in
`.forgejo-token` (gitignored; never commit or echo its value).

### Lifecycle
1. **Reporting** — the user files issues as they encounter bugs or conceive
   features, either directly in Forgejo or by describing them in chat (then the
   agent creates the issue). Aim for one concern per issue.
2. **Triage** — when picking up work, the agent lists open issues
   (`GET /api/v1/repos/alvaro/normogen/issues`), reads them, asks clarifying
   questions as needed, and proposes a plan in the issue (or chat for small
   items) before writing code.
3. **Implementation** — work in chunks tied to issues. Reference the issue
   number in branch names (`fix/123-...`, `feat/456-...`) and commit messages
   (`fix(medication): ... (#123)`). Push progress as comments on the issue for
   anything non-trivial or spanning multiple sessions.
4. **Closure** — close the issue with a comment summarizing what was done and
   pointing at the relevant commits/PR. Don't close until the change is
   verified (tests pass) and merged/pushed.

### API usage patterns
- Auth header: `Authorization: token $(cat .forgejo-token)`
- Create issue: `POST /api/v1/repos/alvaro/normogen/issues` with JSON
  `{title, body, labels}` (labels must exist first; create via
  `POST /api/v1/repos/alvaro/normogen/labels`).
- Add a comment: `POST /api/v1/repos/alvaro/normogen/issues/{index}/comments`
- Close an issue: `PATCH /api/v1/repos/alvaro/normogen/issues/{index}` with
  `{"state": "closed"}` (ideally after a summary comment).

### Conventions
- Use conventional-commit prefixes in titles where natural
  (`fix:`, `feat:`), but keep titles human-readable.
- Add the `bug` / `feature` / `enhancement` label when creating issues if those
  labels exist; otherwise leave unlabelled rather than failing.
- Never paste the token into commit messages, issue bodies, comments, or chat.

## Before Making Changes

1. Read [AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md)
2. Check [product/STATUS.md](docs/product/STATUS.md) for current progress
3. **Check open Forgejo issues** for the current task and its discussion
4. Review existing code patterns
5. Plan your approach

## Common Workflows

### Add Backend Feature
1. Add model to `backend/src/models/`
2. Add handler to `backend/src/handlers/`
3. Register route in `backend/src/main.rs`
4. Add tests
5. Update docs

### Add Frontend Feature
1. Add types to `web/normogen-web/src/types/api.ts`
2. Add API service to `web/normogen-web/src/services/api.ts`
3. Add Zustand store
4. Create page/component
5. Add route

## Testing Before Committing
- Run `cargo test` in backend
- Run `cargo clippy` and fix warnings
- Run `npm test` in frontend if changed
- Run integration tests in `docs/testing/`

## Commit Guidelines
- Format: `feat(scope): description`
- Examples:
  - `feat(backend): implement drug interaction checking`
  - `fix(medication): resolve adherence calculation bug`
  - `docs(ai): add goose-specific rules`

---

**Goose Rules Version**: 1.0  
**Last Updated**: 2026-03-09  
**For detailed guide**: See [docs/AI_AGENT_GUIDE.md](docs/AI_AGENT_GUIDE.md)