Skip to content
SiteSwarm Platform Documentation

Prototype Workflow And Progressive Escalation

Prototype Workflow & Progressive Escalation Runbook

Source Issue: #576
Status: uningested (Point-in-time write-up pending /docs distill alignment)
Target Canonical Spec: docs/runbooks/PROTOTYPE_WORKFLOW_AND_PROGRESSIVE_ESCALATION.md

1. Executive Summary & Paradigm Shift

In high-touch software agency and local business consulting, traditional prospecting relies on pitch decks, abstract wireframes, or generic template galleries. Prospective business owners struggle to visualize how technical superiority translates to their real-world operations, leading to protracted sales cycles, subjective design ping-pong, and low conversion rates.

SiteSwarm replaces passive pitching with active demonstration: We build high-taste, high-fidelity, interactive edge prototypes grounded in the prospect’s verified business facts and deployed to live Cloudflare Worker isolates before the first outreach is even initiated (“Pre-Awareness Prototyping”).

flowchart LR
    subgraph PreAwareness["Pre-Awareness Discovery"]
        WebPresence["Public Web Presence\n(GMB, Yelp, Site)"] --> Extract["Data & Asset Extraction"]
        Extract --> FactSheet["prospect.json\n(NAP & Verified Facts)"]
        Extract --> Vibe["VIBE.md\n(Aesthetic Direction)"]
    end


    subgraph Escalation["Progressive Escalation Model"]
        Phase1["Phase 1: Greenfield Static\n(Pure Astro Worker, Zero-CLS)"] --> Phase2["Phase 2: Platform Capabilities\n(Wiring CMS & Inquiries)"]
        Phase2 --> Phase3["Phase 3: Schema & D1\n(Relational Edge DB & Studio)"]
    end


    subgraph Lifecycle["Tenant Lifecycle"]
        Phase3 --> Promote["Tenant Promotion\n(apps/<client>, Client Intake)"]
    end


    FactSheet --> Phase1
    Vibe --> Phase1

The Greenfield Invariant: Negative Constraint on Sibling Cloning

[!CAUTION] Strict Prohibition on Sibling Blueprint Cloning: Autonomous agents and developers must never clone an existing application workspace (apps/bakery, apps/auto-repair, apps/clk-construction, etc.) when scaffolding a new prototype. Every prototype must start from an empty directory (apps/proto-<slug>/) and be constructed from first principles in accordance with PROTO_BASELINE_REQUIREMENTS.md.

Rationale:

  1. Zero Legacy Cruft: Cloned apps drag forward domain-specific components, stale CSS custom properties, and outdated capability configurations that confuse prospects and contaminate the codebase.
  2. Preventing Platform Leakage: Existing applications contain production database bindings, internal routing artifacts, and platform references that violate the strict no-leakage boundary required during pre-awareness demonstration.
  3. Bespoke Typographic Discipline: Starting greenfield forces authentic typographic and structural choices tailored strictly to the prospect’s brand identity via VIBE.md.

2. The 3-Step Prototype Escalation Model

To optimize engineering efficiency and prevent premature infrastructure overhead, prototypes advance through a structured 3-phase progressive escalation model:

Phase Scope & Name Architecture & State Monorepo Artifacts Transition Trigger
Phase 1 Pure Greenfield Static Worker Prototype Stateless Astro Edge Worker (output: "server" or static edge pre-rendering), session: false, zero D1/KV bindings, remote CDN asset hotlinking with SVG aspect-ratio fallbacks. apps/proto-<slug>/
• package.json
• astro.config.mjs
• wrangler.jsonc
• prospect.json
• VIBE.md		 Initial prospect discovery; authored before or during early outreach.
Phase 2 Platform Capability Integration Headless capability integration: @siteswarm/client-cms (announcement banner, live hours, menu/service specials) and @siteswarm/inquiries (appointment / inquiry routing with Turnstile & honeypot). Connected via client manifest (defineManifest) and monorepo package imports; decoupled preview endpoints. Prospect demonstrates positive engagement, requests dynamic preview, or enters active discovery.
Phase 3 Content Structuring & CMS Schema Translation Relational edge storage: D1 SQLite schemas (schema.sql / seed.sql), isolated backing CMS worker isolate (Worker B) per MULTI_WORKER_PLATFORM_SERVICES.md, and /admin studio controls. • schema.sql
• seed.sql
• apps/proto-<slug>-cms/
• Manifest capability bindings		 Commercial contract signed or verbal commitment secured; preparing for tenant promotion.

