# Agents and Assistant Instructions

## Purpose

This file provides concise, workspace-specific guidance for AI assistants and developer-facing agents working in this repository. Follow the "link, don't embed" principle: point to project files and tests rather than duplicating large documentation.

## Quick start

- Inspect the project root and run the app locally before making changes. Key folders:
  - `api/` — backend API endpoints (PHP)
  - `app/Controllers`, `app/Models`, `app/Views` — core MVC code
  - `public/` — web entrypoint (`index.php`)
  - `assets/` — JS/CSS and service worker (`sw.js`)
  - `storage/migrations` — database migrations

## Conventions

- PHP code follows a small MVC layout under `app/`.
- Keep edits minimal and focused to avoid unrelated regressions.
- When changing server-side behavior, run a local PHP environment similar to the original developer's (Laragon on Windows is used here).

## What agents should do

- Prefer small, reversible changes (one logical change per patch).
- When updating tests or migrations, ensure database schema updates are described clearly.
- Ask for clarification when requirements are ambiguous or when a change may impact production data.

## Where to start (scoped tasks)

- Fix a bug in an API endpoint: inspect `api/v1/*.php` and matching controllers in `app/Controllers`.
- Update UI: modify files under `app/Views/menu/` and assets in `assets/`.
- Add new migrations: put SQL in `storage/migrations/` and include a `.sql` file.

## Example prompts

- "Find and fix the null-pointer bug causing 500s in `api/v1/orders.php`. Show a minimal patch and tests."
- "Add a new API route `GET /v1/menu` that returns simplified menu JSON; update `app/Controllers/MenuController.php`."
- "Improve performance of `assets/menu.js`: reduce duplicate DOM queries and add a minimal unit test."

## Agent behavior rules

- Never access external services or credentials. If a change requires secrets, ask the human operator.
- Do not make large-scale refactors without approval. Propose a plan first.
- When editing files, use the repository's style and keep changes atomic.

## Suggested next customizations

- Create small, focused agent hooks:
  - `/create-agent prompt:bug-fix` — triage and produce a patch for a single failing endpoint
  - `/create-agent prompt:ui-change` — implement a small view change and update a screenshot or test

## Contact / Feedback

If unsure, open an issue or ask the repo owner for clarification before pushing breaking changes.