Impact Suite — Agents playbook

Give this URL to any AI assistant (Claude, Cursor, Codex, ChatGPT, Gemini, local tools). This is a skill-as-a-web-page: human-readable instructions plus a thin JSON API so an agent can draft a Proposal JSON document and have Impact Suite validate it and compute a transparent, sourced feasibility score — without clicking the UI.

When to use

• The user wants a feasibility proposal built or scored for a place, modelled on a proven global precedent (the "global-to-local" pattern).
• You can produce or edit a Proposal JSON (ProposalDocument) and need the engine to validate it and return a scored breakdown.
• The user asks you to "use Impact Suite", "score this proposal", or "run the feasibility engine".

Do not

• Do not invent a parallel schema. Use the existing Proposal JSON contract (same as the Studio editor).
• Do not compute the feasibility score yourself. The engine computes every number from your sourced scoringInputs; your job is to draft sourced, cited inputs, not to estimate scores.
• Do not cite a source you have not verified. Every scored number needs a real citation id.
• Do not treat the output as a bankable study — it is a desk-research feasibility signal over public, cited data.

What the engine does

Four sourced sub-scores (0–25 each → raw max 100), multiplied by a confidence factor derived from the number of disclosed data gaps (each gap −0.05, floored at 0.75). No sub-score is LLM-estimated. See /agents for the human page.

• Land & site readiness, Capital mobilization, Regulatory/institutional readiness, Demand & strategic fit.

Proposal JSON contract

Required top-level keys: ["meta","scoringInputs","disclosedGaps"]; optional ["datasetRows","citations","localConditions","problem","globalModelSection","tradeoffs","whatWouldNeedToBeTrue","limitations","changelog"]. A scored number is { value: number, confidence: 'official'|'press'|'proxy', citationIds: number[] }. Citation rule: Every scored input, and every official/press dataset row, must reference at least one citation id that exists in citations. The engine will not score uncited numbers.

Fetch the live template and a runnable example:

• GET /api/proposal/example?variant=empty — structural skeleton
• GET /api/proposal/example?variant=runnable — a filled example that scores 56.0/100
• GET /api/proposal/schema — field notes + empty template

Agent loop

1. GET instructions — /agents.md or GET /api/agents
2. GET example / schema — GET /api/proposal/example?variant=runnable
3. Draft Proposal JSON — fill scoringInputs with real, cited numbers and list disclosedGaps
4. POST validate — POST /api/proposal/validate → structural + citation check
5. POST run — POST /api/proposal/run → score (components + rationale + adjusted score)
6. Human review — return the Proposal JSON to the user to load in the Studio at /studio

Persistence

The API is stateless — nothing is stored server-side. To save, export the Proposal JSON from the Studio (/studio).

API reference

Base: same origin as this app. Content-Type: application/json.

Method	Path	Purpose
GET	/agents	Human playbook UI
GET	/agents.md	Raw markdown
GET	/api/agents	Instructions JSON or markdown (?format=markdown)
GET	/api/proposal/example	Empty or runnable Proposal JSON (`?variant=empty
GET	/api/proposal/schema	Schema notes + empty template
POST	/api/proposal/validate	Structural + citation validation → { ok, errors }
POST	/api/proposal/run	Stateless validate + score → { ok, score, ... }

Estimates over public, cited data only — not a bankable feasibility study.