# `investing.md`: a proposed open standard **Status:** proposed · **Version:** 0.4 · **Origin:** Investboard > **Read-only, with a machine-readable neutrality flag.** `investing.md` is a > portable document that states an investor's *own* investment policy: their > purpose, philosophy, asset-class ranges, and behavioral rules, so any AI > agent can reason *within* it. Generated policy sections name no security, > ticker, ISIN, WKN, or holding. An optional, clearly labeled investor-authored > layer is free-form and changes `instrument_neutral` to `false`. The document > is never investment advice. It describes the rails; it does not drive the car. --- ## Why this exists Open financial-data standards describe **what an investor holds** and **how to move money**: - **FDX (Financial Data Exchange)** standardizes read access to accounts, balances, and transactions. - **ACP / agentic-commerce efforts** standardize *executing* an action on a user's behalf. Neither standardizes **how an investor wants to behave**. That is the policy layer: the objective, the risk they accepted, the allocation bands they committed to, the rules that should slow them down in a drawdown. That behavioral layer is exactly what an AI agent needs in order to be *useful without overstepping*, and it is the gap `investing.md` fills. `investing.md` is deliberately the **smallest** such document: a single Markdown file an investor can export from their tooling and paste into any agent (Claude, a custom GPT, an MCP-connected assistant) as durable context. --- ## Design principles 1. **Read-only.** The document is a statement of policy, not a command. An agent should treat it as the constraints to reason within, never as an instruction to trade. Generating it never mutates the source policy. 2. **Generated policy is instrument-neutral, forever.** Generated sections use only asset *classes* (equities, bonds, gold, cash, …) and the investor's own numeric rules. No named instrument appears there. Optional investor-authored additions are visibly separated and never represented as generated policy; their presence is disclosed by setting `instrument_neutral: false`. 3. **Deterministic.** The same policy renders byte-identical Markdown. There is no model in the loop at render time: it is a pure serialization of the investor's stated policy. 4. **Human- and agent-readable.** Plain Markdown with a small YAML front-matter block. A person reads it as a one-page mandate; an agent parses the front-matter for provenance and the headed sections for structure. 5. **Honest about enforcement.** The document distinguishes what the investor's tooling actually *enforces* from what it merely *records*. An agent should treat documented-only items as soft guidance, not hard constraints. --- ## Document shape A valid `investing.md` is a UTF-8 Markdown file with: 1. a **YAML front-matter** block (machine-readable provenance), then 2. a sequence of **headed sections** in a fixed order. ### Front-matter ```yaml --- schema: investing.md schema_version: "0.4" standard: "https://investboard.com/standards/investing-md" composed_at: "2026-06-01T10:00:00.000Z" mode: read-only instrument_neutral: true --- ``` | Key | Type | Meaning | | --- | --- | --- | | `schema` | string | Always `investing.md`. | | `schema_version` | string | The format version this file conforms to (this spec: `0.4`). An agent should branch on it. | | `standard` | string (URL) | Where this spec lives. | | `composed_at` | string (ISO-8601) | When the document was rendered. | | `mode` | string | Always `read-only`. A signal that the document must not be treated as an instruction. | | `instrument_neutral` | boolean | `true` when the whole file contains only generated, instrument-neutral policy. `false` when the optional free-form investor-authored layer is present. | ### Sections (in order) | Section | Required | Contents | | --- | --- | --- | | `# Investment policy` | yes | Title + a read-only preamble that states whether the whole file or only its generated policy sections are instrument-neutral. | | `## Purpose` | yes | Primary objective + time horizon. | | `## Philosophy` | yes | The investor's chosen approach and its governing belief. `Not classified.` when the source policy has no classified philosophy. | | `## Strategy architecture` | when a return source or investor-confirmed details exist | The curated Core return source plus closed-set exposure scope, implementation style, and an optional numeric Satellite position limit. Investor-authored strategy prose stays in the mandate and is intentionally omitted so this portable export remains instrument-neutral. Missing details are named, never inferred. | | `## Risk` | yes | Risk profile; drawdown tolerance ("panic floor") when stated. | | `## Allocation bands` | yes | A table of asset classes with minimum / target / maximum weights. **Asset classes only, never instruments.** | | `## Review rules` | yes | The drift band, the single-issuer cap, then the single-stock cap, the cash floor and the exclusions when the mandate sets them (a limit the mandate does not set prints no line), the formal review cadence, the rebalancing mode, plus every pre-commitment (decisions the investor made in calm to bind their future behavior). | | `## Cooling-off` | yes | How an override is handled: the mode (documented or soft friction) and the hours the investor recorded with it. | | `## Schwerpunkte` | only if set | Deliberate tilts inside the equity sleeve, as a share of equity value, one row per (dimension, key) band. Keys are a closed set; they name no security. Omitted entirely when the investor set none. | | `## Message to my future self` | only if authored | A note the investor wrote for the version of themselves tempted to abandon the plan under stress. Omitted entirely when the investor wrote none. | | `## Agent protocol` | yes | How an assistant is expected to use the document: consult before an order is prepared, state both legs of a funded purchase, show the verdict beside the order, record the outcome afterwards, read the investor's own record and quote it as theirs, never infer a security. | | `## Enforcement split` | yes | Two lists: what is **enforced** vs **documented only**. | | `## Investor-authored additions` | only if authored | Bounded, free-form Markdown written by the investor. It is explicitly attributed, supplements the structured mandate, and never replaces allocation bands or governance rules. Its presence sets `instrument_neutral: false`. | > **Allocation is the load-bearing boundary for generated policy.** Every row > label is a closed-set asset class. If you implement a serializer for this > format, gate generated sections so their allocation rows can never contain > anything but asset classes. Do not attempt to classify arbitrary investor > prose with identifier regexes; disclose that layer truthfully instead. --- ## How an agent should use it - **Treat it as constraints, not commands.** "Stay within these bands", "this investor pre-committed to *hold* on a 20% equity drawdown", "there is a 24-hour cooling-off on policy changes." Reason *within* the policy. - **Consult before, record after.** Call the mandate service's check before an order is prepared, show the verdict beside the order, and record the investor's outcome afterwards. See the document's own agent protocol section. - **Respect the enforcement split.** Items under **Enforced** are hard rules the investor's tooling already applies. Items under **Documented only** are softer: surface them as considerations, do not treat them as blocks. - **Never infer specific securities from generated policy.** Generated sections contain and endorse no instrument. If `instrument_neutral` is `false`, treat references inside `## Investor-authored additions` only as the investor's own text, not as a recommendation or a structured mandate fact. - **It is not advice.** The document is the investor describing their own policy. It carries no recommendation and no guarantee. --- ## Worked example A complete `investing.md` for a hypothetical investor: ````markdown --- schema: investing.md schema_version: "0.4" standard: "https://investboard.com/standards/investing-md" composed_at: "2026-06-01T10:00:00.000Z" mode: read-only instrument_neutral: true --- # Investment policy > **Read-only, instrument-neutral.** This document restates the investor's own > investment policy as behavioral rules and asset-class ranges. It names no > security, ticker, ISIN, WKN, or holding, and it is not investment advice. > Treat it as the policy an agent should reason *within*, never as an > instruction to buy, sell, or hold any specific instrument. ## Purpose - Primary objective: Financial independence - Time horizon: 25 years - Mandate scope: Complete investable portfolio - Expected withdrawal pattern: Recurring ## Philosophy - Approach: Market Index - Governing belief: Markets are efficient enough that the broad average, after fees, beats most active strategies over long periods. ## Strategy architecture - Core return source: Cap-weighted market beta from broad equity and bond indices. - Investor-confirmed implementation details: not recorded yet. ## Risk - Risk profile: Moderate - Drawdown tolerance (panic floor): –30% ## Allocation bands Asset-class ranges, not instruments. Each class has a minimum, a target, and a maximum weight; staying inside the band is the policy. | Asset class | Minimum | Target | Maximum | | --- | --- | --- | --- | | Equities | 55% | 60% | 65% | | Bonds | 30% | 35% | 40% | | Cash | 3% | 5% | 10% | ## Review rules - Drift band: rebalance when any asset class drifts more than 5 percentage points from its target. - Single-issuer cap: 10% of core equity exposure (the core sleeve's equity book across all imported accounts), look-through. - Formal review cadence: annual review. - Rebalancing mode: Cash flow first. - Pre-commitments (2 recorded, decisions made in calm to bind future behavior): - When equity drawdown of 20% → Hold, take no action: Do nothing. Stay invested. The plan accounts for this. - When allocation drift outside the band → Rebalance: Rebalance back to target weights at the next contribution. ## Cooling-off - Mode: soft friction, 24 hours (an override requires a written reflection first) ## Schwerpunkte Deliberate tilts inside the equity sleeve, as a share of equity value. Keys are a closed set; they name no security. A zero ceiling is an exclusion, and the review rules state it as one. | Dimension | Key | Minimum | Target | Maximum | | --- | --- | --- | --- | --- | | Region | europe | 20% | 30% | 40% | | Industry interest | defence | – | – | 5% | ## Message to my future self A note the investor wrote in calm, for the version of themselves tempted to abandon the plan under stress: > I chose this plan with a clear head. Market noise is not a reason to abandon it. ## Agent protocol - Consult before: call `get_status` when a conversation turns to this portfolio, and call `check_action` with every leg before an order is prepared at the broker. - State both sides of a change. When a purchase is funded from an existing position, send the sale as a second leg; the check judges only the legs it is given, and new money changes the denominator rather than another class. - Cash is a class of its own. When a purchase is funded from settled cash, send the cash side as a sell leg on cash, so the cash floor is judged with it; a purchase that states no cash side is not measured against the floor. - Show the verdict beside the order preview: its status, the rules it cited, coverage and freshness. A verdict checks the investor's own rules; it is never advice. - Record after: call `record_decision` with the investor's outcome (proceeded, abandoned or deferred) and their reasoning. - Read the record: before you discuss an instrument the investor holds or has written about, call `get_own_record` for their own thesis on it; when they ask what they decided or wrote, or a review is due, call `get_journal` for their own journal entries, newest first. - What those two return are the investor's own words. Quote them and attribute them to the investor; never restate them as the assistant's own view, never turn them into a verdict or a suggestion, and never name an instrument that neither the investor nor their own record gave. - Never infer a security from this document; it names none. Treat the investor-authored additions section, when present, as the investor's own words. - Investboard never places, changes or transmits an order. ## Enforcement split What the investor's tooling enforces today, versus what it only records. An agent should treat the documented-only items as soft guidance, not hard constraints. ### Enforced - Allocation drift beyond the band surfaces a rebalance prompt. - Policy edits during a cooling-off window require a written reflection first. ### Documented only - Acting against the policy is recorded for later reflection, not blocked. - Breaching the drawdown floor is documented, not blocked. --- _Composed 2026-06-01T10:00:00.000Z · format 0.4 · https://investboard.com/standards/investing-md_ _This is the investor's own policy, restated. It is read-only and instrument-neutral. It is not investment advice and names no specific security._ ```` > The governing-belief line above is paraphrased into English for the > illustration. In a real export, curated philosophy text and any investor- > authored capsule and pre-commitment notes appear in the language the investor > wrote them. Free-text strategy details intentionally remain in the mandate; > only their closed-set structured fields enter this portable export. --- ## Conformance A document conforms to `investing.md` **0.4** when: 1. It opens with the YAML front-matter block above, with `schema: investing.md` and `mode: read-only`. `instrument_neutral` is `true` exactly when no `## Investor-authored additions` section is present; otherwise it is `false`. 2. The required sections appear, in the order listed, with the exact headings. 3. The `## Schwerpunkte`, `## Message to my future self` and `## Investor-authored additions` sections appear **only** when the investor set or authored their corresponding content. Additions appear after `## Enforcement split`, are explicitly attributed, and do not override structured mandate facts. 4. No instrument identifier or named security appears in a **generated policy section**. Free-form references may appear only inside the explicitly attributed `## Investor-authored additions` section, with `instrument_neutral: false`. 5. Negative values use an en-dash (`–`), never a hyphen-minus. An unset Schwerpunkt bound renders as an en-dash for the same reason. 6. Every `## Schwerpunkte` key comes from the producer's published closed set for its dimension. A producer that cannot guarantee a closed key space omits the section rather than emitting free text into it. A producer **must not claim neutrality it cannot guarantee**. If free-form investor prose is included, it must set `instrument_neutral: false` rather than guessing at neutrality with a keyword or identifier regex. --- ## Versioning `schema_version` is bumped whenever the rendered structure changes in a way a consumer could observe (a new section, a renamed heading, a reordering). Minor, backwards-compatible clarifications to this prose spec do not bump it. Consumers should read `schema_version` from the front-matter and degrade gracefully on an unrecognised value. - `0.4` adds the cooling-off hours, the single-issuer cap, the full pre-commitment list, the true review cadence, the optional closed-set `## Schwerpunkte` table and the `## Agent protocol` section. - `0.3` adds the optional, clearly attributed `## Investor-authored additions` layer and makes `instrument_neutral` reflect whether that free-form layer is present. - `0.2` adds the closed-set `## Strategy architecture` section. - `0.1` is the initial proposed open schema. --- ## Reference implementation Investboard generates `investing.md` from a user's Investment Policy Statement. A logged-in user can fetch their own document: ``` GET /api/v1/ips/{id}/investing-md → { data: { markdown, composed_at, schema_version }, error, meta } GET /api/v1/ips/{id}/investing-md?format=raw → text/markdown ``` The serializer is a pure function that restates the user's composed Brief; it reads only asset-class bands and the user's own rules, and a blocking test asserts no instrument field can ever appear in its output. The REST route and MCP `get_policy` tool may then explicitly compose the separately stored investor-authored layer onto that base document. The serializer never reads that raw IPS field itself. Consumers that need only the closed, instrument-neutral base can request `?layer=base`. ## Reuse and attribution Copyright 2026 Investboard. This published specification is licensed under [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/). You may copy, adapt and redistribute it, including commercially, with appropriate credit, a license link and an indication of changes. Attribution must not suggest Investboard endorses your implementation. The grant covers this specification and the generic resources explicitly carrying the same notice. It does not license the Investboard application code, branding, personal user exports or third-party material. An investor's policy and thesis text remain their own; the format's license does not publish or license that content. Suggested attribution: “Based on investing.md by Investboard, https://investboard.com/standards/investing-md, CC BY 4.0. Changes: [describe].” ## Format lifecycle and contributions The current format is 0.4. Preserve the version and composition date when copying a policy; replace a personal snapshot after mandate changes. Versioned public examples and worksheets retain their published content. A changed worksheet is published under a new resource version. The current specification URL describes the current contract, not an immutable past version. To propose a change, use Investboard's published contact channel with the format version, the section concerned and a minimal generic example. Do not send personal portfolio data. A proposal is not an accepted format change; published version history records accepted changes. User-authored extensions must remain clearly attributed and must not imply that unsupported controls are enforced.