Whilly Orchestrator — промежуточный отчёт

Период: 2026-04-19 → 2026-04-25 (первая неделя проекта) Версия в PyPI: v3.3.0 Репозиторий: https://github.com/mshegolev/whilly-orchestrator Документация: https://mshegolev.github.io/whilly-orchestrator/

TL;DR

Whilly Orchestrator — Python-обвязка вокруг Ralph-loop техники Ghuntley: бери задачу → агент → verify → коммит. Поверх классического loop’а добавили TRIZ-анализ противоречий, Decision Gate (отказ от мусорных задач до LLM-расхода) и PRD-визард. За 6 дней уехало 6 релизов в PyPI (v3.0 → v3.3), ~12k строк Python, 661 тест на Linux/macOS/Windows × Python 3.10/3.11/3.12.

Курс vNext — Whilly Forge: Issue → Draft PR за один прогон.

1. Что планировали и куда движемся

Базовая идея

Continuous agent loop с предсказуемым ремонтом:

  • Источник задач (GitHub Issues / Projects v2 / Jira / tasks.json / PRD-визард).
  • Pre-flight: TRIZ + Decision Gate + Decomposer.
  • Оркестратор бьёт задачи на батчи по непересекающимся key_files, диспатчит в tmux/worktree, собирает результат через <promise>COMPLETE</promise>.
  • Verify → Repair (self-heal) → Compose PR → Board sync.

vNext — Whilly Forge 

Issue ──► Intake ──► Normalize ──► Readiness ──► Strategy ──► Plan ──► Execute ──► Verify ──► Repair ──► Compose PR ──► Timeline

11 ADR/FR-задач (FR-1 … FR-11) разбивают этот pipeline на сменяемые модули: любая команда может подменить strategy/verifier/PR composer под свой стек.

Ключевые компоненты пакета whilly/

Слой Модули
Цикл и оркестрация cli.py, orchestrator.py, task_manager.py, state_store.py, decomposer.py
Бэкенды агентов (Protocol) agents/{claude,opencode,claude_handoff}.py
Параллельный запуск tmux_runner.py, worktree_runner.py
Источники задач sources/{github_issues,github_issues_and_project,jira}.py
Sinks (PR/борды) sinks/github_pr.py, workflow/{github,analyzer,mapper,sync}.py
Преаналитика triz_analyzer.py, decision_gate.py, prd_{wizard,launcher,generator}.py
Надёжность self_healing.py, recovery.py, doctor.py, verifier.py
UX dashboard.py (Rich TUI), reporter.py, notifications.py, web_status.py

2. Что уже сделали

v3.0.0 — 19.04 — Базовый релиз

Continuous agent loop, Claude CLI wrapper, Rich-дэшборд с hotkeys, tmux/worktree-параллелизм, бюджет/таймауты, --resume.

v3.1.0 — 20.04 — Self-Healing

Traceback-анализ, авто-фиксы NameError / ImportError / TypeError, экспоненциальный backoff (5/10/20/40/60s, до 3 retry), recovery.py для синхронизации статусов после крашей.

v3.2.0 — 22.04 — Большая интеграционная волна

  • Layered config: whilly.toml + OS keyring (Keychain / libsecret / Windows Credential Manager). 5 слоёв: defaults → user TOML → repo TOML → .env → shell env → CLI flags. .env deprecated, миграция через --config migrate.
  • Jira full lifecycle: --from-jira ABC-123 + JiraBoardClient с transitions в lock-step с task status. Stdlib only, без requests.
  • GitHub Projects v2 live sync: карточки переезжают Todo → In Progress → In Review → Done по мере выполнения, --ensure-board-statuses создаёт недостающие колонки, post-merge hook закрывает карточки.
  • claude_handoff backend: file-based RPC — задача отдаётся человеку через .whilly/handoff/<task_id>/prompt.md, новые статусы blocked / human_loop с отдельными колонками на доске.
  • Cross-platform CI: Ubuntu × macOS × Windows × Python 3.10/3.11/3.12 — 9 матриц на каждый PR.
  • Тесты: 490 → 643 (+153 за релиз).
  • Docs: GitHub Pages (Jekyll + just-the-docs), Getting-Started walkthrough, расширенный whilly.example.toml в man-page стиле.

v3.2.1 — 22.04 — Self-healed релиз

Автономный loop whilly-auto-loop.sh поймал и пережил собственный баг парсинга PR-URL в gh pr create: PR #204 был ошибочно закрыт, PR #205 — мёрджнут. Обе истории сохранены как пруф для post-mortem (POSTMORTEM-PR-204.md).

v3.2.2 — 24.04 — Doctor

  • whilly doctor ловит ghost plans (state-файл указывает на удалённый task-plan JSON или путь вне репо) — раньше оркестратор молча подхватывал «фантом».
  • Hotkey n (новый план / PRD-визард) вернули в Rich Live диспатчер.
  • .gitignore теперь экранирует .claude/ — per-machine state не утекает в PR’ы.

v3.3.0 — 24.04 — BREAKING: workspace off by default

Plan-level git worktree (.whilly_workspaces/{slug}/) выключен по умолчанию. В пилотах с pending-changes и subprocess-пайплайнами с абсолютными путями в .venv он чаще удивлял, чем защищал. Включается явно: --workspace или WHILLY_USE_WORKSPACE=1.

