simplicio-prompt 1.14.0

Tuple-Space + Yool safe-speed runtime kernel: lazy 1,000,000+ subagent batch_spawn, adaptive lane concurrency, and a dependency-free OpenAI-compatible provider client for real subagents on DeepSeek / MiMo / OpenRouter / local LLMs.

simplicio-prompt

Tuple-space runtime for real subagent fan-out, consensus, cache-aware prompts, and cost-aware AI execution.
Commands stay in English so they can be copied exactly.

English | Português | Español | 日本語 | 한국어 | 简体中文 | Italiano | Français | Русский | Polski | हिन्दी | العربية | עברית | Bahasa Melayu | Bahasa Indonesia

---

The short version

Tuple-space runtime for real subagent fan-out, consensus, cache-aware prompts, and cost-aware AI execution.

Project DNA

simplicio-prompt is the contract layer: fan-out, consensus, routing discipline, and repeatable prompt behavior for agents that need more than a clever single response. The old README held the runtime vocabulary and benchmark context; the new structure now brings that depth back instead of flattening it into marketing copy.

The new first screen is the doorway; the restored guide below is the workshop. This README should help a stranger understand the promise quickly and still give an operator enough depth to run, validate, and extend the project.

Quick Start

pip install -U simplicio-prompt
simplicio-subagents --help
npm install simplicio-prompt

What it does

• Separates task contract from execution strategy.
• Runs fan-out profiles from quick to 600-lane max breadth.
• Writes reusable JSON/Markdown evidence reports for orchestrators.
• Keeps the kernel dependency-free for Python runtime usage.
• Ships simplicio-edit, a token-free deterministic file editor: an LLM emits a JSON edit script and this CLI applies it without any model calls (see the section below).

Why this README is built to earn attention

• clear first-screen promise
• language links before installation
• badges and a visual hero for fast trust
• copy-ready quick start
• proof before long reference material
• star history for social proof

How it works

