@opengroundplan/core 0.1.1

package/templates/architectures/multi-agent/files/src/agents/orchestrator/lead.ts

@@ -0,0 +1,77 @@
+import { agentConfig } from '../config.js';
+import type { WorkerResult, WorkerTask } from '../contracts/index.js';
+import { getRunner } from '../runtime/index.js';
+import { dispatchToWorker, knownWorkers } from '../workers/index.js';
+import { RunBudget } from './budget.js';
+import { fanOut } from './fanout.js';
+
+export interface RunOutcome {
+  readonly answer: string;
+  readonly workers: readonly WorkerResult[];
+  readonly tokensSpent: number;
+}
+
+/**
+ * Effort is scaled to the query, not fixed: a lookup wants one worker, a comparison two to four.
+ * Over-fanning a simple question is the most expensive mistake this architecture makes.
+ */
+const PLANNER_SYSTEM = [
+  'You are the lead agent. Break the query into independent worker briefs and return JSON only:',
+  'an array of objects with keys objective, outputFormat, tools, boundaries.',
+  'Every brief needs all four — underspecified briefs make workers duplicate each other.',
+  'Briefs must not overlap; workers cannot see each other or ask you questions mid-run.',
+  'Scale effort to the query: one brief for a simple lookup, two to four for a comparison.',
+  `Available workers: ${knownWorkers().join(', ')}. Never plan more than %CAP% briefs.`,
+].join('\n');
+
+export async function runLead(query: string): Promise<RunOutcome> {
+  const config = agentConfig();
+  const budget = new RunBudget(config.runTokenBudget);
+
+  const plan = await getRunner().run({
+    role: 'lead-planner',
+    system: PLANNER_SYSTEM.replace('%CAP%', String(config.fanOutCap)),
+    prompt: query,
+    maxOutputTokens: config.workerTokenBudget,
+  });
+  budget.record(plan.usage);
+
+  const tasks = parsePlan(plan.text, config.workerTokenBudget).slice(0, config.fanOutCap);
+  const workers = await fanOut(tasks, dispatchToWorker, budget, config);
+
+  // The lead synthesizes from summaries only; this is where the context stays small.
+  const answer = await getRunner().run({
+    role: 'lead-synthesizer',
+    system: 'Answer the query using only the worker summaries below. Cite the sources they give.',
+    prompt: `${query}\n\n${workers.map(render).join('\n\n')}`,
+    maxOutputTokens: config.workerTokenBudget,
+  });
+  budget.record(answer.usage);
+
+  return { answer: answer.text, workers, tokensSpent: budget.spent };
+}
+
+const render = (result: WorkerResult): string =>
+  `[${result.workerId} ${result.status}] ${result.summary}\nSources: ${result.citations.join(', ')}`;
+
+/** Models wrap JSON in prose often enough that slicing to the outermost array is the safe read. */
+function parsePlan(text: string, tokenBudget: number): WorkerTask[] {
+  const start = text.indexOf('[');
+  const end = text.lastIndexOf(']');
+  if (start === -1 || end <= start) return [];
+
+  const briefs = JSON.parse(text.slice(start, end + 1)) as Record<string, unknown>[];
+  // An empty registry means nothing can be dispatched, so there is no brief to fall back to.
+  const [fallbackWorker] = knownWorkers();
+  if (!fallbackWorker) return [];
+
+  return briefs.map((brief, index) => ({
+    id: `task-${index + 1}`,
+    workerId: knownWorkers().includes(String(brief.workerId)) ? String(brief.workerId) : fallbackWorker,
+    objective: String(brief.objective ?? ''),
+    outputFormat: String(brief.outputFormat ?? 'A short prose summary with sources.'),
+    tools: Array.isArray(brief.tools) ? brief.tools.map(String) : [],
+    boundaries: Array.isArray(brief.boundaries) ? brief.boundaries.map(String) : [],
+    tokenBudget,
+  }));
+}

package/templates/architectures/multi-agent/files/src/agents/runtime/index.ts

