← roadmap

interleave

improve priority P2 effort M wave 2

What it does: A spec+library plugin (no MCP, no hooks, no agents) implementing the “Deterministic Skeleton with LLM Islands” pattern for token-efficient document generation. Concretely it ships: (1) one skill (skills/interleave/SKILL.md + SKILL-compact.md) — a placeholder-filling orchestrator that scans a markdown file for <!-- LLM:NAME ... END LLM:NAME --> HTML-comment markers, extracts Task/Format/Context fields, routes each island to a model tier via keyword heuristics, dispatches parallel general-purpose subagents, replaces each block with subagent output, and writes warning markers for failures; (2) a 6-file spec under docs/spec/ (pattern, analysis/section-classification flowchart, orchestration lifecycle, placeholder format contract, model-routing contract); (3) a reference bash implementation scripts/template-roadmap-md.sh that renders deterministic roadmap sections from roadmap.json + bd (beads) queries and emits exactly 3 LLM placeholders (NEXT_GROUPINGS=sonnet, MODULE_HIGHLIGHTS=haiku, RESEARCH_AGENDA=haiku). It is actively consumed: interpath’s artifact-gen roadmap-monorepo phase shells out to template-roadmap-md.sh and reimplements the fill loop.</purpose_confirmed> The placeholder mechanism is an informal HTML-comment microformat validated only post-hoc by string-grepping for unclosed tags — it lacks the grammar-constrained / deterministic structured-generation layer that is the 2025-2026 frontier for exactly this “deterministic-skeleton + LLM-island” pattern (Pre3 pushdown-automata constraint compilation, IterGen, draft-conditioned constrained decoding, and the StructuredOutput/JSON-schema contract this very task runs on). A subagent island can emit markdown that breaks the surrounding skeleton because nothing constrains decoding to the island’s declared Format; the skeleton is “deterministic” but the fill is unconstrained free-text. Secondary gap: the claimed savings (67%, 3-5x) and per-island quality are asserted, never instrumented, missing the reliability-science framing (beyond-pass@1 / variance across trials) that interstat could supply. The concept itself is squarely on-trend (this is essentially Code Mode / progressive disclosure at document granularity), so this is a hardening gap, not a wrong bet.

Rationale: The core bet is correct and SOTA-aligned: “render the boring parts with a script, only call the LLM for the interesting islands, route islands to model tiers” is exactly the Code Mode / progressive-disclosure / structured-generation frontier (deterministic code at the skeleton, LLM only at the islands). The prior-art writeup is honest and accurate (Astro Islands, RSC, Qwik, Guidance/LMQL/SGLang, Skeleton-of-Thought). The spec is clean and the reference script is solid. This is not a deprecate (real, used, conceptually current) and not a clean keep, because two concrete frontier ideas are missing and one is load-bearing: (1) grammar/schema-constrained island fills so structure cannot break — the exact technique modern harnesses including this one use for reliable structured output; (2) actual measurement of the savings/quality claims rather than asserted ratios. The duplicated fill loop in interpath is also a real maintenance liability. Improve (harden the existing correct design), not modernize (the architecture doesn’t need replacing).

Redundancy: Mild, one-directional overlap with interpath: interpath’s artifact-gen roadmap-monorepo phase reimplements interleave’s entire scan/extract/route/dispatch/replace fill loop inline (skills/artifact-gen/phases/roadmap-monorepo.md) instead of invoking interleave’s skill — so the orchestrator logic exists in two places and can drift. The deterministic/semantic split concept is singular in the roster; no other plugin duplicates the pattern. Model-tier keyword routing lightly conceptually overlaps interrank/interspect (which own real model routing) but interleave’s is a hardcoded heuristic table, not a competing router.

Actions:

  • Add a per-island Format/schema contract that is machine-checkable: extend the placeholder format with an optional schema: or structured Format: field, and have the orchestrator validate (and on failure, repair-loop or re-dispatch) each subagent’s output against it before replacement — bringing the StructuredOutput/constrained-generation discipline (Pre3/IterGen-style) to the fill step so an island can’t silently break the skeleton’s markdown.
  • Instrument and verify the savings claims: emit per-run island input/output token counts (the reference script already knows island sizes) and wire a quick interstat/interpulse comparison vs full-regen, so the asserted 67% / 3-5x becomes measured per-document rather than a static spec number; this also catches when a document drops below the ≥50% deterministic break-even.
  • De-duplicate the fill loop: have interpath’s artifact-gen roadmap-monorepo phase invoke interleave’s skill (or a shared script) instead of reimplementing scan/extract/route/dispatch/replace inline, so the orchestrator logic lives in one place.
  • Replace the hardcoded sonnet/haiku/opus tier table with a routing-name resolution step (interrank resolve_routing_name / interspect) or at minimum an alias indirection, so model-tier selection survives model renames instead of pinning literal 2025-era names in SKILL.md and model-routing.md.