Fpa scaffold model

Skill JeffBrines/openfpa/skills/fpa-scaffold-model

The FP&A toolbelt for AI coding agents. Claude Code or Codex does the thinking; openfpa gives it a tested finance kernel, durable company memory, and a Karpathy inspired research loop that improves forecasts against your actuals. By Guiderail and Jeff Brines.

Install

npx -y skills add JeffBrines/openfpa --skill fpa-scaffold-model

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when building a new openfpa forecast model from a company's financials - a trial balance, a P&L export, or a pasted income statement - and you need a runnable config to exist before any forecasting or analysis.

SKILL.md

3.1 KB, as published. Nobody here has run it

Scaffold a Model (Phase 1)

Overview

Turn a company's financials into a runnable pyfpa config. Read the business profile first (see fpa-learn-business), infer the chart-of-accounts → model-line mapping, and write a validated EntityConfig YAML following openfpa conventions. Output a runnable skeleton plus an explicit list of assumptions to confirm.

Core principle: Convention over invention. Map the real numbers onto the existing engine shape; don't design a new one.

When to use

A trial balance / P&L (CSV, XLSX, or pasted) needs to become a forecast model
Onboarding follow-on after .fpa/business-profile.md exists

Workflow

Ingest the financials: pyfpa.read_pl_csv(path) (or a pyfpa.io.adapters source) → {account: amount}.
Map accounts to model lines of the EntityConfig schema:
- revenue accounts → channels[] (one Channel per channel/segment, with annual_revenue, a 12-month seasonality weight list, growth_rate, cogs_pct)
- cost accounts → opex[] as OpexLine(kind="fixed", monthly_amount=…) or kind="variable", pct_of_revenue=…
- debt → debt[] (term_loan with monthly_principal, or interest-only loc)
- balance-sheet rhythm → working_capital(dso_days, dpo_days, dio_days) and opening_balances
Write the company model and config under models/generated/. Validate config with pyfpa.load_config(path), which raises on any bad field.
Create a runnable command such as python3 models/generated/run_forecast.py. Keep the runner thin and make its output locations explicit.
Run and validate it. Confirm the model executes, reconciles its inputs, and writes the expected outputs.
Register the tested command with openfpa entrypoint-register, including its inputs and outputs. Registration publishes the command for agent discovery; it does not run it.
Surface assumptions: list the 6-10 inferences a human must confirm (seasonality shape, fixed vs variable splits, cogs_pct per channel, opening balances). Do not bury them.

Conventions (match the engine)

For a config-backed generated model, keep assumptions in validated YAML rather than scattering company numbers through code.
Set opening_balances AR/AP/inventory to the first forecast month's DSO/DPO/DIO-implied balances - the engine diffs each month against the prior, seeding month 1 against opening, so use month-1 projected revenue/COGS, NOT the annual average. Get this wrong and month-1 cash swings on a one-time artifact (see fpa-cfo-judgment working-capital seam).
"total" is a reserved channel/opex name (the engine adds a total column).

A live-formula Excel edition of the model is available via fpa-excel-model.

Runnable config confirmed → fpa-configure-actuals to wire live/real numbers, then the operate skills.