@opengroundplan/core 0.1.1

package/templates/architectures/layered/files/scripts/check-layers.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Layered-architecture boundary check. Fails when an import crosses a layer boundary the
+ * architecture forbids. Zero dependencies so it runs before anything is installed.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+const CONFIG_PATH = process.env.LAYERS_CONFIG ?? 'architecture.layers.json';
+
+/** Import, re-export, dynamic import, and require — the four ways a specifier appears. */
+const SPECIFIER =
+  /(?:\bimport\b|\bexport\b)[^'"();]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]|\b(?:import|require)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+async function loadConfig(root) {
+  const raw = await readFile(path.join(root, CONFIG_PATH), 'utf8');
+  const config = JSON.parse(raw);
+  const layers = new Map();
+
+  config.layers.forEach((layer, index) => {
+    for (const dir of layer.dirs) layers.set(dir, { name: layer.name, index, shared: false });
+  });
+  for (const dir of config.shared ?? []) {
+    layers.set(dir, { name: dir, index: -1, shared: true });
+  }
+  return { ...config, byDir: layers };
+}
+
+async function sourceFiles(dir, config, out = []) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (config.ignore.includes(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) await sourceFiles(full, config, out);
+    else if (config.extensions.includes(path.extname(entry.name))) out.push(full);
+  }
+  return out;
+}
+
+/** Which layer owns a path, by the first folder under the source root. `null` = unclassified. */
+function classify(absolute, root, config) {
+  const relative = path.relative(path.join(root, config.root), absolute);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return config.byDir.get(relative.split(path.sep)[0]) ?? null;
+}
+
+/** Resolve a specifier to an absolute path, or null when it points outside the repo. */
+function resolveSpecifier(specifier, fromFile, root, config) {
+  if (specifier.startsWith('.')) return path.resolve(path.dirname(fromFile), specifier);
+  for (const [prefix, target] of Object.entries(config.aliases ?? {})) {
+    if (specifier.startsWith(prefix)) {
+      return path.resolve(root, target + specifier.slice(prefix.length));
+    }
+  }
+  return null;
+}
+
+function violation(from, to, closed) {
+  if (from.shared) return to.shared ? null : `shared code must not import the ${to.name} layer`;
+  if (to.shared || to.index === from.index) return null;
+  if (to.index < from.index) return `upward import: ${from.name} must not import ${to.name}`;
+  if (closed && to.index > from.index + 1) {
+    return `skipped layer: ${from.name} must go through the layer below it, not straight to ${to.name}`;
+  }
+  return null;
+}
+
+async function main() {
+  const root = process.cwd();
+  const config = await loadConfig(root);
+  const sourceRoot = path.join(root, config.root);
+
+  if (!(await stat(sourceRoot).catch(() => null))) {
+    console.error(`check-layers: source root "${config.root}" does not exist`);
+    process.exit(1);
+  }
+
+  const violations = [];
+  const unclassified = new Set();
+
+  for (const file of await sourceFiles(sourceRoot, config)) {
+    const from = classify(file, root, config);
+    if (!from) {
+      unclassified.add(path.relative(root, file));
+      continue;
+    }
+
+    const source = await readFile(file, 'utf8');
+    for (const match of source.matchAll(SPECIFIER)) {
+      const specifier = match[1] ?? match[2] ?? match[3];
+      const target = resolveSpecifier(specifier, file, root, config);
+      if (!target) continue;
+
+      const to = classify(target, root, config);
+      if (!to) continue;
+
+      const problem = violation(from, to, config.closed);
+      if (problem) violations.push(`${path.relative(root, file)}: ${problem}  ("${specifier}")`);
+    }
+  }
+
+  if (config.unclassified !== 'ignore' && unclassified.size > 0) {
+    const label = config.unclassified === 'error' ? 'error' : 'warning';
+    console.error(`\ncheck-layers: ${unclassified.size} file(s) belong to no layer (${label}):`);
+    for (const file of [...unclassified].sort()) console.error(`  ${file}`);
+    console.error(
+      '  Move them into a layer folder, or map their folder in architecture.layers.json.',
+    );
+  }
+
+  if (violations.length > 0) {
+    console.error(`\ncheck-layers: ${violations.length} boundary violation(s):`);
+    for (const line of violations.sort()) console.error(`  ${line}`);
+    console.error(
+      '\nA layer may only import the layer directly beneath it. See docs/architecture/layered.md.',
+    );
+  }
+
+  const failed =
+    violations.length > 0 || (config.unclassified === 'error' && unclassified.size > 0);
+  if (failed) process.exit(1);
+  console.log(`check-layers: ${config.layers.map((l) => l.name).join(' → ')} — clean.`);
+}
+
+await main();

