Financial Modeling as a Multi-Agent Orchestration

1. The Goal — One Surface, Three Data Streams, Audit-Trail Grade

DC CAP needed one surface that combined three live data streams into a single overarching view of the organization's financial position — current state and projected through FY35. The job was to make financial visibility a core function, refreshed between Board meetings, with cell-by-cell provenance on every value the Investment Committee, the Finance Committee, or the Board would see.

The three data streams the model brings together

Combining three streams of this shape — three refresh cadences, three source systems, three sets of business rules — into a single audit-trail-grade surface is what ruled out Stage 1 (a prompt cannot survive Investment Committee scrutiny) and ruled out Stage 2 (a skill is reusable and still falls short of multi-step workflows with files and gates). Stage 3 (a Project) got close: system instructions, reference files, governance config, workflow doc. The moment all three streams had to reconcile inside the same model in the same conversation, the architecture had to move up one more rung.

2. The Iteration Arc — One Question to Eleven Agents

The build did not arrive fully formed. A lot changed along the way, and the discipline that made the changes survive was not the model — it was the spec that the designer kept rewriting.

The model identity — visibility into what we see, what we owe, what we control

The job was to get the financial picture right and put it in front of the people making the decisions. That meant designing the model around three views:

• The costs that exist. What DC CAP actually spends today, by program and by category, across the full operating arc.
• What we are committed to. Multi-year scholarship pledges, lease obligations, vendor contracts. The part of the cost base that does not move inside one budget cycle.
• What we can control or cut. Discretionary spend, programmatic decisions, the choices the SLT and the Board actually face between Investment Committee meetings.

That three-way visibility feeds three strategic surfaces, each answering a different question from the same audit trail:

• Development. How much do we need to raise? The operating-gap surface answers by source (individual, corporate, philanthropic), by quarter, with confidence bands.
• Finance. How much will the endowment draw be? The model identity returns the implied draw directly:

endowmentDraw = max(0, totalExpenses − operatingRevenue)

• Implied draw is what the model produces. Each Pathstone market refresh moves the FY27–FY35 draw curve in audit-traceable steps.
• Operating. What can we cut, hold back, or defer? The committed-vs-controllable split is the input to the conversation Eric and the SLT have during each budget cycle.

The same numbers, the same audit trail, three surfaces each answering its own question.

The four verification layers

Verification went through four layers, each catching a different failure mode the prior layer missed:

The roster rewrite

Agent specs were rewritten three times. The first roster had a governance-heavy Tier 1 (BoardSource, CFA IPS, NACUBO Spending Policy, NFF). The current roster has an insight-and-analytics Tier 1 (Damodaran, Tufte, Knaflic, Hyndman, McKinsey Valuation, Bridgespan, Few, NACUBO NCSE 2024, AFP). The lesson the rewrite carried: the tool is a strategic analytics surface first, a compliance surface second. The governance references stayed, moved to Tier 2.

3. The Roles — Eleven Opus Agents, One Job Each

Stage 4 means the work is too big for one role. The dispatch protocol splits it into eleven, each with one job and an explicit handoff to the next.

Each output a Builder agent produces has a state contract the next agent reads. The Lead never overwrites; the Lead routes. That single rule — Lead routes, never edits — is what keeps the audit trail intact when seven lanes run in parallel.

4. Instructions vs Reference Files — Where the Rules Live

Each agent ships with a short, prescriptive instructions block (under 600 lines) and loads reference files at session start. The split was deliberate:

• Instructions hold the durable spec. Role, voice, format, the rules that should hold across every conversation, the failure-mode map, the handoff protocol. These do not change between runs.
• Reference files hold the world the rules apply to. The Finance + Development workbook anchors, the ADR registry, the FY27 raise targets, the named donors per segment, the verified outcomes. These refresh on a known cadence.

The boundary was tested. The first version of fpa-data-engineer tried to encode the workbook structure inside the instructions. Every refresh required an instructions edit. Moving the anchors to a reference file the L2 parser hard-gate reads cut maintenance from "every refresh" to "every quarterly restructure." Same expertise; different home.

5. The Skill Chain — Three Layers, Loaded on Demand

Each agent loads named skills at session start. The skills live at three layers, and the dispatch protocol controls which layer loads on which agent.

Naming the chain at design time is what makes the orchestration inheritable. A future analyst picking up the build sees, in one place, exactly which expertise is loaded. Each chained skill is one piece of expertise the build no longer has to invent.

What a single SKILL.md actually contains

Zooming in on one piece of the chain — every skill the agents load is one folder with one canonical file. The shape is the same whether the skill carries five lines of voice rules or 500 lines of financial-modeling methodology.

my-skill/
├── SKILL.md          ← required: frontmatter + body
│   ├── ---           ← YAML frontmatter
│   │   name: my-skill
│   │   description: <what it does> + <when to trigger>.
│   │   ---
│   └── <imperative instructions, under 500 lines>
├── scripts/          ← deterministic code (optional)
├── references/       ← docs loaded on demand (optional)
└── assets/           ← templates and files for output

The frontmatter is the trigger surface. Claude reads name + description from every available skill and decides which ones to consult based on what the user asked for. The body is loaded only after the trigger fires. The bundled resources are loaded only when the body says to read them. That is progressive disclosure — three levels of loading, each gated by the level above it.

How skills relate to agents — composable by design

