# AGENTS.md

This file defines practical guidance for AI coding assistants in this workspace.

## AI assistants (Cursor / MCP)

1. Enable the **`ronyup` MCP server** (`.cursor/mcp.json` or `.ai/mcp/mcp.json`).
2. Invoke the **`ronykit-framework` skill** (`/ronykit-framework`) for orchestration workflows.
3. Read architecture and package guidance from **MCP knowledge resources** — do not invent
   service layout. Index: `.cursor/skills/ronykit-framework/references/mcp-map.md` (also under
   `.agents/skills/ronykit-framework/`).

## Repo Purpose

- Go workspace for RonyKIT services.
- Main folders in generated workspaces:
  - `cmd/service`: service process wiring and bootstrap.
  - `feature/`: business modules.
  - `pkg/`: shared libraries (cross-module, business-agnostic).

## Core Rules

- Keep changes scoped to the requested task.
- Do not edit unrelated files.
- Prefer targeted changes over broad refactors.
- Do not run destructive git operations.
- Run focused checks first, then broader checks.

## Architecture Conventions

- Keep transport concerns in `api/` and business logic in `internal/app/`.
- Keep handlers thin; delegate business behavior to app use-cases.
- Define ports in `internal/repo/port.go`.
- Default repository/storage stack is Postgres + `sqlc`.
- Keep adapter implementations in `internal/repo/v0/` (and use other data stacks only when explicitly requested).
- Keep module config in `internal/settings/`.
- After API contract changes, run `make gen-stub` in that feature module.
- For inter-service calls, use generated stubs from `feature/service/*/stub/*` instead of hand-written clients.
- Shared utilities belong in `pkg/` and should not depend on feature business logic.

## Service Design Pattern

For a new feature module:

- Add/adjust contracts in `api/service.go`.
- Implement use-cases in `internal/app/app.go` (and split files as it grows).
- Add persistence interfaces in `internal/repo/port.go`.
- Implement datastore integration in `internal/repo/v0/adapter.go`.
- Update settings and config templates when new dependencies are introduced.

## Suggested Workflow

1. Scaffold feature: `ronyup setup feature --featureDir <dir> --featureName <name> --template service`
2. Implement contracts and app use-cases.
3. Run `make gen-stub` in the feature module after contract updates.
4. In other service modules, consume the generated stubs for client calls.
5. Add tests for app and API behavior.
6. Run:
   - `make tidy`
   - `make lint`
   - `make test`

## Quality Expectations

- Idempotent behavior for retryable operations.
- Validate input at API boundary.
- Keep domain naming consistent across API, app, repo, and settings.