package/templates/architectures/layered/files/src/__solutionName.dot__.Business/AssemblyMarker.cs

@@ -0,0 +1,7 @@
+namespace {{ solutionName | dot }}.Business;
+
+// Anchors the assembly so the architecture fitness test always has something to inspect.
+// Delete once this layer holds real use cases.
+public static class AssemblyMarker
+{
+}

package/templates/architectures/layered/files/src/__solutionName.dot__.Business/__solutionName.dot__.Business.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Business</RootNamespace>
+  </PropertyGroup>
+
+  <!-- The only reference this layer is allowed: the layer directly beneath it. -->
+  <ItemGroup>
+    <!-- Forward slashes: MSBuild accepts them everywhere, and a backslash before a template
+         token would escape it. -->
+    <ProjectReference Include="../{{ solutionName | dot }}.Data/{{ solutionName | dot }}.Data.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/layered/files/src/__solutionName.dot__.Data/AssemblyMarker.cs

@@ -0,0 +1,7 @@
+namespace {{ solutionName | dot }}.Data;
+
+// Anchors the assembly so the architecture fitness test always has something to inspect.
+// Delete once this layer holds real repositories.
+public static class AssemblyMarker
+{
+}

package/templates/architectures/layered/files/src/__solutionName.dot__.Data/__solutionName.dot__.Data.csproj

@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Data</RootNamespace>
+  </PropertyGroup>
+
+  <!-- Bottom layer: no ProjectReference belongs here. Adding one points a layer upward. -->
+
+</Project>

package/templates/architectures/layered/files/src/__solutionName.snake__/business/__init__.py

@@ -0,0 +1 @@
+"""Business layer: use cases, domain rules, orchestration. Imports `data` only."""

package/templates/architectures/layered/files/src/__solutionName.snake__/data/__init__.py

@@ -0,0 +1 @@
+"""Data layer: repositories, gateways, external service clients. Imports nothing above it."""

package/templates/architectures/layered/files/src/__solutionName.snake__/presentation/__init__.py

@@ -0,0 +1 @@
+"""Presentation layer: FastAPI routers, request/response models. Imports `business` only."""

package/templates/architectures/layered/files/src/business/README.md

@@ -0,0 +1 @@
+Business layer: use cases, domain rules, orchestration. May import `data` and `shared` only.

package/templates/architectures/layered/files/src/data/README.md

@@ -0,0 +1 @@
+Data layer: repositories, data-access gateways, external service clients. May import `shared` only.

package/templates/architectures/layered/files/src/presentation/README.md

@@ -0,0 +1 @@
+Presentation layer: HTTP handlers, UI components, request/response shapes. May import `business` and `shared` only.

package/templates/architectures/layered/files/src/shared/README.md

@@ -0,0 +1 @@
+Cross-cutting primitives (errors, ids, result types). Importable from every layer; may import nothing but itself.

package/templates/architectures/layered/files/tests/__solutionName.dot__.ArchitectureTests/LayerBoundaryTests.cs

