# Simplicio Loop > 🔁 Finishes your entire backlog while you sleep. The AI orchestrator that DOES the work end-to-end on ANY LLM — discover → implement → verify → merge → 24/7 — behind safety gates, at up to 90% fewer tokens. 48 extension points. Not a chatbot. A worker. - **Type:** MCP server - **Install:** `agentstack add mcp-wesleysimplicio-simplicio-loop` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [wesleysimplicio](https://agentstack.voostack.com/s/wesleysimplicio) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [wesleysimplicio](https://github.com/wesleysimplicio) - **Source:** https://github.com/wesleysimplicio/simplicio-loop - **Website:** https://simpleti.com.br/simplicio-loop/ ## Install ```sh agentstack add mcp-wesleysimplicio-simplicio-loop ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 🔁 simplicio-tasks — The Universal Looping AI Orchestrator TL;DR · 11 Skills · Source Adapters · 11 Runtimes · The Loop · Token Economy · Capture Engine · Install 🌍 Languages: 🇬🇧 English | 🇧🇷 Português | 🇪🇸 Español | 🇫🇷 Français | 🇩🇪 Deutsch | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇨🇳 简体中文 | 🇷🇺 Русский | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇳🇱 Nederlands | 🇮🇳 हिन्दी | 🇸🇦 العربية --- ## ⚡ TL;DR **simplicio-tasks** is a runtime-agnostic **super-plugin** — one autonomous looping orchestrator (invoked as **`/simplicio-tasks`**) plus **five satellite skills** — 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 a hard cost kill-switch. ```text /simplicio-tasks finish all open issues → identity + pre-flight (kill-switch, auth, watcher) → 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 11 runtimes**, and it does all of this with **aggressive, honest token economy**. --- ## 📘 Official capability record The complete, official roster of what `simplicio-tasks` ships — every capability below is **real, runnable, and tested** (`python3 scripts/check.py`: claims-audit 4/4 + 28 tests). Each links to its deep section and its worker. | Capability | What it does | Proof / worker | Details | |---|---|---|---| | 🎬 **Video evidence** (`video_evidence`) | Records the **real browser session** as moving proof a UI change works (Playwright, default); renders a **deterministic captioned MP4** with [hyperframes](https://github.com/heygen-com/hyperframes) for an explicit explainer request (`/simplicio-tasks make a video of screen X`) | `scripts/video_evidence.py` · BLOCKED (never fake-pass) without the toolchain | [§ Video evidence](#-video-evidence--playwright-by-default-hyperframes-on-request) | | 🧠 **Attempt memory + stall detector** | A durable run-journal (`.orchestrator/loop/journal.jsonl`) + a stall detector so the loop **changes strategy instead of oscillating**; incremental triage (`since`) reads only the delta each turn | `scripts/loop_journal.py` · `selftest` 9/9 | [§ Anti-oscillation](#-attempt-memory--stall-detector-anti-oscillation) | | 🧭 **Repo conventions** (`repo_conventions`) | **Learns the repo's own playbook** — mines git history + merged PRs + static config into `.orchestrator/conventions.json` so every new branch/commit/PR mirrors the team's established style; worktree-per-item isolation is the default | `scripts/repo_conventions.py` · `selftest` 19/19 | [§ The full flow](#️-the-full-flow--from-demand-to-delivery) | | 🔒 **Fail-closed safety gate** (`action_gate`) | A `PreToolUse`/git-pre-push hook that **mechanically blocks** force-push, history rewrite, mass-delete, destructive DDL, infra teardown, and secret-laden commits/pushes — Step 5 made executable, not prose | `hooks/action_gate.py` · `selftest` 15/15 | [§ Safety](#-safety-non-negotiable) | | 🔬 **Local verification** | A test suite (worker selftests + an **e2e of the loop driver** proving evidence-gated exit) + a **claims-audit** (referenced scripts exist · counts consistent · `_bundle ≡ source`) — all local, **no paid CI** | `scripts/check.py` · `scripts/claims_audit.py` · `tests/` | [§ Tests & local checks](#-tests--local-checks-no-paid-ci) | | ✅ **Honest savings** | The savings line is now **evidence-gated, not mandatory** — a number is shown only with a measured receipt (clamp/signatures/cache/`deterministic_edit`/ledger); never fabricated | token-economy contract | [§ Token economy](#-token-economy) | Two loop **modes** make termination explicit: **converge** (a single hard task — ends on the evidence-gated `` 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`, budget, 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 11 skills & accelerators The orchestrator core + five 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. | # | Capability | Absorbs | What it does | Token impact | |---|---|---|---|---| | 1 | 🔁 **simplicio-tasks** | — | The orchestrator loop: 48 extension points, dual-path router, self-audit convergence | Core | | 2 | ♾️ **simplicio-loop** | [ralph-loop](https://github.com/cursor/plugins/tree/main/ralph-loop) | Hardened Ralph loop: evidence-gated `` exit, max_iterations cap | Loop drive | | 3 | 🧱 **simplicio-orient** | [rtk](https://github.com/rtk-ai/rtk) + [caveman](https://github.com/JuliusBrussee/caveman) | Terminal-first execution, output-reduction catalog, tee-cache, signatures-read | L0 deterministic | | 4 | 🔥 **simplicio-review** | [thermos](https://github.com/cursor/plugins/tree/main/thermos) | Parallel adversarial review on distinct rubrics → deduped verdict | Quality gate | | 5 | 🗜️ **simplicio-compress** | [caveman](https://github.com/JuliusBrussee/caveman) | Output + memory compression, fail-closed `transform_guard` | 40-60% fewer | | 6 | 🎓 **simplicio-learn** | [teaching](https://github.com/cursor/plugins/tree/main/teaching) | Post-run retrospective → durable, deduped lessons in memory | Smarter each run | | 7 | 🧭 **Understand Anything** | [Egonex-AI](https://github.com/Egonex-AI/Understand-Anything) | Knowledge graph orient: semantic search, guided tours, dependency graph | **L0 zero tokens** | | 8 | 📊 **agentsview** | [kenn-io](https://github.com/kenn-io/agentsview) | Session analytics, cost tracking, stalled-session discovery | **L1** SQL only | | 9 | ⚡ **LMCache** | [LMCache](https://github.com/LMCache/LMCache) | KV cache between loop turns — 40-70% TTFT reduction on local models | GPU time ↓ | | 10 | 🗜️ **Simplicio capture engine** | `engine/simplicio_engine.py` (native, stdlib-only) | Transparent capture proxy: forwards to the real provider, measures + deterministically compresses, writes `proxy_savings.json` | **deterministic** | | 11 | 🎬 **video_evidence** | Playwright (default) · [hyperframes](https://github.com/heygen-com/hyperframes) (on request) | Records the **real session** as moving proof of a UI change (Playwright); renders a **deterministic captioned MP4** explainer with hyperframes when the video IS the deliverable | Evidence producer | Each skill lives under [`.claude/skills/`](.claude/skills); each accelerator has a reference doc under `.claude/skills/simplicio-tasks/references/` (the video producer: [`video-evidence.md`](.claude/skills/simplicio-tasks/references/video-evidence.md), worker [`scripts/video_evidence.py`](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`. | Source | Adapter | Purpose | |---|---|---| | GitHub Issues/PRs | `gh` CLI (native) | Primary work-item source | | Jira / Asana / ClickUp / Linear / Notion | host connector | Board/project management | | Trello / Azure DevOps | `az boards` adapter | Azure work tracking | | **agentsview sessions** | `scripts/agentsview_adapter.py` | Stalled session recovery + cost observability | | Local files / CI queue | filesystem / CI API | Internal work tracking | See each adapter's reference doc under `.claude/skills/simplicio-tasks/references/`. --- ## 🌐 11 runtimes, one protocol 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.** | Runtime | Skill load | Loop drive | Native bind | |---|---|---|---| | **Claude Code** | `.claude/skills/` + plugin | `Stop` hook | MCP | | **Codex** | `AGENTS.md` | self-paced | MCP / adapter | | **VS Code (Copilot)** | `copilot-instructions.md` | tasks | MCP | | **Cursor** | `.cursor-plugin/` | `stop`+`afterAgentResponse` | MCP / rules | | **Antigravity** | rules / `AGENTS.md` | self-paced | MCP | | **Kiro** | `.kiro/steering/` | specs | MCP | | **OpenCode** | `AGENTS.md` | self-paced | MCP | | **Gemini** | `GEMINI.md` | self-paced | MCP / adapter | | **Aider** | `CONVENTIONS.md` | self-paced | — (LLM fallback) | | **Hermes** | native recall | native loop | **native** | | **OpenClaw** | plugin SDK | native scheduler | **native** | The promise: **same protocol, same gates, same safety on all 11 — only the speed differs.** `orient_clamp.py` (token economy) works on every runtime with zero wiring. See [`adapters/MATRIX.md`](adapters/MATRIX.md). --- ## 🗺️ 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. ```mermaid flowchart TD subgraph SRC["1 · Demand sources (any adapter)"] direction LR S1["GitHub Issues / PRs / CI"] S2["Jira · Azure DevOps · Linear · ClickUp · Notion · agentsview · Understand Anything (orient)"] S3["Assigns · TODO/FIXME · CVE · local files · LMCache (inference accelerator)"] end SRC --> PF subgraph PF["2 · Pre-flight gates"] direction LR P1["cost kill-switch budget · agentsview cost check"] P2["source auth + scopes"] P3["arm 24/7 watcher"] end PF --> DISC subgraph DISC["3 · Discover + normalize"] direction LR D1["source_adapter: list metadata only"] D2["normalize to canonical schema"] D3["dedup id+title+fingerprint+branch/PR"] D4["dependency DAG"] end DISC --> INTK subgraph INTK["4 · Deep intake (per item)"] direction LR I1["body + ALL comments"] I2["extract acceptance criteria"] I3["orient code · signatures-only reads or Understand Anything knowledge graph"] I4["plan + AC checklist + complexity"] end INTK --> RT{"5 · Route"} RT -->|"small and every item complexity at most 3"| FAST["Fast-path: solo, one targeted test"] RT -->|"large queue or any medium+"| POOL subgraph POOL["6 · Continuous worker pool (autoscaled, conflict-aware)"] direction LR W1["claim · branch · worktree if overlap"] W2["deterministic_edit"] W3["quality loop: edit-lint-test-fix"] end FAST --> QG POOL --> QG subgraph QG["7 · Quality gates"] direction LR Q1["AC gate = real DoD"] Q2["WORKS not just compiles · web_verify (Playwright) · video_evidence (Playwright recording · hyperframes on request)"] Q3["adversarial review · thermos rubrics"] end QG --> SG subgraph SG["8 · Safety gates (non-negotiable)"] direction LR G1["secret-scan"] G2["irreversible-op human gate"] G3["4-state verdict · attestation"] end SG --> DEL subgraph DEL["9 · Deliver"] direction LR L1["commit · push · Draft PR"] L2["close in-source + evidence"] L3["verify reality, not self-report"] end DEL --> FB subgraph FB["10 · Feedback loop to merge-ready"] direction LR F1["CI fail -> fix root cause"] F2["review comments -> adjust"] F3["branch behind main -> additive rebase"] end FB -->|"merged and closed"| DONE(["done + evidence + measured savings (only if a receipt exists)"]) WATCH["11 · 24/7 watcher · simplicio-loop evidence-gated promise · max-iterations cap · cost kill-switch · LMCache KV cache warm"] FB -. "poll new work / comments / checks" .-> WATCH DONE -. "idle until new work" .-> WATCH WATCH -. "re-feed the goal" .-> DISC ``` --- ## 🔁 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 ``** — 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. **Budget kill-switch** — `daily_usd_ceiling` halts the loop when spent 4. **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`) and a **stall detector** ([`scripts/loop_journal.py`](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. ```bash loop_journal.py resume # what was tried + dead-ends to avoid loop_journal.py record --iteration N --action "…" --gate fail --gate-output test.log loop_journal.py stall --k 3 --exit-code # PROGRESS → re-feed · STALLED → switch/escalate ``` --- ## 🎬 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`](scripts/video_evidence.py), contract [`references/video-evidence.md`](.claude/skills/simplicio-tasks/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 ``. ```bash 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 … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [wesleysimplicio](https://github.com/wesleysimplicio) - **Source:** [wesleysimplicio/simplicio-loop](https://github.com/wesleysimplicio/simplicio-loop) - **License:** MIT - **Homepage:** https://simpleti.com.br/simplicio-loop/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-wesleysimplicio-simplicio-loop - Seller: https://agentstack.voostack.com/s/wesleysimplicio - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.