@opengroundplan/core 0.1.1

package/templates/architectures/multi-agent/files/docs/architecture/multi-agent.node.md

@@ -0,0 +1,110 @@
+# Architecture — Multi-Agent (Orchestrator-Worker)
+
+A lead agent breaks the request into briefs, dispatches them to workers that run in **isolated
+contexts**, and synthesizes a response from what those workers report back. Subtasks are not
+pre-defined; the lead decides them from the input. That is what separates orchestrator-worker
+from plain parallel fan-out.
+
+## The one rule that matters
+
+> **A worker returns a summary, never its run.** Nothing under `src/agents/workers/` may import
+> `src/agents/orchestrator/`, no worker may import another worker, and `WorkerResult` declares no
+> transcript field. `node scripts/check-agent-boundaries.mjs` fails the build the moment any of
+> that changes.
+
+Break this rule and every worker's tool output lands back in the lead's context. The contexts
+merge, the window fills, and you are paying multi-agent prices for single-agent behaviour.
+
+## The budget is a first-class artifact
+
+Anthropic measured agents at ~4x the tokens of a chat interaction and **multi-agent systems at
+~15x**. `src/agents/config.ts` therefore ships hard limits, not metrics:
+
+- `fanOutCap` — workers dispatched in one fan-out. Default {{ fanOutCap }}; a lead spinning up
+  3–5 subagents in parallel is the normal shape of a complex request.
+- `runTokenBudget` — whole-run ceiling, default {{ runTokenBudget }} (a ~25k chat turn times that
+  measured 15x). `RunBudget` reserves before dispatch, so an over-plan is refused rather than
+  discovered afterwards.
+- `workerConcurrency` — how many workers are in flight at once. On a server this is the knob that
+  decides whether one expensive request can starve every other one.
+
+Every limit is overridable with `{{ solutionName | upperSnake }}_AGENTS_*`. No other module names
+a number.
+
+## Layout
+
+```
+src/agents/
+  config.ts                 # every limit, one typed default table
+  contracts/                # the seam. Imports nothing else under agents/.
+    task.ts                 #   WorkerTask: objective, outputFormat, tools, boundaries
+    result.ts               #   WorkerResult + condense(): a whitelist projection
+  orchestrator/
+    index.ts                #   the public surface: runLead()
+    lead.ts                 #   plan -> fan out -> synthesize from summaries
+    fanout.ts               #   private: the cap, the concurrency gate
+    budget.ts               #   private: the per-run token ledger
+  workers/
+    index.ts                #   registry — the lead names a worker, never imports one
+    {{ workerName | kebab }}/
+      worker.ts             #   one isolated context
+      prompt.ts             #   the brief, and how citations come back
+  runtime/
+    runner.ts               # AgentRunner: the ONLY folder that may import a model SDK
+scripts/
+  check-agent-boundaries.mjs  # the fitness test
+```
+
+## Running it inside a request
+
+`runLead()` is synchronous from the caller's point of view and internally serial: the lead waits
+for its workers before it can synthesize. A multi-agent run is therefore a slow request by
+construction. Give it its own route, its own timeout, and — once runs outlive a sensible HTTP
+deadline — a job record rather than an open connection.
+
+Construct a fresh `RunBudget` per run. It is deliberately not a singleton; a process-wide ledger
+would let one request exhaust another's budget.
+
+## Writing a brief
+
+A worker sees its brief and nothing else, so an underspecified brief is why workers duplicate
+work and leave gaps. `WorkerTask` makes all four fields structural: `objective`, `outputFormat`,
+`tools`, `boundaries`.
+
+Scale effort to the request. One brief answers a lookup; two to four answer a comparison. The cap
+is a ceiling, not a target.
+
+## Wiring it up
+
+Implement `AgentRunner` against your LLM client and call `setRunner(...)` once during startup,
+beside the rest of your composition root. Resolve the model **by role** (`lead-planner`,
+`lead-synthesizer`, `{{ workerName | kebab }}-worker`), never by a model id at the call site.
+
+## Enforcement
+
+`node scripts/check-agent-boundaries.mjs` — add it to `npm run check:agents` and to CI:
+
+- no worker imports the orchestrator, and no worker imports another worker,
+- `orchestrator/fanout` and `orchestrator/budget` are private, so the cap and the ledger cannot
+  be routed around,
+- workers are reachable only through the orchestrator's fan-out,
+- `contracts/` stays a leaf,
+- inside `src/agents/`, only `runtime/` imports a model SDK,
+- `WorkerResult` declares no transcript, messages, or history field.
+
+It reads import specifiers as written and never resolves them on disk, so it runs on sources with
+no build step. `--self-test` proves the rules still fire.
+
+## What is not enforced mechanically
+
+- **That a summary is actually condensed.** `summaryCharLimit` truncates; it cannot tell a
+  distilled finding from a pasted transcript. Review worker prompts, not just worker code.
+- **That briefs do not overlap.** Two workers researching the same thing pay twice and no import
+  graph can see it. This is the most common and most expensive defect in this architecture.
+- **That effort matched the request.** Fanning out five workers for a lookup is legal and
+  wasteful. Watch `RunOutcome.tokensSpent` per route.
+- **Behaviour between runs.** The system is non-deterministic; identical prompts produce
+  different trajectories, so no test here asserts an answer. Evaluate outcomes, not transcripts.
+
+Sources: [Anthropic — How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system) ·
+[Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents).