@@ -0,0 +1,151 @@
+using System.Reflection.Metadata;
+using System.Reflection.PortableExecutable;
+using Xunit;
+
+namespace {{ solutionName | dot }}.ArchitectureTests;
+
+// Reads each layer assembly's AssemblyRef table directly, so nothing has to be loaded and
+// no architecture-testing package is needed.
+public sealed class LayerBoundaryTests
+{
+    private const string SolutionPrefix = "{{ solutionName | dot }}.";
+
+    // Closed layers: a layer may reference only the layer directly beneath it.
+    private const bool ClosedLayers = {{ closedLayers }};
+
+    // Highest layer first. Matched on the assembly-name suffix so the presentation project
+    // keeps whichever name the base gave it.
+    private static readonly string[][] LayerSuffixes =
+    [
+        [".Api", ".Presentation", ".Web"],
+        [".Business"],
+        [".Data"],
+    ];
+
+    [Fact]
+    public void Layers_reference_only_the_layer_beneath_them()
+    {
+        var assemblies = LayerAssemblies().ToList();
+
+        // Guards against a silent pass when the project references were never wired up.
+        Assert.True(
+            assemblies.Count >= 2,
+            $"Expected at least two layer assemblies in {AppContext.BaseDirectory}, found {assemblies.Count}. "
+                + "Check the ProjectReference entries in this test project.");
+
+        var failures = new List<string>();
+
+        foreach (var (path, from) in assemblies)
+        {
+            foreach (var referenced in ReferencedAssemblyNames(path))
+            {
+                if (LayerIndex(referenced) is not int to || to == from)
+                {
+                    continue;
+                }
+
+                if (to < from)
+                {
+                    failures.Add($"{Name(path)} references {referenced} — that is an upward reference.");
+                }
+                else if (ClosedLayers && to > from + 1)
+                {
+                    failures.Add($"{Name(path)} references {referenced} — it skips the layer in between.");
+                }
+            }
+        }
+
+        Assert.True(
+            failures.Count == 0,
+            string.Join(Environment.NewLine, failures.Prepend("Layer boundary violations (see docs/architecture/layered.md):")));
+    }
+
+    // This project's own output covers business and data; the presentation project is read out
+    // of its build directory so referencing it never drags its packages into the test project.
+    private static IEnumerable<(string Path, int Layer)> LayerAssemblies()
+    {
+        var seen = new HashSet<string>(StringComparer.Ordinal);
+
+        foreach (var file in CandidateAssemblies())
+        {
+            var name = Name(file);
+            if (LayerIndex(name) is int index && seen.Add(name))
+            {
+                yield return (file, index);
+            }
+        }
+    }
+
+    private static IEnumerable<string> CandidateAssemblies()
+    {
+        foreach (var file in Directory.EnumerateFiles(AppContext.BaseDirectory, "*.dll"))
+        {
+            yield return file;
+        }
+
+        var source = Path.Combine(RepositoryRoot(), "src");
+        if (!Directory.Exists(source))
+        {
+            yield break;
+        }
+
+        foreach (var file in Directory.EnumerateFiles(source, "*.dll", SearchOption.AllDirectories))
+        {
+            if (file.Contains($"{Path.DirectorySeparatorChar}bin{Path.DirectorySeparatorChar}", StringComparison.Ordinal))
+            {
+                yield return file;
+            }
+        }
+    }
+
+    private static string RepositoryRoot()
+    {
+        var directory = new DirectoryInfo(AppContext.BaseDirectory);
+        while (directory is not null && !Directory.Exists(Path.Combine(directory.FullName, "src")))
+        {
+            directory = directory.Parent;
+        }
+
+        return directory?.FullName ?? AppContext.BaseDirectory;
+    }
+
+    // Which layer an assembly belongs to, or null when it is not part of this solution.
+    private static int? LayerIndex(string assemblyName)
+    {
+        if (!assemblyName.StartsWith(SolutionPrefix, StringComparison.Ordinal))
+        {
+            return null;
+        }
+
+        for (var index = 0; index < LayerSuffixes.Length; index++)
+        {
+            foreach (var suffix in LayerSuffixes[index])
+            {
+                if (assemblyName.EndsWith(suffix, StringComparison.Ordinal))
+                {
+                    return index;
+                }
+            }
+        }
+
+        return null;
+    }
+
+    private static IEnumerable<string> ReferencedAssemblyNames(string path)
+    {
+        using var stream = File.OpenRead(path);
+        using var peReader = new PEReader(stream);
+        if (!peReader.HasMetadata)
+        {
+            yield break;
+        }
+
+        var reader = peReader.GetMetadataReader();
+        foreach (var handle in reader.AssemblyReferences)
+        {
+            yield return reader.GetString(reader.GetAssemblyReference(handle).Name);
+        }
+    }
+
+    private static string Name(string path) => Path.GetFileNameWithoutExtension(path);
+}

