Incubation Workflow (GitHub Spark)

Rapid prototyping with GitHub Spark and a zero-friction graduation path into the Foundation production monorepo.

Incubation Workflow (GitHub Spark)

The Incubation Workflow allows for zero-friction prototyping using GitHub Spark. Use Spark to vibe the initial UI and logic of a feature or micro-app. Once the idea has legs, use the Foundation agentic pipeline to port the code into the production monorepo.

The Service-First Rule

To ensure graduation is a near 1:1 operation, every Spark project must follow the Service Abstraction Pattern. This prevents lock-in to Spark's managed runtime (window.spark).

Spark Context File

When starting a new Spark project, upload or paste the following rules into the Spark editor as context. A ready-to-use template is available for download:

📥 Download SPARK-RULES.md

SPARK-RULES.md lives in public/templates/SPARK-RULES.md. To bootstrap a new Spark session, cat public/templates/SPARK-RULES.md and paste the output into the Spark editor.

Spark Context: Foundation Portability Rules

  1. Directory Structure: All side effects must live in a src/services/ directory.
  2. Data Abstraction: Create a DataService.ts. Never call window.spark.kv directly in a component. Wrap it in methods like getData() and setData() (use domain-specific names in practice, e.g., getUserProfile(), saveUserProfile()).
  3. AI Abstraction: Create an AIService.ts. Wrap window.spark.llm in a typed function.
  4. Auth Abstraction: Create an AuthService.ts. Use a placeholder for user identity that can be swapped for Better Auth.
  5. Styling: Use Tailwind CSS exclusively. Avoid custom CSS files to ensure compatibility with the Foundation design system.

The Graduation Process

When you are ready to move a Spark project into the Foundation monorepo, follow these steps:

StepAction
1. SyncEnsure the Spark project is synced to a standalone GitHub repository.
2. TargetIdentify the target workspace in the Foundation monorepo (e.g., ui/web-app/features/[name]).
3. PortUse the APPLY-ARCHITECTURE.md prompt with the instruction: "Port this Spark repository to the Foundation architecture. Review APPLY-ARCHITECTURE.md specifically for the Service Mapping rules."

Before merging a ported Spark project, ensure the Pre-Commit Check skill runs clean and a PR Preview Environment has been verified by the submitter.

Self-Consistency Checklist

The Incubation Workflow is consistent with the following Foundation principles:

PrincipleHow it applies
One concern per fileEach service (DataService.ts, AIService.ts, AuthService.ts) addresses exactly one side-effect concern. No service file is responsible for more than one Spark API.
Pre-Commit CheckPorted code must pass the Pre-Commit Check skill before the PR is opened. The skill enforces Biome and Ruff formatting rules that the graduated code must satisfy.
PR Preview EnvironmentEvery graduation PR automatically provisions a PR Preview Environment — an isolated Neon branch plus a dedicated Cloud Run deployment — so the submitter can verify the result before anything touches production.