jira-agent/CLAUDE.md

jira-agent

Что это

Клиент моста Jira для виртуалки с доступом к Jira банка. Опрашивает хаб jira-hub (Mac mini), выполняет команды «желаемый результат» по правилу «проверь, потом сделай», ведёт журнал на диске и отдаёт хабу состояние задач. Главный сценарий: хаб ставит команду (например, создать задачу, перевести статус, перенести в спринт), агент читает задачу в Jira, записывает только разницу и возвращает результат; хаб синхронизирует зеркало через refresh. Спека: ../jira-hub/openspec/specs/ (agent/spec.md, commands/spec.md).

Стек и ограничения

• Python 3.9.6 (как на виртуалке), только стандартная библиотека, без venv и зависимостей.
• Запрещено: синтаксис 3.10+ и сторонние импорты. tests/test_py39.py ловит синтаксис 3.10+ (match и т. п.) и сторонние импорты; X | Y — синтаксис 3.10: в 3.9 аннотации функций вычисляются при импорте, и прогон тестов на /usr/bin/python3 3.9.6 это ловит; аннотации локальных переменных не вычисляются, их и API новее 3.9 проверяет только ревью.
• agent.json содержит учётные данные Jira — не коммитить, не отправлять в хаб, не выносить с виртуалки. Шаблон без секретов — src/agent.example.json.

Архитектура

• src/agent.py — весь агент, один файл. Разделы в порядке файла: HTTP-клиенты (Http, JiraClient, HubClient; FolderTransport — транспорт folder: к хабу через общую папку, ошибки как у Http, спека jira-hub/openspec/specs/agent/), Journal, Executor (по методу do_<тип> на каждый тип команды), Runner (цикл claim → пауза → журнал → выполнение → отчёт), CLI (cmd_check, cmd_run, main).
• Границы: Executor знает Jira, но не знает хаб (кроме refresh, где хаб нужен для known_keys и state). Runner знает и хаб, и Jira, и журнал. Журнал не знает о Jira.
• src/agent.example.json — шаблон настроек, README.md — эксплуатация.
• Подробнее: ARCHITECTURE.md.

Команды

• /usr/bin/python3 -m unittest discover -s tests -t . — весь набор тестов. Зелёным считается только весь набор.
• /usr/bin/python3 -W error::ResourceWarning -m unittest discover -s tests -t . — то же с ошибками на незакрытые ресурсы (так проверяем перед коммитом).
• /usr/bin/python3 src/agent.py check — доступность хаба и Jira, без записи в Jira.
• /usr/bin/python3 src/agent.py — основной цикл (нужен agent.json рядом с agent.py).
• /usr/bin/python3 src/agent.py prune — очистка журнала (при работающем агенте откажет).

Тесты

• Тесты в tests/, запуск из корня worktree. Внешних сервисов нет: Jira и хаб заменяют фейки tests/fake_jira.py и tests/fake_hub.py.
• tests/_common.py — общая настройка: путь к src, SETTINGS (как их отдаёт /agent/settings), jira_cfg(), no_sleep(). Паузы в тестах отключаются через ZERO_PACING и no_sleep.
• Тесты разбиты по областям, а не по типам команд: test_executor_fields.py (ensure_issue, ensure_fields, ensure_comment), test_executor_links.py (ensure_status, ensure_link, ensure_sprint), test_refresh.py (refresh), test_runner.py (цикл и восстановление), test_journal.py (журнал), test_clients.py (HTTP и 429).
• Golden-фикстур пока нет: каждый тест строит сценарий в коде.

Первая подсистема

Исполнитель команд и цикл агента (спека agent/spec.md, commands/spec.md) — реализованы целиком: все типы команд, журнал, восстановление после перезапуска, CLI run|check|prune. План и спека живут в jira-hub: openspec/changes/bridge-core/ и docs/superpowers/plans/2026-10-11-bridge-core-hub.md; план агента лежит здесь: docs/superpowers/plans/2026-10-11-bridge-core-agent.md.

OpenSpec и superpowers

• Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.
• Когда brainstorming классифицировал задачу как architectural, структуру change создать через openspec new change <id> (или /opsx:propose <id>), а содержимое proposal.md, specs/ и design.md написать по итогам brainstorming. tasks.md из OpenSpec не заполнять — задачи живут в плане superpowers.
• /opsx:apply не использовать: исполнение идёт через writing-plans и SDD/executing-plans.
• openspec archive <id> — после merge PR, как часть чеклиста закрытия.
• Хук require-plan защищает любой каталог src/ на любой глубине. Если код лежит иначе — перечислить каталоги (префиксы от корня, по одному в строке) в .claude/code-paths.