package/templates/architectures/layered/files/tests/__solutionName.dot__.ArchitectureTests/__solutionName.dot__.ArchitectureTests.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <OutputType>Exe</OutputType>
+    <RootNamespace>{{ solutionName | dot }}.ArchitectureTests</RootNamespace>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <!-- Underscored test names are the convention here; the repo builds warnings-as-errors. -->
+    <NoWarn>$(NoWarn);CA1707</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+  </ItemGroup>
+
+  <!-- Only the two layers this overlay owns. The presentation project is deliberately NOT
+       referenced: it would pull the API's transitive packages past the repo's central version
+       pins. The test reads it out of src/*/bin instead. -->
+  <ItemGroup>
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Business/{{ solutionName | dot }}.Business.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Data/{{ solutionName | dot }}.Data.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/llm-workflow/blueprint.yaml

@@ -0,0 +1,129 @@
+id: llm-workflow
+kind: architecture
+name: LLM Workflow (Predefined Code Paths)
+description: >-
+  Folder overlay for LLM systems whose control flow is fixed in code: prompt chaining, routing
+  and parallelization as separate composable units, prompts as versioned files, a golden dataset
+  in git with deterministic assertions, and a boundary check that fails when a step reaches a
+  model without going through the provider seam.
+
+tags:
+  - llm-workflow
+  - prompt-chaining
+  - routing
+  - parallelization
+  - provider-seam
+  - versioned-prompts
+  - golden-dataset
+  - import-linter
+
+requires: []
+conflicts: []
+provides:
+  - workflow-layout
+  - provider-seam
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # The chain is the unit of work here; the layout says nothing without one to show the shape.
+  - name: workflowName
+    prompt: Name of the first workflow (the predefined code path, e.g. "summarize")
+    type: string
+    default: summarize
+    required: false
+
+  # Seeds the one step that actually calls a model, and the prompt folder that backs it.
+  - name: firstStep
+    prompt: Name of the first model-calling step (also names its prompt folder)
+    type: string
+    default: extract
+    required: false
+
+  # Named once: it is a folder name, the settings default, and what the boundary check reads.
+  - name: promptsDir
+    prompt: Directory holding versioned prompt files
+    type: string
+    default: prompts
+    required: false
+
+  # Prompt versions are files, so this names a file as well as the pin inside the step.
+  - name: promptVersion
+    prompt: Initial prompt version (add v2 beside v1; never edit a shipped version)
+    type: string
+    default: v1
+    required: false
+
+  # test_import_contracts_hold fails when the linter is absent, so every manager needs a path.
+  - name: pythonPackageManager
+    prompt: Python package manager
+    type: select
+    default: uv
+    required: false
+    when: "stack == 'python'"
+    choices:
+      - { value: uv, label: uv }
+      - { value: pip, label: pip }
+      - { value: poetry, label: poetry }
+
+files:
+  # ── shared ──────────────────────────────────────────────────────────────────
+  # Prompts sit at the repo root for every stack, so one rule serves all of them.
+  - from: files/__promptsDir__/**/*.md
+    to: .
+    when: "stack == 'python' || stack == 'typescript' || stack == 'node'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/docs/architecture/llm-workflow.python.md
+    to: .
+    when: "stack == 'python'"
+  - from: files/src/__solutionName.snake__/**/*.py
+    to: .
+    when: "stack == 'python'"
+  # Dataset is data, not code, so it is not covered by the *.py rule above.
+  - from: files/src/__solutionName.snake__/workflow/evals/goldens.jsonl
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+  # A boundary rule that lives only in prose gets violated; these fail the test command.
+  - from: files/tests/test_workflow_*.py
+    to: .
+    when: "stack == 'python'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One layout serves both: the workflow root is the same whether the base is Next.js, Vite,
+  # Hono, or Nest.
+  - from: files/docs/architecture/llm-workflow.typescript.md
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/workflow/**/*.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/workflow/evals/goldens.jsonl
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/scripts/check-llm-workflow.mjs
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  # The golden runner executes TypeScript directly; the boundary check needs nothing.
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+postApply:
+  # Contract file is useless without the linter that reads it. The ast-based tests still hold
+  # without it, which is why these stay optional.
+  - run: uv add --dev "import-linter==2.13"
+    when: "stack == 'python' && pythonPackageManager == 'uv'"
+    optional: true
+  - run: python -m pip install "import-linter==2.13"
+    when: "stack == 'python' && pythonPackageManager == 'pip'"
+    optional: true
+  - run: poetry add --group dev "import-linter==2.13"
+    when: "stack == 'python' && pythonPackageManager == 'poetry'"
+    optional: true

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

