@opengroundplan/core 0.1.1

package/templates/architectures/monolith/files/src/__solutionName.snake__/features/__featureName.snake__/__init__.py

@@ -0,0 +1,31 @@
+"""The front door of the {{ featureName | kebab }} feature.
+
+Every other module in this package is private to it, and
+tests/architecture/test_monolith_boundaries.py fails when something outside reaches past here.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from {{ solutionName | snake }}.features.{{ featureName | snake }}.service import (
+    {{ featureName | pascal }}Service,
+    {{ featureName | pascal }}Summary,
+)
+
+
+class {{ featureName | pascal }}Feature(Protocol):
+    """Everything another feature may call. Widen it deliberately, not by accident."""
+
+    def find(self, item_id: str) -> {{ featureName | pascal }}Summary: ...
+
+
+def create_{{ featureName | snake }}_feature() -> {{ featureName | pascal }}Feature:
+    return {{ featureName | pascal }}Service()
+
+
+__all__ = [
+    "{{ featureName | pascal }}Feature",
+    "{{ featureName | pascal }}Summary",
+    "create_{{ featureName | snake }}_feature",
+]

package/templates/architectures/monolith/files/src/__solutionName.snake__/features/__featureName.snake__/service.py

@@ -0,0 +1,22 @@
+"""Private to this feature. Replace with the real implementation; add modules beside it freely."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from {{ solutionName | snake }}.shared import AppError
+
+
+@dataclass(frozen=True)
+class {{ featureName | pascal }}Summary:
+    """The read model handed across the boundary. Never a persistence row."""
+
+    id: str
+    name: str
+
+
+class {{ featureName | pascal }}Service:
+    def find(self, item_id: str) -> {{ featureName | pascal }}Summary:
+        if not item_id.strip():
+            raise AppError("invalid_id", "An id is required.")
+        return {{ featureName | pascal }}Summary(id=item_id, name=f"{{ featureName | title }} {item_id}")

package/templates/architectures/monolith/files/src/__solutionName.snake__/features/__init__.py

