🔁 simplicio-loop — The Universal Looping AI Orchestrator

🚀 The new generation — an operating system for verified agent work

simplicio-loop has evolved far beyond a repeat-until-done prompt. It now compiles intent into a frozen task contract, maps the repository, schedules dependency-aware work, fans execution out into isolated worktrees, collects structured receipts, verifies independently, rolls back safely, remembers every attempt, and keeps the source of record synchronized through delivery.

• Contract first — acceptance criteria, dependencies, risks, source state, and the completion oracle are explicit before execution.
• Parallel without corruption — ready tasks run in isolated lanes/worktrees and converge through an operational ledger.
• Automatic fan-out by default — batch provisions one owned worktree per independent, authorized task; overlap, missing evidence, or unavailable isolation falls back to a visible serial lane. See docs/AUTO_FAN_OUT.md.
• Proof before completion — tests, impact/flow checks, watcher challenges, delivery receipts, and HBP evidence reject false done states.
• Memory that changes behavior — the journal, stall detector, checkpoints, and cross-agent wiki prevent oscillation and make handoffs durable.

That architecture lets one goal become a governed delivery system: from a single hard task to an entire backlog, across sessions and runtimes, with local-first operators and receipts strong enough for humans, CI, or another agent to audit.

🤖 Shipped: a concrete agent behind every stage

Implementation status: #422–#436 — the whole EPIC — is closed and shipped as of v3.37.0, including the full mandatory stage-reporting gate (#433) and the multi-tracker interface (#436). v3.38.0 adds the multi-agent coordination layer on top (scripts/coordinator.py, scripts/pr_dod_review.py) — see § What's new.

The portable driver assigns one accountable agent to intake/planning, implementation, safety, delivery, feedback/recovery, and final completion audit. Review fans out to four independent agents — security/correctness, code quality, runtime reproduction, and blast radius — before it can reconverge. Every transition emits an event and receipt; the completion auditor accepts evidence, never self-reported confidence.

Work-item comment policy

flowchart LR
  SOURCE["Issue · task · queue"] --> COORD["Portable coordinator"]
  COORD --> PLAN["Intake + Planner agent"]
  PLAN --> BUILD["Implementation agent"]
  BUILD --> SAFE["Safety agent"]
  SAFE --> R1["Review agent · security"]
  SAFE --> R2["Review agent · quality"]
  SAFE --> R3["Review agent · runtime/E2E"]
  SAFE --> R4["Review agent · blast radius"]
  R1 --> DELIVER["Delivery agent"]
  R2 --> DELIVER
  R3 --> DELIVER
  R4 --> DELIVER
  DELIVER --> RECOVER["Feedback + Recovery agent"]
  RECOVER --> BUILD
  DELIVER --> AUDIT["Completion auditor"]
  AUDIT --> VERDICT{"COMPLETE · PARTIAL · BLOCKED · REGRESSED"}
  PLAN -. "events + receipts" .-> LEDGER["Append-only stage ledger"]
  BUILD -.-> LEDGER
  SAFE -.-> LEDGER
  DELIVER -.-> LEDGER
  AUDIT -.-> LEDGER
  LEDGER --> GH["GitHub comments · REQUIRED"]
  LEDGER -. "only if connected" .-> AZ["Azure DevOps comments"]
  LEDGER -. "only if connected" .-> JIRA["Jira comments"]
  LEDGER -. "only if connected" .-> ASANA["Asana comments"]
  LEDGER -. "only if connected" .-> TRELLO["Trello comments"]
  GH --> AUDIT

The provider-neutral contract, capability probes, idempotent markers, durable outboxes, recovery rules, sandbox E2E matrix, and acceptance criteria are specified in #436. An optional provider is never treated as connected merely because a CLI exists, and no remote acknowledgment is ever invented.

🆕 What's new in v3.38.0 — the multi-agent coordination release

This release is about one hard problem that only shows up once several agent sessions work the same repo at once: how does a session know what's already claimed, what's already merged-but- incomplete, and what to do with its own idle time instead of duplicating a sibling's work? Every item below was built, tested, and shipped against the live, multi-session state of this very repo — not a synthetic scenario.

