Kjell Tore Guttormsen
5de1c93b69
Author shared/method-spec.md: the 8-step loop (normative, RFC-2119), the verdict JSON contract incl. the id-minting algorithm and the chosen conflict semantics, the inbox/outbox folder contract, the fail-closed promotion-gate semantics, the IR projection + golden suite as the only ground truth (incl. the reproducible Monte Carlo procedure), and the budget/stop, provenance and startup-contract requirements — every normative claim cross-checked against the load-bearing tests/code. The sibling implementation builds from this spec alone. Load-bearing trio (tests/test_method_spec_loadbearing.py, persona-trio style): required structure, a name-shaped framework-neutrality guard over the spec + the persona skill tree, and a cross-check-completeness test driven from the REAL artifacts and the REAL verdict serializer (red on code drift). All three detach points proven RED (missing file / framework name / dropped field). shared/README.md: the "(planned)" line replaced with the real entry. Suite 152 -> 155 passed / 4 skipped; ruff check+format clean; mypy src clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi |
||
|---|---|---|
| .. | ||
| examples/bygg-energi-mikro | ||
| skills/expert-reviewer | ||
| CONCEPT.md | ||
| method-spec.md | ||
| README.md | ||
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— the business concept, written for a non-specialist (e.g. a business developer at another company).examples/bygg-energi-mikro/— the first example knowledge bundle (OKF / LLM-wiki): one office building, one LED-retrofit measure, with a seed expert verdict encoding the realization gap and a golden-suite of expected validator outcomes. A small dev fixture for exercising the agentic loop; a realistic full-scale example comes later.skills/expert-reviewer/— the expert-reviewer persona as a framework-neutral Agent Skill: aSKILL.mdpersona prompt (energy-advisor / M&V role + the realization-gap methodology the validator cannot compute) and a canonicalreferences/example-verdict.json. Both reference implementations instantiate the reviewer from this one artifact;shared/stays pure data (each stack reads the JSON with its own loader).method-spec.md— the normative method specification, framework-neutral (the prose never names a concrete agent toolkit — enforced by a guard test): the 8-step loop, the verdict JSON contract, the inbox/outbox folder contract, the promotion-gate semantics, the IR projection + golden suite as the only ground truth, and the budget/provenance requirements. The sibling implementation is built from this spec alone, without reverse-engineering the reference code.
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) viagit 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.