@@ -0,0 +1,3 @@
+// The only folder permitted to import a model SDK; everything else goes through AgentRunner.
+export type { AgentRunner, RunnerRequest, RunnerResponse } from './runner.js';
+export { getRunner, setRunner } from './runner.js';

package/templates/architectures/multi-agent/files/src/agents/runtime/runner.ts

@@ -0,0 +1,36 @@
+import type { TokenUsage } from '../contracts/index.js';
+
+export interface RunnerRequest {
+  /** Purpose, not model id — the binding resolves the model from this. */
+  readonly role: string;
+  readonly system: string;
+  readonly prompt: string;
+  readonly maxOutputTokens: number;
+}
+
+export interface RunnerResponse {
+  readonly text: string;
+  readonly usage: TokenUsage;
+}
+
+/**
+ * The single seam to the model provider. Only `runtime/` may talk to an SDK, which is what makes
+ * the run ledger complete — one unmetered call somewhere else silently invalidates the budget.
+ */
+export interface AgentRunner {
+  run(request: RunnerRequest): Promise<RunnerResponse>;
+}
+
+let bound: AgentRunner | null = null;
+
+/** Bind at startup, next to wherever the app builds its LLM client. */
+export function setRunner(runner: AgentRunner): void {
+  bound = runner;
+}
+
+export function getRunner(): AgentRunner {
+  if (!bound) {
+    throw new Error('No AgentRunner bound — call setRunner() at startup. See docs/architecture/.');
+  }
+  return bound;
+}

package/templates/architectures/multi-agent/files/src/agents/workers/README.md

@@ -0,0 +1,13 @@
+# Workers
+
+One folder per worker. A worker runs in its own context: it receives a `WorkerTask` brief and
+returns a condensed summary, never its transcript.
+
+Add one by copying `{{ workerName | kebab }}/` and registering it in `index.ts`.
+
+A worker may import `../../contracts`, `../../runtime`, and `../../config`. It may **not** import
+`../../orchestrator` or another worker's folder — `node scripts/check-agent-boundaries.mjs` fails
+the build if it does.
+
+Give every worker a distinct specialization. Two workers with overlapping objectives pay twice
+for one answer, which is the failure mode this architecture is most prone to.

package/templates/architectures/multi-agent/files/src/agents/workers/__workerName.kebab__/prompt.ts

@@ -0,0 +1,22 @@
+import type { WorkerTask } from '../../contracts/index.js';
+
+/**
+ * A worker's entire context is this brief plus what its own tools return. It never sees the
+ * lead's history, so anything missing here is missing for good.
+ */
+export function brief(task: WorkerTask, maxSteps: number): string {
+  return [
+    'You are a {{ workerName | title }} worker running in isolation.',
+    `Objective: ${task.objective}`,
+    `Output format: ${task.outputFormat}`,
+    `Tools you may use: ${task.tools.join(', ') || 'none'}`,
+    `Out of scope: ${task.boundaries.join('; ') || 'nothing specified'}`,
+    `Stop after at most ${maxSteps} tool calls and report what you have.`,
+    'Return a condensed summary, not a transcript. End with a line "Sources:" listing every URL.',
+  ].join('\n');
+}
+
+/** The lead only ever sees what the worker chose to keep, so citations must be machine-readable. */
+export function citationsOf(text: string): string[] {
+  return [...new Set(text.match(/https?:\/\/\S+/g) ?? [])];
+}

package/templates/architectures/multi-agent/files/src/agents/workers/__workerName.kebab__/worker.ts

@@ -0,0 +1,25 @@
+import { agentConfig } from '../../config.js';
+import type { WorkerTask } from '../../contracts/index.js';
+import { getRunner } from '../../runtime/index.js';
+import { brief, citationsOf } from './prompt.js';
+
+/**
+ * One worker, one isolated context. Copy this folder to add another; it may import `contracts`,
+ * `runtime` and `config`, and nothing else under `agents/`.
+ */
+export async function run{{ workerName | pascal }}(task: WorkerTask): Promise<Record<string, unknown>> {
+  const config = agentConfig();
+  const response = await getRunner().run({
+    role: '{{ workerName | kebab }}-worker',
+    system: brief(task, config.workerMaxSteps),
+    prompt: task.objective,
+    maxOutputTokens: Math.min(task.tokenBudget, config.workerTokenBudget),
+  });
+
+  return {
+    summary: response.text,
+    citations: citationsOf(response.text),
+    usage: response.usage,
+    status: 'ok',
+  };
+}

