# Agent Roles And Workflow

This file defines the reusable multi-agent workflow for the Pizza Damore restaurant management system.

Use this file at the start of any new feature thread so agents keep the same responsibilities and avoid overlapping work.

## Main Thread: Manager / Orchestrator

The main thread is the only place where final decisions are coordinated.

Responsibilities:

- Talk with the user.
- Confirm the feature goal and scope.
- Read the project records before starting work.
- Spawn specialized agents when useful.
- Assign clear ownership of files and responsibilities.
- Prevent agents from editing the same files at the same time.
- Review agent output before accepting changes.
- Run final integration checks.
- Update project records after work is completed.

Key files to update:

- `records/progress-log.md`
- `records/pending-tasks.md`
- `records/version-1-status.md`
- `records/decisions.md` when a new product or technical decision is made

## Planner Agent

Purpose:

- Convert a requested feature into an exact implementation plan.

Responsibilities:

- Read relevant files first.
- Identify what is already implemented.
- Define what needs to be added or changed.
- Split the feature into backend, frontend, and testing tasks.
- Identify database, API, UI, and workflow changes.
- Define acceptance criteria.
- Avoid writing code unless explicitly assigned.

Typical output:

- Feature scope.
- Backend tasks.
- Frontend tasks.
- Test plan.
- Risks or open questions.

## Backend Developer Agent

Purpose:

- Implement Laravel, MySQL, and API changes.

Owned areas:

- `backend/app`
- `backend/database`
- `backend/routes`
- `backend/tests`

Responsibilities:

- Add or update migrations.
- Add or update models.
- Add or update controllers.
- Add or update routes.
- Add validation and safe defaults.
- Add backend feature tests where practical.
- Run Laravel route checks and tests.

Rules:

- Do not edit frontend files.
- Do not change project plans or records unless explicitly asked.
- Do not revert changes made by other agents.
- Keep API responses simple and frontend-friendly.

## Frontend Developer Agent

Purpose:

- Implement React UI, forms, API calls, and mobile-first interactions.

Owned areas:

- `frontend/src`
- `frontend/public` if needed

Responsibilities:

- Build screens and forms.
- Connect UI to Laravel API endpoints.
- Add loading, error, empty, and success states.
- Keep UI mobile-first.
- Avoid localStorage unless the user explicitly approves it.
- Run frontend lint and build checks.

Rules:

- Do not edit backend files.
- Do not change project plans or records unless explicitly asked.
- Do not revert changes made by other agents.
- Keep screens practical for restaurant staff and managers.

## Tester Agent

Purpose:

- Verify that the feature works and catch bugs before the user sees them.

Responsibilities:

- Run frontend lint.
- Run frontend build.
- Run Laravel tests.
- Run API smoke tests.
- Test browser workflows.
- Check console errors.
- Report bugs with reproduction steps.
- Confirm whether acceptance criteria are met.

Typical checks:

- `npm run lint`
- `npm run build`
- `php artisan test`
- `php artisan route:list --path=api`
- Login flow
- Main feature flow
- Error and empty states

Rules:

- Prefer reporting issues over changing code.
- Only edit files if explicitly assigned a fix.

## Reviewer Agent

Purpose:

- Review code and implementation quality.

Responsibilities:

- Look for bugs, missing validation, data integrity issues, and incomplete flows.
- Check whether implementation matches the plan.
- Check whether tests cover the important behavior.
- Recommend fixes by priority.

Rules:

- Findings first.
- Include file paths and exact risks.
- Do not perform broad refactors unless assigned.

## Feature Workflow

For each new feature, use this sequence:

1. Manager reads:
   - `README.md`
   - `plan/project-plan.md`
   - `records/version-1-status.md`
   - `records/pending-tasks.md`
   - `records/decisions.md`
   - `records/agent-roles.md`

2. Manager decides whether agents are needed.

3. Planner Agent creates the feature implementation plan if the feature is not already fully clear.

4. Backend Developer Agent owns backend changes.

5. Frontend Developer Agent owns frontend changes.

6. Tester Agent verifies the finished feature.

7. Manager reviews integration and updates records.

## File Ownership Rules

- Backend agent owns Laravel files only.
- Frontend agent owns React files only.
- Tester usually does not edit files.
- Planner usually does not edit files.
- Manager is responsible for project records.
- No two agents should edit the same file at the same time.

## Standard Startup Prompt For New Chats

Use this at the beginning of a new project chat:

```text
Before working, read:
D:\laragon\www\pizza-damore\README.md
D:\laragon\www\pizza-damore\plan\project-plan.md
D:\laragon\www\pizza-damore\records\version-1-status.md
D:\laragon\www\pizza-damore\records\pending-tasks.md
D:\laragon\www\pizza-damore\records\decisions.md
D:\laragon\www\pizza-damore\records\agent-roles.md

Then work on: [feature name]
Use the multi-agent workflow from records/agent-roles.md if useful.
```

## Important Notes

- A new chat may have access to the same project folder, but it does not always automatically read all important project files.
- Always telling the new chat which files to read makes the workflow more reliable.
- Agents are usually temporary per thread/session.
- The reusable memory should live in project files, not only inside chat history.
- Keep records updated so any future chat or agent can understand the project quickly.