hybrid — a design pattern for LLM-and-code cycles
A cycle, not a pipeline. Concretely: a tool that watches a recurring stream of soft input — agent traces, evaluator outputs, meeting transcripts, knowledge-base entries — labels each new item against a curated vocabulary, and flags when a pattern you said you'd address recurs. LLM extracts (lens) → typed records accumulate (substrate) → deterministic code filters and ranks (gate) → LLM reasons over the filtered slice (reasoner) → notification or action lands. Each new item becomes input for the next turn's lens.
That's a hybrid loop. The design pattern places LLM judgment and deterministic code in alternating layers that mutually generate each other's working surface — not just constraining each other, but producing the very inputs the other half operates over. The LLM generates typed records (and often the schema, notation, or code those records live in). The deterministic layer takes those records and produces filtered, scored, ranked context that becomes the next LLM call's input. Each half makes the other possible.
flowchart LR
classDef llm fill:#fff4d6,stroke:#b8860b,color:#000
classDef code fill:#d6e9ff,stroke:#1e6ab8,color:#000
classDef data fill:#e8e8e8,stroke:#666,color:#000
soft[(soft input<br/>transcript / doc / event)]:::data
lens["LENS<br/>LLM extracts"]:::llm
sub[(SUBSTRATE<br/>typed records)]:::data
gate["GATE<br/>code: filter / score / rank"]:::code
reason["REASONER<br/>LLM consumes substrate"]:::llm
action["ACTION<br/>code: apply / dispatch"]:::code
soft --> lens
lens --> sub
sub --> gate
gate --> reason
reason --> action
action -. new content .-> soft
Yellow = LLM acts. Blue = code acts. Grey = data flowing between. Two meta-layers close additional loops: calibration (predict + verdict log per evaluator — does the lens actually work?) and metabolism (substrate-wide audit — is the accumulated record drifting?).
What this project actually is
What you get from reading this repo: a vocabulary for naming recurring shapes in LLM-and-code systems, a Claude Code skill that auto-triggers when you describe one of those shapes, and pointers to working repos exemplifying each shape.
The skill is diagnostic-first — most projects don't need this pattern, and the skill tells Claude when not to use it. When a project does need it, the skill points at a library of recognizable shapes (RAG, ReAct, codegen-with-verification, multi-agent panels, the canonical 5-role hybrid loop, dev-time critique loops, knowledge-base auditors, plus a couple of cross-domain metaphors for the shape) so the design conversation has somewhere to start.
The framework's actual content is the disciplines the new block type (LLMs as fuzzy pattern mappers) requires beyond the conventional von-Neumann graph algebra: per-block calibration, context-as-code as load-bearing infrastructure, and the dev-time hybrid loop wrapping the runtime. These are named in THE_CASE.md.
Who it's for
- AI engineers shipping production LLM features. The framework provides a unifying vocabulary for what DSPy / LangGraph / AutoGen / pydantic each implement pieces of, and names the disciplines those tools leave open: calibration, context-as-code, dev-time loops.
- Solo developers and small teams building tools that involve LLM judgment, who haven't internalized the agent-framework ecosystem yet and want a starting model.
Install — Claude Code
The skill is markdown; install it however you prefer.
Symlink (simplest, recommended for solo use):
ln -s /path/to/hybrid/skills/hybrid-loops ~/.claude/skills/hybrid-loops
Marketplace install (discoverable, recommended for sharing):
/plugin marketplace add justinstimatze/hybrid
/plugin install hybrid-loops@hybrid-loops
Either path gives you the same thing: the hybrid-loops skill auto-triggers on relevant prompts. To confirm install worked, type something like "build me a tool that watches my evaluator outputs and flags when a regression pattern recurs" — the skill should activate and start asking diagnostic questions about surfaces, scope, and shape. If it doesn't, the install didn't take — file a GitHub issue.
The marketplace command requires this GitHub repo to be reachable. For forks or local development, use the local-path forms: /plugin marketplace add /path/to/hybrid and /plugin install hybrid-loops@hybrid-loops.
Install — other agents
The skill content is model-agnostic. Stub manifests are included for OpenAI Codex, Cursor, and Gemini — see CROSS_AGENT.md. The maintainer's primary platform is Claude Code; PRs from users on other agents are welcome.
Where to start reading
If you arrived here cold and want one entry point: SKILL.md is the operational center.
The reference docs each have a different reader in mind:
