A phase-based agent system for high-stakes spreadsheet-centric workflows.
This repo exists because single-session AI workflows were fast but unreliable for executive-grade analytical work. They could produce polished outputs that skipped edge cases, approximated math, trusted assumptions they should have challenged, or effectively self-approved their own mistakes.
The current proving ground is M&A execution. A seller's advisor sends a forecast model, the acquirer's team must interrogate it, build their own layer on top, calibrate assumptions from customer data when available, audit everything independently, and deliver a leadership-ready package under deal-speed timelines. The underlying idea is broader than M&A: reliability improves when questioning, building, and auditing are separated into different phases with explicit handoffs and human gates.
┌─────────────────────────────────────────────────────────┐
│ Human Operator / Deal Lead │
│ (current deployment: Corp Dev, gatekeeper at │
│ every approval point) │
└────────────┬──────────────┬──────────────┬──────────────┘
│ │ │
┌──────▼──────┐ ┌────▼─────┐ ┌──────▼──────┐
│ Planner │ │ Builder │ │ Auditor │
│ (Phase 0) │ │(Phase 1) │ │ (Phase 3) │
│ Questions │ │Constructs│ │Finds faults │
│ everything │ │the model │ │adversarially│
└─────────────┘ └──────────┘ └─────────────┘
Three cognitive modes. Separate sessions. Human as router.
- Phase 0 — Interrogation (Auditor mode): Structural mapping, assumption deep dive, risk register. Self-contained — does not need the Model Spec.
- Phase 0.5 — Customer Cube Analysis (conditional): Segmentation, retention curves, unit economics derivation from raw customer data.
- Phase 1 — Acquirer Layer Build (Builder mode): Control_Toggle → Synergy_Waterfall → Integration_Costs → EVP_PL → DCF. Full acquisition model.
- Phase 2 — Charting & IC Deck (outside current release): Chart PNGs + PPTX assembly.
- Phase 3 — Audit & Delivery (Adversarial mode): Two-tier audit — continuous (every iteration) + terminal (formula, structural, calibration, narrative).
Even though the current deployment is acquisition modeling, the repo is really a worked example of agent reliability architecture:
- Cognitive mode separation keeps generation and validation out of the same context window.
- Structured handoffs turn chat sessions into a persistent operating memory instead of relying on implicit context.
- Human approval gates prevent agents from silently self-approving leadership-facing output.
- Locked decisions with provenance convert painful failures into explicit policy that future sessions can inherit.
- Synthetic validation and eval harnesses turn hard-won lessons into regression checks instead of tribal memory.
If you want to evaluate the system quickly, start with the repo-owned proof artifacts:
- Synthetic dry run:
python3 tools/run_synthetic_validation.py - Safe end-to-end rehearsal pack:
examples/synthetic_deal/ - Visual workflow demo:
examples/demo_walkthrough/(seedocs/RUN_DEMO_LOCALLY.md)
From seller data + deal thesis, the current M&A implementation builds:
- Full acquisition model (Excel): Dynamic_Time, Control_Toggle, Calibration, Revenue Engine, Synergy_Waterfall, Integration_Costs, Detailed_PL, BU Impact output, DCF, UE Dashboard
- Risk register with deal-specific flags
- Numbered handoff docs carrying context between phases
- Audit trail with formula verification and structural checks
| Principle | Why It Matters |
|---|---|
| Cognitive mode separation | Builder agents trust; auditor agents question. Never mix in one session. |
| Locked decisions | 66+ design decisions with provenance, rationale, and lessons learned. Prevent regression and preserve hard-won judgment. |
| Numbered handoffs | Context travels between sessions via structured docs, not memory. |
| Read-only audit | Phase 3 never edits the model — it flags issues for the human to resolve. |
| Human-in-the-loop | Every phase gate requires explicit human approval. Agents cannot self-approve. |
| Compounding feedback loop | Retrospectives, lessons-learned issues, and changelog-driven refinement feed new failure patterns back into the system. |
| Eval-backed refinement | Synthetic validation, holdout tests, and Phase 0.5 eval harnesses catch regressions before release. |
The current implementation handles acquisition targets across economic archetypes:
| Archetype | Depth | Notes |
|---|---|---|
| SaaS / Subscription | Deep | Full synergy waterfall, retention modeling, cross-sell engine |
| Payments / Interchange | Deep | Take rate modeling, TPV-based revenue, multi-product attach |
| Deposits / Banking | Deep | NIM modeling, balance-based revenue, regulatory considerations |
| Lending / Credit | Starter | Extensible — contributions welcome |
| Marketplace / Platform | Starter | Extensible — contributions welcome |
| Ad / Lead-Gen | Starter | Extensible — contributions welcome |
A single target can span multiple archetypes. The Planner identifies which apply during deal intake.
Open the repo in Claude Code or Cursor, or upload a tested snapshot to Claude.ai. See QUICKSTART.md for the step-by-step operational guide and tool-specific setup paths.
Quick validation (no deal data needed):
python3 tools/run_synthetic_validation.pyThis runs the full test suite, synthetic deal flow, Phase 0.5 eval harness, and demo build path.
| Path | Purpose |
|---|---|
instructions/ |
Dispatch-ready instruction docs for each phase agent |
planner_skill/ |
Master orchestration skill + reference files |
spec/model_spec_v1.md |
Reference architecture — tab structure, conventions, business type modules |
tools/ |
Python pipeline tools (Phase 0, Phase 0.5, shared utilities) |
tests/ |
pytest suite — unit tests + generalization holdout set |
templates/ |
Blank-fillable handoffs, risk registers, dispatch packages |
examples/ |
Synthetic deal pack for safe workflow rehearsal |
- 173+ tests (unit + generalization holdout)
- 66 locked decisions with provenance
- 6 economic archetypes (3 deep, 3 starter)
- Applied to live deal workflows and synthetic validation packs
Works with Claude Code, Cursor, or Claude.ai (via uploaded snapshot). See QUICKSTART.md for setup instructions per tool.
The framework gets stronger with every deal and every piece of input:
- Share strong workflows or models — especially Lending, Marketplace, and Ad/Lead-Gen archetypes
- Share domain knowledge — each archetype has its own modeling patterns
- Flag what's missing — see How to Give Feedback
BSL 1.1 — free for non-production use. Commercial use requires a separate license. Converts to Apache 2.0 after 3 years.
Current: v1.3.23 (2026-03-30). See CHANGELOG.md for full history.