Scaffolder Pattern

Generate a service skeleton from a template. The mechanism behind Backstage Software Templates, cookiecutter, Yeoman, and platform-ctl's `new service`.

One command. Template applied. New service skeleton with all the platform hygiene (CI, observability hooks, NetworkPolicy, SLO stub) pre-wired. Status: STUB — promoted to OUTLINE in Y3 Phase 26.

What this pattern is

A scaffolder generates a working service skeleton from a template, applying the platform’s conventions automatically. Spotify Backstage Software Templates, cookiecutter, Yeoman, and platform-ctl’s new service are all scaffolders. The output is not just code — it’s a full bootstrap: Git repo + CI config + Helm chart skeleton + Kustomize overlays + observability hooks + SLO definitions + runbook templates + service-catalog entry. A developer runs one command and ends with something that already passes the platform contract.

The pattern’s insight is that the “starting a new service” moment is a leverage point. Every service starts once but runs forever. Getting the starting configuration right saves compounded cost over the service’s lifetime. Getting it wrong (missing observability, incorrect security posture, unclear ownership) creates debt that’s expensive to fix later. Scaffolders make it easy to start right.

The pattern’s trade-off space: generate-once (developer owns the output forever; updates to the template don’t propagate) vs template-as-library (template updates propagate via controller; output stays in sync but has less local flexibility). /root’s platform-ctl operator leans toward the latter — the Workload CRD is reconciled continuously, so the platform’s evolving contract reaches existing services without forcing manual upgrades. This is the modern K8s-native shape; the alternative is the cookiecutter-style one-shot generation that leaves each service on its own.

Composition matters. A good scaffolder integrates with the platform’s service catalog (new service appears automatically), CI/CD pipeline (deploy templates ready to go), observability stack (metrics + SLOs pre-wired), and security posture (NetworkPolicy + service account scoped correctly). Without integration, the scaffolder produces isolated code that developers then have to wire into the platform manually.

Concrete instances in the wild

  • Backstage Software Templates. The reference implementation. Templates written in JSON schema; scaffolder plugin executes them; result gets registered in the service catalog. Common across Backstage-adopting organizations.
  • cookiecutter. Python-based project templating tool. Templates are Git repos with parameterized variables. Widely used for language-specific project starters.
  • Yeoman. Older JavaScript-based scaffolder. Popular in the mid-2010s frontend scene.
  • platform-ctl new service (Y3 Phase 26). basecamp’s scaffolder. Materializes a Workload CRD instance that the platform-ctl operator then reconciles into concrete resources.
  • create-react-app. Frontend-framework-specific scaffolder for React projects. The pattern applied at framework scale.
  • Vite scaffolds. npm create vite@latest — modern JS ecosystem scaffolder.
  • Rails generators. rails new, rails generate scaffold user name:string — the pattern baked into a framework.
  • cargo new (Rust). cargo new my-project creates a working Rust project. Language-level scaffolding.
  • Helm chart scaffolds. helm create mychart generates a Chart skeleton.
  • kubebuilder init. kubebuilder init scaffolds a K8s operator project. The scaffolder pattern applied to operator authoring.

Why this pattern matters

Without scaffolders, every new service starts from a partial memory of “what did the last service look like?” Each engineer copies from their previous project, forgets some details, invents others. Services drift apart in structure; platform-team standards get violated silently; onboarding a new developer requires them to learn each service’s idiosyncrasies. Multi-service systems become archaeology projects.

With scaffolders, every service starts with the same structure and the same integration. The scaffolder is the enforcement mechanism for platform standards. If the platform requires structured logging, the scaffolder pre-wires it. If the platform requires an SLO per service, the scaffolder generates a Pyrra SLO stub. Standards get followed because deviating from them requires deliberate work.

The pattern also accelerates the “new service to production” timeline. Without a scaffolder, that timeline is measured in days (write the deploy configs, wire the CI, connect observability, provision resources). With a good scaffolder, it’s measured in minutes. The compounding effect on platform velocity is significant: teams that can spin up new services quickly experiment more; teams that can’t don’t.

The template-vs-library trade-off is real. Templates that generate-and-forget produce services that drift from the platform contract over time (the template evolves; existing services don’t). Templates that live as continuous reconciliation (like /root’s Workload CRD operator) keep services in sync with the platform, at the cost of less local flexibility. Different scales favor different approaches: small teams can accept drift; large platforms need continuous reconciliation.

The failure modes to avoid: scaffolders that generate ceremony without value (a hundred-file skeleton for a fifty-line service), scaffolders that hide too much (developers can’t debug when the scaffold breaks), and scaffolders that don’t evolve (a scaffold from 2020 that still references deprecated tools). Well-run scaffolders are simple, transparent, and versioned like any other platform component.

Depth progression

STUB     ← you are here.
OUTLINE  Promoted when Y3 Phase 26 ships platform-ctl `new service`.
DEEP     Promoted after Y3 end — at least 3 services bootstrapped via the
         scaffolder, including at least one template-update propagation event.

Preview: what OUTLINE will answer

When Y3 Phase 26 promotes this entry to OUTLINE, it will name:

  • PROBLEM. How do you make starting a new service easy while enforcing platform standards uniformly?
  • PRINCIPLES. Templates encode platform contract. One-command bootstrap. Integrated with catalog, CI, observability, security. Update path from template to running service (either template-as-library or migration tools).
  • TRADE-OFFS. Generate-once (developer owns; drift over time) vs template-as-library (kept in sync, less local flexibility). Template richness (comprehensive, complex) vs minimal (simple, requires more manual work). CLI-based (developer-invoked) vs portal-based (self-service through UI).
  • TOOLS (time-stamped as of 2026-06): Backstage Software Templates, cookiecutter, Yeoman, framework-specific (create-react-app, Rails generators, cargo new, Helm create), custom operator-based (platform-ctl Workload CRD).

The DEEP promotion, after Y3 end with 3+ services bootstrapped, will add MASTERY (operating scaffolder-based service creation), COMPARE (generate-once vs template-as-library approaches), OPERATE (a specific template-update propagation event), and CONTRIBUTE (a Backstage template shared publicly or a scaffolder plugin contribution).

Canonical references

  • Backstage Software Templates documentation. Free at backstage.io.
  • Camille Fournier, Platform Engineering — chapter on paved roads and templates.
  • Spotify’s engineering blog on scaffolder patterns. Free.
  • CNCF Platforms Working Group whitepaper. Free.
  • kubebuilder book (operator scaffolding). Free at book.kubebuilder.io.

Cross-references