v0.18.0 — Phase 1 blueprint templates

v0.18.0 - 2026-07-07

Ecosystem epic #254 Phase 1 — blueprint templates. Adds a name-parameterized make:swarm:blueprint generator over a unified, tokenized blueprint catalog, so a developer can scaffold a complete, runnable, use-case-shaped swarm (swarm + agents + console command + README) as their own — renamed and namespaced — rather than only reading the fixed-name reference copies that swarm:install:examples lands. One tokenized corpus now serves both: install:examples lands it verbatim, make:swarm:blueprint lands it renamed.

Added

• make:swarm:blueprint — scaffold a complete, runnable swarm from a curated blueprint (#378). Where make:swarm:swarm scaffolds an empty swarm shell for a topology, make:swarm:blueprint <Name> --template=<slug> scaffolds a whole working use-case — the swarm class, its agents, and a runnable console command — renamed and namespaced as your own. It draws from the same curated corpus under stubs/examples/ that swarm:install:examples lands, but where the installer copies a tree verbatim (fixed-name reference to read), this copies it renamed (a starting point to edit). Omit --template in an interactive terminal to pick from a list; the swarm name can be prompted too. Ships three blueprints to start — pipeline (sequential), research (parallel fan-out), and approval (durable, human-in-the-loop) — with more to follow. The generator fails loud rather than overwrite existing app files (pass --force to overwrite) or generate uncompilable code (reserved names are rejected). Each blueprint declares its canonical class/command names in a per-tree blueprint.json manifest; agent class names are preserved on rename by design.
• triage blueprint — hierarchical routing (#379). Adds a fourth blueprint, hierarchical-support-triage, exercising the hierarchical topology: a RequestClassifier coordinator reads the incoming request, classifies it, and returns a structured route plan (start_at + nodes) that dispatches to exactly one of three worker handlers (BillingResponder, TechnicalResponder, GeneralResponder). It is the first shipped example of a coordinator-owned route plan — no route() callback — and, like the other blueprints, runs end-to-end with no live model by shipping the coordinator as a ScriptedAgent that also implements HasStructuredOutput. Scaffold it with make:swarm:blueprint <Name> --template=triage.
• extraction blueprint — structured output, not free text (#380). A new sequential blueprint (--template=extraction) that pulls a typed, schema-validated record out of unstructured input: FieldExtractor extracts the raw fields as JSON, then RecordNormalizer validates and canonicalises them into a trusted contact record. Both agents implement Laravel AI's HasStructuredOutput and declare a schema(JsonSchema $schema): array, so the example demonstrates producing a validated STRUCTURED result rather than prose — the headline structured-output pattern. Runs end-to-end via prompt() with the shipped ScriptedAgents (no provider, no API key), which keeps the structured-output agents off the streaming path where the #321 guard applies.
• streaming blueprint — durable per-node streaming, end to end (#382). A new sequential blueprint (--template=streaming) that runs in durable mode with #[DurableStreaming]: two worker nodes each token-stream a section of a digest, every delta is persisted to the causal log under its node id, and the run is replayable per node afterwards via CausalLogView::forRun($store, $runId)->fold() + SwarmTextDelta::combine(). It ships a small provider-free streaming agent — ScriptedStreamingEditor, whose stream() hand-yields TextDelta → TextEnd → StreamEnd offline — because the corpus's usual ScriptedAgent cannot stream. And it stays honest about durability: the runner command dispatches via dispatchDurable() (never ->run()/->stream(), which would carry the attribute but persist zero rows), and the smoke test asserts the run is actually durable — durable_streaming pinned true on the run row and per-node swarm_text_delta rows in swarm_stream_events. Requires the database persistence driver + migrations; the in-process advance drain in the runner is a demo-only shortcut for a queue worker, and the streamed tokens are scripted, not model-generated.
• memory blueprint — share a fact across steps through Swarm memory (#381). A new sequential blueprint (--template=memory, tree sequential-conversation-memory) that demonstrates the remember / recall memory-as-tool surface: RequestListener extracts the subject from a customer message and writes it to Run-scoped memory with the real Remember tool, then ReplyWriter reads it back with the real Recall tool and composes a reply that names it. Step one's acknowledgement deliberately omits the subject, so the only channel that can carry it to step two is memory — proving a value written in an earlier step shapes a later one, not the prompt chain. Run-scoped writes reach later agents via the default propagation policy (no custom policy needed), and Recall reads through that policy. Runs end-to-end via prompt() with the shipped ScriptedAgents (no provider, no API key), which call the same production tools a live model would. Scaffold it with make:swarm:blueprint <Name> --template=memory.

Changed

• Shared blueprint-corpus machinery extracted from swarm:install:examples (#378). The tree-walking, namespace-placeholder rewriting, and host-root-namespace resolution that swarm:install:examples used are now shared with make:swarm:blueprint via the InteractsWithBlueprintCorpus and ResolvesHostRootNamespace concerns, so the two commands stay in lockstep. swarm:install:examples' file output is unchanged — it continues to land example trees verbatim and skips the package-side README.md and (new) blueprint.json metadata. Its interactive picker now prefers the tree's blueprint.json summary as the single source of truth for the one-line description (falling back to the README's first line for any tree without a manifest).

Documentation

• Blueprint generator + catalog documented (#383). Added a make:swarm:blueprint section to docs/generators.md — the whole-use-case-vs-empty-shell distinction, the install-verbatim-vs-scaffold-renamed relationship with swarm:install:examples, the seven-blueprint catalog table (what each teaches / when to reach for it), the interactive and --template flows, options, and the fail-loud behavior. Surfaced the command in the README quick-start and added it to docs/public-surface.md.