@@ -0,0 +1,34 @@
+# Structural boundaries for the workflow. Run with `lint-imports`.
+# Kept out of pyproject.toml so the base stays sole owner of its packaging file.
+# The "no direct model call" rule is enforced separately, in tests/test_workflow_boundaries.py,
+# so it holds whether or not import-linter is installed.
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+[importlinter:contract:workflow-composition-is-one-way]
+name = Composition flows evals -> chains -> steps -> ports and never back
+type = layers
+layers =
+    {{ solutionName | snake }}.workflow.evals
+    {{ solutionName | snake }}.workflow.chains
+    {{ solutionName | snake }}.workflow.steps
+    {{ solutionName | snake }}.workflow.ports
+
+[importlinter:contract:steps-are-leaves]
+name = A step does not import composition code
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.workflow.steps
+forbidden_modules =
+    {{ solutionName | snake }}.workflow.chains
+    {{ solutionName | snake }}.workflow.routing
+    {{ solutionName | snake }}.workflow.parallel
+
+[importlinter:contract:composition-does-not-loop-back]
+name = Routing and parallelization do not import a chain
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.workflow.routing
+    {{ solutionName | snake }}.workflow.parallel
+forbidden_modules =
+    {{ solutionName | snake }}.workflow.chains

package/templates/architectures/llm-workflow/files/__promptsDir__/README.md

@@ -0,0 +1,26 @@
+# Prompts
+
+Every prompt this workflow sends is a file in this directory. Nothing here is generated at
+runtime and nothing here is assembled from string literals in a step.
+
+```
+{{ promptsDir }}/<prompt-name>/<version>.md
+```
+
+- `<prompt-name>` matches the step that loads it, so a call site reads
+  `loadPrompt("{{ firstStep | kebab }}", "{{ promptVersion }}")` — `load_prompt(...)` in
+  Python — and the file it means is obvious.
+- `<version>` is `v1`, `v2`, … **Never edit a shipped version in place.** Add the next one
+  beside it and change the pin in the step. A prompt edit is a behaviour change; if it is not a
+  new file, an eval score can no longer be attributed to a wording, and a bad prompt cannot be
+  rolled back by reverting one line.
+
+The boundary check reads the pinned name and version out of the step source and fails when the
+file is missing, so a dangling pin cannot reach main.
+
+## Changing a prompt
+
+1. Copy `<name>/{{ promptVersion }}.md` to the next version and edit that.
+2. Change the version argument in the step.
+3. Run the golden suite. If the expected outputs moved, update the dataset in the *same*
+   commit — a golden change reviewed on its own tells nobody why the behaviour moved.

package/templates/architectures/llm-workflow/files/__promptsDir__/__firstStep.kebab__/__promptVersion__.md

@@ -0,0 +1,7 @@
+You extract the load-bearing facts from a passage of text.
+
+Rules:
+- Return only the facts, one per line, in the order they appear.
+- Copy names, numbers, dates and units exactly as written. Do not convert or round.
+- Omit anything the passage does not state. An empty answer is correct when there are no facts.
+- Do not summarise, rank, or add commentary.