openfpa AGENTS.md

openfpa Agent Operating Contract

openfpa is an agent-native FP&A workbench, not a fixed application. The goal is to help an AI build the finance system that fits one company while preserving a small, trustworthy accounting kernel.

Architecture

• pyfpa/ is the stable kernel: schemas, accounting mechanics, reconciliation, scoring, persistence contracts, and reusable analysis helpers.
• .fpa/ is company memory: business context, sources, mappings, corrections, forecasts, experiments, decisions, and accepted learnings.
• Company-specific code belongs in visible generated namespaces such as models/generated/, connectors/generated/, skills/generated/, and agents/generated/.
• Do not force a business into EntityConfig when its economics require a different model. Extend the company workspace and use the kernel where useful.

Company Onboarding

• Trigger onboarding when .fpa/intake.md is incomplete and the user asks to build, configure, forecast, analyze, or learn the business.
• Do not force onboarding for a narrow task that can be completed independently.
• Use the machine-oriented CLI as the default workspace control surface:
  • openfpa status <company-root>
  • openfpa init <company-root> --business-name "<name>" when uninitialized
  • openfpa inspect-data <data-root> for each user-supplied data location
  • openfpa source-profile <company-root> --file <source-file> before mapping
  • openfpa source-register <company-root> ... for each relied-on source
  • openfpa source-list <company-root> before source-dependent work
  • openfpa mapping-register <company-root> ... for each exact mapping
  • openfpa mapping-list <company-root> --source-id <source-id> before modeling
  • openfpa reconcile-source <company-root> ... before using mapped totals
  • openfpa connector-list <company-root> before generating recurring access
  • openfpa connector-scaffold <company-root> ... from a redacted fixture
  • openfpa connector-validate <company-root> --name <name> after connector edits
  • openfpa intake-next <company-root> before asking intake questions
  • openfpa intake-record <company-root> ... for each established fact
  • openfpa entrypoint-list <company-root> before generated workflows
  • openfpa entrypoint-register <company-root> ... after validating a command
  • openfpa doctor <company-root> before relying on workspace state
  • openfpa correction-record <company-root> --slug <slug> --type <type> --target <target> --date <date> after establishing a correction
  • openfpa correction-list <company-root> to review recorded corrections
  • openfpa scorecard-render <company-root> to rebuild scorecard.md from all snapshots
  • openfpa experiment-list <company-root> to review experiment records
  • openfpa context-pack <company-root> --task "<task>" to retrieve bounded memory for a task
  • openfpa onboarding-render <company-root> --proposal-summary "<summary>" when intake is ready
• The CLI emits JSON and performs deterministic workspace operations. Read its output as evidence; do not treat it as the reasoning engine.
• If the console script is unavailable in a source checkout, use python3 -m pyfpa.cli with the same arguments.
• Inspect supplied local files before asking questions. Do not access external systems or connectors without user approval.
• Register every source used by a model with its entity, currency, periods, extraction method, and location. A file existing in the workspace is not sufficient lineage.
• Persist exact mappings, including deliberate ignores with rationale. Never infer an unmapped account into a model silently.
• Run openfpa reconcile-source for compatible account-amount CSV sources. For richer sources, build an equivalent tested reconciliation and register its command as an entrypoint.
• Generate a connector only when recurring access is useful and the architecture is approved. One-time local files do not need connector code.
• Scaffold connectors from explicit redacted fixtures only. Never copy a production export into connectors/generated/ without confirming it is safe to commit.
• Treat connector-validate as a fixture-mode contract test. It must not access a live system. Implement live extraction separately using host-managed credentials, then register the tested recurring command as an entrypoint.
• Record source-derived and user-confirmed facts with citations and confidence using openfpa intake-record.
• Ask only unresolved questions returned by pyfpa.next_intake_questions, in rounds of at most three related questions.
• Record direct user answers immediately as confirmed facts. Ask for confirmation only when evidence conflicts or confidence is low.
• When pyfpa.intake_ready is true, write the business profile and .fpa/decisions/initial-model-architecture.md with pyfpa.write_onboarding_outputs.
• Stop before scaffolding connectors, models, skills, or agents until the user approves the architecture proposal.
• After a generated workflow has a tested command, register it in .fpa/models/entrypoints.yaml. Registration advertises the command but does not execute it.