package/templates/architectures/multi-agent/files/docs/architecture/multi-agent.python.md

@@ -0,0 +1,94 @@
+# Architecture — Multi-Agent (Orchestrator-Worker)
+
+A lead agent breaks the query into briefs, dispatches them to workers that run in **isolated
+contexts**, and synthesizes an answer from what those workers report back. Subtasks are not
+pre-defined; the lead decides them from the input. That is what separates orchestrator-worker
+from plain parallel fan-out.
+
+## The one rule that matters
+
+> **A worker returns a summary, never its run.** Nothing under `agents/workers/` may import
+> `agents.orchestrator`, no worker may import another worker, and `WorkerResult` carries no
+> transcript field. `pytest tests/architecture/test_agent_boundaries.py` fails the build the
+> moment any of that changes.
+
+Break this rule and every worker's tool output lands back in the lead's context. The contexts
+merge, the window fills, and you are paying multi-agent prices for single-agent behaviour.
+
+## The budget is a first-class artifact
+
+Anthropic measured agents at ~4x the tokens of a chat interaction and **multi-agent systems at
+~15x**. `agents/config.py` therefore ships two hard limits, not two metrics:
+
+- `fan_out_cap` — workers dispatched in one fan-out. Default {{ fanOutCap }}; a lead spinning up
+  3–5 subagents in parallel is the normal shape of a complex query.
+- `run_token_budget` — whole-run ceiling, default {{ runTokenBudget }} (a ~25k chat turn times
+  that measured 15x). `RunBudget` reserves before dispatch, so an over-plan is refused rather
+  than discovered afterwards.
+
+Every limit is overridable with `{{ solutionName | upperSnake }}_AGENTS_*`. No other module
+names a number.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/agents/
+  config.py                 # every limit, one typed default table
+  contracts.py              # WorkerTask / WorkerResult — the seam. Imports nothing.
+  orchestrator/
+    __init__.py             #   the public surface: run_lead()
+    lead.py                 #   plan -> fan out -> synthesize from summaries
+    fanout.py               #   private: the cap, the concurrency gate
+    budget.py               #   private: the per-run token ledger
+  workers/
+    __init__.py             #   registry — the lead names a worker, never imports one
+    {{ workerName | snake }}/
+      worker.py             #   one isolated context
+      prompt.py             #   the brief, and how citations come back
+  runtime/
+    runner.py               # AgentRunner: the ONLY place a model SDK may be imported
+tests/architecture/
+  test_agent_boundaries.py  # the fitness test
+.importlinter               # the standard-tool half of the same rules
+```
+
+## Writing a brief
+
+A worker sees its brief and nothing else, so an underspecified brief is why workers duplicate
+work and leave gaps. `WorkerTask` makes all four fields structural: `objective`, `output_format`,
+`tools`, `boundaries`.
+
+Scale effort to the query. One brief answers a lookup; two to four answer a comparison. The cap
+is a ceiling, not a target.
+
+## Wiring it up
+
+Implement `AgentRunner` against your LLM client and `set_runner(...)` at startup. Resolve the
+model **by role** (`lead-planner`, `lead-synthesizer`, `{{ workerName | kebab }}-worker`), never
+by a model id at the call site.
+
+## Enforcement
+
+1. `pytest tests/architecture/test_agent_boundaries.py` — parses every import and enforces the
+   full rule set: no worker→orchestrator back-edge, no worker→worker import, `fanout`/`budget`
+   private to the orchestrator, workers reachable only through fan-out, `contracts` a leaf, and
+   only `agents.runtime` importing a model SDK. It also asserts `WorkerResult` declares no
+   transcript field. Runs standalone:
+   `python tests/architecture/test_agent_boundaries.py`.
+2. `lint-imports` reads `.importlinter` for the layering and worker-independence contracts. List
+   each new worker in the `workers-are-isolated` contract.
+
+## What is not enforced mechanically
+
+- **That a summary is actually condensed.** `summary_char_limit` truncates; it cannot tell a
+  distilled finding from a pasted transcript. Review worker prompts, not just worker code.
+- **That briefs do not overlap.** Two workers researching the same thing pay twice and no import
+  graph can see it. This is the most common and most expensive defect in this architecture.
+- **That effort matched the query.** Fanning out five workers for a lookup is legal and wasteful.
+  Watch `RunOutcome.tokens_spent` per query type.
+- **Behaviour between runs.** The system is non-deterministic; identical prompts produce
+  different trajectories, so no test here asserts an answer. Evaluate outcomes, not transcripts.
+
+Sources: [Anthropic — How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system) ·
+[Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) ·
+[import-linter](https://import-linter.readthedocs.io/).

package/templates/architectures/multi-agent/files/docs/architecture/multi-agent.typescript.md

@@ -0,0 +1,102 @@
+# Architecture — Multi-Agent (Orchestrator-Worker)
+
+A lead agent breaks the query into briefs, dispatches them to workers that run in **isolated
+contexts**, and synthesizes an answer from what those workers report back. Subtasks are not
+pre-defined; the lead decides them from the input. That is what separates orchestrator-worker
+from plain parallel fan-out.
+
+## The one rule that matters
+
+> **A worker returns a summary, never its run.** Nothing under `src/agents/workers/` may import
+> `src/agents/orchestrator/`, no worker may import another worker, and `WorkerResult` declares no
+> transcript field. `node scripts/check-agent-boundaries.mjs` fails the build the moment any of
+> that changes.
+
+Break this rule and every worker's tool output lands back in the lead's context. The contexts
+merge, the window fills, and you are paying multi-agent prices for single-agent behaviour.
+
+## The budget is a first-class artifact
+
+Anthropic measured agents at ~4x the tokens of a chat interaction and **multi-agent systems at
+~15x**. `src/agents/config.ts` therefore ships two hard limits, not two metrics:
+
+- `fanOutCap` — workers dispatched in one fan-out. Default {{ fanOutCap }}; a lead spinning up
+  3–5 subagents in parallel is the normal shape of a complex query.
+- `runTokenBudget` — whole-run ceiling, default {{ runTokenBudget }} (a ~25k chat turn times that
+  measured 15x). `RunBudget` reserves before dispatch, so an over-plan is refused rather than
+  discovered afterwards.
+
+Every limit is overridable with `{{ solutionName | upperSnake }}_AGENTS_*`. No other module names
+a number.
+
+## Layout
+
+```
+src/agents/
+  config.ts                 # every limit, one typed default table
+  contracts/                # the seam. Imports nothing else under agents/.
+    task.ts                 #   WorkerTask: objective, outputFormat, tools, boundaries
+    result.ts               #   WorkerResult + condense(): a whitelist projection
+  orchestrator/
+    index.ts                #   the public surface: runLead()
+    lead.ts                 #   plan -> fan out -> synthesize from summaries
+    fanout.ts               #   private: the cap, the concurrency gate
+    budget.ts               #   private: the per-run token ledger
+  workers/
+    index.ts                #   registry — the lead names a worker, never imports one
+    {{ workerName | kebab }}/
+      worker.ts             #   one isolated context
+      prompt.ts             #   the brief, and how citations come back
+  runtime/
+    runner.ts               # AgentRunner: the ONLY folder that may import a model SDK
+scripts/
+  check-agent-boundaries.mjs  # the fitness test
+```
+
+The types do half the work here: `WorkerResult` has no transcript field, and `condense()` copies
+only the fields on that interface, so a worker returning extra keys cannot leak them at runtime
+either. `tsc` catches the first mistake, the checker catches the second.
+
+## Writing a brief
+
+A worker sees its brief and nothing else, so an underspecified brief is why workers duplicate
+work and leave gaps. `WorkerTask` makes all four fields structural: `objective`, `outputFormat`,
+`tools`, `boundaries`.
+
+Scale effort to the query. One brief answers a lookup; two to four answer a comparison. The cap
+is a ceiling, not a target.
+
+## Wiring it up
+
+Implement `AgentRunner` against your LLM client and call `setRunner(...)` at startup. Resolve the
+model **by role** (`lead-planner`, `lead-synthesizer`, `{{ workerName | kebab }}-worker`), never
+by a model id at the call site.
+
+## Enforcement
+
+`node scripts/check-agent-boundaries.mjs` (wire it into CI and `npm run check:agents`):
+
+- no worker imports the orchestrator, and no worker imports another worker,
+- `orchestrator/fanout` and `orchestrator/budget` are private, so the cap and the ledger cannot
+  be routed around,
+- workers are reachable only through the orchestrator's fan-out,
+- `contracts/` stays a leaf,
+- inside `src/agents/`, only `runtime/` imports a model SDK,
+- `WorkerResult` declares no transcript, messages, or history field.
+
+It reads import specifiers as written and never resolves them on disk, so it is immune to
+bundler/TS resolution quirks. Run `--self-test` to prove the rules still fire.
+
+## What is not enforced mechanically
+
+- **That a summary is actually condensed.** `summaryCharLimit` truncates; it cannot tell a
+  distilled finding from a pasted transcript. Review worker prompts, not just worker code.
+- **That briefs do not overlap.** Two workers researching the same thing pay twice and no import
+  graph can see it. This is the most common and most expensive defect in this architecture.
+- **That effort matched the query.** Fanning out five workers for a lookup is legal and wasteful.
+  Watch `RunOutcome.tokensSpent` per query type.
+- **Behaviour between runs.** The system is non-deterministic; identical prompts produce
+  different trajectories, so no test here asserts an answer. Evaluate outcomes, not transcripts.
+
+Sources: [Anthropic — How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system) ·
+[Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents).

package/templates/architectures/multi-agent/files/pyproject.toml

@@ -0,0 +1,2 @@
+[dependency-groups]
+dev = ["import-linter==2.13"]

package/templates/architectures/multi-agent/files/scripts/check-agent-boundaries.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * 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. Exits non-zero on a violation, so it belongs in `lint` and CI.
+ *
+ * It reads import specifiers as written and never resolves them on disk, so it is immune to
+ * TypeScript/bundler resolution differences and works the same on .ts and .js.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** Every tunable lives here. Nothing below reads the environment directly. */
+const config = {
+  agentsRoot: process.env.ARCH_AGENTS_ROOT ?? 'src/agents',
+  /** Orchestrator modules nothing outside the orchestrator may import. */
+  orchestratorPrivate: split(process.env.ARCH_ORCHESTRATOR_PRIVATE) ?? ['fanout', 'budget'],
+  /** SDKs that spend tokens. Only `runtime/` may import one, or the ledger under-counts. */
+  modelPackages:
+    split(process.env.ARCH_MODEL_PACKAGES) ??
+    ['@anthropic-ai/sdk', '@anthropic-ai/bedrock-sdk', '@anthropic-ai/vertex-sdk', 'openai', 'ai',
+      '@google/genai', '@aws-sdk/client-bedrock-runtime', 'ollama'],
+  /** Fields whose presence on WorkerResult would reintroduce the shared context. */
+  forbiddenResultFields: split(process.env.ARCH_FORBIDDEN_RESULT_FIELDS) ??
+    ['transcript', 'messages', 'history', 'trace', 'conversation'],
+  extensions: ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'],
+  skipDirs: ['node_modules', 'dist', 'build', 'out', 'coverage', '.git', '.turbo', '.next'],
+};
+
+function split(value) {
+  return value ? value.split(',').map((entry) => entry.trim()).filter(Boolean) : undefined;
+}
+
+const SPECIFIER_PATTERNS = [
+  /(?:^|[\s;}])(?:import|export)[^;]*?\sfrom\s*['"]([^'"]+)['"]/g,
+  /(?:^|[\s;}])import\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+
+export function specifiersOf(source) {
+  const found = new Set();
+  for (const pattern of SPECIFIER_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of source.matchAll(pattern)) found.add(match[1]);
+  }
+  return [...found];
+}
+
+/** Which part of the agent tree a path belongs to, and which worker if any. */
+export function zoneOf(filePath, workers = []) {
+  const prefix = config.agentsRoot + '/';
+  if (!filePath.startsWith(prefix)) return null;
+  const parts = filePath.slice(prefix.length).split('/');
+  return {
+    area: parts[0],
+    worker: parts[0] === 'workers' && workers.includes(parts[1]) ? parts[1] : null,
+    module: parts[1] ? parts[1].replace(/\.[^.]+$/, '') : '',
+  };
+}
+
+/** Worker names come from disk; a path segment alone cannot tell a worker from a plain file. */
+async function discoverWorkers() {
+  const entries = await readdir(`${config.agentsRoot}/workers`, { withFileTypes: true }).catch(() => []);
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+
+const packageOf = (specifier) => {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+};
+
+/** The whole rule set, isolated so `--self-test` can prove it still fires. */
+export function violationOf(fromFile, specifier, workers) {
+  const from = zoneOf(fromFile, workers);
+
+  if (!specifier.startsWith('.')) {
+    // Scoped to the agent tree: the app's own LLM layer is where an AgentRunner gets built.
+    if (!from || !config.modelPackages.includes(packageOf(specifier))) return null;
+    return from.area === 'runtime'
+      ? null
+      : `imports "${specifier}" — inside ${config.agentsRoot}, only runtime/ may call a model SDK, or the run token ledger under-counts`;
+  }
+
+  const target = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+  const to = zoneOf(target, workers);
+  if (!to) return null;
+
+  if (from?.area === 'contracts' && to.area !== 'contracts') {
+    return `imports "${specifier}" — contracts/ is the seam and must stay a leaf`;
+  }
+  if (from?.area === 'workers' && to.area === 'orchestrator') {
+    return `imports "${specifier}" — a worker must not reach back into the orchestrator; it returns a summary and nothing else`;
+  }
+  if (from?.worker && to.worker && from.worker !== to.worker) {
+    return `imports "${specifier}" — workers run in isolated contexts and must not import one another`;
+  }
+  if (to.worker && from?.area !== 'workers') {
+    return `imports "${specifier}" — reach a worker through the orchestrator's fan-out; the cap and the budget live there`;
+  }
+  if (to.area === 'orchestrator' && config.orchestratorPrivate.includes(to.module) && from?.area !== 'orchestrator') {
+    return `imports "${specifier}" — orchestrator/${to.module} is private; the fan-out cap and token ledger must not be routed around`;
+  }
+  return null;
+}
+
+/** The contract is the last place the rule can be broken: a transcript field on WorkerResult. */
+async function contractViolations() {
+  const file = `${config.agentsRoot}/contracts/result.ts`;
+  const source = await readFile(file, 'utf8').catch(() => null);
+  if (source === null) return [`${file}: missing — the worker/orchestrator contract defines the boundary`];
+
+  // Scoped to the declaration body so prose in comments elsewhere cannot trip it.
+  const body = /interface\s+WorkerResult\s*(?:extends[^{]*)?\{([\s\S]*?)\n\}/.exec(source);
+  if (!body) return [`${file}: no WorkerResult interface found — the seam is not declared here`];
+
+  return config.forbiddenResultFields
+    .filter((field) => new RegExp(`(?:^|[{;,])\\s*(?:readonly\\s+)?${field}\\??\\s*:`, 'm').test(body[1]))
+    .map((field) => `${file}: WorkerResult declares "${field}" — a worker returns a summary, never its run`);
+}
+
+async function listFiles(root) {
+  const found = [];
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = path.posix.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!config.skipDirs.includes(entry.name)) await walk(child);
+      } else if (config.extensions.includes(path.extname(entry.name))) {
+        found.push(child);
+      }
+    }
+  };
+  await walk(root);
+  return found;
+}
+
+const SELF_TEST_WORKERS = ['research', 'review'];
+const SELF_TEST_CASES = [
+  ['src/agents/workers/research/worker.ts', '../../orchestrator/fanout.js', true],
+  ['src/agents/workers/research/worker.ts', '../../runtime/index.js', false],
+  ['src/agents/workers/research/worker.ts', '../review/worker.js', true],
+  ['src/agents/workers/index.ts', './research/worker.js', false],
+  ['src/agents/contracts/result.ts', '../config.js', true],
+  ['src/agents/contracts/result.ts', './task.js', false],
+  ['src/agents/orchestrator/lead.ts', './fanout.js', false],
+  ['src/app/route.ts', '../agents/orchestrator/fanout.js', true],
+  ['src/app/route.ts', '../agents/orchestrator/index.js', false],
+  ['src/app/route.ts', '../agents/workers/research/worker.js', true],
+  ['src/agents/runtime/anthropic.ts', '@anthropic-ai/sdk', false],
+  ['src/agents/orchestrator/lead.ts', '@anthropic-ai/sdk', true],
+];
+
+function selfTest() {
+  const wrong = SELF_TEST_CASES.filter(
+    ([file, specifier, expected]) =>
+      Boolean(violationOf(file, specifier, SELF_TEST_WORKERS)) !== expected,
+  );
+  for (const [file, specifier] of wrong) console.error(`self-test failed: ${file} -> ${specifier}`);
+  return wrong.length === 0;
+}
+
+async function main() {
+  if (process.argv.includes('--self-test')) {
+    if (!selfTest()) process.exit(1);
+    console.log(`agent boundary rules verified against ${SELF_TEST_CASES.length} cases`);
+    return;
+  }
+
+  const workers = await discoverWorkers();
+  const files = [...new Set((await Promise.all(['src', 'apps'].map(listFiles))).flat())];
+  const inAgents = files.filter((file) => zoneOf(file, workers));
+  if (inAgents.length === 0) {
+    // A silent pass over an empty file set is the failure mode this check exists to avoid.
+    console.error(`No agent code found under ${config.agentsRoot} — is ARCH_AGENTS_ROOT right?`);
+    process.exit(1);
+  }
+
+  const violations = await contractViolations();
+  for (const file of files) {
+    const source = await readFile(file, 'utf8');
+    for (const specifier of specifiersOf(source)) {
+      const violation = violationOf(file, specifier, workers);
+      if (violation) violations.push(`${file}: ${violation}`);
+    }
+  }
+
+  if (violations.length > 0) {
+    console.error(`Agent boundary violations (${violations.length}):\n` + violations.join('\n'));
+    process.exit(1);
+  }
+  console.log(`Agent boundaries hold across ${inAgents.length} file(s) under ${config.agentsRoot}.`);
+}
+
+if (!selfTest()) {
+  console.error('The boundary rules no longer detect a known violation — fix violationOf().');
+  process.exit(1);
+}
+await main();

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Multi-agent runtime: a lead agent that plans, workers that run in isolated contexts.
+
+`orchestrator` is the only entry point. `contracts` is the seam; `runtime` is the only place a
+model SDK may be imported, which is what keeps the run token ledger complete.
+"""

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/config.py

@@ -0,0 +1,52 @@
+"""Every agent-runtime limit lives here.
+
+No other module reads the environment or names a number. Overridable with
+``{{ solutionName | upperSnake }}_AGENTS_*``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+
+ENV_PREFIX = "{{ solutionName | upperSnake }}_AGENTS_"
+
+
+def _positive_int(name: str, fallback: int) -> int:
+    try:
+        value = int(os.environ[ENV_PREFIX + name])
+    except (KeyError, ValueError):
+        return fallback
+    return value if value > 0 else fallback
+
+
+@dataclass(frozen=True, slots=True)
+class AgentConfig:
+    #: Hard ceiling on workers dispatched in one fan-out.
+    fan_out_cap: int
+    #: How many of those actually run at once.
+    worker_concurrency: int
+    #: Whole-run token ceiling, orchestrator included. Anthropic measured multi-agent systems at
+    #: ~15x the tokens of a chat interaction, so this is a budget the run is held to, not a
+    #: number it reports afterwards.
+    run_token_budget: int
+    #: A single worker may never eat the whole run.
+    worker_token_budget: int
+    #: Tool calls a worker may make before it must report back.
+    worker_max_steps: int
+    #: Condensation is the whole point — a "summary" longer than this is a transcript.
+    summary_char_limit: int
+
+
+@lru_cache(maxsize=1)
+def agent_config() -> AgentConfig:
+    run_token_budget = _positive_int("RUN_TOKEN_BUDGET", {{ runTokenBudget }})
+    return AgentConfig(
+        fan_out_cap=_positive_int("FAN_OUT_CAP", {{ fanOutCap }}),
+        worker_concurrency=_positive_int("WORKER_CONCURRENCY", 3),
+        run_token_budget=run_token_budget,
+        worker_token_budget=_positive_int("WORKER_TOKEN_BUDGET", run_token_budget // 5),
+        worker_max_steps=_positive_int("WORKER_MAX_STEPS", 15),
+        summary_char_limit=_positive_int("SUMMARY_CHAR_LIMIT", 4000),
+    )

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/contracts.py

@@ -0,0 +1,62 @@
+"""The only types that cross the orchestrator/worker seam. This module imports nothing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+WorkerStatus = Literal["ok", "budget-exceeded", "failed"]
+_STATUSES = ("ok", "budget-exceeded", "failed")
+
+
+@dataclass(frozen=True, slots=True)
+class TokenUsage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+    @property
+    def total(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerTask:
+    """A brief carries everything the worker needs and nothing about the run it came from;
+    that omission is what keeps the contexts isolated."""
+
+    id: str
+    worker_id: str
+    # The four fields a subagent brief must carry. Underspecified briefs are why workers
+    # duplicate each other's work and leave gaps — they are required, not decorative.
+    objective: str
+    output_format: str
+    tools: tuple[str, ...] = ()
+    boundaries: tuple[str, ...] = ()
+    token_budget: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerResult:
+    """No transcript, message list, or history field: the lead's context must grow by a summary,
+    never by a worker's whole run. Adding one turns this back into a single shared context."""
+
+    task_id: str
+    worker_id: str
+    summary: str
+    usage: TokenUsage
+    status: WorkerStatus
+    citations: tuple[str, ...] = field(default=())
+
+
+def condense(task: WorkerTask, raw: dict[str, Any], summary_char_limit: int) -> WorkerResult:
+    """Whitelist projection over every worker return value — extra keys cannot reach the lead."""
+    status = raw.get("status")
+    usage = raw.get("usage")
+    return WorkerResult(
+        task_id=task.id,
+        worker_id=task.worker_id,
+        summary=str(raw.get("summary", ""))[:summary_char_limit],
+        citations=tuple(str(c) for c in raw.get("citations", ())),
+        usage=usage if isinstance(usage, TokenUsage) else TokenUsage(),
+        status=status if status in _STATUSES else "failed",  # type: ignore[arg-type]
+    )

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/orchestrator/__init__.py

@@ -0,0 +1,9 @@
+"""The orchestrator's public surface.
+
+``fanout`` and ``budget`` stay private so the cap and the ledger cannot be routed around —
+tests/architecture/test_agent_boundaries.py enforces that.
+"""
+
+from .lead import RunOutcome, run_lead
+
+__all__ = ["RunOutcome", "run_lead"]