# Operator Quickstart

## Куда смотреть в первую очередь

Тебе для работы нужны только эти файлы:

1. `/Users/delete/projects/update_server/docs/agents/WORKFLOW.md`
2. `/Users/delete/projects/update_server/PRODUCT_SPEC.md`
3. `/Users/delete/projects/update_server/IMPLEMENTATION_PLAN.md`
4. `/Users/delete/projects/update_server/DEVELOPMENT_WORKFLOW.md`

Перед каждым новым агентом дополнительно смотри:

- последний файл из `/Users/delete/projects/update_server/docs/agents/handoffs`
- последний файл из `/Users/delete/projects/update_server/docs/agents/validation`

## Что запускать по порядку

Всегда идёшь по одной и той же схеме:

1. запускаешь implementation agent;
2. ждёшь, пока он закончит код и создаст handoff;
3. запускаешь validator;
4. если `APPROVED`, переходишь к следующему агенту;
5. если `CHANGES_REQUIRED`, заново запускаешь того же агента с его handoff и validation report.

Порядок агентов смотри в:

- `/Users/delete/projects/update_server/docs/agents/WORKFLOW.md`

## Базовый промт для implementation agent

Копируй этот промт и меняй только название агента и секцию.

```text
You are <AGENT NAME>.

Read these files first:
- /Users/delete/projects/update_server/docs/agents/WORKFLOW.md
- /Users/delete/projects/update_server/PRODUCT_SPEC.md
- /Users/delete/projects/update_server/IMPLEMENTATION_PLAN.md
- /Users/delete/projects/update_server/DEVELOPMENT_WORKFLOW.md

Then read:
- the section for "<AGENT NAME>" in WORKFLOW.md
- the latest file in /Users/delete/projects/update_server/docs/agents/handoffs if it exists
- the latest file in /Users/delete/projects/update_server/docs/agents/validation if it exists

Follow the rules and fixed decisions exactly.
Work only within your assigned scope.
Do not redesign unrelated parts.
After implementation:
- create or update code
- run relevant checks if possible
- create a handoff file in /Users/delete/projects/update_server/docs/agents/handoffs using /Users/delete/projects/update_server/docs/agents/HANDOFF_TEMPLATE.md

In your final response:
- summarize what you changed
- list files changed
- list checks run
- mention limitations
- mention the exact next recommended step
```

## Базовый промт для validator

```text
You are the validation agent.

Read these files first:
- /Users/delete/projects/update_server/docs/agents/WORKFLOW.md
- /Users/delete/projects/update_server/PRODUCT_SPEC.md
- /Users/delete/projects/update_server/IMPLEMENTATION_PLAN.md
- /Users/delete/projects/update_server/DEVELOPMENT_WORKFLOW.md

Then read:
- the section for "<AGENT NAME>" in WORKFLOW.md
- the latest file in /Users/delete/projects/update_server/docs/agents/handoffs

Review the code produced for that stage.
Run relevant tests or checks if possible.
Look for:
- missing scope items
- regressions
- spec mismatches
- unsafe behavior
- missing tests

Create a validation report in /Users/delete/projects/update_server/docs/agents/validation using /Users/delete/projects/update_server/docs/agents/VALIDATION_TEMPLATE.md

Finish with exactly one status:
- APPROVED
- or CHANGES_REQUIRED
```

## Базовый промт для доработки после замечаний

Если валидатор вернул `CHANGES_REQUIRED`, используй такой промт для того же агента:

```text
You are <AGENT NAME> continuing the same stage.

Read these files first:
- /Users/delete/projects/update_server/docs/agents/WORKFLOW.md
- /Users/delete/projects/update_server/PRODUCT_SPEC.md
- /Users/delete/projects/update_server/IMPLEMENTATION_PLAN.md
- /Users/delete/projects/update_server/DEVELOPMENT_WORKFLOW.md

Then read:
- your stage section in WORKFLOW.md
- your last handoff file
- the latest validation report in /Users/delete/projects/update_server/docs/agents/validation

Fix all blocking issues from the validation report.
Do not start the next stage.
Stay within your original scope unless a fix strictly requires a small adjacent change.

After fixes:
- update the code
- update or create a new handoff file
- summarize exactly which validation findings were fixed
```

## Что поставить через Homebrew

### Минимум для локальной разработки

```bash
brew install go sqlite goose just air
```

Что это даёт:

- `go` — сам Go-компилятор и `go mod`
- `sqlite` — локальная SQLite CLI, удобно смотреть базу руками
- `goose` — миграции базы
- `just` — удобный runner для коротких команд проекта
- `air` — live reload для локальной разработки Go-сервера

### Опционально, но очень полезно

```bash
brew install caddy
```

`caddy` пригодится позже для локального прогона reverse proxy и HTTPS-подобной схемы.

### Если захочешь локально проверять контейнеры

```bash
brew install --cask docker-desktop
```

Если Docker Desktop тебе не нравится, можно потом выбрать более лёгкую схему с `colima`, но для старта это не обязательно.

## Что ещё желательно иметь

Это не Homebrew-пакет проекта, но на Mac очень желательно:

```bash
xcode-select --install
```

Это ставит Command Line Tools и часто экономит кучу времени при сборке Go-зависимостей.

## Самый короткий практический сценарий

1. ставишь `go sqlite goose just air`;
2. открываешь `docs/agents/WORKFLOW.md`;
3. копируешь базовый промт для `Agent 01 - Foundation`;
4. запускаешь агента;
5. проверяешь, что он создал handoff;
6. копируешь промт для validator;
7. после `APPROVED` переходишь к следующему агенту.