@@ -0,0 +1,14 @@
+"""Composition root for features: the one module allowed to know all of them.
+
+Extracting a feature into its own service starts by deleting a line from build_features().
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from {{ solutionName | snake }}.features.{{ featureName | snake }} import create_{{ featureName | snake }}_feature
+
+
+def build_features() -> dict[str, Any]:
+    return {"{{ featureName | snake }}": create_{{ featureName | snake }}_feature()}

package/templates/architectures/monolith/files/src/__solutionName.snake__/shared/__init__.py

@@ -0,0 +1,11 @@
+"""The shared kernel: everything the features stand on and nothing that stands on a feature.
+
+Admission rule — a thing moves here when a second feature needs it AND it names no feature.
+Skip the second half and the kernel becomes the thing you cannot extract a feature away from.
+"""
+
+from __future__ import annotations
+
+from {{ solutionName | snake }}.shared.errors import AppError
+
+__all__ = ["AppError"]

package/templates/architectures/monolith/files/src/__solutionName.snake__/shared/errors.py

@@ -0,0 +1,13 @@
+"""The kernel's failure type.
+
+Features report failure with a stable code and the edge — HTTP handler, worker, CLI — is the
+only place that turns a code into a status.
+"""
+
+from __future__ import annotations
+
+
+class AppError(Exception):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code

package/templates/architectures/monolith/files/src/features/__featureName.kebab__/__featureName.kebab__.service.ts

@@ -0,0 +1,15 @@
+import { AppError } from '../../shared/index.js';
+// Type-only, so it is erased at build and the front door stays the single runtime entry point.
+import type { {{ featureName | pascal }}Feature, {{ featureName | pascal }}Summary } from './index.js';
+
+/** Private to this feature. Replace with the real implementation; add files beside it freely. */
+export function create{{ featureName | pascal }}Service(): {{ featureName | pascal }}Feature {
+  return {
+    find(id: string): {{ featureName | pascal }}Summary {
+      if (id.trim() === '') {
+        throw new AppError('invalid_id', 'An id is required.');
+      }
+      return { id, name: `{{ featureName | title }} ${id}` };
+    },
+  };
+}

package/templates/architectures/monolith/files/src/features/__featureName.kebab__/index.ts

@@ -0,0 +1,20 @@
+import { create{{ featureName | pascal }}Service } from './{{ featureName | kebab }}.service.js';
+
+/** The read model handed across the boundary. Never a persistence row. */
+export interface {{ featureName | pascal }}Summary {
+  id: string;
+  name: string;
+}
+
+/** Everything another feature is allowed to call. Widen it deliberately, not by accident. */
+export interface {{ featureName | pascal }}Feature {
+  find(id: string): {{ featureName | pascal }}Summary;
+}
+
+/**
+ * The front door. Every file beside this one is private to the feature, and
+ * `scripts/check-monolith-boundaries.mjs` fails the build when something outside reaches past it.
+ */
+export function create{{ featureName | pascal }}Feature(): {{ featureName | pascal }}Feature {
+  return create{{ featureName | pascal }}Service();
+}

package/templates/architectures/monolith/files/src/features/index.ts

@@ -0,0 +1,11 @@
+import { create{{ featureName | pascal }}Feature } from './{{ featureName | kebab }}/index.js';
+
+/**
+ * Composition root for features: the one place they are assembled, and the only file allowed to
+ * know all of them. Extracting a feature into its own service starts by deleting a line here.
+ */
+export function buildFeatures() {
+  return {
+    {{ featureName | camel }}: create{{ featureName | pascal }}Feature(),
+  };
+}

package/templates/architectures/monolith/files/src/shared/errors.ts

@@ -0,0 +1,13 @@
+/**
+ * The kernel's failure type. Features report failure with a stable code and the edge — HTTP
+ * handler, job runner, CLI — is the only place that turns a code into a status.
+ */
+export class AppError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'AppError';
+    this.code = code;
+  }
+}

package/templates/architectures/monolith/files/src/shared/index.ts

@@ -0,0 +1,7 @@
+/**
+ * The shared kernel: everything the features stand on and nothing that stands on a feature.
+ *
+ * Admission rule — a thing moves here when a second feature needs it AND it names no feature.
+ * Skip the second half and the kernel becomes the thing you cannot extract a feature away from.
+ */
+export { AppError } from './errors.js';

package/templates/architectures/monolith/files/tests/ArchitectureTests/ArchitectureTests.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <!-- xUnit v3 test projects are executables. TargetFramework comes from Directory.Build.props. -->
+    <OutputType>Exe</OutputType>
+    <!-- Folder and file are fixed so `dotnet sln add tests/ArchitectureTests` resolves without
+         globbing, which the .NET CLI does not do. The assembly still carries the solution name. -->
+    <AssemblyName>{{ solutionName | dot }}.ArchitectureTests</AssemblyName>
+    <RootNamespace>{{ solutionName | dot }}.ArchitectureTests</RootNamespace>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <!-- CA1707 polices public API naming; underscored test names are the convention here and
+         the repo builds with warnings as errors. -->
+    <NoWarn>$(NoWarn);CA1707</NoWarn>
+  </PropertyGroup>
+
+  <!-- Versions come from Directory.Packages.props; both .NET bases turn central package
+       management on, so no version belongs here.
+       NetArchTest.Rules has been unmaintained since 2021; this fork is the maintained one. -->
+  <ItemGroup>
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="NetArchTest.eNhancedEdition" />
+  </ItemGroup>
+
+  <!-- Wildcard: the two .NET bases name their API project differently. -->
+  <ItemGroup>
+    <ProjectReference Include="../../src/*.Api/*.Api.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/monolith/files/tests/ArchitectureTests/FeatureBoundaryTests.cs

@@ -0,0 +1,129 @@
+using System.Reflection;
+using NetArchTest.Rules;
+using Xunit;
+
+// xUnit ships a TestResult of its own.
+using TestResult = NetArchTest.Rules.TestResult;
+
+namespace {{ solutionName | dot }}.ArchitectureTests;
+
+/// <summary>The rules of this architecture, enforced instead of documented.</summary>
+public sealed class FeatureBoundaryTests
+{
+    private const string InternalSuffix = ".Internal";
+
+    private static readonly Assembly Api = LoadApiAssembly();
+
+    private static readonly string Root = Api.GetName().Name
+        ?? throw new InvalidOperationException("The API assembly has no simple name.");
+
+    private static readonly string FeaturesNamespace = $"{Root}.Features";
+
+    private static readonly List<string> Features = DiscoverFeatures();
+
+    [Fact]
+    public void Features_are_discovered()
+    {
+        // Without this, every rule below would pass by inspecting nothing.
+        Assert.True(
+            Features.Count > 0,
+            $"No namespace under {FeaturesNamespace} contains a type, so every rule below "
+                + "would pass by inspecting nothing. Add your first feature there.");
+    }
+
+    [Fact]
+    public void Nothing_reaches_behind_another_features_front_door()
+    {
+        foreach (var feature in Features)
+        {
+            var result = Types.InAssembly(Api)
+                .That().DoNotResideInNamespace($"{FeaturesNamespace}.{feature}")
+                .ShouldNot().HaveDependencyOnAny($"{FeaturesNamespace}.{feature}{InternalSuffix}")
+                .GetResult();
+
+            Assert.True(
+                result.IsSuccessful,
+                Describe(
+                    $"Something outside feature \"{feature}\" depends on its internals. " +
+                    $"Expose what is needed from {FeaturesNamespace}.{feature} instead.",
+                    result));
+        }
+    }
+
+    [Fact]
+    public void Kernel_does_not_depend_on_any_feature()
+    {
+        var result = Types.InAssembly(Api)
+            .That().ResideInNamespace($"{Root}.Kernel")
+            .ShouldNot().HaveDependencyOnAny(FeaturesNamespace)
+            .GetResult();
+
+        Assert.True(
+            result.IsSuccessful,
+            Describe("The kernel names a feature, which is what makes a feature unextractable.", result));
+    }
+
+    [Fact]
+    public void Internal_types_are_never_public()
+    {
+        var result = Types.InAssembly(Api)
+            .That().ResideInNamespaceContaining(InternalSuffix)
+            .Should().NotBePublic()
+            .GetResult();
+
+        Assert.True(result.IsSuccessful, Describe("A feature's internals leaked as public API.", result));
+    }
+
+    /// <summary>Feature names taken from the namespaces the API assembly actually contains.</summary>
+    private static List<string> DiscoverFeatures()
+    {
+        var prefix = FeaturesNamespace + ".";
+        return Api.GetTypes()
+            .Select(type => type.Namespace)
+            .Where(name => name is not null && name.StartsWith(prefix, StringComparison.Ordinal))
+            .Select(name => name![prefix.Length..].Split('.')[0])
+            .Distinct(StringComparer.Ordinal)
+            .ToList();
+    }
+
+    /// <summary>
+    /// Located by pattern so the same project works on either .NET base. `*.Api.dll` also matches
+    /// packages such as OpenTelemetry.Api, so the assembly is confirmed by the namespace these
+    /// rules are actually about.
+    /// </summary>
+    private static Assembly LoadApiAssembly()
+    {
+        var candidates = Directory.GetFiles(AppContext.BaseDirectory, "*.Api.dll")
+            .Select(Assembly.LoadFrom)
+            .Where(HasFeatureNamespace)
+            .ToList();
+
+        return candidates.Count == 1
+            ? candidates[0]
+            : throw new InvalidOperationException(
+                $"Expected exactly one *.Api.dll with a Features namespace beside the tests, found {candidates.Count}.");
+    }
+
+    private static bool HasFeatureNamespace(Assembly assembly)
+    {
+        try
+        {
+            return Array.Exists(
+                assembly.GetTypes(),
+                type => type.Namespace?.Contains(".Features.", StringComparison.Ordinal) == true);
+        }
+        catch (ReflectionTypeLoadException)
+        {
+            // A package we do not own failing to load its own types is not this repo's problem.
+            return false;
+        }
+    }
+
+    private static string Describe(string violation, TestResult result)
+    {
+        // FailingTypes is null on a passing test, and this message is built either way.
+        var failing = result.FailingTypes ?? [];
+        var lines = failing.Select(type => $"  {type.FullName} — {type.Explanation}");
+        return string.Join(Environment.NewLine, lines.Prepend(violation));
+    }
+}

package/templates/architectures/monolith/files/tests/architecture/test_monolith_boundaries.py

@@ -0,0 +1,136 @@
+"""Architecture fitness test for the monolith.
+
+Two rules, both of which exist so a feature can still be lifted out into its own service later:
+1. from outside a feature, the only importable module is that feature's package (its front door),
+2. the shared kernel never imports a feature.
+
+Calling another feature through its front door is allowed — that is the point of paying for one
+deployable instead of several. Runs under pytest, and standalone
+(`python tests/architecture/test_monolith_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
+
+# Every tunable lives here; nothing below reads the environment directly.
+CONFIG = {
+    "source_root": Path(os.environ.get("ARCH_SOURCE_ROOT", "src")),
+    "features_package": os.environ.get("ARCH_FEATURES_PACKAGE", "features"),
+    "shared_package": os.environ.get("ARCH_SHARED_PACKAGE", "shared"),
+}
+
+
+def _locate(dotted: str) -> tuple[str, list[str]] | None:
+    """`acme.features.catalog.store` -> ("catalog", ["store"]); outside a feature -> None."""
+    parts = dotted.split(".")
+    marker = CONFIG["features_package"]
+    if marker not in parts:
+        return None
+    index = parts.index(marker)
+    if len(parts) <= index + 1:
+        return None
+    return parts[index + 1], parts[index + 2 :]
+
+
+def _is_kernel(dotted: str) -> bool:
+    return CONFIG["shared_package"] in dotted.split(".")
+
+
+def violation(importer: str, imported: str) -> str | None:
+    """The two rules, isolated so the self-test below can prove they still fire."""
+    target = _locate(imported)
+    if target is None:
+        return None
+    feature, rest = target
+
+    if _is_kernel(importer):
+        return f"{importer} imports {imported}: the kernel must not name a feature"
+
+    owner = _locate(importer)
+    if owner is not None and owner[0] == feature:
+        return None
+    if not rest:
+        return None
+    return (
+        f"{importer} imports {imported}: that is behind the front door of feature "
+        f"'{feature}' — re-export what you need from the feature package"
+    )
+
+
+def _dotted_name(path: Path, root: Path) -> str:
+    parts = list(path.relative_to(root).with_suffix("").parts)
+    if parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts)
+
+
+def _is_module(dotted: str, root: Path) -> bool:
+    base = root.joinpath(*dotted.split("."))
+    return base.with_suffix(".py").is_file() or (base / "__init__.py").is_file()
+
+
+def _imports(source: str, importer: str, root: Path) -> list[str]:
+    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 = importer.split(".")[: -node.level] or [""]
+                base = ".".join([*package, base]) if base else ".".join(package)
+            found.append(base)
+            # `from pkg.features.x import y` reaches a module when y is one, not just a name.
+            found.extend(
+                f"{base}.{alias.name}"
+                for alias in node.names
+                if base and _is_module(f"{base}.{alias.name}", root)
+            )
+    return [name for name in found if name]
+
+
+def collect_violations(root: Path) -> list[str]:
+    found: list[str] = []
+    for path in sorted(root.rglob("*.py")):
+        importer = _dotted_name(path, root)
+        source = path.read_text(encoding="utf-8")
+        for imported in _imports(source, importer, root):
+            message = violation(importer, imported)
+            if message:
+                found.append(message)
+    return found
+
+
+SELF_TEST_CASES = [
+    ("acme.features.orders.service", "acme.features.catalog.service", True),
+    ("acme.features.orders.service", "acme.features.catalog", False),
+    ("acme.features.catalog", "acme.features.catalog.service", False),
+    ("acme.features", "acme.features.catalog", False),
+    ("acme.shared.errors", "acme.features.catalog", True),
+    ("acme.main", "acme.features.catalog", False),
+]
+
+
+def test_the_rules_still_detect_a_violation() -> None:
+    for importer, imported, expected in SELF_TEST_CASES:
+        assert bool(violation(importer, imported)) is expected, f"{importer} -> {imported}"
+
+
+def test_features_are_entered_through_their_front_door() -> None:
+    root = CONFIG["source_root"]
+    assert root.is_dir(), f"{root} not found — set ARCH_SOURCE_ROOT"
+    found = collect_violations(root)
+    assert not found, "Monolith boundary violations:\n" + "\n".join(found)
+
+
+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/multi-agent/blueprint.yaml

@@ -0,0 +1,97 @@
+id: multi-agent
+kind: architecture
+name: Multi-Agent (Orchestrator-Worker)
+description: >-
+  Folder overlay for a lead agent that dynamically plans work and dispatches it to workers with
+  isolated contexts, each returning a condensed summary instead of its transcript. Ships an
+  explicit fan-out cap, a per-run token ledger, and a boundary check per stack that fails when a
+  worker reaches back into the orchestrator, into another worker, or around the budget.
+
+tags:
+  - multi-agent
+  - orchestrator-worker
+  - subagents
+  - token-budget
+  - fan-out
+  - boundaries
+
+requires: []
+conflicts: []
+provides:
+  - agent-orchestration
+  - agent-token-budget
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # Workers are the unit of work here, so the layout is meaningless without one to show the shape.
+  - name: workerName
+    prompt: Name of the first worker (a specialization, e.g. "research")
+    type: string
+    default: research
+    required: true
+
+  # Anthropic's lead agent spins up 3-5 subagents in parallel for a complex query; the cap is the
+  # ceiling on that, not the target.
+  - name: fanOutCap
+    prompt: Maximum workers dispatched in a single fan-out
+    type: number
+    default: 5
+    required: true
+
+  # Anthropic measured multi-agent systems at ~15x the tokens of a chat interaction. 25k x 15 is
+  # where this default comes from — change the number, not the reasoning, when your baseline differs.
+  - name: runTokenBudget
+    prompt: Whole-run token ceiling (default is a ~25k chat turn times the measured 15x multiplier)
+    type: number
+    default: 375000
+    required: true
+
+files:
+  # ── docs ────────────────────────────────────────────────────────────────────
+  - from: files/docs/architecture/multi-agent.python.md
+    to: .
+    when: "stack == 'python'"
+  - from: files/docs/architecture/multi-agent.typescript.md
+    to: .
+    when: "stack == 'typescript'"
+  - from: files/docs/architecture/multi-agent.node.md
+    to: .
+    when: "stack == 'node'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One layout serves both: the agent tree is the same whether the base is Next.js, Vite,
+  # Hono, or Nest.
+  - from: files/src/agents/**/*
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/scripts/check-agent-boundaries.mjs
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/src/__solutionName.snake__/agents/**/*
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/architecture/test_agent_boundaries.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+
+  # Declared, not installed by a post-apply step: a package added after generation is
+  # missing from the first install (ADR 0005, spec 003). The .importlinter contract file
+  # is useless without the linter that reads it.
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+postApply:
+  # Manifest-only, matching the other blueprints: no install runs here.
+  - run: npm pkg set "scripts.check:agents"="node scripts/check-agent-boundaries.mjs"
+    when: "stack == 'typescript' || stack == 'node'"
+    optional: true

package/templates/architectures/multi-agent/files/.importlinter

@@ -0,0 +1,36 @@
+# import-linter contracts — the standard-tool half of the boundary enforcement.
+# `lint-imports` fails the build; wire it into CI next to pytest and ruff.
+# The rules import-linter cannot express — orchestrator/fanout and orchestrator/budget being
+# private, and only agents.runtime importing a model SDK — are enforced by
+# tests/architecture/test_agent_boundaries.py, which needs no per-worker upkeep.
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+# A worker must never reach back up into the lead; that back-edge is how the two contexts merge.
+[importlinter:contract:agent-layers]
+name = Orchestrator sits above workers, workers above the runtime seam
+type = layers
+layers =
+    {{ solutionName | snake }}.agents.orchestrator
+    {{ solutionName | snake }}.agents.workers
+    {{ solutionName | snake }}.agents.runtime
+    {{ solutionName | snake }}.agents.contracts
+
+[importlinter:contract:contracts-are-a-leaf]
+name = The orchestrator/worker seam depends on nothing
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.agents.contracts
+forbidden_modules =
+    {{ solutionName | snake }}.agents.config
+    {{ solutionName | snake }}.agents.orchestrator
+    {{ solutionName | snake }}.agents.workers
+    {{ solutionName | snake }}.agents.runtime
+
+# As you add workers, list them here so import-linter proves their contexts stay isolated.
+# Independence forbids imports in BOTH directions between every pair named.
+[importlinter:contract:workers-are-isolated]
+name = Workers do not import one another
+type = independence
+modules =
+    {{ solutionName | snake }}.agents.workers.{{ workerName | snake }}