@opengroundplan/core 0.1.1

package/templates/architectures/llm-workflow/files/docs/architecture/llm-workflow.python.md

@@ -0,0 +1,133 @@
+# LLM Workflow — Python
+
+**Stack:** `{{ stack }}` · **Chain:** `{{ workflowName | snake }}` · **First step:** `{{ firstStep | snake }}` · **Prompts:** `{{ promptsDir }}/`
+
+An LLM *workflow* orchestrates models and tools through **code paths you wrote in advance**.
+The control flow lives in a chain function you can read top to bottom; the model fills in the
+parts a model is good at. That is the whole trade: you give up handling inputs nobody
+anticipated, and you get a system that is debuggable, reproducible, and cheap to evaluate.
+
+## The one rule that matters
+
+> **A step may not call a model directly. It receives the provider on its context.**
+
+Every model call goes through the seam in `{{ solutionName | snake }}/workflow/ports/`. Nothing
+else under `workflow/` may import a vendor SDK, construct a client, or make an HTTP request.
+
+This is not a style preference. It is the property the rest of the architecture is built on:
+
+- **A model can be swapped and re-evaluated** by registering another binding, with no edit to
+  any step, chain, or prompt.
+- **The golden suite can run offline**, because the stub binding is injected exactly where the
+  real one would go — which is why `pytest tests/test_workflow_goldens.py` is green on a fresh
+  clone with no API key.
+- **A regression is attributable.** The completion records which model answered; the step
+  records which prompt version it pinned.
+
+The moment one step constructs its own client, all three properties are gone for the whole
+workflow, not just that step.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/workflow/
+  settings.py             the only module that reads os.environ
+  types.py                StepContext and the Step protocol
+  prompts.py              loads a pinned prompt version off disk
+  ports/
+    llm.py                the seam — no vendor, no model id, no endpoint
+    stub.py               deterministic offline binding
+    __init__.py           binding registry; the ONLY place an SDK may be imported
+  steps/                  leaves — one purpose each, composed by someone else
+    {{ firstStep | snake }}.py
+    normalize.py          a step need not call a model
+  routing/route.py        pick the branch, in code, before any model call
+  parallel/gather.py      fan out with a concurrency ceiling, fan back in *in order*
+  chains/{{ workflowName | snake }}.py     the predefined code path
+  evals/
+    goldens.jsonl         the dataset, reviewed in git
+    assertions.py         deterministic assertions
+    runner.py             runs the dataset against the stub binding
+{{ promptsDir }}/<name>/<version>.md       every prompt, versioned as a file
+.importlinter                              structural contracts
+tests/test_workflow_boundaries.py          the seam rule, checked by reading the source
+tests/test_workflow_goldens.py             the golden suite
+```
+
+Composition flows one way: `chains` → `routing`/`parallel` → `steps` → `ports`. A step never
+imports another step. When two steps need to run in sequence, that sequence *is* the chain —
+putting it inside a step hides a code path that was supposed to be predefined.
+
+## The three patterns, and when each applies
+
+| Pattern | Lives in | Use when |
+|---|---|---|
+| **Prompt chaining** | `chains/` | The task decomposes into fixed subtasks, each one easier than the whole. Trades latency for accuracy. |
+| **Routing** | `routing/` | Inputs fall into distinct categories that are better handled separately, and classifying is cheap. |
+| **Parallelization** | `parallel/` | Subtasks are independent — for speed, or to raise confidence by taking several passes. |
+
+Keep the classifier in `routing/` deterministic. If a branch genuinely needs a model to decide,
+make that decision its own step and route on the step's output, so the branch is still
+reproducible from a recorded run.
+
+## Prompts are files, not literals
+
+`{{ promptsDir }}/<name>/<version>.md`. A step pins its version with literal arguments:
+
+```python
+load_prompt("{{ firstStep | kebab }}", "{{ promptVersion }}")
+```
+
+Never edit a shipped version in place — add `v2.md` beside it and move the pin. A prompt edit is
+a behaviour change; if it is not a new file, an eval score cannot be attributed to a wording and
+a bad prompt cannot be rolled back by reverting one line.
+
+## Enforcement — what fails, and how
+
+| Command | What it rejects |
+|---|---|
+| `{{ testCommand }}` | `test_only_ports_reach_a_model` — an SDK or HTTP import outside `ports/`. `test_only_settings_reads_the_environment`. `test_steps_are_leaves` — a step importing a step, chain, routing, or parallel module. `test_every_pinned_prompt_version_exists` — a `load_prompt(…)` pin with no file, or one built from non-literal arguments. `test_golden_dataset_is_checked_in`. `test_golden_cases_pass` — any golden whose output moved. |
+| `lint-imports` | The layering contracts in `.importlinter`. Also run inside the suite, so CI catches them either way. |
+
+The source-reading tests use only `ast` from the standard library, so the seam rule holds even
+before `import-linter` is installed — which matters, because the one check you most want is the
+one that cannot be turned off by skipping an optional dependency.
+
+### What is not enforced mechanically
+
+- **A step doing more than one thing.** Nothing detects a step that quietly grew a second model
+  call. Review for it; the smell is a step whose name has an "and" in it.
+- **A model reached through a name the checker does not know.** The import scan works from a
+  list of SDK and HTTP package names. A new vendor package, or a client injected through a
+  dependency container, passes. Add the package to `MODEL_ACCESS` in
+  `tests/test_workflow_boundaries.py` when you adopt one.
+- **Prompt drift across versions.** The check proves the pinned file exists, not that `v2` is an
+  improvement on `v1`. That is what the golden dataset is for, and the dataset only covers the
+  cases someone wrote down.
+- **The stub telling the truth.** The offline binding proves the orchestration, never the
+  model. A run against a real binding is a separate, budgeted job — schedule it; do not put it
+  on every commit.
+- **Knowing when to stop.** No check can tell you the number of steps has become unpredictable.
+  That is the boundary where this style ends and an agentic loop begins, and it is a judgement
+  call — record it in an ADR when you make it.
+
+## Wiring a real provider
+
+Add `ports/<vendor>.py`, implement `LlmPort`, register it in `ports/__init__.py`, and set
+`{{ solutionName | upperSnake }}_WORKFLOW_BINDING`. If the base you generated on already ships a
+provider registry, the binding is a thin adapter onto it — the seam stays, and the model id and
+key keep resolving by role through that layer rather than at a call site.
+
+## When this stops being the right shape
+
+Anthropic's guidance is explicit that multi-step systems trade latency and cost for better task
+performance, and are worth it *only* when a single well-optimized prompt with retrieval and
+in-context examples has already fallen short. Two signals mean the fixed control flow has
+stopped paying: the chain has grown branches for inputs you keep discovering in production, and
+you can no longer predict the number of steps at design time. The second one is the real line —
+past it, you want an agent, and you want the guardrails that come with one.
+
+## Sources
+
+- Anthropic, [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
+- Anthropic, [How to implement tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works)

package/templates/architectures/llm-workflow/files/docs/architecture/llm-workflow.typescript.md

@@ -0,0 +1,124 @@
+# LLM Workflow — TypeScript / Node
+
+**Stack:** `{{ stack }}` · **Chain:** `{{ workflowName | kebab }}` · **First step:** `{{ firstStep | kebab }}` · **Prompts:** `{{ promptsDir }}/`
+
+An LLM *workflow* orchestrates models and tools through **code paths you wrote in advance**.
+The control flow lives in a chain function you can read top to bottom; the model fills in the
+parts a model is good at. That is the whole trade: you give up handling inputs nobody
+anticipated, and you get a system that is debuggable, reproducible, and cheap to evaluate.
+
+## The one rule that matters
+
+> **A step may not call a model directly. It receives the provider on its context.**
+
+Every model call goes through the seam in `src/workflow/ports/`. Nothing else under
+`src/workflow/` may import a vendor SDK, construct a client, or make an HTTP request.
+
+This is not a style preference. It is the property the rest of the architecture is built on:
+
+- **A model can be swapped and re-evaluated** by registering another binding, with no edit to
+  any step, chain, or prompt.
+- **The golden suite can run offline**, because the stub binding is injected exactly where the
+  real one would go — which is why `npm run check:goldens` is green on a fresh clone with no
+  API key.
+- **A regression is attributable.** The completion records which model answered; the step
+  records which prompt version it pinned.
+
+The moment one step constructs its own client, all three properties are gone for the whole
+workflow, not just that step.
+
+## Layout
+
+```
+src/workflow/
+  settings.ts             the only module that reads process.env
+  types.ts                StepContext and the Step signature
+  prompts.ts              loads a pinned prompt version off disk
+  ports/
+    llm.ts                the seam — no vendor, no model id, no endpoint
+    stub.ts               deterministic offline binding
+    index.ts              binding registry; the ONLY place an SDK may be imported
+  steps/                  leaves — one purpose each, composed by someone else
+    {{ firstStep | kebab }}.ts
+    normalize.ts          a step need not call a model
+    index.ts              the surface chains compose against
+  routing/route.ts        pick the branch, in code, before any model call
+  parallel/gather.ts      fan out with a concurrency ceiling, fan back in *in order*
+  chains/{{ workflowName | kebab }}.ts     the predefined code path
+  evals/
+    goldens.jsonl         the dataset, reviewed in git
+    assert.ts             deterministic assertions
+    run.ts                runs the dataset against the stub binding
+{{ promptsDir }}/<name>/<version>.md      every prompt, versioned as a file
+scripts/check-llm-workflow.mjs
+```
+
+Composition flows one way: `chains` → `routing`/`parallel` → `steps` → `ports`. A step never
+imports another step. When two steps need to run in sequence, that sequence *is* the chain —
+putting it inside a step hides a code path that was supposed to be predefined.
+
+## The three patterns, and when each applies
+
+| Pattern | Lives in | Use when |
+|---|---|---|
+| **Prompt chaining** | `chains/` | The task decomposes into fixed subtasks, each one easier than the whole. Trades latency for accuracy. |
+| **Routing** | `routing/` | Inputs fall into distinct categories that are better handled separately, and classifying is cheap. |
+| **Parallelization** | `parallel/` | Subtasks are independent — for speed, or to raise confidence by taking several passes. |
+
+Keep the classifier in `routing/` deterministic. If a branch genuinely needs a model to decide,
+make that decision its own step and route on the step's output, so the branch is still
+reproducible from a recorded run.
+
+## Prompts are files, not literals
+
+`{{ promptsDir }}/<name>/<version>.md`. A step pins its version with literal arguments:
+
+```ts
+loadPrompt('{{ firstStep | kebab }}', '{{ promptVersion }}')
+```
+
+Never edit a shipped version in place — add `v2.md` beside it and move the pin. A prompt edit is
+a behaviour change; if it is not a new file, an eval score cannot be attributed to a wording and
+a bad prompt cannot be rolled back by reverting one line.
+
+## Enforcement — what fails, and how
+
+| Command | What it rejects |
+|---|---|
+| `npm run check:workflow` | An SDK or HTTP import outside `ports/`; a bare `fetch()`; `process.env` read outside `settings.ts`; a step importing a step, a chain, routing, or parallel; a `loadPrompt(…)` pin with no file behind it; a missing or empty golden dataset. Exits non-zero with the file and the reason. |
+| `npm run check:goldens` | Any golden case whose output moved. Runs `chains/{{ workflowName | kebab }}.ts` against the stub binding — offline and deterministic. |
+
+Wire both into CI next to `{{ lintCommand }}`. The boundary check is zero-dependency Node, so it
+works whichever linter the base chose; the golden runner needs `tsx`, which the manifest adds.
+
+Every path and list in `scripts/check-llm-workflow.mjs` is overridable by environment variable
+(`WORKFLOW_DIR`, `WORKFLOW_PORTS_DIR`, `WORKFLOW_PROMPTS_DIR`, …) — move the layout, do not fork
+the script.
+
+### What is not enforced mechanically
+
+- **A step doing more than one thing.** Nothing detects a step that quietly grew a second model
+  call. Review for it; the smell is a step whose name has an "and" in it.
+- **Prompt drift across versions.** The check proves the pinned file exists, not that `v2` is an
+  improvement on `v1`. That is what the golden dataset is for, and the dataset only covers the
+  cases someone wrote down.
+- **The stub telling the truth.** The offline binding proves the orchestration, never the
+  model. A run against a real binding is a separate, budgeted job — schedule it; do not put it
+  on every commit.
+- **Knowing when to stop.** No check can tell you the number of steps has become unpredictable.
+  That is the boundary where this style ends and an agentic loop begins, and it is a judgement
+  call — record it in an ADR when you make it.
+
+## When this stops being the right shape
+
+Anthropic's guidance is explicit that multi-step systems trade latency and cost for better task
+performance, and are worth it *only* when a single well-optimized prompt with retrieval and
+in-context examples has already fallen short. Two signals mean the fixed control flow has
+stopped paying: the chain has grown branches for inputs you keep discovering in production, and
+you can no longer predict the number of steps at design time. The second one is the real line —
+past it, you want an agent, and you want the guardrails that come with one.
+
+## Sources
+
+- Anthropic, [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
+- Anthropic, [How to implement tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works)

package/templates/architectures/llm-workflow/files/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "check:workflow": "node scripts/check-llm-workflow.mjs",
+    "check:goldens": "tsx src/workflow/evals/run.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.1"
+  }
+}

package/templates/architectures/llm-workflow/files/scripts/check-llm-workflow.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// Fails when a workflow module reaches a model without going through the provider seam, when a
+// step composes another step, or when a pinned prompt version has no file behind it.
+// Zero dependencies on purpose: the bases disagree on linter (ESLint vs Biome), so this check
+// must work without editing whichever config the base already owns.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** The only place these paths and lists are written. Environment overrides them per repo. */
+const defaults = {
+  workflowDir: 'src/workflow',
+  portsDir: 'src/workflow/ports',
+  stepsDir: 'src/workflow/steps',
+  settingsFile: 'src/workflow/settings.ts',
+  promptsDir: '{{ promptsDir }}',
+  goldensFile: 'src/workflow/evals/goldens.jsonl',
+  extensions: '.ts,.tsx,.mts,.cts,.js,.jsx,.mjs,.cjs',
+};
+
+const env = (name, fallback) => process.env[name]?.trim() || fallback;
+
+const workflowDir = toPosix(env('WORKFLOW_DIR', defaults.workflowDir));
+const portsDir = toPosix(env('WORKFLOW_PORTS_DIR', defaults.portsDir));
+const stepsDir = toPosix(env('WORKFLOW_STEPS_DIR', defaults.stepsDir));
+const settingsFile = toPosix(env('WORKFLOW_SETTINGS_FILE', defaults.settingsFile));
+const promptsDir = toPosix(env('WORKFLOW_PROMPTS_DIR', defaults.promptsDir));
+const goldensFile = toPosix(env('WORKFLOW_GOLDENS_FILE', defaults.goldensFile));
+const extensions = new Set(env('WORKFLOW_EXTENSIONS', defaults.extensions).split(','));
+
+/** Vendor SDKs and raw HTTP clients. Only the ports directory may name any of these. */
+const MODEL_ACCESS = [
+  '@anthropic-ai/',
+  'openai',
+  '@azure/openai',
+  '@google/genai',
+  '@google-cloud/vertexai',
+  '@aws-sdk/client-bedrock',
+  '@mistralai/',
+  'cohere-ai',
+  'groq-sdk',
+  'replicate',
+  'ollama',
+  'langchain',
+  '@langchain/',
+  'ai',
+  '@ai-sdk/',
+  'axios',
+  'got',
+  'node-fetch',
+  'undici',
+  'superagent',
+  'node:http',
+  'node:https',
+];
+
+/** Composition directions a step may never take. Steps are leaves. */
+const STEP_FORBIDDEN = ['/chains/', '/routing/', '/parallel/'];
+
+const SPECIFIER_PATTERNS = [
+  /\bfrom\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\bimport\s+['"]([^'"]+)['"]/g,
+];
+
+const FETCH_CALL = /(?<![.\w])fetch\s*\(/;
+const ENV_READ = /\bprocess\s*\.\s*env\b/;
+const LOAD_PROMPT = /\bloadPrompt\s*\(\s*['"]([^'"]+)['"]\s*,\s*['"]([^'"]+)['"]\s*\)/g;
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+/** Comments quote import syntax as documentation; scanning them reports violations that are prose. */
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+async function listFiles(dir) {
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    const child = `${dir}/${entry.name}`;
+    if (entry.isDirectory()) found.push(...(await listFiles(child)));
+    else if (extensions.has(path.extname(entry.name))) found.push(child);
+  }
+  return found;
+}
+
+function specifiersIn(source) {
+  const found = new Set();
+  for (const pattern of SPECIFIER_PATTERNS) {
+    for (const match of source.matchAll(pattern)) found.add(match[1]);
+  }
+  return found;
+}
+
+function isModelAccess(specifier) {
+  return MODEL_ACCESS.some((banned) =>
+    banned.endsWith('/')
+      ? specifier.startsWith(banned)
+      : specifier === banned || specifier.startsWith(`${banned}/`),
+  );
+}
+
+/** Resolve a relative specifier to a repo-root-relative path so step-to-step imports are visible. */
+function resolveLocal(specifier, fromFile) {
+  if (!specifier.startsWith('.')) return null;
+  return path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+}
+
+async function exists(file) {
+  return stat(file).then(
+    () => true,
+    () => false,
+  );
+}
+
+async function findViolations() {
+  const violations = [];
+  const files = await listFiles(workflowDir);
+
+  if (files.length === 0) {
+    return [`${workflowDir}/ has no source files — the workflow layout is missing`];
+  }
+
+  for (const file of files) {
+    const source = stripComments(await readFile(file, 'utf8'));
+    const inPorts = file === portsDir || file.startsWith(`${portsDir}/`);
+    // The barrel exists to re-export steps, so it is the one file in steps/ allowed to import them.
+    const inSteps = file.startsWith(`${stepsDir}/`) && !/\/index\.[^/]+$/.test(file);
+
+    for (const specifier of specifiersIn(source)) {
+      if (!inPorts && isModelAccess(specifier)) {
+        violations.push(
+          `${file}: imports "${specifier}" — only ${portsDir}/ may reach a model. ` +
+            `Take an LlmPort on the step context instead.`,
+        );
+      }
+
+      const local = resolveLocal(specifier, file);
+      if (!inSteps || local === null) continue;
+
+      if (local.startsWith(`${stepsDir}/`)) {
+        violations.push(`${file}: step imports another step ("${specifier}") — compose in a chain`);
+      }
+      for (const direction of STEP_FORBIDDEN) {
+        if (local.includes(direction)) {
+          violations.push(
+            `${file}: step imports ${direction.replaceAll('/', '')} code ("${specifier}") — composition flows one way`,
+          );
+        }
+      }
+    }
+
+    if (!inPorts && FETCH_CALL.test(source)) {
+      violations.push(
+        `${file}: calls fetch() — a model call belongs behind the port in ${portsDir}/`,
+      );
+    }
+    if (file !== settingsFile && ENV_READ.test(source)) {
+      violations.push(`${file}: reads process.env — configuration belongs in ${settingsFile}`);
+    }
+
+    for (const [, name, version] of source.matchAll(LOAD_PROMPT)) {
+      const prompt = `${promptsDir}/${name}/${version}.md`;
+      if (!(await exists(prompt))) {
+        violations.push(`${file}: loadPrompt("${name}", "${version}") has no file at ${prompt}`);
+      }
+    }
+  }
+
+  const goldens = await readFile(goldensFile, 'utf8').catch(() => null);
+  if (goldens === null) {
+    violations.push(`${goldensFile} is missing — the golden dataset is checked in, not generated`);
+  } else if (
+    goldens.split(/\r?\n/).filter((line) => line.trim() && !line.startsWith('#')).length === 0
+  ) {
+    violations.push(`${goldensFile} has no cases — an empty dataset is not a passing suite`);
+  }
+
+  return violations;
+}
+
+const violations = await findViolations();
+if (violations.length > 0) {
+  console.error(`LLM workflow boundary violations (${violations.length}):`);
+  for (const violation of violations) console.error(`  ${violation}`);
+  process.exit(1);
+}
+
+console.log(
+  `Workflow boundaries hold: every model call in ${workflowDir}/ goes through ${portsDir}/.`,
+);

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/__init__.py

@@ -0,0 +1,5 @@
+"""Predefined LLM code paths: steps compose into chains through routing and parallelization.
+
+Import order in this package is one-way — ``chains`` -> ``routing``/``parallel`` -> ``steps``
+-> ``ports`` — and no module outside ``ports`` may reach a model.
+"""

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/chains/__init__.py

@@ -0,0 +1,5 @@
+"""Chains: the predefined code paths. One function per workflow, control flow visible in it."""
+
+from .{{ workflowName | snake }} import run_{{ workflowName | snake }}
+
+__all__ = ["run_{{ workflowName | snake }}"]

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/chains/__workflowName.snake__.py

@@ -0,0 +1,19 @@
+"""Route, fan out, then chain the deterministic tail.
+
+The whole control flow is visible in one function, which is what makes this style debuggable
+and evaluable. When the number of steps stops being predictable, this is no longer the right
+shape — see docs/architecture/llm-workflow.python.md.
+"""
+
+from __future__ import annotations
+
+from ..parallel import gather
+from ..routing import route
+from ..steps import {{ firstStep | snake }}_step, normalize_step
+from ..types import StepContext
+
+
+async def run_{{ workflowName | snake }}(text: str, ctx: StepContext) -> str:
+    routed = route(text, ctx)
+    extracted = await gather(routed.chunks, {{ firstStep | snake }}_step, ctx)
+    return await normalize_step(extracted, ctx)

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/evals/__init__.py

@@ -0,0 +1 @@
+"""Golden dataset and deterministic assertions for the workflow's predefined code paths."""

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/evals/assertions.py

@@ -0,0 +1,82 @@
+"""Deterministic assertions only.
+
+A model grading another model is itself stochastic and cannot tell a regression from noise.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class Expectation:
+    equals: str | None = None
+    contains: list[str] = field(default_factory=list)
+    not_contains: list[str] = field(default_factory=list)
+    regex: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class GoldenCase:
+    id: str
+    text: str
+    expect: Expectation
+    # Per-case override so a case can force the chunked branch without moving the default.
+    chunk_chars: int | None = None
+
+
+def _collapse(value: str) -> str:
+    return " ".join(value.split())
+
+
+def check(expect: Expectation, output: str) -> list[str]:
+    """One message per violated expectation; an empty list means the case passed."""
+    failures: list[str] = []
+    actual = _collapse(output)
+    haystack = actual.lower()
+
+    if expect.equals is not None and actual != _collapse(expect.equals):
+        failures.append(f'equals: expected "{_collapse(expect.equals)}", got "{actual}"')
+    for needle in expect.contains:
+        if needle.lower() not in haystack:
+            failures.append(f'contains: "{needle}" missing')
+    for needle in expect.not_contains:
+        if needle.lower() in haystack:
+            failures.append(f'notContains: "{needle}" present')
+    if expect.regex is not None and re.search(expect.regex, actual) is None:
+        failures.append(f'regex: /{expect.regex}/ did not match "{actual}"')
+
+    return failures
+
+
+def parse_goldens(source: str) -> list[GoldenCase]:
+    """One case per line, reviewed in git. Blank lines and ``#`` comments are allowed."""
+    cases: list[GoldenCase] = []
+
+    for number, line in enumerate(source.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        try:
+            raw = json.loads(stripped)
+        except json.JSONDecodeError as error:
+            raise ValueError(f"golden line {number} is not valid JSON: {error}") from error
+
+        expected = raw.get("expect", {})
+        cases.append(
+            GoldenCase(
+                id=raw["id"],
+                text=raw["input"],
+                chunk_chars=raw.get("chunkChars"),
+                expect=Expectation(
+                    equals=expected.get("equals"),
+                    contains=list(expected.get("contains", [])),
+                    not_contains=list(expected.get("notContains", [])),
+                    regex=expected.get("regex"),
+                ),
+            )
+        )
+
+    return cases

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/evals/goldens.jsonl

@@ -0,0 +1,4 @@
+{"id": "short-input-takes-the-single-branch", "input": "alpha beta", "chunkChars": 24, "expect": {"equals": "{{ firstStep | kebab }}:alpha beta"}}
+{"id": "long-input-fans-out-and-joins-in-order", "input": "one two three four five six seven eight", "chunkChars": 24, "expect": {"equals": "{{ firstStep | kebab }}:one two three four five | {{ firstStep | kebab }}:six seven eight"}}
+{"id": "ragged-whitespace-does-not-change-the-result", "input": "   alpha    beta   ", "chunkChars": 24, "expect": {"equals": "{{ firstStep | kebab }}:alpha beta"}}
+{"id": "empty-input-produces-no-model-calls", "input": "   ", "chunkChars": 24, "expect": {"equals": ""}}

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/evals/runner.py

@@ -0,0 +1,64 @@
+"""Runs the golden dataset against the stub binding.
+
+Offline, deterministic, and green on a fresh clone — it proves the orchestration, not the
+model. Swapping in a real binding is how you evaluate a model; that run belongs in CI on a
+schedule, not on every commit.
+
+    python -m {{ solutionName | snake }}.workflow.evals.runner [path/to/goldens.jsonl]
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from ..chains import run_{{ workflowName | snake }}
+from ..ports.stub import StubLlm
+from ..settings import get_settings
+from ..types import create_context
+from .assertions import GoldenCase, check, parse_goldens
+
+
+def load_cases(path: str | None = None) -> tuple[Path, list[GoldenCase]]:
+    """Reading is synchronous on purpose — no blocking file I/O inside the event loop."""
+    file = Path(path or get_settings().goldens_file)
+    return file, parse_goldens(file.read_text(encoding="utf-8"))
+
+
+async def run_cases(cases: Sequence[GoldenCase]) -> list[str]:
+    llm = StubLlm()
+    failures: list[str] = []
+
+    for case in cases:
+        overrides = {"chunk_chars": case.chunk_chars} if case.chunk_chars else {}
+        ctx = create_context(llm=llm, **overrides)
+        try:
+            output = await run_{{ workflowName | snake }}(case.text, ctx)
+        except Exception as error:  # a throwing case is a failing case, not a crashed run
+            failures.append(f"{case.id}: threw {error!r}")
+            continue
+        failures.extend(f"{case.id}: {message}" for message in check(case.expect, output))
+
+    return failures
+
+
+async def run_goldens(path: str | None = None) -> list[str]:
+    """Returns one message per failing case; an empty list means the suite passed."""
+    file, cases = load_cases(path)
+    if not cases:
+        return [f"No golden cases in {file} — an empty dataset is not a passing suite."]
+    return await run_cases(cases)
+
+
+def main() -> int:
+    failures = asyncio.run(run_goldens(sys.argv[1] if len(sys.argv) > 1 else None))
+    for failure in failures:
+        print(f"  FAIL  {failure}", file=sys.stderr)
+    print(f"{len(failures)} golden failure(s)")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/parallel/__init__.py

@@ -0,0 +1,5 @@
+"""Parallelization: fan out over independent inputs, fan back in without losing order."""
+
+from .gather import gather
+
+__all__ = ["gather"]