pal-e-docs

Convention: Pipeline Stages

convention-pipeline-stages Convention

active convention
Project

Convention: Pipeline Stages

Every consumer-facing project follows a four-stage pipeline from prototype to production, with dedicated repos at each stage.

Rule

Projects progress through four stages: Playground, Svelte Sandbox, App, App Store. Each stage has a dedicated repo following the naming pattern {project}-playground, {project}-svelte-playground, {project}-app, {project}-api. Use the word stages, never "phases" (phases are a deprecated plan-era concept).

Rationale

Without enforced stages, agents skip prototyping and ship unreviewed designs straight to production. The playground gate ensures Lucas approves on phone before any SvelteKit work begins. The naming convention lets any agent find the right repo for any project at any stage without guessing. Using "stages" instead of "phases" prevents confusion with the deprecated plan decomposition model.

The Four Stages

Stage Repo Pattern Purpose Tech
<strong>1. Playground</strong> <code>{project}-playground</code> Static HTML/CSS prototypes. Mobile-first. No framework, no data bindings. Lucas approves on phone before anything moves forward. Vanilla HTML, CSS, JS
<strong>2. Svelte Sandbox</strong> <code>{project}-svelte-playground</code> Playground pages promoted into SvelteKit components. Copy-paste from playground, add data bindings and routing. Still static adapter. SvelteKit (adapter-static)
<strong>3. App</strong> <code>{project}-app</code> Production SvelteKit application. Real API integration, auth (Keycloak), full routing. Deployed to k3s via ArgoCD. SvelteKit (adapter-node or adapter-static)
<strong>4. App Store</strong> <code>{project}-app</code> + Capacitor Native mobile wrapper via Capacitor. Same SvelteKit app, bundled for iOS/Android. Only reached after App stage is stable. Capacitor + SvelteKit

Stage Gate Rules

  • Playground approved on phone before promoting to Svelte Sandbox.
  • Svelte Sandbox pages are literal copy-paste from playground + data bindings — .svelte files ARE HTML.
  • App stage requires local dev validation (Vite-on-host or k3s dev namespace) before prod deploy.
  • App Store stage requires App stage stable for days before Capacitor wrapping.

Examples

Correct Incorrect Why
<code>westside-playground</code> <code>westside-prototypes</code> Naming convention requires <code>-playground</code> suffix
<code>mcd-tracker-svelte-playground</code> <code>mcd-tracker-sandbox</code> Must use <code>-svelte-playground</code> for stage 2
"Move to stage 3" "Move to phase 3" Stages, not phases. Phases are deprecated plan-era terminology.
Prototype in <code>westside-playground</code>, then promote Build directly in <code>westside-app</code> Skipping the playground gate means unreviewed design hits production
<code>pal-e-playground</code> is CSS guide only Put westside prototypes in <code>pal-e-playground</code> Hub playground is the CSS guide. Each project owns its own playground repo.

Enforcement

Convention only. Agents are expected to check this convention before creating repos or referencing pipeline progression. Betty Sue validates during ticket review that work targets the correct stage repo.
  • convention-kanban-over-plans — why plans are obsolete and boards are the decomposition tool
  • convention-sveltekit-spa — SvelteKit app conventions for stages 2-4
  • convention-frontend-css — CSS conventions across stages
  • convention-playground-data-contracts — data contract comments in playground HTML
  • convention-blocker-labels — blocker labels that can gate stage transitions