Whilly Orchestrator — Weekly Status

Period: 2026-04-19 → 2026-04-25 (week 1) PyPI: v3.3.0 Repo: https://github.com/mshegolev/whilly-orchestrator Docs: https://mshegolev.github.io/whilly-orchestrator/

TL;DR

Whilly Orchestrator is a Python implementation of Ghuntley’s Ralph-loop technique with brains: pick a task → hand to an LLM agent → verify → commit. On top of the base loop we ship TRIZ contradiction analysis, a Decision Gate that refuses garbage tasks before any LLM spend, and a PRD wizard. Six PyPI releases in six days (v3.0 → v3.3), ~12k LoC Python, 661 tests across Linux/macOS/Windows × Python 3.10/3.11/3.12.

Direction (vNext): Whilly Forge — turn one GitHub Issue into a reviewable Draft PR.

1. Plan & direction

Core idea

A continuous agent loop with predictable repair:

  • Task sources (GitHub Issues / Projects v2 / Jira / tasks.json / PRD wizard).
  • Pre-flight: TRIZ + Decision Gate + Decomposer.
  • Orchestrator batches tasks by non-overlapping key_files, dispatches into tmux/worktree, collects results via the <promise>COMPLETE</promise> contract.
  • Verify → Repair (self-heal) → Compose PR → Board sync.

vNext — Whilly Forge 

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

Eleven scoped issues (FR-1 … FR-11) decompose this pipeline into swappable modules: any team can replace the strategy / verifier / PR composer for their own stack.

Components

Layer Modules
Loop & orchestration cli.py, orchestrator.py, task_manager.py, state_store.py, decomposer.py
Agent backends (Protocol) agents/{claude,opencode,claude_handoff}.py
Parallel execution tmux_runner.py, worktree_runner.py
Task sources sources/{github_issues,github_issues_and_project,jira}.py
Sinks (PR / boards) sinks/github_pr.py, workflow/{github,analyzer,mapper,sync}.py
Pre-flight triz_analyzer.py, decision_gate.py, prd_{wizard,launcher,generator}.py
Reliability self_healing.py, recovery.py, doctor.py, verifier.py
UX dashboard.py (Rich TUI), reporter.py, notifications.py, web_status.py

2. What’s shipped

v3.0.0 — 19 Apr — Initial release

Continuous agent loop, Claude CLI wrapper, Rich TUI dashboard with hotkeys, tmux / git-worktree parallel execution, budget / timeout guards, --resume.

v3.1.0 — 20 Apr — Self-Healing

Traceback pattern analysis, automated fixes for NameError / ImportError / TypeError, exponential backoff (5/10/20/40/60s, max 3 retries), recovery.py for task-status reconciliation after crashes.

v3.2.0 — 22 Apr — Integration wave

  • Layered config: whilly.toml + OS keyring (Keychain / libsecret / Windows Credential Manager). Five precedence layers; .env deprecated, one-shot migration via --config migrate.
  • Jira full lifecycle: --from-jira ABC-123 source adapter + JiraBoardClient driving Jira transitions in lock-step with task status. Stdlib-only, no requests dependency.
  • GitHub Projects v2 live sync: cards move Todo → In Progress → In Review → Done as tasks run; --ensure-board-statuses creates missing columns; post-merge hook closes cards.
  • claude_handoff backend: file-based RPC — delegates a task to a human via .whilly/handoff/<task_id>/prompt.md; new task statuses blocked / human_loop with dedicated board columns.
  • Cross-platform CI: Ubuntu × macOS × Windows × Python 3.10/3.11/3.12 — nine matrices per PR.
  • Tests: 490 → 643 (+153 in one release).
  • Docs: GitHub Pages site (Jekyll + just-the-docs), Getting-Started walkthrough, expanded whilly.example.toml in man-page style.

v3.2.1 — 22 Apr — Self-healed release

The autonomous whilly-auto-loop.sh caught and survived its own bug — PR-URL parsing in gh pr create. PR #204 was wrongly closed, PR #205 was merged. Both kept as evidence for the post-mortem (POSTMORTEM-PR-204.md).

v3.2.2 — 24 Apr — Doctor

  • whilly doctor now detects ghost plans (state file referencing a task-plan JSON that no longer exists or points outside the repo).
  • Hotkey n (new plan / PRD wizard) routed back through the Rich Live dispatcher.
  • .gitignore excludes .claude/ — per-machine Claude Code state never leaks into PRs again.

v3.3.0 — 24 Apr — BREAKING: workspace off by default