• scripts/coordinator.py — the decision core. Given today's GitHub state (open-issue claim comments + merged PRs), it returns one deterministic action per issue: OWN (nothing claimed yet), CONTINUE_OWN (you're already the latest claimant), DEFER_ACTIVE_CLAIM (a sibling session claimed it recently — don't duplicate), RECLAIM_STALE (that claim went cold, safe to pick up), or VERIFY_PARTIAL (a PR already merged for this issue, but it's still open — check what's actually done before assuming either "nothing happened" or "it's finished"). It also raises a duplicate_risk flag the instant two sessions claim the same issue close together. Caught, live, on day one: two sessions independently building a findings collector for the same issue under two different filenames.
• scripts/pr_dod_review.py — the reviewer for idle time. When every open issue is already claimed, a session's highest-leverage move isn't to wait — it's to check the open PRs against this repo's own bar: the 7-dimension Definition of Done (implementation, unit/integration/ system/regression tests, a performance benchmark, ≥85% coverage) and the underlying issue's frozen acceptance-criteria checklist. check --post posts a mechanical, line-by-line verdict as a PR comment instead of a vibe-based approval. Proven against a real, already-merged "MVP slice" PR: it correctly flagged 17 of 17 acceptance criteria on the parent epic as still unresolved.
• scripts/finding_collector.py — durable, deduplicated defect memory (issue #466, phase 1). A simplicio.finding/v1 record per distinct defect, fingerprinted so the same underlying bug — seen by any agent, any run, any timestamp — collapses into one record with an occurrence count instead of spawning duplicate noise. No GitHub calls yet; that's the next phase. scripts/evolution.py (taxonomy + priority + dedup) and scripts/workflow_topology.py (DAG diff + validator) shipped as the first MVP slices of the companion Continuous Evolution (#467) and Adaptive Architecture (#468) epics; scripts/agent_replication.py did the same for Elastic Replication (#469) — admission control and winner-selection for speculative duplicate execution.
• references/multi-agent-coordination.md + references/background-verification.md — two new documented conventions wired straight into SKILL.md's triage step: check coordinator ownership before touching an issue, review PRs instead of idling once everything's claimed, and launch slow verification commands (tests/claims_audit.py) in the background so a turn keeps making progress instead of watching a progress bar.
• Mandatory post-merge cleanup (scripts/worktree_cleanup.py, #484) — a merged branch's local worktree and branch ref are now removed automatically instead of accumulating across sessions.
• CLI contract additions (WI-471) — a preflight subcommand and a --json flag on status, so an external supervisor can machine-check readiness before arming a run.
• Continuous Findings wiring (WI-466) — the completion gate now genuinely consults the finding store, and a store/repo consistency bug was found and fixed in the same pass.
• Two real regressions caught and fixed on main itself, live, this release cycle — a PR that silently deleted a function definition (breaking loop_progress.py's own selftest) merged once, and a squash-merge race then reintroduced the exact same broken code onto main a second time. Both were found by actually running the affected script, not by trusting a green PR description — the whole reason coordinator.py and pr_dod_review.py exist now.
• Carried forward from v3.37.0's Portable Stage Agents epic (#422–#436) — a concrete, independently verifiable agent behind every stage (intake/planner, implementation, four-way review panel, safety gate, delivery, feedback/recovery, completion auditor), a portable contract validator for the shared graph/receipt schema, human-readable agent identities, and optional native binds for simplicio-runtime, simplicio-mapper, and simplicio-dev-cli. Runtime rows are capability inventory; a runtime is counted as executed only by the separate installed lane when its binary and executable adapter are actually available.
• Test-suite inventory is measured, not hard-coded. The checkout and the latest local gate receipt are the source of truth for file and result counts. scripts/test_categories.py reports the unit/integration/system/regression convention where it applies, including any uncategorized files; scripts/claims_audit.py stayed at 14/14 through every merge this cycle.

What this means for you, concretely: if you run simplicio-loop across more than one session or machine against the same repo, it now actively protects you from the two failure modes that actually happen in practice — two agents quietly redoing the same work, and a "done" PR that merged but left the real issue only partially solved. Neither used to be visible; both now are, mechanically, every triage pass.

See CHANGELOG.md for the full list and the v3.38.0 release for signed artifacts (wheel, sdist, SBOM, provenance).

⚡ TL;DR

simplicio-loop is a runtime-agnostic super-plugin — one autonomous looping orchestrator (invoked as /simplicio-loop) plus six satellite skills and five accelerators — that turns any strong LLM (Claude, Codex, Copilot, Gemini, Cursor, local models) into a self-driving worker. You point it at a body of work — "finish all the open issues", "clear the CI queue", "drain the Jira board" — and it runs the whole lifecycle on its own:

discover → understand → decide → act → verify → correct → record → repeat

It discovers work from any source (GitHub Issues, Jira, Azure DevOps, agentsview sessions, and more), dedups, auto-scales an agent fleet to your machine, implements each item through a quality loop that runs the code (not just compiles it), opens PRs, resolves CI/review feedback, merges, and keeps watching 24/7 for new work — all behind safety gates and evidence checks.

/simplicio-loop finish all open issues
→ identity + pre-flight (auth, watcher, STOP path)
→ discover 50 issues · dedup · build dependency DAG
→ autoscale fleet = 14 · pipeline implement→review→merge
→ each item: read body+ACs → orient code → plan → edit → run → verify → PR
→ merge · close with evidence · rollback if main breaks
→ keep looping every ~2 min until the queue is dry (evidence-gated, never a false "done")

Three things make it different: it is a super-plugin of focused skills, it runs the same protocol on 15 runtimes, and it does all of this with aggressive, honest token economy.

The skill installs standalone too: you do not need simplicio-runtime or any mandatory runtime-native component just to use simplicio-loop. Native binds, operators, capture services, and the wider Simplicio runtime stack are optional accelerators on top of the core skill bundle.

Within the Simplicio product line, this repo is also the current reference task flow for company work. simplicio-runtime is the unified entrypoint going forward, but it is expected to reuse this loop's evidence-gated converge/drain discipline, durable attempt journal, and worker coordination patterns instead of creating a separate task semantics.

👁️ Progresso visual, honesto e portátil

Cada execução pode ser acompanhada por texto, Markdown, JSON ou uma animação ANSI. Todas as superfícies consomem o mesmo evento simplicio.progress/v1, incluindo ícones de etapa, gates de evidence/watcher/oracle, lanes de worktrees e eventos de worker_claimed até delivery_reconciled.

simplicio-loop progress <run-id> --format text --once
simplicio-loop progress <run-id> --format markdown --once   # LLM/chat
simplicio-loop progress <run-id> --format json --once       # dashboard/adapters
simplicio-loop progress <run-id> --format text --ascii --no-animation  # log/PowerShell

100% só aparece com receipt do oracle pronto (COMPLETE/DRAINED); uma fase done sem prova fica quase concluída e mostra o blocker. Consulte o contrato completo em docs/PROGRESS_PROTOCOL.md.

🤖 LLM front door

If you are an agent/runtime entering this repo cold, read llms.txt first for the short operational contract, then AGENTS.md, then .claude/skills/simplicio-loop/SKILL.md.

📘 Official capability record

The complete, official roster of what simplicio-loop ships — every capability below is real, runnable, and tested by the applicable local gate. Exact collected/executed/skipped/deselected counts belong to that gate receipt, not this document. Each capability links to its deep section and its worker.

Two loop modes make termination explicit: converge (a single hard task — ends on the evidence-gated <promise> or a stall escalation) vs drain (a queue — ends when the source re-query stays empty K rounds). Both still obey the universal exits (promise+evidence, max_iterations, STOP).

Loop scoring across this line of work: 7.5 (strong design, unproven) → 9 (attempt memory + anti-oscillation) → 9.5 (reproducible local proof) → ~10 (enforced safety + complete loop semantics). The verification infra now catches the project's own regressions as it grows.

🧠 The 7 skills + 5 accelerators

The orchestrator core + six satellites + five accelerators/integrations. Each satellite is optional — when loaded, the orchestrator delegates to it (richer + cheaper); when absent, the inline protocol covers 100%. Accelerators are auto-detected — present = used, absent = LLM fallback.

Each skill lives under .claude/skills/; each accelerator has a reference doc under .claude/skills/simplicio-loop/references/ (the video producer: video-evidence.md, worker scripts/video_evidence.py).

📡 Source adapters

The orchestrator discovers work from any source via pluggable adapters. Each exposes six verbs: list_ready, get_details, claim, update_status, attach_evidence, close.

See each adapter's reference doc under .claude/skills/simplicio-loop/references/.

🌐 15 runtimes, one protocol — 3 guaranteed + 12 best-effort

One universal skill core + one set of hooks drives every runtime. An adapter is thin: it tells a runtime where to load the skills, how to arm the loop, and how to bind native speed. The skill names no runtime; the runtime detects the skill. The native simplicio-runtime MCP bind is optional: when it is missing or unreachable, the adapter reports explicit degraded mode rather than blocking the standalone loop — see docs/MCP_SETUP.md for per-host configuration.

Tier 1 — Guaranteed (gated on every commit)

Tier 2 — Best-effort (contributions welcome, no gate)

The promise: same protocol, same gates, same safety on all 15 — Tier 1 verified mechanically, Tier 2 best-effort. orient_clamp.py (token economy) works on every runtime with zero wiring. See adapters/MATRIX.md for the promotion/demotion rules.

🗺️ The full flow — from demand to delivery

Every layer the orchestrator acts on, in order — from reading the demand (issues, tasks, assigns) to delivering merged, evidenced work, then looping 24/7 for more.

flowchart LR
  IN["Intent: issue · task · queue"] --> CONTRACT["1 · Freeze task contract"]
  CONTRACT --> MAP["2 · Map source + normalize"]
  MAP --> COORD{"3 · Coordinator decide (multi-session)"}
  COORD -->|"OWN / CONTINUE_OWN / RECLAIM_STALE"| PLAN["4 · Dependency DAG + acceptance criteria"]
  COORD -->|"DEFER_ACTIVE_CLAIM (all issues)"| REVIEW["PR DoD/AC review — never idle"]
  COORD -->|"VERIFY_PARTIAL"| RECHECK["Verify what's actually merged before continuing"]
  RECHECK --> PLAN
  REVIEW --> IN
  PLAN --> ROUTE{"5 · Ready task?"}
  ROUTE -->|"solo / small"| SOLO["Targeted lane"]
  ROUTE -->|"parallel / medium+"| FAN["Bounded fan-out"]
  FAN --> A["Isolated worktree A"]
  FAN --> B["Isolated worktree B"]
  FAN --> C["Isolated worktree C"]
  SOLO --> VERIFY["6 · Test + impact/flow evidence"]
  A --> VERIFY
  B --> VERIFY
  C --> VERIFY
  VERIFY --> RECEIPT["Watcher challenge + evidence receipt"]
  RECEIPT --> ORACLE{"7 · Completion oracle"}
  ORACLE -->|"pending / blocked"| RECOVER["Journal · checkpoint · rollback · backlog-only maintenance"]
  RECOVER --> PLAN
  ORACLE -->|"verified / measured"| DELIVER["8 · Source sync · PR · merge"]
  DELIVER --> CLEANUP["Post-merge worktree/branch cleanup"]
  CLEANUP --> MEMORY["9 · Ledger · wiki · durable attempt memory"]
  MEMORY --> WATCH["10 · Re-feed · watcher · STOP path"]
  WATCH -->|"new work"| IN

Multi-agent coordination (new in v3.38.0). Step 3 is the mechanical answer to "is a sibling session already on this?" — scripts/coordinator.py decides from live GitHub state, never a guess. When every candidate issue comes back deferred, the loop doesn't idle: it reviews open PRs against the DoD + acceptance criteria (scripts/pr_dod_review.py) instead. Full detail: references/multi-agent-coordination.md.

Planning gate (issue #284). Steps 1–3 above are not just guidance — simplicio_loop/planning_gate.py makes them a fail-closed mechanical barrier between "claimed" and "mutating": every real arm_run() self-builds a planning-receipt.json binding run/attempt/contract/plan/lease/fence (and, on a GitHub source, the source-snapshot hash) into a single-use mutation_authority token, and execute_operator()/execute_operator_batch() refuse to run without a matching one. Both halves of the gate (SIMPLICIO_REQUIRE_MUTATION_AUTHORITY, SIMPLICIO_LOOP_AUTO_PLANNING_RECEIPT) are mandatory by default — see .claude/skills/simplicio-loop/references/planning-gate.md and docs/adr/0004-planning-gate-rollout.md.

🔁 The loop

The Evidence-Gated Loop is the core mechanism. It re-feeds the same goal each turn so the agent sees its own prior work. Exit is ONLY via:

1. Evidence-gated <promise> — the turn that emits the promise MUST also carry concrete proof (passing test, merged PR, closed-item re-query). A promise with no evidence = ignored.
2. max_iterations cap — hard safety backstop
3. STOP signal — .orchestrator/STOP or channel command

Between turns, LMCache (when available) caches the KV state so re-feed costs near-zero prefill.

🧠 Attempt memory + stall detector (anti-oscillation)

A re-feed loop that remembers nothing oscillates — try X, fail, try X again — until the cap burns. simplicio-loop keeps a durable run-journal (.orchestrator/loop/journal.jsonl, append-only: iteration · action · hypothesis · gate · error-fingerprint, plus optional lineage like execution_state · stage_id · validator · decision · retry_count) and a stall detector (scripts/loop_journal.py, deterministic + model-free):

• Error fingerprint — the failing gate output is reduced to a stable hash with line numbers, paths, hex/uuids, timestamps and durations normalized away, so the same bug is recognized across turns even when the incidental text differs.
• Stall = K identical-fingerprint failures in a row (default K=3). A changing fingerprint means the loop is moving (PROGRESS); the same one K times means it is spinning (STALLED).
• On STALLED the loop does not re-feed the same goal — it names the dead-end actions to avoid, then switches strategy or escalates to the human gate with the fingerprint.
• loop_journal.py resume is read at the top of every turn, so a fresh process continues without re-deriving prior attempts (real resume) and never retries a known dead-end.
• When the loop is doing extraction, validation, or governed retries, record can also stamp --execution-state, --stage-id, --source-artifact, --chunk-id, --validator, --decision, --retry-count, --blocked-reason, and --next-action, so the next turn knows not just what failed, but where in the flow it failed.

loop_journal.py resume                       # what was tried + dead-ends to avoid
loop_journal.py record --iteration N --action "…" --gate fail --gate-output test.log \
  --execution-state planned --stage-id validate --validator pytest --decision retry
loop_journal.py stall --k 3 --exit-code      # PROGRESS → re-feed · STALLED → switch/escalate

📦 Exported contract for other runtimes — simplicio.loop-execution/v1

simplicio-loop is the reference implementation of this converge/drain discipline. So that simplicio-runtime (or any other consumer) reuses this semantics instead of inventing a second, incompatible execution contract (#115), the discipline is published as versioned, testable fixtures under contracts/loop-execution/v1/: converge success, stall + escalation, drain with empty rounds, the STOP path, evidence-gated completion, and the minimal append-only journal shape. python3 scripts/check_loop_contract.py (wired into scripts/check.py) validates every fixture against the REAL producers (hooks/loop_stop.py, scripts/loop_journal.py) by actually running them in an isolated temp directory — not a re-description of them — so a runtime implementing its own executor can diff its behavior against each fixture's expected.json instead of re-deriving the rules from prose. See contracts/loop-execution/v1/SCHEMA.md for the full contract and how to consume it.

🎬 Video evidence — Playwright by default, hyperframes on request

The loop produces demo videos as proof a change works — two engines, one video_evidence extension point (worker scripts/video_evidence.py, contract references/video-evidence.md):

1. Default — the normal evidence flow uses Playwright. After a UI change, video_evidence records the real browser session driving the screen (Playwright native video → .webm, → .mp4 with FFmpeg) — the strongest "works, not just compiles" receipt (Step 4b) and a valid evidence-gated <promise>.

   python3 scripts/video_evidence.py verify --url http://localhost:3000/login \
       --name login-demo --expect "Sign in" --issue 42 [--upload --pr 42]
   

2. On request — a personalized explainer uses hyperframes. When the deliverable IS a video ("make an explainer video of screen X"), the orchestrator renders a deterministic, captioned slideshow of the web_verify screenshots with hyperframes (by HeyGen — "same input, same frames, same output", CI-reproducible, no API keys, local render via headless Chrome + FFmpeg).

   /simplicio-loop make an explainer video of the system login screen
   → detect: video-creation request → web_verify captures the screens
   → video_evidence verify --engine hyperframes → deterministic MP4 → attached to the PR
   

Either engine: a video that never recorded/rendered yields BLOCKED, never a fake pass. Evidence is always a file path + boolean verdict — never video bytes in context (token economy).

📊 Token economy