Phase 1: Pure Greenfield Static Worker Prototype

Objective

Produce a visually stunning, lightning-fast edge prototype in under 2 hours that renders the prospect’s authentic business identity with 100/100 Core Web Vitals and zero layout shift.

Core Characteristics

  • Empty Directory Scaffold: Initialized cleanly at apps/proto-<slug>/.
  • Stateless Cloudflare Worker: Built on Astro with @astrojs/cloudflare. Direct database bindings (D1, KV, R2) are explicitly omitted to ensure instant deployment and zero maintenance overhead.
  • Astro Session Suppression: session: false is configured in astro.config.mjs to eliminate orphan KV auto-provisioning per docs/write-ups/ADR-0003-WORKER-SPLITTING-AND-KV-ELIMINATION.md.
  • Verified Facts & Aesthetic Grounding:
    • prospect.json: Complete Name, Address, Phone (NAP), weekly operating hours, authentic service offerings, and social proof. Zero hallucinated data.
    • VIBE.md: Bespoke typography pairings, color palette extracted from prospect branding, and tone contract aligning with CLIENT_APP_REVIEW.md.
  • Zero-CLS Image Fallbacks: Remote CDN asset hotlinking backed by inline SVG aspect-ratio placeholders.
  • Security & Privacy Guardrails:
    • Mandatory X-Robots-Tag: noindex, nofollow, noarchive HTTP response headers.
    • Zero internal platform leakage (strict ban on SiteSwarm, EmDash, Cloudflare Worker, Worktrunk).

Phase 2: Platform Capability Integration

Objective

Demonstrate operational platform superpowers to the prospect during active discovery by enabling dynamic content updates and frictionless inquiry intake.

Core Characteristics

  • Client Manifest Declaration: The prototype defines an application manifest using @siteswarm/manifest (see CAPABILITY_MANAGEMENT.md) declaring active capabilities.
  • Dynamic Content Integration (@siteswarm/client-cms):
    • Announcement Banners: Real-time emergency closures, holiday hours, or seasonal greetings.
    • Live Operational Status: Real-time indicator (“Open Now until 6:00 PM”) computed against prospect.json hours.
    • Dynamic Offerings: Daily specials or featured services rendered via headless CMS client adapters.
  • Interactive Inquiry Capture (@siteswarm/inquiries):
    • Frictionless 1-step inline appointment or quote inquiry forms.
    • Integrated bot protection (Cloudflare Turnstile token validation and invisible honeypot traps).
    • Preview routing: Form submissions route to simulated edge notification sinks or staging webhooks, displaying instant confirmation states without touching production databases.

Phase 3: Content Structuring & CMS Schema Translation

Objective

Transition unstructured prospect content into structured relational edge models, provision dedicated administrative studio controls, and establish the multi-worker architecture required for long-term production operations.

Core Characteristics

  • Relational Schema Design (schema.sql & seed.sql):
    • Unstructured arrays in prospect.json are translated into normalized D1 SQLite tables:
      • business_profile (NAP, legal name, tax/license IDs)
      • operating_hours (day_of_week, open_time, close_time, is_closed)
      • services_or_menu (id, title, category, description, price_cents, sort_order)
      • inquiries (id, prospect_id, customer_name, phone, email, notes, created_at)
    • seed.sql populates the D1 database directly from prospect.json facts to ensure seamless continuity.
  • Worker Isolate Splitting (Worker A & Worker B Topology):
    • In alignment with MULTI_WORKER_PLATFORM_SERVICES.md, heavy administrative dependencies and direct D1/R2 bindings are segregated:
      • Worker A (apps/proto-<slug>): Visitor frontend worker. Ultra-lean bundle, edge-cached, zero direct database credentials.
      • Worker B (apps/proto-<slug>-cms): Backing CMS studio worker. Houses the administrative interface (/admin), D1 database mutations, and media processing.
    • Connected via native Cloudflare Service Bindings, preserving 100/100 Core Web Vitals on the public visitor path.
  • Readiness for Promotion: The prototype is now architecturally indistinguishable from a production client tenant, ready for execution of the promotion runbook into apps/<client-prefix>-<site-slug>/.