v3.3.0+1 — 25.04

Fix: retry на EAGAIN (macOS RLIMIT_NPROC) при субпроцесс-спавне агентов (#213).

Параллельно

  • Workshop kit HackSprint1: BRD/PRD/12 ADR/двуязычный 90-минутный туториал, две дорожки (tasks.json без GitHub auth и full-e2e через GitHub Issues).
  • E2E-скрипты: scripts/whilly_e2e_demo.py (Ralph-loop reference) и scripts/whilly_e2e_triz_prd.py (TRIZ → PRD → tasks → execute → quality gate → PR).

Метрики

  • 6 релизов в PyPI за 6 дней.
  • ~12 125 строк Python в whilly/.
  • 661 тест (+35% за неделю).
  • CI: 9 матриц зелёных на каждый PR.
  • 3 backend’а агентов (Claude / OpenCode / handoff) за общим Protocol.
  • 4 источника задач + интерактивный PRD-визард.

3. Технологический стек

Категория Что
Язык Python 3.10+ (CI на 3.10/3.11/3.12)
Платформы Linux / macOS / Windows
Runtime deps rich, psutil, platformdirs, keyring, tomli (только на 3.10)
Принцип Минимум зависимостей — нет requests, всё через stdlib urllib
Внешние CLI (subprocess) Claude CLI, OpenCode, tmux, git worktree, gh (включая gh api graphql для Projects v2)
Dev pytest, ruff==0.11.5 (line-length 120, py310 target), mypy>=1.8
CI GitHub Actions, 9 OS×Python матриц на PR
Дистрибуция PyPI пакет whilly-orchestrator, pipx-friendly
Docs GitHub Pages (Jekyll + just-the-docs)
Интеграции GitHub Issues / Projects v2 / PR API, Jira (полный цикл), Audio (macOS), OS keyring

4. Главные сложности

  1. Subprocess-spawn под нагрузкой (macOS). Параллельные агенты упирались в EAGAIN / RLIMIT_NPROC — потребовался retry-loop при спавне. На macOS дефолтный лимит процессов на пользователя пробивается раньше, чем ulimit -n. Fix: #213.

  2. State source-of-truth. Конкуренция между tasks.json на диске и in-memory state — только дисциплиной «mark_status → save → reload» + atomic-write. Стэйл in_progress после краша → recovery.py + сброс на старте.

  3. Ghost plans. .whilly_state.json мог держать ссылки на уже удалённые планы. Решено детектором в whilly doctor, а не «починкой по факту». Урок: «инвалидация ссылок на внешние артефакты — это feature, а не побочный эффект». PR: #209.

  4. Workspace-by-default оказался анти-фичей. Plan-level git worktree выглядел безопасным, но в пилотах с uncommitted changes и абсолютными путями в .venv ломал больше, чем защищал. Откатили дефолт в v3.3.0 (BREAKING) — это было дорогое, но честное решение. PR: #212.

  5. Парсинг внешних CLI. gh pr create иногда печатает Warning: строкой stdout-а; парсер ловил всё разом и закрывал чистый PR. Ушли на строгий regex по PR-URL + отдельный gh pr merge без --delete-branch. Привычка: «никаких whole-stdout-capture для CLI-вывода».

  6. GitHub Projects v2 пагинация. Доски с >100 карточек получали HTTP 400 на каждой live-sync транзакции. items(first: 100) без пагинации — баг, который проявляется только в проде.

  7. Полиплатформенный лог. Cyrillic-преамбула падала на Windows cp1252, termios/tty нет на Windows. Поправили UTF-8 + guard на импортах. После этого CI на 3 OS стал зелёным.

  8. Token shadowing. GITHUB_TOKEN в env молча перебивал keyring-аутентификацию gh в 7 местах. Централизовали разрешение через WHILLY_GH_TOKEN / WHILLY_GH_PREFER_KEYRING. Memory-rule: «unset GITHUB_TOKEN перед gh командами».

  9. <promise>COMPLETE</promise> как контракт. Без жёсткого маркера завершения агенты «зацикливались, изображая работу». Решение — единый промпт-билдер и проверка is_complete в agent_runner. Любой новый backend обязан попадать в этот контракт.

  10. Цена / бюджет. Без жёсткого WHILLY_BUDGET_USD агенты улетали в облако. Сделали 80%-warning

    • 100%-kill (exit 2), плюс панель cost в дэшборде (NFR-5, #201).

5. Архитектурная схема

См. whilly-architecture.mmd (Mermaid) и whilly-archimate.xml (ArchiMate Open Exchange, импорт в Archi через File → Import → Open Exchange XML File).

6. Ближайшие шаги

  • vNext / Forge: FR-1 (Intake) → FR-11 (Timeline) — каждый как отдельный PR.
  • Quality gate v2: structured verdict в verifier.py + repo-profile aware checks.
  • Demo screencast (NFR-2): 3-минутное видео для лендинга PyPI.
  • Backend-coverage: dogfood OpenCode на собственных issue’ах.
  • Onboarding-материал: Workshop kit → видео-туториал.

Подготовлено: 2026-04-25. Следующее обновление: 2026-05-02.