beam-ai-team/proposal-creation

Proposal Creation (Engagement Proposal engine, v3)

Produces a board-quality, CFO-grade Phase 1 Engagement Proposal: the deep commercial + technical document a customer can read on its own and take to their board. Built on the design system a real customer signed off on (Saudi Paper Manufacturing Co., Tadawul 2300 — the canonical example in examples/).

Safety Contract

Before creating project files, editing account config, rendering PDFs, or drafting commercial terms, show the account, project path, value/pricing assumptions, output artifacts, and confidential customer context included. Require explicit user approval in the current turn before writing files, rendering customer artifacts, or preparing external-send drafts. Do not send proposals or update CRM from this skill.

Where this sits (the three gates)

| Gate | Artifact | Skill | |---|---|---| | 1 | Operating Diagnostic — "you understand our operation", no pricing | operating-diagnostic | | 2 | Capability statement | — | | 3 | Engagement Proposal — "here is the deal": value, architecture, team, proof, terms | this skill |

This is the priced Gate-3 artifact. It combines gates 1–3 when needed, but its job is to earn the signature: it shows the value at stake, derives every figure, proves the platform in production, and lays out gated pay-as-proven terms.

Triggers

• "build a proposal for [account]" / "build an engagement proposal for [account]"
• "commercial proposal" / "SOW proposal" / "priced proposal for [account]"
• "/proposal [account]"

What it produces (~34 pages, overflow-clean, A4 light-theme PDF)

Part 0 exec brief · Part 1 value at stake + operating map + ROI-vs-complexity · Part 2 line-by-line value derivation · Part 3 architecture, autonomy/governance, dedicated in-region deployment + security · Part 4 delivery lifecycle, delivery ops, the team, production proof + in-depth case studies, why-Beam · Part 5 one-page summary, license, investment, roadmap, terms (pricing only at the end) · Annexes A process register, B anchor deep-dives, C Scope of Work, D service levels, E security answer bank.

Architecture — engine vs. account (read this first)

The skill is self-contained (fonts, logos, team photos, case logos all bundled in assets/). Two layers:

• Engine (fixed, Beam-canonical — never edit per deal): scripts/render_handbook.py (CSS/brand), scripts/render_diagnostic.py (light theme), plus the canonical pages in render_proposal.py: the team, the 6 case studies + Volkswagen, platform architecture, autonomy/governance, security, delivery lifecycle, delivery ops, why-Beam, the SLA annex and security annex. These are the same every deal.
• Account config (scripts/account.py) — the per-deal file: identity (company, legal name, listing, preparer, date, doc title/version), currency, the WORKFLOWS value table, all pricing + SAR_* display figures, and the headline economics (receivables, DSO, cost of funds, EV multiple). Copy templates/account.template.py → scripts/account.py and fill it.
• Bespoke analytical content — tailored in render_proposal.py (see the checklist below). This is the operating-map layout, the process register, the ROI matrix, the value derivation, and the "maps to <you>" lines. It is genuinely deal-specific and edited by hand, exactly like a real analyst would.

Workflow

1. Create/locate the project

Each account = its own project under 03-projects/XX-<account-slug>/. Never mingle accounts.

2. Research (match the depth of the canonical example)

Entity tree, systems (ERP), the back-office processes, volumes, the receivables/DSO picture, listing + multiple. Pull from the Operating Diagnostic if one was run. The value model must be sized against the customer's own figures, and stated as validated-in-discovery.

3. Fill scripts/account.py

Copy templates/account.template.py. Fill identity, currency, WORKFLOWS (6–8 Phase-1 workflows with build + annual value + the lever), pricing, SAR_* display figures, and the economics block. Keep everything conservative.

4. Tailor the bespoke pages in render_proposal.py

Work through the PER-ACCOUNT TAILORING CHECKLIST below. Everything not listed there is Beam-canonical and stays untouched.

5. Render