flowchart LR
  mapper["simplicio-mapper
repo context"] --> current["simplicio-prompt
this project"]
  prompt["simplicio-prompt
reasoning runtime"] --> current
  current --> evidence["validated evidence
tests, docs, screenshots"]
  current --> sprint["simplicio-sprint
delivery loop"]

Proof and validation

• The package is dual-published to PyPI and npm.
• The fan-out runtime is used by Simplicio CLI and SendSprint planning paths.
• Changelog documents local Ollama defaults and real-stack evidence routing.

Simplicio ecosystem

• simplicio-mapper supplies repo context before interpretation.
• simplicio-cli executes focused code tasks with verification.
• simplicio-prompt provides fan-out and consensus runtime patterns.
• simplicio-sprint turns cards into draft PR delivery loops.

Documentation standard

• YOOL_TUPLE_HAMT.md
• CONTRIBUTING.md
• SECURITY.md
• CODE_OF_CONDUCT.md
• docs/runtime-contracts.md — machine-readable prompt/output schemas + local-agent status/escalation protocol for supervisory runtimes (manifest in contracts/manifest.json)
• docs/readme-globalization-standard.md

Original Field Guide

The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.

simplicio-prompt

Capability-addressing pattern: yool (atomic action) wrapped in tuples (addressable envelopes) over an HAMT (Hash Array Mapped Trie) registry, coordinated through a tuple-space with content-addressable receipts.

This repo is the canonical spec. Vendor it into any project that wants the pattern.

What's new in 1.13

More features, more reach, and a tighter runtime:

• Now on PyPI — pip install simplicio-prompt ships the dependency-free Python kernel and a simplicio-subagents console command, alongside the existing npm package.
• Real subagents on any model / provider — DeepSeek, MiMo, OpenRouter, or a free local LLM (Ollama / vLLM / LM Studio) all run through the same --provider / --model flags. The default standard fan-out is 200 subagents; --fanout-profile max selects 600 for max-breadth parallel audits, and explicit --subagents N still wins.
• Reusable evidence artifacts — --report-dir writes JSON/Markdown summaries for single runs and NDJSON/Markdown summaries for batch orchestrators, including status, counts, tokens, cost, samples, and errors.
• Safer wide fan-out defaults — runs with 64+ subagents auto-enable deterministic diversified personas unless --no-auto-diversify is passed.
• First-class observability — PromptFanout adapters plus per-lane token/cost accounting, circuit-breaker state, and cache stats in every snapshot.
• Always-on invocation — a UserPromptSubmit hook routes every message through the runtime with no trigger keyword, now including a Gemini CLI target.
• One-command test suite — npm test runs the Node CLI/hook/cache/target tests plus the full Python kernel suite in a single pass.

Scope — where simplicio-prompt actually wins

simplicio-prompt is a runtime for fan-out, not a wrapper that makes single LLM calls more accurate. Be honest about the evidence before picking this up:

• Single-call code generation — the ONE-SHOT template adds runtime framing on top of a normal prompt. Across 4 models × 12 cases × 3 sides the bench shows parity or marginal regression vs sending the task through simplicio-cli directly. If your use case is "one model, one prompt, one artifact", use cli alone — sp adds overhead with no measurable lift.
• Fan-out with consensus aggregation — this is where sp earns its keep. On the same bench, cli + sp running N=200 subagents with modal-vote on qwen-coder-next-instruct scored 12/12 PHPUnit green — the only configuration that did so. Modal-vote on smaller MoE models can collapse to uniq=1 when prompts are bit-identical; that's the bottleneck the v1.11 diverse-prompt and v1.12 behavior- consensus phases attack.

The two products are composable, not alternatives:

Layer	Project	Answer
WHAT the task is	simplicio-cli	role / stack / goal / target / testable criteria / constraints / output shape (6-layer contract)
HOW the agent operates	simplicio-prompt (this repo)	orchestration, fan-out, real subagents, safe-speed runtime

For code tasks, send the contract through cli and let sp handle fan-out when N>1 makes sense.

Real-stack evidence requests

When the task asks for Playwright/browser proof of web screens connected to a real API and PostgreSQL/local database, simplicio-prompt treats it as analysis-first work. The runtime contract now points agents to load mapper artifacts, route through simplicio-dev-cli or simplicio-sprint, start the real services, collect focused Playwright screenshots/traces/network evidence, and close with exact validation commands plus pushed commits.

Two physically separate templates

So the BATCH content never enters the model's context in single-artifact tasks:

Template	File	When
ONE-SHOT (default)	prompts/agent-runtime-execution-prompt.md	Single deliverable per request: file edit, diff, snippet, answer, classification. Lean persona, no tuple-space framing in the body.
BATCH (opt-in)	prompts/agent-runtime-batch.md	Orchestrated fan-out: parallel audits, item-parallel work, 200+ real subagents, brainstorm at scale. Tuple-space primitives, batch_spawn, LaneWorkerPool, real subagent invocation via simplicio-subagents.

Opt-in paths to BATCH:

• Set YOOL_TUPLE_FULL_RUNTIME=1 — the Claude Code hook switches to the BATCH directive.
• Run npx simplicio-prompt --batch / --batch --raw to print the BATCH template.
• Run npx simplicio-prompt --batch tasks.jsonl --fanout-profile max --json to process many SendSprint items with one runtime/provider boot and emit one NDJSON result per task; add --report-dir reports/batch to persist review artifacts.
• Import getBatchPrompt() / getBatchPromptSection() from the npm API, or use the simplicio-prompt/batch-prompt package export.
• Have your coding agent invoke simplicio-subagents via shell when the task is genuinely fan-out (the BATCH template includes this protocol).

Highlight: 1,000,000+ subagents, zero enumeration

simplicio-prompt scales to 1,000,000+ subagents in a single task without enumerating them, without spawning a million processes, and without melting your provider quota.

It does this with batch_spawn(depth, branching, compression_threshold) — a lazy hierarchical fan-out over a Hilbert-indexed tuple graph. The kernel stores virtual-agent counts and content-addressable receipts instead of a flat list of agents, so the cost of representing the work is logarithmic, not linear.

• depth=4, branching=32 ⇒ 1,048,576 subagents materialized only when a tuple is actually visited.
• 2,833.75x faster scale representation than a flat instruction flow (V2 benchmark).
• 26.93x faster active execution than naive sequential fan-out.
• compress_token + prune_idle keep inactive subagents as auditable tokens, so a million-subagent task still fits in a small working set.
• LaneWorkerPool enforces bounded per-lane concurrency (YOOL_TUPLE_LANE_CONCURRENCY=32, YOOL_TUPLE_MAX_LANE_CONCURRENCY=64), so a million-subagent graph never turns into a million concurrent calls.
• Provider safety stays intact: receipt/input cache, jittered backoff, circuit breakers, and small-task batching apply at the million-subagent scale exactly as they do at one.
• Observability is first-class: snapshots include per-lane token/cost usage, circuit breaker state, cache stats, and lane worker success/failure metrics.

The output shape stays auditable at any scale:

[Tuple Space Snapshot]
[Active Agents/Subagents]      ← materialized, small
[Total Agents/Subagents]       ← virtual, up to 1,000,000+
[Proximo Yool a executar]
[Resultado parcial]

See prompts/agent-runtime-execution-prompt.md and kernel/yool_tuple_kernel.py for the canonical batch_spawn contract.

Real subagents — any model, any provider

Point simplicio-prompt at any OpenAI-compatible provider and one task fans out across 200 real subagents by default — actual LLM calls, not placeholders, through the same safe-speed runtime. The provider doesn't matter: DeepSeek, MiMo, OpenRouter (any model it gateways), a free local LLM (Ollama / vLLM / LM Studio), or any custom endpoint all work through the same --provider / --model flags.

Use --fanout-profile quick for tight budgets, the default --fanout-profile standard for normal fan-out, and --fanout-profile max for max-breadth: large parallel audits, item-parallel work where N items >= 200, or running the live-bench scenario below. Explicit --subagents N overrides the profile.

Verified live on OpenRouter (deepseek/deepseek-chat) with the max-breadth setting: 600/600 subagents, 0 failures, ~103s, ≈$0.045 at illustrative pricing on a single task. Change --subagents to run any count.

batch_spawn represents subagents virtually. To make them real, the kernel ships a dependency-free, OpenAI-compatible provider client and a fan-out runtime that drains N materialized subagent tuples through LaneWorkerPool — so every real call inherits the same guardrails (bounded per-lane concurrency, the receipt/input cache that de-duplicates identical prompts, jittered backoff, and a provider circuit breaker).

• kernel/providers.py — LLMProvider + presets for deepseek, mimo, local/ollama, and a generic OpenAI-compatible config, with per-call token usage and cost accounting.
• kernel/subagent_runtime.py — SubagentRuntime fans a task across N real subagents and aggregates results, tokens, and cost.

Run real subagents on DeepSeek. Default fan-out is 200 via the standard profile; opt in to --fanout-profile max for 600-subagent max-breadth runs.

export DEEPSEEK_API_KEY=sk-...

# default 200 subagents
python kernel/subagent_runtime.py --provider deepseek \
  --task "Brainstorm edge cases and tests for a distributed rate limiter"

# opt-in: max-breadth fan-out for large parallel audits
python kernel/subagent_runtime.py --provider deepseek --fanout-profile max \
  --task "Audit these 600 functions in parallel"

# offline cost projection / demo — no key, no network:
python kernel/subagent_runtime.py --provider deepseek --fanout-profile max \
  --task "..." --dry-run --report-dir reports/fanout

# other providers (default 200 subagents)
python kernel/subagent_runtime.py --provider mimo  --task "..."
python kernel/subagent_runtime.py --provider local --subagents 50 --task "..."   # Ollama

For orchestrators that already have many task prompts, use JSONL batch mode. Each input line is one object:

{"task_id":"WS-101","prompt":"Audit this change","system":"You are a reviewer"}

simplicio-prompt --batch tasks.jsonl --fanout-profile max --dry-run --json \
  --report-dir reports/batch > out.ndjson

For the Python runtime CLI directly, use the non-overloaded alias:

simplicio-subagents --batch-file tasks.jsonl --fanout-profile max --dry-run \
  --json --report-dir reports/batch > out.ndjson

Each output line is { "task_id": "...", "status": "ok", "result": ... } or { "task_id": "...", "status": "error", "error": "..." }. A malformed line or single task error does not stop the rest of the batch.

Or programmatically:

from kernel.providers import resolve_provider_config, LLMProvider
from kernel.subagent_runtime import SubagentRuntime

provider = LLMProvider(resolve_provider_config("deepseek"))
# CLI profiles resolve to an explicit API count; standard is 200.
report = SubagentRuntime(provider).run("Audit this module", subagents=200)
print(report.format_summary())   # completed/failed, tokens, total cost in USD

Provider configuration

Preset	Default base URL	API key env	Notes
deepseek	https://api.deepseek.com/v1	DEEPSEEK_API_KEY	cheap cloud, OpenAI-compatible
mimo	https://api.mimo.ai/v1	MIMO_API_KEY	set MIMO_BASE_URL to your endpoint
openrouter	https://openrouter.ai/api/v1	OPENROUTER_API_KEY	OpenAI-compatible gateway; set --model (e.g. deepseek/deepseek-chat)
local / ollama	http://localhost:11434/v1	none	free/offline, defaults to openbmb/minicpm5:latest
(any other id)	SIMPLICIO_LLM_BASE_URL	SIMPLICIO_LLM_API_KEY	generic OpenAI-compatible

Per-provider env overrides (example for DeepSeek): DEEPSEEK_BASE_URL, DEEPSEEK_MODEL, DEEPSEEK_PROMPT_COST_PER_MTOK, DEEPSEEK_COMPLETION_COST_PER_MTOK. Cost defaults are illustrative — set the *_COST_PER_MTOK vars to your live contract pricing (e.g. 0.003) so the reported cost_usd matches your bill.

Behavior consensus (Phase 2) — oracle-driven modal-vote

kernel/aggregator.py::BehaviorConsensus replaces naive string modal-vote with oracle-driven consensus: each candidate is run through your test runner (PHPUnit, pytest, jest, regex — anything that returns a {test_name: bool} profile) and the winner is the candidate whose pass/fail profile aligns best with the rest of the pool on the tests the majority also passes. If any candidate passes every observed test, that one wins outright.

from kernel.aggregator import BehaviorConsensus

def oracle(code: str) -> dict[str, bool]:
    return {
        "unit:rejects_admin": "admin" in code and "deny" in code,
        "unit:allows_member": "member" in code,
        "regex:no_eval":      "eval(" not in code,
    }

candidates = [r.text for r in report.results if r.ok]   # fan-out output
result = BehaviorConsensus.pick(candidates, oracle)

print(result.index)            # winning candidate index
print(result.passed_tests)     # tests it passes
print(result.broken_tests)     # tests it still breaks
print(result.consensus_score)  # how aligned its profile is with majority
print(result.coverage)         # fraction of total tests it passes

This is the mechanism behind the headline 12/12 PHPUnit result on qwen-coder-next-instruct — modal-vote alone collapses to uniq=1 on MoE models when the prompts are bit-identical; an oracle breaks that tie by voting on behavior, not on strings.

Adversarial pairs (Phase 3) — arena selection

kernel/arena.py::AdversarialPairs runs M implementer attempts and M senior-reviewer critiques in parallel, then picks the attempt with the highest critic score and zero violations. Optional oracle integration applies the Phase 2 selector to the surviving candidates for a double gate (review-passed + behavior-correct).

from kernel.providers import resolve_provider_config, LLMProvider
from kernel.arena import AdversarialPairs

generator = LLMProvider(resolve_provider_config("deepseek"))
critic    = LLMProvider(resolve_provider_config("openrouter"))

arena  = AdversarialPairs(M=100, max_workers=32)
report = arena.run(
    task="repair the role guard in App\\Auth\\Router",
    generator_provider=generator,
    critic_provider=critic,
    # optional double-gate via Phase 2:
    # oracle_fn=lambda code: {"unit": "admin" in code, ...},
)

winner = report.winner             # ArenaAttempt | None
print(report.winner_index)
print(winner.text if winner else "no clean winner")
for review in report.reviews:
    print(review.score, review.violations)

It is API-only by design: the ONE-SHOT default fan-out path stays intact, so production wins from arena only when callers opt in.

Acknowledgement

Special thanks to Jesse Daniel Brown, PhD, my mentor, a California, USA native and author of 100+ scientific articles. His humanitarian and educational perspective on programming, AI, and scientific work helped reinforce the mission behind this repository: practical agent systems that increase human capability through safer, more auditable automation.

V2 safe-speed infographics

English

Portuguese Brazil

Infographic Explanation

The infographics compare a loose prompt flow against the simplicio-prompt V2 safe-speed runtime. The left side shows the old failure modes: flat agent lists, sequential work, repeated provider calls, no cache, fixed concurrency, retry storms, large LLM context, and weak audit trails.

The right side shows the V2 path: tuple-space routing, lazy batch_spawn, adaptive LaneWorkerPool, receipt/input cache, small-task batching, circuit breakers, backoff with jitter, context compression, local yool routing, and speculative execution only for idempotent work. The practical result is faster delivery through avoided repeat work and safer provider behavior, not through unbounded calls.

Measured V2 benchmark highlights:

• Scale representation: 2,833.75x faster than a normal instruction flow.
• Active execution: 26.93x faster than normal sequential execution.
• Cache: 4x fewer provider calls, a 75% reduction.
• Batching: 32x fewer small-task calls, a 96.88% reduction.
• Circuit breaker: 64x fewer failure attempts, a 98.44% reduction.
• Token economy: 76.32% estimated savings through context compression.

Quick read

• YOOL_TUPLE_HAMT.md - full spec with diagrams, algorithms, examples, guardrails.
• kernel/yool_tuple_kernel.py - reference Python kernel with lazy batch_spawn, compress_token, hookwall, indexed tuple-space scans, and lane worker fan-out.
• prompts/agent-runtime-execution-prompt.md - ready prompt for Claude, Codex, Hermes, and other coding agents.
• examples/ - runnable minimal implementations (Python, Node).
• guardrails/ - CPU throttle + disk GC reference implementations.
• adopters.md - projects that vendor this spec.

Install via npm

The repo ships as an npm package and as a multi-IDE plugin. Use it without cloning:

# print the full prompt
npx simplicio-prompt

# print only the `## Prompt` body (no surrounding markdown)
npx simplicio-prompt --raw

# install as a plugin for one (or many) coding agents
npx simplicio-prompt --target claude-code     # → CLAUDE.md
npx simplicio-prompt --target codex           # → AGENTS.md
npx simplicio-prompt --target hermes          # → AGENTS.md
npx simplicio-prompt --target opencode        # → AGENTS.md  (alias: openclaw)
npx simplicio-prompt --target cursor          # → .cursor/rules/*.mdc + .cursorrules
npx simplicio-prompt --target copilot         # → .github/copilot-instructions.md
npx simplicio-prompt --target cline           # → .clinerules/simplicio-prompt.md
npx simplicio-prompt --target aider           # → CONVENTIONS.md
npx simplicio-prompt --target gemini          # → GEMINI.md
npx simplicio-prompt --install-all            # → every target above

# inspect / discover
npx simplicio-prompt --list-targets

Or add it as a dependency and consume it programmatically:

npm install simplicio-prompt

import {
  getPrompt,
  getPromptSection,
  getPromptPath,
  getTargets,
  findTarget,
} from "simplicio-prompt";

const fullMarkdown = getPrompt();        // entire prompt file
const promptOnly   = getPromptSection(); // just the `## Prompt` body
const filePath     = getPromptPath();    // absolute path on disk
const targets      = getTargets();       // multi-IDE plugin target registry
const cursor       = findTarget("cursor");

Every install wraps the prompt in <!-- simplicio-prompt:start --> / <!-- simplicio-prompt:end --> markers so reinstalling updates the block in place instead of duplicating it. The Cursor .mdc rule and any new directory (.cursor/rules/, .github/, .clinerules/) are created automatically.

simplicio-edit — token-free deterministic file editing

The npm package also ships a second binary, simplicio-edit, which applies a JSON edit script to files with zero LLM calls — instant, free, and reproducible. An LLM (or a script, or you) emits a small JSON patch describing what to change; the CLI applies it. Full operation reference in docs/json-file-editor.md.

# apply an edit script
npx simplicio-edit edits.json

# preview changes without writing
npx simplicio-edit edits.json --dry-run

# read script from stdin, emit machine-readable report
cat edits.json | npx simplicio-edit - --json

Script shape (version: 1):

{
  "version": 1,
  "edits": [
    { "file": "src/app.ts", "ops": [
        { "op": "replace", "find": "TODO", "value": "DONE" },
        { "op": "insertAfter", "find": "// hooks", "value": "useDebounce();" }
    ] },
    { "file": "src/new.ts", "create": true, "content": "export {};\n" },
    { "file": "src/old.ts", "delete": true }
  ]
}

Supported text ops: replace, regexReplace, insertAfter, insertBefore, insertAtLine, deleteLine, deleteMatching, append, prepend. Exit codes: 0 success, 1 edit/validation error, 2 usage error.

Programmatic API via the dedicated export:

import {
  applyEditScript,
  applyOps,
  parseEditScript,
  EditError,
} from "simplicio-prompt/json-file-editor";

const report = applyEditScript(scriptObjectOrString, {
  dryRun: false,        // true to compute changes without writing
  cwd: process.cwd(),   // resolve relative file paths against this
});
// report.results is [{ file, action, changed, ops? }] where:
//   action  = "create" | "overwrite" | "edit" | "delete"
//   changed = boolean (false on a no-op edit)
//   ops     = per-op applied list (only on action === "edit")

applyOps(text, ops) is the lower-level helper that operates on a single string (no filesystem access) and returns the edited text — useful for unit tests or when you want to drive the script-runner yourself.

Install via PyPI (Python)

The reference kernel ships as a dependency-free Python package, so you can run real subagents on any OpenAI-compatible provider without cloning the repo:

pip install simplicio-prompt

from kernel.providers import resolve_provider_config, LLMProvider
from kernel.subagent_runtime import SubagentRuntime
from kernel.yool_tuple_kernel import build_default_space

# 1,000,000+ subagents represented lazily, materialized only when visited
space, root = build_default_space()
receipt = space.batch_spawn(root, "codex_worker", depth=4, branching=32)
print(receipt.virtual_agents)  # 1048576

# real subagents on any provider (DeepSeek / MiMo / OpenRouter / local)
provider = LLMProvider(resolve_provider_config("deepseek"))
# CLI profiles resolve to an explicit API count; standard is 200.
report = SubagentRuntime(provider).run("audit this module", subagents=200)
print(report.format_summary())  # completed/failed, tokens, total cost in USD

The install also exposes a console entry point for offline cost projection and live fan-out:

# default fan-out (200 subagents) — offline cost projection, no API key
simplicio-subagents --provider deepseek --task "..." --dry-run \
  --report-dir reports/fanout

# max-breadth fan-out (opt-in) for large parallel audits
simplicio-subagents --provider deepseek --fanout-profile max --task "..." \
  --dry-run --report-dir reports/fanout

Optional Rust acceleration (PyO3)

For hot paths (prompt section extraction, multi-needle pattern scan, and guardrail validation) the repo ships an optional native extension written in Rust with PyO3 bindings. The default pip install simplicio-prompt remains pure-Python and dependency-free; the native extension is opt-in.

Build and install the extension locally:

pip install maturin
cd rust && maturin develop --release

That produces _simplicio_native in the current Python environment. kernel/utils/accel.py transparently picks it up on the next import:

from kernel.utils import accel

accel.backend_name()                              # "native" (or "python" w/o the wheel)
accel.extract_prompt_section(text)                # native if available, identical output
accel.find_patterns(text, ["needle-a", "needle-b"])
accel.validate_guardrails(["rule-a", "rule-b"], text)

The native path is parity-tested against the pure-Python fallback (tests/test_accel.py) so the output is identical byte-for-byte; pick whichever your install has. Measured speedups on local builds:

extract / ONESHOT (~75 lines)             ~3.0x
extract / BATCH   (~280 lines)            ~3.1x
extract / 5KB body                        ~7.0x
find_patterns / 4 needles in 5KB          ~2.2x
validate_guardrails / 6 rules in 5KB      ~7.4x

(50k iterations each, Rust 1.94, CPython 3.11.) Run python benchmarks/accel_benchmark.py to reproduce locally.

The native wheel is not published to PyPI yet — that requires a manylinux/macOS/Windows wheel matrix in CI. For now cd rust && maturin develop is the canonical install path.

Multi-IDE plugin matrix

Target id	IDE / agent	Files written
claude-code	Anthropic Claude Code	CLAUDE.md
codex	OpenAI Codex CLI	AGENTS.md
hermes	Nous Research Hermes	AGENTS.md
opencode (alias openclaw)	OpenCode / OpenClaw	AGENTS.md
cursor	Cursor IDE	.cursor/rules/simplicio-prompt.mdc, .cursorrules
copilot (alias github-copilot)	GitHub Copilot	.github/copilot-instructions.md
cline	Cline (VS Code)	.clinerules/simplicio-prompt.md
aider	Aider	CONVENTIONS.md
gemini (alias gemini-cli)	Google Gemini CLI	GEMINI.md

Auto-invocation per agent

The runtime is meant to be always-on — every user message is treated as the task and routed through the runtime, with no trigger keyword. How that invocation is wired depends on the agent:

Agent	Invocation mechanism	Always-on?
Claude Code	UserPromptSubmit hook (plugins/claude-code/hooks/) injects the runtime contract on every prompt; plus a simplicio-runtime skill and slash commands	yes, programmatic
Codex / Hermes / OpenCode	AGENTS.md loaded as standing instructions	yes (context file)
Cursor	.cursor/rules/*.mdc with alwaysApply: true	yes (always-apply rule)
GitHub Copilot	.github/copilot-instructions.md	yes (context file)
Cline	.clinerules/simplicio-prompt.md	yes (context file)
Aider	CONVENTIONS.md	yes (context file)
Gemini CLI	GEMINI.md loaded every turn	yes (context file)

A true prompt-submit hook (inject-on-every-prompt with programmatic stand-down) exists only in Claude Code. For the other agents, the always-applied context file is the invocation — it is read on every turn, so the contract is always present. All of them honor in-message stand-down phrases ("stop", "cancel", "exit runtime", "ignore simplicio").

Claude Code plugin

plugins/claude-code/ is a full Claude Code plugin: drop it into ~/.claude/plugins/simplicio-prompt/ (or your project's .claude/plugins/) to get an always-on hook, three slash commands, and a runtime skill:

• UserPromptSubmit hook (hooks/hooks.json → hooks/user-prompt-submit.mjs) — injects the runtime contract (hooks/runtime-directive.md) on every prompt, unless the prompt is an explicit stand-down. This is the always-on invocation.
• /simplicio <task> — run the next task through the Tuple-Space + Yool runtime.
• /simplicio-install <target> — install the runtime contract into the current repo (claude-code, codex, cursor, copilot, gemini, all, …).
• /simplicio-status on|off|<field>:on — toggle the opt-in status output.
• simplicio-runtime skill — auto-activates in repos that vendor the spec.

Legacy --install

The original single-file installer still works for backwards compatibility:

npx simplicio-prompt --install CLAUDE.md
npx simplicio-prompt --install AGENTS.md
npx simplicio-prompt --install .cursorrules

Integration adapter

For orchestration repos that want the runtime without copying tuple boilerplate, use the Python adapter:

from examples.python.prompt_fanout import PromptFanout

fanout = PromptFanout(repo="my-service", authority="simplicio-sprint")
root, receipt = fanout.spawn_task(
    "review checkout edge cases",
    mapper_context={"target": "src/checkout.ts"},
    depth=2,
    branching=8,
)
fanout.record_tokens("analysis", prompt_tokens=1200, completion_tokens=300, cost_usd=0.02)
print(receipt.virtual_agents)
print(fanout.snapshot()["token_usage"])

simplicio-dev-cli can use the same adapter for internal verification reasoning when it already has structured mapper context.

How to use the prompt

Use simplicio-prompt as a canonical execution prompt for coding agents such as Claude, Codex, Hermes, Cursor, Cline, or any assistant that can read repository instructions.

1. Run npx simplicio-prompt --install CLAUDE.md (or paste the ## Prompt section from prompts/agent-runtime-execution-prompt.md into AGENTS.md, CLAUDE.md, .cursorrules, or a custom system prompt).
2. In the target repository, just ask for work in your own words. You do not need to start the message with Implement — any user input (a sentence, a bug description, a code snippet, a one-word request) is treated as the task X and routed through the same runtime. The only opt-outs are explicit stand-down phrases like "stop", "cancel", "exit runtime".
3. The agent will read the canonical files listed in the prompt, decompose the task into a Hilbert-indexed tuple graph, create a root tuple, route active work through tuple-space primitives, and use LaneWorkerPool plus the V2 safe-speed controls.
4. Status output is opt-in (default: silent). Enable with YOOL_TUPLE_STATUS=true (or status_output=true runtime flag). When on, the agent returns this shape:

[Tuple Space Snapshot]
[Active Agents/Subagents]
[Total Agents/Subagents]
[Next Yool to Execute]
[Partial Result]

Per-field toggles (default false): YOOL_TUPLE_STATUS_SNAPSHOT, YOOL_TUPLE_STATUS_ACTIVE, YOOL_TUPLE_STATUS_TOTAL, YOOL_TUPLE_STATUS_NEXT, YOOL_TUPLE_STATUS_PARTIAL.

For high-throughput local runs, set the runtime environment variables before starting the agent or scripts:

$env:YOOL_TUPLE_LANE_CONCURRENCY="32"
$env:YOOL_TUPLE_MAX_LANE_CONCURRENCY="64"
$env:YOOL_TUPLE_CPU_QUOTA_PCT="95"
$env:YOOL_TUPLE_QUEUE_MAXSIZE="8192"
$env:YOOL_TUPLE_COMPRESSION_THRESHOLD="1024"
$env:YOOL_TUPLE_CACHE_MAX_ENTRIES="16384"
$env:YOOL_TUPLE_CACHE_TTL_S="3600"
$env:YOOL_TUPLE_API_MAX_RETRIES="3"
$env:YOOL_TUPLE_API_BACKOFF_BASE_MS="100"
$env:YOOL_TUPLE_API_BACKOFF_MAX_MS="5000"
$env:YOOL_TUPLE_CIRCUIT_FAILURE_THRESHOLD="5"
$env:YOOL_TUPLE_CIRCUIT_COOLDOWN_S="30"
$env:YOOL_TUPLE_BATCH_SMALL_TASK_SIZE="32"
$env:YOOL_TUPLE_CONTEXT_COMPRESSION_CHARS="6000"

Run the reference kernel and tests:

python kernel/yool_tuple_kernel.py
python -m unittest discover -s tests -p "test_*.py"

V2 benchmark report

The V2 report is the main evidence for the safe-speed runtime. Read it before adopting the prompt in another project:

• V2 Markdown report
• V2 PDF report
• V2 benchmark script
• V2 PDF generator

What the V2 report shows:

• 2,833.75x faster scale representation than normal instruction flow.
• 26.93x faster active execution than normal sequential execution.
• 4x fewer repeated provider calls through receipt/input cache.
• 32x fewer small-task calls through batching.
• 64x fewer provider failure attempts through circuit breakers.
• 76.32% estimated token savings through context compression.

The key point: V2 speeds up by avoiding repeated work and controlling provider pressure. It does not depend on unsafe infinite calls, unbounded concurrency, or retry storms.

High-throughput runtime defaults

The reference kernel is tuned for speed while keeping host guardrails explicit:

Env var	Default	Purpose
YOOL_TUPLE_LANE_CONCURRENCY / YOOL_LANE_CONCURRENCY	32	Preferred workers per lane.
YOOL_TUPLE_MAX_LANE_CONCURRENCY / YOOL_MAX_LANE_CONCURRENCY	64	Ceiling for workers per lane.
YOOL_TUPLE_CPU_QUOTA_PCT / YOOL_CPU_QUOTA_PCT	95	Default per-yool CPU budget.
YOOL_TUPLE_QUEUE_MAXSIZE / YOOL_QUEUE_MAXSIZE	8192	Lane queue scan cap.
YOOL_TUPLE_COMPRESSION_THRESHOLD / YOOL_COMPRESSION_THRESHOLD	1024	Active materialized agents before pruning.
YOOL_TUPLE_CACHE_MAX_ENTRIES / YOOL_CACHE_MAX_ENTRIES	16384	Receipt/input-hash cache size.
YOOL_TUPLE_CACHE_TTL_S / YOOL_CACHE_TTL_S	3600	Cache TTL in seconds.
YOOL_TUPLE_API_MAX_RETRIES / YOOL_API_MAX_RETRIES	3	Retry budget for transient API/LLM failures.
YOOL_TUPLE_API_BACKOFF_BASE_MS / YOOL_API_BACKOFF_BASE_MS	100	Initial jittered backoff delay.
YOOL_TUPLE_API_BACKOFF_MAX_MS / YOOL_API_BACKOFF_MAX_MS	5000	Backoff ceiling.
YOOL_TUPLE_CIRCUIT_FAILURE_THRESHOLD / YOOL_CIRCUIT_FAILURE_THRESHOLD	5	Failures before opening provider breaker.
YOOL_TUPLE_CIRCUIT_COOLDOWN_S / YOOL_CIRCUIT_COOLDOWN_S	30	Provider cooldown after breaker opens.
YOOL_TUPLE_BATCH_SMALL_TASK_SIZE / YOOL_BATCH_SMALL_TASK_SIZE	32	Default small-task batch size.
YOOL_TUPLE_CONTEXT_COMPRESSION_CHARS / YOOL_CONTEXT_COMPRESSION_CHARS	6000	Large LLM context compression threshold.

Safe speedups now live in the kernel, not only in the prompt: receipt/input cache, adaptive lane concurrency, jittered backoff, provider circuit breakers, small-task batching, prompt/context compression, local yool routing, and speculative execution only for tuples marked idempotent=True.

Run the reference kernel and tests:

python kernel/yool_tuple_kernel.py
python -m unittest discover -s tests -p "test_*.py"

Benchmark reports:

• Prompt vs normal Markdown
• Prompt vs normal PDF
• V2 safe-speed Markdown
• V2 safe-speed PDF

Why a separate repo

The pattern is cross-project. SendSprint, llm-project-mapper, future agents - all consume the same spec. One source of truth, vendored on demand.

License

MIT © Wesley Simplicio. See LICENSE.

Star History

License

MIT. See LICENSE.