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) ```bash 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.