@blackbelt-technology/pi-dashboard-cost-estimator

Estimate software cost and effort from use cases, functional and non-functional requirements, and a technology stack — then calibrate the model against what actually happened, using real pi session telemetry.

Ships three things:

1. A skill (.pi/skills/software-cost-estimator) — the workflow, references and rules the agent follows when producing an estimate.
2. A zero-dependency engine (src/engine/) — the arithmetic, so the numbers are reproducible and auditable rather than model-generated.
3. A dashboard plugin (src/client/, src/server/) — measured steering hours, agent cost and subscription leverage per project.

Why the split matters

The LLM does judgment: decomposing use cases, counting transactions, rating TCF/ECF factors, routing NFRs, classifying which work AI is actually good at.

The engine does arithmetic: UCP → COCOMO II scale → role distribution → four delivery modes → Monte Carlo → NPV.

That separation is what makes an estimate defensible to a client. Every number has a derivation someone can check.

Quick start

# estimate
node bin/estimate.mjs input.yaml --out ./out

# calibrate scope productivity from a delivered project
node bin/calibrate.mjs input.yaml --actual-days 479 --exclude-contingency

# calibrate agent cost + steering time from real session telemetry
node bin/calibrate-sessions.mjs --plans
node bin/calibrate-sessions.mjs --plan anthropic-max-20x --seats 2
node bin/calibrate-sessions.mjs --project my-repo --actual-days 120

Outputs: estimate-report.md, delivery-mode-comparison.md, business-case.md, estimate.xlsx.

The four delivery modes

| Mode | Who writes the code | |---|---| | human_only | People, no assistance | | human_with_ai | People with inline assistance | | ai_steered_human_supervised | Agents, steered and reviewed by a person | | agentic_hitl | Agents, with human-in-the-loop oversight at an intensity level |

AI compresses build effort only (~60% of a project). PM, client iteration, compliance, manual QA and security sign-off do not shrink because a model writes the code. That single constraint is why "AI is 10× faster" collapses into single-digit project savings.

Cost basis: subscription vs metered

Session logs record a metered API-price computation. Most teams do not pay that — they buy flat seat plans. The two bases have different shapes:

| | Metered | Subscription | |---|---|---| | Cost scales with | work volume | seats × calendar months | | Marginal cost of more agent use | linear | zero, until quota | | Overrun risk lands on | cost | schedule (throttling) |

So under a subscription, schedule is a cost driver and quota exhaustion is a schedule risk, not a cost overrun. Set ai.cost_basis: subscription and list your seat plans.

Leverage (meter-equivalent ÷ seat cost) is reported as leverage — never as a saving passed to a client. It is on-demand value the flat plan captured, not a discount.

Dependency split (load-bearing)

| Layer | Dependencies | |---|---| | src/engine/ | none — hand-rolled YAML parser, Monte Carlo, XLSX writer | | src/telemetry/ | pi-dashboard-shared, pi-dashboard-session-distiller |

The engine must run in any project with no dashboard installed. Only the telemetry adapter touches the session store, and it reads through the dashboard's own readers so a session-schema change lands in one place. If engine code imports from telemetry/, portability is gone.

Dashboard plugin

| Slot | Component | Purpose | |---|---|---| | command-route | CostView | cost command → steering hours, meter-equivalent, actual subscription cost, leverage, per-project table | | settings-section | CostSettings | Seat plan, seat count, break threshold |

Server route: GET /api/cost-estimator/telemetry (read-only, 60s cache).

No content-view claim. forSession() keeps every predicate-less claim, so an unpredicated content-view claim replaces ChatView for every session, always, with no chrome to dismiss it. CostView is a global report — the cost command-route is its entry point.

Tests

npx vitest run packages/cost-estimator    # from the monorepo root

43 tests covering the published formulas (Karner's worked example, COCOMO II.2000 constants, Beta-PERT), the NFR double-counting guard, the correlated-risk shape, the subscription cost basis, and the gap-capping rule.

License

MIT