3. Operational Step-by-Step Runbook Workflow

This procedural guide details the operational steps for executing a prototype cycle from initial prospect identification through progressive escalation.

+-----------------------------------------------------------------------------------------+
|                               PROTOTYPE LIFECYCLE FLOW                                  |
|                                                                                         |
|  [Step 1: Prospect Fact Gathering] ────> [Step 2: Aesthetic Contract (VIBE.md)]         |
|                     │                                          │                        |
|                     ▼                                          ▼                        |
|  [Step 3: Greenfield Scaffolding]  ────> [Step 4: Section & Component Assembly]         |
|                     │                                          │                        |
|                     ▼                                          ▼                        |
|  [Step 5: Verification & Audit]    ────> [Step 6: Progressive Escalation Decision]      |
|                                                                │                        |
|                                                                ▼                        |
|                                         [Step 7: Promotion to Production Client Tenant] |
+-----------------------------------------------------------------------------------------+

Step 1: Prospect Discovery & Grounding (prospect.json)

  1. Identify Prospect: Locate target local business (e.g., premier regional bakery, precision machine shop, specialized contractor).
  2. Collect Public Truth:
    • Google Business Profile / Google Maps: Extract exact physical address, official phone number, published opening hours, and rating/review metrics.
    • Existing Website / Socials: Extract service lists, pricing ranges, founder history, and brand assets (logo, high-res photography).
    • State Trade Licensing / Registrations: Verify official legal name, DBA, and active licenses.
  3. Author prospect.json:
    • Create apps/proto-<slug>/prospect.json following the schema defined in PROTO_BASELINE_REQUIREMENTS.md.
    • Validate that 100% of the content is grounded. Zero placeholder text (555-0199, lorem ipsum).

Step 2: Aesthetic Contract Formulation (VIBE.md)

  1. Analyze Brand Character:
    • Evaluate existing logo, storefront signage, and vehicle wraps.
    • Establish emotional tone: Warm & artisanal, high-precision technical, or quiet corporate authority.
  2. Author VIBE.md:
    • Select tailored font pairing (Display + Body) from system or high-performance edge webfonts.
    • Define semantic color tokens (--bg-canvas, --bg-surface, --color-accent, --text-primary, --border-subtle).
    • Define shape geometry (corner radii, border weights, whitespace rhythm).

Step 3: Greenfield Workspace Initialization

  1. Create Blank Directory:
    Terminal window
    mkdir -p apps/proto-<slug>/src/{components,layouts,pages} apps/proto-<slug>/public
    (Reminder: Never copy an existing app directory.)
  2. Initialize Workspace Configuration:
    • Create package.json with workspace dependencies (astro, @astrojs/cloudflare, typescript).
    • Create astro.config.mjs configured with output: "server" and session: false.
    • Create wrangler.jsonc declaring the Worker isolate name (proto-<slug>) and nodejs compatibility.
    • Create tsconfig.json extending root Astro tsconfig.
    • Place _headers in public/ enforcing X-Robots-Tag: noindex, nofollow.

Step 4: Component Construction & Section Assembly

  1. Construct Semantic Layout Hierarchy:
    • Header.astro: Sticky navigation with brand logotype, 1-tap tel: phone call link, and dynamic “Open Now” badge.
    • Hero.astro: Grounded geographic headline, verified value proposition, high-impact CTA.
    • Offerings.astro: Semantic list/grid mapping directly over prospect.json offerings.
    • ProofPoints.astro: Verified customer reviews, license numbers, years in business.
    • LocationHours.astro: Physical address, Google Maps directions link, formatted weekly hours table with current day highlighted.
    • Footer.astro: Unbranded copyright, legal entity name, strict zero platform leakage.
  2. Implement Zero-CLS Image Patterns:
    • Every image must contain explicit width, height, or aspect-ratio rules.
    • Provide inline SVG aspect-ratio placeholders for remote CDN assets.

Step 5: Verification & Anti-Leakage Audit

