portfolio-optimiser/shared/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: a SKILL.md persona prompt (energy-advisor / M&V role + the realization-gap methodology the validator cannot compute) and a canonical references/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, realized 2026-07-03): the shared core lives in its own repository, portfolio-optimiser-commons — the source of truth. Each implementation repo consumes it as a git subtree at this unchanged shared/ path (so tests and the PORTFOLIO_SHARED_ROOT default resolver are unaffected). Do not edit commons content anywhere else without syncing.

Subtree sync (run from the consuming repo's root)

The remote is registered as commons (ssh://git@git.fromaitochitta.com/ktg/portfolio-optimiser-commons.git).

• Pull upstream changes from commons into this repo:

  git subtree pull --prefix=shared commons main --squash
  

• Push local shared/ edits (committed here first) back to commons:

  git subtree push --prefix=shared commons main
  

Edits should preferably land in commons first and be pulled; pushing from a consumer is for small fixes made in place. Either way, commons remains the source of truth.

See the target picture for the full architecture: docs/plan/2026-06-26-maalbilde-agentic-loop.md.