cfa-managed-agent

CFA Managed Agent Tooling

You have access to the managed-agent cookbook tooling for CFA agents. All work happens in deterministic Rust in crates/corp-finance-core/src/managed_agent/. This skill describes the available surfaces — CLI, MCP tools, NAPI bindings — and when to use which. The skill itself contains no business rules; if you need to know what makes a cookbook valid, read the Rust source or call the validate tool.

Cost-tier discovery — before anything else

CFA cookbooks are tagged by cost tier so users can run the system without paying for any vendor data subscription:

Tier	Meaning
core_only	Runs against cfa-core MCP only. User supplies inputs as JSON. Always free.
freemium	cfa-core + free public data (FRED, EDGAR, FIGI, YF, WB, geopolitical) and/or FMP free tier. No paid subscription required.
paid_vendor	Requires LSEG, S&P Global, FactSet, Morningstar, Moody's, PitchBook, Aiera, or Daloopa subscription. User must supply credentials at deploy time.

To enumerate cookbooks by tier, prefer the MCP tool over scraping the registry:

managed_agent_list({ tier: "core_only" })   # 5 cookbooks
managed_agent_list({ tier: "freemium" })    # 8 cookbooks
managed_agent_list({ tier: "paid_vendor" }) # 2 cookbooks
managed_agent_list({})                      # all 15, grouped

For users on the free tier, never suggest a paid_vendor cookbook unless they've explicitly indicated they have the vendor credentials. The 13 non-paid cookbooks cover equity research, IB pitch / merger / LBO, PE deal screening / IC memo / LP audit, wealth planning, KYC, GL recon, model audit, and earnings analysis end-to-end.

MCP tools (preferred for in-conversation use)

All exposed by the cfa-core MCP server:

Tool	What it does
managed_agent_list	Enumerate cookbooks by cost tier. Registry-only, no I/O.
managed_agent_validate	Schema-validate one cookbook. Checks slug allowlist, agent.json shape, system prompt + skill + subagent path resolution, steering examples. Returns per-check pass/fail.
managed_agent_check_all	Walk every cookbook under cookbooks_root and validate each. Returns aggregate counts + per-cookbook outcome.
managed_agent_sync	Coverage audit between cookbooks and skills. Flags missing skills (referenced but not on disk) and orphan skills (on disk but unreferenced). Does NOT copy files — skills are resolved at deploy time in our pattern.
managed_agent_deploy	Assemble a deploy-ready JSON payload for one cookbook: ${VAR} substitution from env_vars, system-prompt inlining, skill resolution. Returns orchestrator + subagent + skill payloads. The consumer POSTs to /v1/agents.
managed_agent_orchestrate	Route a single handoff_request event to a target cookbook. Validates event type and target slug against the allowlist.

CLI (for shell / CI use)

cfa managed-agent list                          # all cookbooks
cfa managed-agent list --tier=core-only         # zero-dependency cookbooks
cfa managed-agent list --tier=freemium
cfa managed-agent list --tier=paid-vendor

cfa managed-agent validate <slug>               # one cookbook
cfa managed-agent check-all                     # every cookbook
cfa managed-agent sync                          # cookbook ↔ skill coverage
cfa managed-agent deploy <slug>                 # assembled JSON to stdout
cfa managed-agent orchestrate <slug>            # stdin event-loop router

scripts/test-cookbooks.sh runs validate + dry-run deploy on every cookbook (CI smoke harness).

When to use which surface

• In a conversation, picking a cookbook for a user: managed_agent_list MCP tool with the appropriate tier filter.
• Validating a cookbook the user just edited: managed_agent_validate MCP tool, or CLI cfa managed-agent validate <slug>.
• CI gate: scripts/test-cookbooks.sh.
• Programmatic deploy from a Node host: managedAgentDeploy(JSON.stringify(input)) via the NAPI binding directly (no MCP overhead).

Architecture invariant

There is one and only one source of truth for what a valid cookbook is: crates/corp-finance-core/src/managed_agent/validate.rs. The CLI, MCP tool, and NAPI binding are pure adapters. Do not duplicate validation rules in this skill, in cookbook READMEs, or anywhere else — call the validator.

Where the cookbooks live

• Cookbook source: managed-agent-cookbooks/<slug>/agent.json + subagents/*.json + steering-examples.json + README.md
• Skill referenced via from_skill: <slug> resolves to .claude/skills/<slug>/SKILL.md
• System prompt referenced via system.file resolves first to cookbook-relative, then to .claude/agents/cfa/<name>.md
• Allowlist + tier registry: crates/corp-finance-core/src/managed_agent/types.rs (COOKBOOK_REGISTRY + ALLOWED_SLUGS)

Skipped upstream items (and why)

• chronograph, egnyte vendor MCPs — closed-source vendor APIs we don't have keys for.
• MS Teams add-in installer — we are headless / CLI-only.

Skipped because they belonged in the rules engine, not here

The upstream Python tooling shipped validate-cookbook.py and check.py as separate scripts. Both fold into one Rust function (validate::validate_manifest) and one batched walker (validate::validate_all). If you find yourself wanting to add a new validation rule, add it to validate.rs and write a Rust unit test, not a markdown checklist.