Plan-level git worktree (.whilly_workspaces/{slug}/) is off by default. In real-world pilots with pending changes and subprocess pipelines holding absolute paths into .venv, it surprised users more often than it protected them. Opt in explicitly via --workspace or WHILLY_USE_WORKSPACE=1.

v3.3.0+1 — 25 Apr

Fix: retry on EAGAIN (macOS RLIMIT_NPROC) when spawning agent subprocesses (#213).

In parallel

  • HackSprint1 workshop kit: BRD/PRD/12 ADRs/bilingual 90-minute tutorial, two tracks (tasks.json without GitHub auth, full e2e via GitHub Issues).
  • E2E scripts: scripts/whilly_e2e_demo.py (Ralph-loop reference) and scripts/whilly_e2e_triz_prd.py (TRIZ → PRD → tasks → execute → quality gate → PR).

Numbers

  • 6 PyPI releases in 6 days.
  • ~12,125 LoC Python in whilly/.
  • 661 tests (+35% in one week).
  • CI: 9 green matrices per PR.
  • 3 agent backends (Claude / OpenCode / handoff) behind a single Protocol.
  • 4 task sources + interactive PRD wizard.

3. Tech stack

Category What
Language Python 3.10+ (CI on 3.10/3.11/3.12)
Platforms Linux / macOS / Windows
Runtime deps rich, psutil, platformdirs, keyring, tomli (3.10 only)
Principle Minimal deps — no requests, everything via stdlib urllib
External CLIs (subprocess) Claude CLI, OpenCode, tmux, git worktree, gh (incl. gh api graphql for Projects v2)
Dev pytest, ruff==0.11.5 (line-length 120, py310 target), mypy>=1.8
CI GitHub Actions, 9 OS×Python matrices per PR
Distribution PyPI package whilly-orchestrator, pipx-friendly
Docs GitHub Pages (Jekyll + just-the-docs)
Integrations GitHub Issues / Projects v2 / PR API, Jira (full cycle), Audio (macOS), OS keyring

4. Top challenges so far

  1. Subprocess spawn under load (macOS). Parallel agents hit EAGAIN / RLIMIT_NPROC; on macOS the default per-user process limit is hit before ulimit -n. Fix: retry loop on spawn (#213).

  2. State source-of-truth. Discipline of mark_status → save → reload + atomic write is the only thing keeping on-disk JSON and in-memory state consistent. Stale in_progress after crashes → recovery.py resets on startup.

  3. Ghost plans. .whilly_state.json could point to deleted plan JSONs; solved with a detector in whilly doctor rather than a fix-up step (#209).

  4. Workspace-by-default was an anti-feature. Looked safe; broke more often than it helped. Reverted the default in v3.3.0 (BREAKING) (#212).

  5. Parsing external CLIs. gh pr create may print a Warning: line on stdout; whole-stdout capture closed a clean PR by mistake. Now strict regex on the PR URL + separate gh pr merge without --delete-branch.

  6. GitHub Projects v2 pagination. Boards with >100 cards returned HTTP 400 on every live-sync — bug only visible in prod-scale boards.

  7. Cross-platform logging. Cyrillic preamble crashed Windows cp1252; termios/tty missing on Windows. UTF-8 + import guards turned 3-OS CI green.

  8. Token shadowing. GITHUB_TOKEN in env silently overrode keyring auth in seven gh call sites — centralised resolution via WHILLY_GH_TOKEN / WHILLY_GH_PREFER_KEYRING.

  9. <promise>COMPLETE</promise> as a contract. Without a hard completion marker, agents loop forever pretending to work. Single prompt builder + agent_runner.is_complete check; any new backend must honour the contract.

  10. Cost / budget. Hard WHILLY_BUDGET_USD cap with 80% warning + 100% kill (exit code 2); cost panel in the dashboard (NFR-5, #201).

5. Architecture diagram

See whilly-architecture.mmd (Mermaid) and whilly-archimate.xml (ArchiMate Open Exchange — import into Archi via File → Import → Open Exchange XML File).

6. Next up

  • vNext / Forge: FR-1 (Intake) → FR-11 (Timeline), one PR per item.
  • Quality gate v2: structured verdict in verifier.py + repo-profile-aware checks.
  • Demo screencast (NFR-2): 3-minute landing video for PyPI.
  • Backend coverage: dogfood OpenCode on our own issues.
  • Onboarding: Workshop kit → video tutorial.

Prepared 2026-04-25. Next update: 2026-05-02.