package/templates/architectures/multi-agent/files/src/agents/workers/index.ts

@@ -0,0 +1,15 @@
+import type { WorkerTask } from '../contracts/index.js';
+import { run{{ workerName | pascal }} } from './{{ workerName | kebab }}/worker.js';
+
+/** Registry, so the lead names a worker instead of importing one. */
+const WORKERS: Record<string, (task: WorkerTask) => Promise<Record<string, unknown>>> = {
+  '{{ workerName | kebab }}': run{{ workerName | pascal }},
+};
+
+export const knownWorkers = (): string[] => Object.keys(WORKERS);
+
+export async function dispatchToWorker(task: WorkerTask): Promise<Record<string, unknown>> {
+  const worker = WORKERS[task.workerId];
+  if (!worker) throw new Error(`Unknown worker "${task.workerId}". Known: ${knownWorkers().join(', ')}`);
+  return worker(task);
+}

package/templates/architectures/multi-agent/files/tests/architecture/test_agent_boundaries.py

@@ -0,0 +1,184 @@
+"""Architecture fitness test for the multi-agent (orchestrator-worker) layout.
+
+The rule it exists for: a worker's context never merges with the lead's. Everything below is a
+mechanical consequence of that. Runs under pytest, and standalone
+(``python tests/architecture/test_agent_boundaries.py``) so a repo without the test layer still
+has the guard.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import sys
+from pathlib import Path
+
+
+def _split(value: str | None) -> list[str] | None:
+    return [item.strip() for item in value.split(",") if item.strip()] if value else None
+
+
+# Every tunable lives here; nothing below reads the environment directly.
+CONFIG = {
+    "source_root": Path(os.environ.get("ARCH_SOURCE_ROOT", "src")),
+    "agents_package": os.environ.get("ARCH_AGENTS_PACKAGE", "agents"),
+    # Orchestrator modules nothing outside the orchestrator may import.
+    "orchestrator_private": _split(os.environ.get("ARCH_ORCHESTRATOR_PRIVATE")) or ["fanout", "budget"],
+    # SDKs that spend tokens. Only `runtime` may import one, or the ledger under-counts.
+    "model_packages": _split(os.environ.get("ARCH_MODEL_PACKAGES"))
+    or ["anthropic", "openai", "boto3", "google", "ollama", "litellm", "vertexai"],
+}
+
+
+def _zone(dotted: str) -> tuple[str, str | None] | None:
+    """`acme.agents.workers.research.worker` -> ("workers", "research")."""
+    parts = dotted.split(".")
+    marker = CONFIG["agents_package"]
+    if marker not in parts:
+        return None
+    rest = parts[parts.index(marker) + 1 :]
+    if not rest:
+        return ("", None)
+    return (rest[0], rest[1] if len(rest) >= 2 else None)
+
+
+def discover_workers(root: Path) -> frozenset[str]:
+    """Worker names come from disk: an imported dotted name cannot tell a sub-package from a symbol."""
+    return frozenset(
+        child.name
+        for path in root.rglob(f"{CONFIG['agents_package']}/workers")
+        for child in path.iterdir()
+        if child.is_dir() and not child.name.startswith("_")
+    )
+
+
+def violation(importer: str, imported: str, workers: frozenset[str]) -> str | None:
+    """The whole rule set, isolated so the self-test below can prove it still fires."""
+    origin = _zone(importer)
+    target = _zone(imported)
+
+    def say(reason: str) -> str:
+        return f"{importer} imports {imported}: {reason}"
+
+
+    if target is None:
+        # Scoped to the agent tree: the app's own LLM layer is where an AgentRunner gets built.
+        if origin is None or imported.split(".")[0] not in CONFIG["model_packages"]:
+            return None
+        if origin[0] == "runtime":
+            return None
+        return say("inside agents, only agents.runtime may call a model SDK, or the ledger under-counts")
+
+    from_area, from_sub = origin if origin else ("", None)
+    to_area, to_sub = target
+    to_worker = to_sub if to_area == "workers" and to_sub in workers else None
+    from_worker = from_sub if from_area == "workers" and from_sub in workers else None
+
+    if from_area == "contracts" and to_area != "contracts":
+        return say("contracts is the seam and must stay a leaf")
+    if from_area == "workers" and to_area == "orchestrator":
+        return say("a worker must not reach back into the orchestrator")
+    if from_worker and to_worker and from_worker != to_worker:
+        return say("workers run in isolated contexts and must not import one another")
+    if to_worker and from_area != "workers":
+        return say("reach a worker through the orchestrator's fan-out, where the cap and budget live")
+    if to_area == "orchestrator" and to_sub in CONFIG["orchestrator_private"] and from_area != "orchestrator":
+        return say(f"orchestrator.{to_sub} is private; the fan-out cap and token ledger are not optional")
+    return None
+
+
+def _dotted_name(path: Path, root: Path) -> tuple[str, bool]:
+    relative = path.relative_to(root).with_suffix("")
+    parts = list(relative.parts)
+    is_package = parts[-1] == "__init__"
+    if is_package:
+        parts.pop()
+    return ".".join(parts), is_package
+
+
+def _imports(source: str, importer: str, is_package: bool) -> list[str]:
+    # Inside a package's __init__, `from .x` resolves against the package itself, not its parent.
+    anchor = importer.split(".") if is_package else importer.split(".")[:-1]
+    found: list[str] = []
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.Import):
+            found.extend(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            base = node.module or ""
+            if node.level:
+                package = anchor[: len(anchor) - (node.level - 1)]
+                base = ".".join([*package, base]) if base else ".".join(package)
+            found.extend(f"{base}.{alias.name}" if base else alias.name for alias in node.names)
+            found.append(base)
+    return [name for name in found if name]
+
+
+def collect_violations(root: Path) -> list[str]:
+    workers = discover_workers(root)
+    problems: list[str] = []
+    for path in sorted(root.rglob("*.py")):
+        dotted, is_package = _dotted_name(path, root)
+        for imported in _imports(path.read_text(encoding="utf-8"), dotted, is_package):
+            message = violation(dotted, imported, workers)
+            if message:
+                problems.append(message)
+    return problems
+
+
+SELF_TEST_WORKERS = frozenset({"research", "review"})
+SELF_TEST_CASES = [
+    ("acme.agents.workers.research.worker", "acme.agents.orchestrator.fanout", True),
+    ("acme.agents.workers.research.worker", "acme.agents.runtime.runner", False),
+    ("acme.agents.workers.research.worker", "acme.agents.workers.review.worker", True),
+    ("acme.agents.workers", "acme.agents.workers.research.worker", False),
+    ("acme.agents.contracts", "acme.agents.config", True),
+    ("acme.agents.orchestrator.lead", "acme.agents.orchestrator.fanout", False),
+    ("acme.api.routes", "acme.agents.orchestrator.fanout", True),
+    ("acme.api.routes", "acme.agents.orchestrator", False),
+    ("acme.api.routes", "acme.agents.workers.research.worker", True),
+    ("acme.agents.runtime.anthropic_runner", "anthropic", False),
+    ("acme.agents.orchestrator.lead", "anthropic", True),
+    # A re-exported symbol is not a sub-package; only names found on disk count as workers.
+    ("acme.agents.orchestrator.lead", "acme.agents.workers.dispatch_to_worker", False),
+]
+
+
+def test_the_rules_still_detect_a_violation() -> None:
+    for importer, imported, expected in SELF_TEST_CASES:
+        found = bool(violation(importer, imported, SELF_TEST_WORKERS))
+        assert found is expected, f"{importer} -> {imported}"
+
+
+def test_no_worker_context_leaks_into_the_orchestrator() -> None:
+    root = CONFIG["source_root"]
+    assert root.is_dir(), f"{root} not found — set ARCH_SOURCE_ROOT"
+    found = collect_violations(root)
+    assert not found, "Agent boundary violations:\n" + "\n".join(found)
+
+
+def test_the_result_contract_carries_no_transcript() -> None:
+    """The last place the rule can be broken: a transcript field on WorkerResult."""
+    forbidden = {"transcript", "messages", "history", "trace", "conversation"}
+    contracts = list(CONFIG["source_root"].rglob(f"{CONFIG['agents_package']}/contracts.py"))
+    assert contracts, "agents/contracts.py not found — it defines the orchestrator/worker seam"
+
+    for path in contracts:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef) or node.name != "WorkerResult":
+                continue
+            fields = {
+                n.target.id
+                for n in node.body
+                if isinstance(n, ast.AnnAssign) and isinstance(n.target, ast.Name)
+            }
+            leaked = fields & forbidden
+            assert not leaked, f"WorkerResult declares {leaked} — a worker returns a summary, never its run"
+
+
+if __name__ == "__main__":
+    test_the_rules_still_detect_a_violation()
+    problems = collect_violations(CONFIG["source_root"])
+    for problem in problems:
+        print(problem, file=sys.stderr)
+    sys.exit(1 if problems else 0)

package/templates/architectures/mvc-mvvm/blueprint.yaml

@@ -0,0 +1,156 @@
+id: mvc-mvvm
+kind: architecture
+name: MVC / MVVM (Separated Presentation)
+description: >-
+  Folder overlay for separated presentation: domain models kept apart from the presentation
+  objects on screen. Models/Views/Controllers for server-rendered MVC in Python, a UI-free
+  Models/ViewModels/Views presentation library for .NET MAUI/WPF/Razor, and the React
+  equivalent — a hook that is the ViewModel with the component only rendering. Ships a boundary
+  check per stack that fails a command, because the two rules this pattern rests on (no business
+  logic in a view, no view imported by a model) get violated the moment they live only in prose.
+
+tags:
+  - mvc
+  - mvvm
+  - separated-presentation
+  - presentation-model
+  - view-model
+  - data-binding
+  - boundaries
+  - fitness-test
+
+# An overlay contributes structure and one gate; it composes onto whatever base was chosen.
+requires: []
+
+# Rival overlays declare the conflict from their own blueprint — conflicts are symmetric, and
+# naming an id from here that never names this one back fails the library-wide invariant.
+conflicts: []
+
+provides:
+  - presentation-boundaries
+  - architecture-overlay
+
+# Meaningless on an overlay: this blueprint *is* the architecture.
+supportsArchitectures: []
+
+variables:
+  # Seeds one screen end to end. The layout says nothing without a model, a view, and the
+  # thing between them existing together.
+  - name: firstScreen
+    prompt: Name of the first screen (one model + view + controller/view-model is created for it)
+    type: string
+    default: home
+    required: false
+
+  # Same name and default as the .NET bases, so a dotnet interview asks once.
+  - name: dotnetTargetFramework
+    prompt: Target framework for the presentation library and the architecture test
+    type: string
+    default: net10.0
+    required: false
+    when: "stack == 'dotnet'"
+
+  # Same name and choices as the other overlays, for the same reason.
+  - name: pythonPackageManager
+    prompt: Python package manager (used to install import-linter)
+    type: select
+    default: uv
+    required: false
+    when: "stack == 'python'"
+    choices:
+      - { value: uv, label: uv }
+      - { value: pip, label: pip }
+      - { value: poetry, label: poetry }
+
+  - name: netArchTestVersion
+    prompt: NetArchTest.eNhancedEdition version (enforces the presentation boundaries in tests)
+    type: string
+    default: '1.4.5'
+    when: "stack == 'dotnet'"
+
+files:
+  # ── docs ────────────────────────────────────────────────────────────────────
+  # One per stack: the rule is constant but what enforces it, and what it cannot see, is not.
+  - from: files/docs/architecture/mvc-mvvm.dotnet.md
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/docs/architecture/mvc-mvvm.python.md
+    to: .
+    when: "stack == 'python'"
+  - from: files/docs/architecture/mvc-mvvm.typescript.md
+    to: .
+    when: "stack == 'typescript'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  # A class library with no UI package reference: presentation logic that cannot name a view
+  # type is presentation logic a test can drive headless. That is the whole bet of MVVM.
+  - from: files/src/__solutionName.dot__.Presentation/**/*
+    to: .
+    when: "stack == 'dotnet'"
+  # A boundary rule that lives only in prose gets violated; this fails `dotnet test` instead.
+  - from: files/tests/__solutionName.dot__.ArchitectureTests/*
+    to: .
+    when: "stack == 'dotnet'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/src/__solutionName.snake__/**/*.py
+    to: .
+    when: "stack == 'python'"
+  # .importlinter, not pyproject.toml, so the base keeps sole ownership of its packaging file.
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/test_presentation_boundaries.py
+    to: .
+    when: "stack == 'python'"
+
+  # ── typescript ──────────────────────────────────────────────────────────────
+  # Skeleton only, with no framework import anywhere: the overlay must not decide whether this
+  # repo has React, and a package.json fragment claiming it would be a lie on a Hono base.
+  - from: files/src/{models,viewmodels,views}/index.ts
+    to: .
+    when: "stack == 'typescript'"
+  - from: files/scripts/check-mvvm-boundaries.mjs
+    to: .
+    when: "stack == 'typescript'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # Solution membership only — the csproj files already carry their own references and pins.
+  # cmd.exe does not expand globs, so on Windows this is a no-op and the doc states the
+  # one-line equivalent.
+
+  # A contract file is useless without the linter that reads it.
+  - 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
+
+  # Manifest-only, like the layers: nothing installs here, so a pnpm or yarn repo never gains
+  # a stray npm lockfile. `pretest` is what makes `npm test` fail on a violation; pnpm needs
+  # enable-pre-post-scripts=true in .npmrc for that hook to run.
+  - run: npm pkg set "scripts.check:mvvm"="node scripts/check-mvvm-boundaries.mjs"
+    when: "stack == 'typescript'"
+    optional: true
+  - run: npm pkg set scripts.pretest="node scripts/check-mvvm-boundaries.mjs"
+    when: "stack == 'typescript'"
+    optional: true

package/templates/architectures/mvc-mvvm/files/.importlinter

@@ -0,0 +1,25 @@
+# Presentation boundaries for this repo. Run `lint-imports`.
+# Kept out of pyproject.toml so the base stays sole owner of its packaging file.
+# The package must be importable, so run `uv sync` (or `pip install -e .`) first.
+[importlinter]
+root_packages =
+    {{ solutionName | snake }}
+
+[importlinter:contract:presentation-layers]
+name = Controllers may use views and models; views may use models; models use neither
+type = layers
+containers =
+    {{ solutionName | snake }}
+# Highest first. This is the whole of MVC's directionality in five lines.
+layers =
+    controllers
+    views
+    models
+
+[importlinter:contract:views-never-fetch]
+name = A view renders what it was handed and never reaches the data source
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.views
+forbidden_modules =
+    {{ solutionName | snake }}.models.repository

package/templates/architectures/mvc-mvvm/files/Directory.Packages.props

@@ -0,0 +1,8 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
+    <PackageVersion Include="NetArchTest.eNhancedEdition" Version="{{ netArchTestVersion }}" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
+    <PackageVersion Include="xunit.v3" Version="3.2.2" />
+  </ItemGroup>
+</Project>

package/templates/architectures/mvc-mvvm/files/__solutionName.dot__.slnx

@@ -0,0 +1,8 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | dot }}.Presentation/{{ solutionName | dot }}.Presentation.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/{{ solutionName | dot }}.ArchitectureTests/{{ solutionName | dot }}.ArchitectureTests.csproj" />
+  </Folder>
+</Solution>

package/templates/architectures/mvc-mvvm/files/docs/architecture/mvc-mvvm.dotnet.md

@@ -0,0 +1,84 @@
+# Separated Presentation (MVVM) — .NET
+
+{{ solutionName | title }} keeps its presentation logic in a UI-free class library. The view is
+markup that binds; the view model is the part you can test with no UI present.
+
+```
+src/
+  {{ solutionName | dot }}.Presentation/        # no UI package reference, ever
+    Models/
+      {{ firstScreen | pascal }}.cs             # domain data — knows nothing above it
+    ViewModels/
+      ViewModelBase.cs                          # INotifyPropertyChanged + SetProperty
+      RelayCommand.cs                           # ICommand, BCL only
+      {{ firstScreen | pascal }}ViewModel.cs    # state + commands for one screen
+    Views/
+      README.md                                 # XAML / Razor / Blazor lives here or in the UI head
+tests/
+  {{ solutionName | dot }}.ArchitectureTests/
+    PresentationBoundaryTests.cs                # the gate
+```
+
+## The one rule that matters
+
+> **A view may not contain business logic, and a model may not import a view.**
+
+The dependency is one-way and never negotiable: **View → ViewModel → Model**. A view names its
+view model; a view model must be constructible, drivable, and assertable with no view in the
+process. The moment a view model reaches for a UI type, the pattern has bought you nothing —
+you now have the same untestable code-behind with more folders.
+
+In practice, for .NET:
+
+- Code-behind holds `InitializeComponent()` and a `BindingContext`/`DataContext` assignment.
+  Nothing else. No `if` on a domain rule, no service call, no navigation decision.
+- The view model exposes bindable properties and `ICommand`s. It never references
+  `Microsoft.Maui.*`, `System.Windows.Controls.*`, `Avalonia.*`, or a Razor component type.
+- `System.Windows.Input.ICommand` is deliberately *allowed*: it is the binding contract, not a
+  view type.
+- Dependencies arrive through the constructor (`{{ firstScreen | pascal }}ViewModel` takes a
+  load function). A view model that news up its own data source cannot be tested.
+
+## What fails the build
+
+```
+dotnet test
+```
+
+`PresentationBoundaryTests` (NetArchTest, plus one reflection check) fails on any of:
+
+| Test | Fires when |
+|---|---|
+| `ViewModels_do_not_depend_on_views` | a type in `*.Presentation.ViewModels` references `*.Presentation.Views` |
+| `Models_do_not_depend_on_the_presentation_above_them` | a model references a view model or a view |
+| `Presentation_logic_never_references_a_ui_framework` | any type in the library references MAUI, WinUI, WPF controls, Avalonia, or Blazor components |
+| `Every_view_model_raises_change_notification` | a concrete `*ViewModel` does not implement `INotifyPropertyChanged` |
+
+The third test is the one that fires on day one, and it is the load-bearing one: it is what
+keeps the presentation library headless. The first two are guards that arm as soon as view
+types land next to view models.
+
+Both projects are in the `.slnx` from generation, so `dotnet test` finds the boundary tests on
+a fresh clone with nothing to wire.
+
+## Attaching a UI head
+
+- **MAUI / WPF / WinUI** — add the head project with its own SDK, reference
+  `{{ solutionName | dot }}.Presentation`, and put XAML in the head. The boundary tests keep
+  running against the library, which is the half that matters.
+- **ASP.NET Core MVC** — the same library serves server-rendered MVC unchanged: a controller
+  builds a `{{ firstScreen | pascal }}ViewModel`, the Razor view binds to it and does nothing
+  else. That is Fowler's Model–View–Controller with the view model doing the presentation work.
+
+## What is not enforced mechanically
+
+**"No logic in the view" is not checkable on the .NET side.** XAML code-behind lives in the UI
+head project, outside this library and outside the fitness test's assembly. Nothing in the
+toolchain will stop you writing a `switch` on a domain rule in `MainPage.xaml.cs`. Treat that as
+a code-review rule, and keep code-behind files small enough that a reviewer notices.
+
+## References
+
+- [Fowler — GUI Architectures](https://martinfowler.com/eaaDev/uiArchs.html)
+- [Microsoft Learn — Model-View-ViewModel (MVVM) in .NET MAUI](https://learn.microsoft.com/en-us/dotnet/architecture/maui/mvvm)
+- [Herberto Graça — MVC and its variants](https://herbertograca.com/2017/08/17/mvc-and-its-variants/)