open/portfolio-optimiser
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
portfolio-optimiser/shared/README.md
Kjell Tore Guttormsen 5de1c93b69 feat(spec): S2 — normative framework-neutral method spec as the fourth shared artifact 
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
2026-07-03 00:50:42 +02:00

2.7 KiB
Raw Blame History

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, 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.