jira-agent/CLAUDE.md

jira-agent

Что это

Клиент моста Jira для виртуалки с доступом к Jira банка. Опрашивает хаб sdlc-hub (Mac mini), выполняет команды «желаемый результат» по правилу «проверь, потом сделай», ведёт журнал на диске и отдаёт хабу состояние задач. Главный сценарий: хаб ставит команду (например, создать задачу, перевести статус, перенести в спринт), агент читает задачу в Jira, записывает только разницу и возвращает результат; хаб синхронизирует зеркало через refresh. Спека: ../sdlc-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, спека sdlc-hub/openspec/specs/agent/), Journal, Executor (по методу do_<тип> на каждый тип команды), Runner (цикл claim → пауза → журнал → выполнение → отчёт), Updater (самообновление: update.json, скачивание, selftest, выход 75), CLI (cmd_check, cmd_selftest, cmd_run, cmd_prune, main).
• src/run.py — запускатель: дочерний agent.py run, подмена версии, пробный период, откат, перезапуск; agent.py не импортирует.
• Границы: Executor знает Jira, но не знает хаб (кроме refresh, где хаб нужен для known_keys и state, ensure_attachment, где у хаба берётся файл вложения, и fetch_attachment, где скачанный из Jira файл отдаётся хабу). 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 — очистка журнала (при работающем агенте откажет).
• /usr/bin/python3 src/agent.py selftest — версия + check; код 0 или 3.
• /usr/bin/python3 src/run.py — запуск через запускатель (самообновление).

Тесты

• Тесты в 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_executor_sprints.py (ensure_sprint_meta, ensure_sprint_state, ensure_rank), test_executor_attachments.py (ensure_attachment, fetch_attachment), test_refresh.py (refresh), test_runner.py (цикл и восстановление), test_journal.py (журнал), test_clients.py (HTTP и 429), test_update.py (самообновление агента), test_launcher.py (запускатель на поддельных агентах), test_self_update_e2e.py (run.py + настоящий agent.py + фейки).
• Golden-фикстур пока нет: каждый тест строит сценарий в коде.

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

Исполнитель команд и цикл агента (спека agent/spec.md, commands/spec.md) — реализованы целиком: все типы команд, журнал, восстановление после перезапуска, CLI run|check|selftest|prune, самообновление через run.py. Последний change — ../sdlc-hub/openspec/changes/sp-estimation-board/ (агент v16: оценка через доску; решения агента — openspec/changes/agent-v16-sp-estimation/design.md), план — docs/superpowers/plans/2026-10-25-sp-estimation-agent.md. План и спека живут в sdlc-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.

Выкатка новой версии

Самообновление (с v5): после merge PR агента в main — поднять AGENT_VERSION (если не поднят в PR) и опубликовать: uv run --project ../sdlc-hub sdlc-hub agent publish src/agent.py (из основного checkout jira-agent на main). Через несколько минут MCP agent_status должен показать «обновление: ok v<старая> → v<новая>»; откат — «откат с v…» (причина — в логе агента на виртуалке). Это пункт чеклиста «закрывай» для PR агента. run.py публикацией не обновляется — только вручную через общую папку.

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.