The exact loadings from the financial_modeling agent specs (verified against the SKILL and Expertise Specification section of each agent's frontmatter file):

• One agent loads many skills. fpa-storyteller loads four BRAIN skills — preston-writing (voice), dc-cap-org-intelligence (verified facts + framing rules), executive-summary-formatter (board-memo structure), funder-framing (funder-type-specific voice) — plus the Tier-1 references knaflic_storytelling_with_data, damodaran_valuation_storytelling, bridgespan_nonprofit_strategic_finance, and the Tier-2 boardsource_finance_committee when the artifact is bound for Finance Committee. Each contributes one piece of expertise. None of them know about each other.
• One skill is loaded by many agents. dccap-brand loads inside both fpa-frontend (brand-token application in React + Recharts components) and fpa-viz (brand-token discipline on chart specs). Same SKILL.md, two different lanes, no duplication. funder-framing follows the same pattern — loaded by fpa-strategist for funder-ask context and by fpa-storyteller for funder narratives.
• The agent decides whether to consult a skill. Skills appear in the agent's available skills list. The agent reads the descriptions and decides which to load for the current task. Bad description, missed trigger. Pushy description with concrete user-phrase examples, reliable trigger.

The canonical guidance for what makes a good SKILL.md lives in the skill-creator skill itself — the Anthropic-authored skill for creating skills. Load it whenever you start a new Skill build. Most of the rules in this section are pulled from there: under-500-line body, pushy description, progressive disclosure across three loading levels.

6. Tools and Permissions — The Smallest Set That Runs

The build runs with a deliberately small tool surface. File read, file write (scoped to the project directory), and code execution (R + Python, scoped to the parser and quant lanes). No web access at runtime. No email. No external API calls during a model run.

Web access lives on the design side. The run side stays sealed. New ADRs and reference updates happen between runs, in the open. The audit trail stays reproducible — if the same workbook goes in, the same surfaces come out.

• Worst case if a tool fires incorrectly? Cosmetic drift in a chart (caught at viz lane review), or a parser refusal (caught at L2 hard-gate). No catastrophic failure paths are reachable from the runtime tool set.
• Who catches it? The verification gates between layers. Each gate sits between two named agents and has a written pass criterion.

7. Verification — Four Layers, One Audit Trail

The four verification layers (L1–L4) are the spine of the audit trail. They run automatically; nothing ships to a Board surface unless all four pass.

How the layers compose

1. L1 source-cell provenance runs at parser intake. Each value gets a {sheet, cell, value, last_seen} tag. Values without tags are dropped.
2. L2 parser hard-gate runs immediately after. The parser refuses to proceed if any anchor, sheet name, or row label has drifted from the contract. The lane that catches a refusal here is fpa-data-engineer, which logs the structural drift and pings fpa-lead for routing.
3. L3 runtime cross-foots runs inside fpa-quant. Computed totals cross-foot against the workbook's own totals at the runtime layer. Mismatches halt the lane.
4. L4 defaults alignment runs before any surface renders. Default raise targets and market scenarios reconcile against the IC-approved set. The Lead consolidates the L4 result and decides whether to publish.

At the most recent build, all four layers passed 53/53 checks green. The number is itself a verification artifact — a missed check is a routing signal that halts the lane and pings fpa-lead for triage.

The failure-mode map

Each agent ships with cosmetic / costly / catastrophic failure modes named in its own instructions. Examples from fpa-storyteller:

• Cosmetic: Big Idea ends with a forbidden construction. Caught at light gate by the storyteller's self-audit checklist.
• Costly: Number cited without provenance pull from L1. Caught at standard gate by fpa-lead consolidation.
• Catastrophic: Named donor segment cited with an unverified expected close date. Caught at full gate before Board surface renders.

8. How the Orchestration Runs End-to-End

A request lands at fpa-lead. The Lead dispatches lanes in parallel where dependencies allow, sequentially where they do not. Each lane writes to its own state file. The Lead consolidates. The Output Verification protocol runs before anything ships.

The FY27 revenue-walk request — a worked dispatch

The Lead dispatches to fpa-data-engineer first to reconcile the three streams at intake: development raise targets (individual, corporate, philanthropic), finance historical-and-projected actuals, and the most recent Pathstone market projection set. Once L1 + L2 pass on all three, fpa-quant runs the math layer with L3 cross-foots — the endowment draw recomputes from the Pathstone bands, the operating gap recomputes from finance + development. In parallel, fpa-insight-hunter runs the Pareto and bias diagnostic on the cleaned data. fpa-storyteller reads both lanes and writes the Big Idea in Preston's voice. fpa-frontend publishes to the live surface after L4 defaults alignment. The Lead writes the consolidated audit trail.

Iteration cadence and governance line

• Verification cadence: L1–L4 gates run automatically on every build. Standard gate for internal surfaces; full gate (including fpa-lead consolidation review) before any Board, Investment Committee, or Finance Committee surface renders.
• Iteration cadence: ADRs revisit quarterly. Reference updates whenever a new canonical source lands. Agent specs revisited at each major data refresh or when a new failure mode surfaces downstream.
• Governance line: Tier 3 (internal strategy) for the working surface; Tier 2 (sensitive operational) for the Board-facing artifacts. Live behind Cloudflare Access at dccapinnovation.org/financial_modeling/. Escalation path: fpa-lead → designer (Preston) → Finance / IC chair.