# Luma Web — основа агентной разработки

Переносимый каталог планирования и workflow для создания Web-клиента Luma. **Готового мессенджера здесь пока нет.** Будущие задачи отмечены todo, исходные clear-спецификации сохранены без изменения байтов. Framework и XMPP/OMEMO библиотеки выбираются через начальные ADR и проверку совместимости.

## Быстрый старт

Для инструмента нужен Python 3.10+; сторонние Python-пакеты не нужны.

```sh
python3 scripts/tasks.py validate
python3 -m unittest discover -s tests/tooling -v
python3 scripts/tasks.py status
python3 scripts/tasks.py next --role orchestrator
```

Передать агенту `master_prompt.md`; role/id можно добавить в пользовательское поручение. После blocker прежний agent id не используется: следующий процесс назначает runner.

```sh
python3 scripts/tasks.py claim S00-001 --agent local-architect-1 --role orchestrator
python3 scripts/tasks.py packet S00-001 --agent local-architect-1 --output state/context-S00-001.md
```

Оператор выбирается из 12 файлов ролей; маленькой модели не нужно читать весь tasks.json. Ограниченный context packet содержит максимум 48 000 символов.

Один рабочий цикл — одна задача, её focused checks, evidence, handoff и независимое review. Все команды запускаются из корня этой основы; script сам разрешает пути относительно своего расположения.

## Навигация

- `master_prompt.md`, `AGENTS.md` — старт/продолжение работы.
- `specs/tz_clear.md`, `specs/uikit_clear.md` — оригиналы целевых требований.
- `planning/ROADMAP.md` — этапы и gates.
- `planning/TASK_MATRIX.md`, `planning/task_matrix.csv` — задачи, операторы, зависимости, статусы.
- `planning/TRACEABILITY.md` — применимость требований Web и связь с задачами.
- `planning/tasks/<ID>.md` — подробная атомарная карточка.
- `roles/` — полномочия и инструкции операторов.
- `docs/` — architecture/profile/contracts/workflow/testing/security и `BOOTSTRAP_PROMPTS.md` с готовыми поручениями.
- `state/` — статусы, evidence, handoffs; не secrets.
- `scripts/tasks.py` — dependency-free task CLI.
- `tests/tooling/` — тесты инструмента и целостности.
- `src/`, `services/`, `infra/` — будущая реализация; пояснения внутри директорий.

## Перенос

Можно скопировать весь каталог в отдельный репозиторий, включая `.github`, `.gitignore`, `.editorconfig` и текущий state. Git metadata родительского репозитория не требуется. Внутри исходного Apple-репозитория корневая `.github` этой основы не запускается автоматически; workflow начнёт работать после переноса `.github` в корень отдельного Web-репозитория.

`make check` проверяет только подготовленную основу. App build/test pipeline будет подключён после принятия стека. Нельзя считать готовые документацию/матрицу выполненными продуктовыми задачами.

## Автоматический режим

Один раз заполнить `runner.local.json` по `runner.example.json` командой своего tool-capable agent CLI, затем:

```sh
python3 scripts/runner.py --dry-run
python3 scripts/runner.py --config runner.local.json
```

Каждый запуск модели получает ровно одну задачу и fresh session. При blocker инструмент создаёт remediation и блокирует original; reporter заканчивает работу. Новый агент исправляет причину, другой проверяет, новый продолжает original. При необходимости внешнего input runner останавливается с конкретным запросом. Подробности — `docs/AUTOMATION.md`.

После каждого завершённого запуска runner делает осмысленный commit с task ID, описанием actual changes и проверок: реализация → отдельный review → следующая задача. Blocker сохраняется как незавершённый checkpoint. Агент заранее пишет сообщение, Git выполняет coordinator. Перед первым запуском нужен первоначальный commit основы и чистый Git checkout; подробности — `docs/GIT_WORKFLOW.md`. Ошибка commit останавливает очередь и сохраняет изменения.