Before preview deployment, execute the verification suite:

  1. Machine Gate Verification:
    Terminal window
    pnpm --filter proto-<slug> run check
    pnpm run lint:arch
  2. Anti-Leakage Grep Audit: Verify zero platform terms are present in public-facing markup:
    Terminal window
    grep -riE "SiteSwarm|EmDash|Cloudflare Worker|Worktrunk" apps/proto-<slug>/src/
  3. Core Web Vitals Check:
    • Verify layout stability (CLS = 0) and sub-second TTFB on preview worker.

Step 6: Progressive Escalation Decision Matrix

Determine when to transition the prototype across escalation phases:

+------------------------------------+------------------------------------+
| TRIGGER / PROSPECT EVENT           | ESCALATION ACTION                  |
+------------------------------------+------------------------------------+
| Cold outbound / initial outreach   | Keep at Phase 1 (Static Edge)      |
| Prospect visits preview link       | Monitor telemetry; keep Phase 1    |
| Prospect asks "Can I update hours?"| Escalate to Phase 2 (Wiring CMS)   |
| Discovery call scheduled           | Escalate to Phase 2 (Inquiries) |
| Commercial proposal accepted       | Escalate to Phase 3 (D1 & Schema)  |
| Contract signed / deposit paid     | Execute Tenant Promotion (to client)|
+------------------------------------+------------------------------------+

Step 7: Promotion to Production Client Tenant

Once a prospect executes a service agreement:

  1. Hand off the Phase 3 prototype to the formal Client Intake & Onboarding workflow (CLIENT_INTAKE_AND_ONBOARDING.md).
  2. Execute the tenant promotion recipe (/prototype promote governed under Epic #575 and Story #578) to re-namespace the workspace into apps/<client-prefix>-<site-slug>/.
  3. Provision production Cloudflare for Platforms custom domain ingress and D1 database bindings.

4. Anti-Patterns & Operational Guardrails

Anti-Pattern Severity Impact Corrective Mandate
Sibling App Cloning Critical Drags forward stale CSS, broken bindings, domain cruft, and cognitive overhead. Enforce blank directory scaffolding (apps/proto-<slug>/).
Content Hallucination Critical Destroys prospect trust with fake phone numbers, wrong hours, or imaginary offerings. Every claim and fact must trace directly to prospect.json.
Platform Terminology Leakage High Exposes internal engine brand (SiteSwarm, EmDash, Cloudflare Worker) on prospect-facing pages. Maintain white-label posture; run automated grep linter before preview publish.
Search Engine Indexing High Ephemeral or unapproved prospect sites indexed by Google, causing client brand confusion. Ensure X-Robots-Tag: noindex, nofollow is active on all routes.
Premature Relational Schemas Medium Wasting hours configuring D1 databases and admin panels for cold prospects who never convert. Keep cold prototypes in Phase 1; escalate to Phase 2/3 only upon prospect interest.
Heavy Client-Side Frameworks Medium Bloated JavaScript bundles degrading mobile Core Web Vitals below 100/100. Total client JS budget < 10KB; use vanilla TypeScript and Astro static islands.

🔍 Founder Trimming & Condensation Notes

Items flagged for condensation during Phase 2 /docs distill alignment into docs/runbooks/PROTOTYPE_WORKFLOW_AND_PROGRESSIVE_ESCALATION.md:

  • The detailed runbook step-by-step instructions can be consolidated into an operational command checklist once the /prototype agent skill (#444) automates scaffolding and audits.
  • The Mermaid flowcharts can be unified into a single lifecycle diagram bridging prospecting, escalation, and tenant promotion.
  • Escalation triggers can be embedded directly into the Client Intake Checklist (docs/runbooks/CLIENT_INTAKE_CHECKLIST.md).

Decisions Intentionally Deferred

  • Automated Outbound CRM Sync: Synchronization of prototype preview URLs with HubSpot or outbound mailers is deferred to platform marketing automation epics.
  • Preview TTL & Auto-Teardown: Automatic purging of ephemeral prototype preview workers after 30 days of inactivity is governed under preview infrastructure (#577).
  • Interactive Multi-Agent CLI Commands: Interactive wizard tooling (/prototype new, /prototype escalate) is tracked under Story #444.