Build Demo

Build Demo

A demo is a persuasion instrument aimed at a specific reviewer reading a specific solicitation. Its job is to prove we move fast, in alignment, on their stated requirements. Decoration serves nobody. Every step below exists to keep the demo unmistakably connected to source language.

Model Tiering

Two tiers of model share this workflow. Do not hardcode model names; resolve the current lineup each time:

• Top model (most capable available, tokens permitting): the demo fit decision (Step 1 judgment), the demo plan (Step 3), and all buyer-facing communication guidance (Step 5).
• Second-tier model (cost-effective): the deep recon reading in Step 1, and the build/test/deploy execution in Step 4.

The lesser model reads deeply and builds; the top model judges, plans, and writes the words a reviewer will feel.

The Five Steps

Step 1: Decide whether a demo makes sense at all

Evaluate the source material (usually an RFP/RFQ) from the reviewer's point of view before anything is built. A demo that does not fit the requirement in an obvious way is harmful rather than neutral: it demonstrates being out of touch with the source and a willingness to spend resources in the wrong direction. Reviewers score that against us.

• Run a deep buyer-and-solicitation reconnaissance pass on a second-tier model; pass its handoff to the top model, which makes the go/no-go call.
• No-go signals: general-purpose staff augmentation with no defined scope; pure commodity pricing competitions; solicitations where nothing concrete could be demonstrated; anything where a demo would read as answering a question nobody asked.
• Constraint, rather than kill, signals: language warning against elaborate, expensive, or fancy submissions constrains the demo without automatically killing it. In that case the demo must differentiate on demonstrated ability rather than visuals: restrained presentation, capability-dense content, and proposal framing that explicitly respects the warning.
• Record the decision and its source-quoted rationale. "No demo" is a complete, successful outcome of this skill.

Step 2: Extract the verbatim guiding-light document

Select verbatim source text into one document that governs everything downstream: exact evaluation criteria and factor language, the load-bearing requirement sentences, Q&A answers that shape scope, page/format/content constraints on the quote itself, and every mention of the buyer's existing systems and software estate. Cite file and location for each quote. Do not paraphrase; the point is that demo copy and proposal framing can later be traced word-for-word to source. Every screen, interaction, and caption built later must map to a line in this document; anything that maps to nothing gets cut.

Step 3: Plan the demo (top model)

Write the plan before any code:

• Define the few journeys that prove fast movement in alignment with the requirements: the journeys evaluators explicitly named, nothing else. Do not pad with unrelated features.
• Plan one or two screenshots as the primary communication artifact: decide up front which screens will be captured, what each must show, and design those screens to read clearly at print size. A screen that only works interactively is a poor screenshot candidate.
• Design restraint: never overwhelming, clearly connected to real requirements, buyer language preserved without impersonating the buyer or inventing endorsements. Make the first screen the usable experience rather than a marketing explanation.
• Enclave framing is mandatory. When the buyer has existing software the work would build on, the demo and every word about it must make clear we know that estate exists and are proposing nothing like a rebuild. The demo is an enclave: a bounded, deliberately separate environment that demonstrates fast movement and specific capability. Never let a reviewer wonder whether we think we're building from scratch.
• Map each planned element to its guiding-light quote, note what is synthetic and how it will be labeled, and keep forms local and non-transmitting unless a real integration is explicitly authorized.

Step 4: Build, test, deploy (second-tier model)

Hand the plan and the guiding-light document to the second-tier model for execution.

Build rules:

• Prefer an independent static project (a static-site generator such as Astro, or plain HTML). Avoid external runtime dependencies when a static interaction demonstrates the requirement honestly.
• No analytics, pixels, tag managers, session replay, cookies, Search Console, sitemaps, schema campaigns, or SEO work. Add noindex, nofollow unless public indexing is explicitly requested (a privacy guard, unrelated to SEO).
• Label synthetic statuses, sample records, illustrative dashboards, and non-live integrations in context. Include a concise demo disclosure without turning the UI into implementation documentation.
• Build the primary journeys and their mobile states; add empty/loading/error/reduced-motion states where the demonstrated feature implies them; keep navigation, dialogs, and local state keyboard- and AT-accessible.
• Apply a deliberate visual design system, use a real copywriting pass for substantial copy, and use restrained humor only where source context supports it and never in safety/legal/accessibility/emergency notices.

Local gate (all required before any deploy or screenshot):

• Production build passes; run python3 scripts/verify_static_demo.py <dist-directory>.
• Test rigorously: exercise primary journeys with browser automation, run axe on every materially different route (resolve serious/critical findings), check for overflow, and capture a fixed multi-viewport screenshot suite including open navigation and at least one interaction state. Review screenshots visually; a green assertion log is no substitute for visual proof.

Deploy only with explicit deployment intent:

• Read references/aws-static-demo.md; follow the aws-static-site skill guardrails (verify AWS identity, read-only inspection first, private versioned S3 + OAC, CloudFront TLS/HTTP3, branded 404, Route53 aliases, full deployment receipt with rollback).
• Live gate: verify exact HTTPS host, redirects, deep routes, 404 status, DNS, direct-S3 denial; re-run focused interaction/accessibility/viewport checks against production; compare deployed artifact hash to the tested local build.

Step 5: Hand the proposal agent its integration instructions (top model)

Switch back to the top model and write instructions for the proposal agent, as a secret-safe /tmp handoff when another agent or thread will do the writing:

• Positioning is optional, and that is the point. Do not make the demo a core requirement of reviewers. Write the proposal so the demo is available should reviewers want to see what we built for them and what we are capable of, while our people, history, work, and ethos speak for themselves. Keep it classy and unforced.
• Repeat the enclave framing in proposal language: a bounded environment built quickly and specifically for this requirement, fully aware of the buyer's existing estate.
• Screenshots must be high resolution and must sit well in the final rendered PDF (often Word-embedded): one or two, on non-busy pages, sized and captioned deliberately, each caption tying the image to specific source requirement language.
• Never put transitional language (not live, coming soon, deployment target, at proposal drafting) in anything buyer-facing. Deploy and verify the evaluator URL before submission, or omit the URL.
• Honor any source warnings verbatim: if the solicitation cautions against elaborate or expensive material, the proposal must show the demo as evidence of ability and economy rather than production values.

Companion Skills

Use a reconnaissance skill for Step 1 and aws-static-site for deployment when those skills are available. For Step 4, bring equivalent discipline for visual design, copywriting, responsive layout, and rigorous browser testing, whether or not dedicated skills exist for them. Generate bitmap imagery only when a needed asset cannot come from verified public or licensed sources.

Deliverables

• Step 1 decision record with source-quoted rationale (even when the answer is "no demo").
• Guiding-light verbatim source document.
• Demo plan with element-to-quote map and screenshot plan.
• Local source, production build, test/screenshot/accessibility evidence, and remaining risks.
• If deployed: live URL, AWS resource receipt, artifact hash, rollback instructions.
• Proposal-integration handoff.

Do not claim a demo is the proposed production architecture, a live buyer integration, a certification, or past performance unless independent evidence supports the claim.

Language pass

All demo copy (UI strings, headings, about/method text) gets a final plain-English pass: no antithesis framings, no filler, maximum information density.