cd scripts
python3 render_proposal.py --pdf     # writes to ../output/<Company>-<Doc-Title>-<version>.{html,pdf}

6. QA (mandatory — see checklist)

python3 check_overflow.py ../output/<...>.html   # must report clean

Then run the content QA (AVOID list, em-dashes, figures reconcile). Screenshot key pages with pdftoppm and read them.

7. Save the example

Copy the filled account.py + rendered PDF into examples/<account-slug>/ for the record.

---

PER-ACCOUNT TAILORING CHECKLIST (render_proposal.py)

Config (account.py) drives identity + all commercial numbers automatically. These pages contain deal-specific analytical content or prose that you edit by hand:

• exec_brief — the one-paragraph operation narrative + "what Phase 1 is" (the three suites) + "why safe to start".
• operating_map_page — the hub-and-spoke SVG: the four cluster hubs, the process cards (coordinates + code + name + value + AUTO/P2/KEEP), and the centre value figure. Hand-laid per operation.
• roi_matrix_page — the ROI-vs-complexity placement of each workflow.
• value_how_page / value_buildup_ap_page / value_buildup_ar_page / value_derivation_page — the line-by-line value arithmetic and the receivables build-up (value AR as a suite, counted once; the per-agent split is an allocation "by primary driver", never an independently-derived line).
• tech_deployment_security_page — the in-region deployment naming (cloud region/provider) and the "isolated to <company>" language.
• annex_register_page — the process register (the processes, phase tags, priority/complexity).
• annex_deepdive_page — the anchor-process decision-logic deep-dives + the facts table (revenue, EV multiple, DSO, etc.).
• annex_sow_page — the Scope of Work specifics (suites, Definition of Done gates, volumes).
• Reused commercial pages (in render_pages.py): license_page module split, roadmap_page Phase 2/3 scope + pricing, terms_page milestone amounts, and the value_page "where the value sits" bullets.
• Case-study "maps to <you>" lines — each case's relevance / maps string references the account; update the mapping to the account's processes. The cases themselves (Americana, Zurich, BID-Coburg, Porsche, Fraisa, Forvia, VW) are fixed Beam proof — do not invent customers.

Fixed — never edit per deal: team_page, leadership_page, the CASES structure + case pages, proof_page, tech_architecture_page, tech_autonomy_page, delivery_lifecycle_page, delivery_ops_page, why_beam_page (except the one company-name mention), annex_sla_page, annex_security_page.

---

QA checklist (before it leaves)

• Overflow: check_overflow.py reports clean on every page.
• Figures reconcile: the suite sums equal the Phase-1 total; Year-1 = build + setup + prorated license; the value table totals match the headline.
• Conservative value: DSO improvement is banked at a conservative slice (e.g. 15 of 37 days), the rest framed as upside; value AR as a suite counted once; exclude new revenue (cost + cash only).
• AVOID list: no IBM/Cisco unless the proposal is explicitly partner-fronted; no "Sven", no HIPAA (unless healthcare), no Oakberry/Bosch/Crepa as references; accuracy claims show upside only (95%+/99%+), not gate numbers; no over-owning the working-capital / EV upside.
• No em dashes in prose — use commas/colons/periods. (Em dashes are fine only as title separators, e.g. "Annex A — …".)
• Names mirror the source's spelling exactly.
• Pricing reads firm at the commercial end (the engine's _firm() strips the "~" on license/investment/terms pages; value pages keep "~").

Canonical example

examples/saudi-paper-group-v3.0/ — the filled account.py and the rendered 34-page PDF that was sent to the CFO. Use it as the fidelity bar.

Related skills

• operating-diagnostic — the Gate-1 artifact this follows (no pricing; one hero cost-of-current-operation number).
• contract-creation / scope-of-work-creation — the binding contract pack (Master + SOW + DPA) that follows a signed-off proposal.

---

The previous lightweight beam_pdf-based generator is archived at scripts/generate_proposal_pdf.py.legacy.