From 65e4f5d9e49740180c0ff63db6888991abf8973a Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 26 Jun 2026 21:26:45 +0200 Subject: [PATCH] docs(shared): framework-neutral concept note + shared-core contract First artifact in the framework-neutral shared core (R1 effectuated). CONCEPT.md is a plain-language business description of the method for a non-specialist audience; README.md documents the shared-core contract (consumed unchanged by both the MAF impl and the future Claude Agents SDK sibling; extract to commons repo via git subtree split when sibling work starts). English per the repo's documentation-language convention + open-publish intent. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_019any9zfGNNwWJPX5Zq2QRz --- shared/CONCEPT.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++ shared/README.md | 31 +++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 shared/CONCEPT.md create mode 100644 shared/README.md diff --git a/shared/CONCEPT.md b/shared/CONCEPT.md new file mode 100644 index 0000000..e60212b --- /dev/null +++ b/shared/CONCEPT.md @@ -0,0 +1,79 @@ +# The Concept + +*A plain-language description of what this project is and why it matters — written for a +non-specialist, e.g. a business developer at another company. Framework-neutral: it +describes the method, not any particular implementation.* + +--- + +## The problem + +Many organizations run a **portfolio of independent projects** at the same time — +construction projects, IT services, infrastructure works, production lines. Inside *each +individual* project sit hidden cost savings: a material that could be substituted, a +specification that is needlessly conservative, a procurement contract that could be +renegotiated. Finding them requires an experienced specialist to study that specific +project in depth — and that expertise is expensive and scales poorly across a whole +portfolio. So the savings are left on the table. + +Generative AI can suggest ideas, but a business developer immediately sees two obstacles: +you cannot trust numbers a language model *guesses*, and the model does not know your +industry's actual rules and experience. The concept is built precisely to remove these +two obstacles. + +## How it works + +For each project, everything known about it is gathered — project documents, the +discipline's assessment methodology, relevant professional literature, and the hard +constraints (budget, what cannot change, regulatory requirements) — into a **curated, +per-project knowledge base**. It is built on an open, vendor-neutral standard (Google's +Open Knowledge Format), so it is portable and not locked to a single vendor. + +A team of AI agents reads this context, proposes concrete measures, and debates them +against each other — one proposes, another critiques. But — and this is the heart of it — +**the agents are never allowed to decide the value themselves.** Every number is sent to a +separate, **deterministic calculation engine** (mathematical optimization plus risk +simulation) that computes the actual saving. The AI proposes; the math decides. That is +the trust anchor that separates this from "ask a chatbot." + +The measures that survive the calculation are presented to a **human domain expert** who +issues a verdict: approve, improve, or reject. + +## What makes it valuable over time + +This is where the differentiation lies. The system **learns from the experts' verdicts.** +There is almost always a gap between what a model *computes* and what an experienced +specialist actually *approves* — because the expert knows how measures behave in practice, +not just in theory. The system captures that gap and feeds it back, so the proposals get +sharper on *your* organization's reality, not generic averages. The more verdicts, the +better. + +And it respects how experts actually work: sometimes they respond on the spot, other times +it takes days or weeks. The expert simply places their assessment into a **folder**, and +the system picks it up whenever it arrives. No requirement for real-time, and no one has to +be standing by. + +## What it is — and isn't + +It is a **purely technical framework**, not a finished compliance product. The +organization that adopts it owns its own purpose, privacy, and governance; the framework +only provides the technical preconditions (run locally, traceability on every proposal, no +data leaving silently). It can run locally or in the cloud, and is published openly so +others can adopt it. + +## Why it is built twice + +The same concept is built on **two different AI agent platforms** — Microsoft's Agent +Framework and Claude's Agent SDK — on exactly the same example, so they can be compared +fairly. This gives both an open reference others can copy, and an honest basis for judging +which platform fits the task best. + +## Concretely + +Consider energy efficiency across a portfolio of buildings. Each building is a project with +its own measure options (ventilation, lighting, insulation). The calculation engine +computes the *modeled* saving for a package of measures under a budget. But an energy +advisor knows that modeled and realized savings are rarely the same — behavior, measurement +uncertainty, and interactions between measures create a gap. The expert's verdicts teach the +system to close that gap over time. It is exactly in a field like this — where genuine +expert judgment exists *beyond* pure calculation — that the concept comes into its own. diff --git a/shared/README.md b/shared/README.md new file mode 100644 index 0000000..bcdb1c1 --- /dev/null +++ b/shared/README.md @@ -0,0 +1,31 @@ +# shared/ — framework-neutral core + +This directory holds the parts of the project that are **independent of any AI agent +framework** and are meant to be **shared, unchanged, between both reference +implementations**: + +- **this repository** — the method built on Microsoft Agent Framework (MAF); +- **a sibling repository** (built later, in sequence) — the same method on the + **Claude Agents SDK**. + +Sharing one identical core is what makes the two implementations a *fair comparison*: +both consume the same concept, the same example data, and the same expected outcomes, +so the only thing that differs is the agent framework itself. + +## Contents (growing) + +- [`CONCEPT.md`](CONCEPT.md) — the business concept, written for a non-specialist + (e.g. a business developer at another company). +- *(planned)* the method specification, the example knowledge bundles (OKF / LLM-wiki), + the expert-reviewer persona, and the golden-suite of expected validator outcomes. + +## Rules + +- **Nothing in here may import or depend on a specific agent framework.** If it does, + it does not belong in `shared/`. +- **Repo layout (decision R1, 2026-06-26):** the shared core lives here for now. When + work on the sibling repository begins, it will be extracted into its own repository + (e.g. `portfolio-optimiser-commons`) via `git subtree split`, and both implementation + repos will consume it. This defers cross-repo plumbing until it is actually needed. + +See the target picture for the full architecture: `docs/plan/2026-06-26-maalbilde-agentic-loop.md`.