Simplicio Loop

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.

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.

1. max_iterations cap — hard safety backstop
2. Budget kill-switch — daily_usd_ceiling halts the loop when spent
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) 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.

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] ``

1. 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
• Source: wesleysimplicio/simplicio-loop
• License: MIT
• Homepage: https://simpleti.com.br/simplicio-loop/

Install and usage instructions live in the source repository linked above.