Sandcastle

Building safely inside bounded engineering environments.

Welcome to Sandcastle, the construction-layer course of the Open Engineering Academy. This course teaches how a Sandcastle — an isolated, disposable engineering workspace — is used to safely produce Open Engineering artifacts such as the hello-world-pico you built in the Pico course.

The academy story this course fits into is:

Crossplane composes, Sandcastle constructs, Picos behave.

The Pico course teaches the runtime layer (what an artifact does). The Crossplane course teaches the composition layer (what should exist on a control plane). This Sandcastle course teaches the construction layer between them: how new artifacts are built safely, by whom, from what, and with what guarantees.

What you will learn

By the end of the course you will be able to:

• Explain what a Sandcastle is and how it differs from a Pico runtime and from a Crossplane composition.
• Describe the five construction-layer concerns a Sandcastle addresses: isolated workspaces, repo/branch flow, tools and permissions, agent iteration, and artifact boundaries.
• Sketch, on paper, how a Crossplane-driven request for a HelloWorldPico would be constructed inside a Sandcastle and delivered back as a durable Git artifact.

See the course descriptor in metadata.yaml for the machine-readable summary (id, level, duration, prerequisites, teaches, produces).

Prerequisites

• Completion of the Pico course, or equivalent familiarity with Rules, the Parser, and the Composer — you need to know what a durable Pico artifact looks like before you can reason about how a Sandcastle builds one.
• Familiarity with Crossplane at the level of Part 1 is helpful but not required — this course only refers to Crossplane conceptually, as the layer that requests engineering work from a Sandcastle.
• Working shell (bash or zsh), a text editor, and basic Git (clone, branch, commit, push).

How this course is structured

The course follows the shared academy course structure — parts, lessons, and per-lesson index / exercise / lab / summary / quiz pages:

courses/sandcastle/
  _quarto.yml          # this course website
  index.qmd            # you are here
  metadata.yaml        # machine-readable course descriptor
  glossary.qmd         # course glossary
  part-1/              # section
    index.qmd
    01-inside-a-sandcastle/   # lesson
      index.qmd
      exercise.qmd
      lab.qmd
      summary.qmd
      quiz.qmd
  part-2/
  part-3/
  labs/                # course-scoped labs

Start here

• Part 1 — Inside a Sandcastle
• Part 2 — Composing Sandcastles with Crossplane
• Part 3 — Delivering artifacts from a Sandcastle
• Labs
• The Hello Pico realization chain — the staged Pico → Sandcastle → Crossplane → Kubernetes chain, end to end, with lifecycle, partial-realization, validation evidence, and feedback pointed at concrete learner material.
• Hello Pico as a checkable realization — the same path read through the Phase 4 hello-pico-v1 checkable profile, mapping each shape rule to concrete metadata.yaml, walkthrough, and verify.sh artifacts.
• Hello Pico profile validation — the opt-in Phase 5 workflow that verifies a hello-pico-v1 claim on that same path, and the shape of a passing, failing, or inconclusive validation report.
• Hello Pico validation history and feedback — the Phase 6 aggregate view: the report index over current hello-pico-v1 claimants, the historical-snapshot convention, and the narrow feedback loop that lets approved reports refine the governing Definition.
• Glossary

NoteCourse status — Parts 1, 2 (lesson 01), and 3 runnable end-to-end

Part 1 is runnable end-to-end via the Part 1 Lab, which links to the reusable Hello World Pico Sandcastle lab. Part 2’s first lesson, 01 Composing a Sandcastle request, is runnable end-to-end via the reusable Compose a Sandcastle request lab, which takes a learner-authored Crossplane XR through an EngineeringTask and has a Sandcastle construct the requested artifact on a durable branch. Part 3’s first lesson, 01 Handing off to Kubernetes, is runnable end-to-end via the reusable Sandcastle → Kubernetes hand-off lab, which takes the branch produced by the Sandcastle lab and hands its greeting off as a Crossplane Composite Resource compatible with the Hello Pico on Kubernetes lab. Part 3’s second lesson, 02 The outer delivery loop, is now also runnable end-to-end via the reusable Outer delivery loop lab, which carries the hand-off XR through branch → PR review → merge → GitOps delivery → downstream reconciliation against live GitHub. Its later delivery and reconciliation stages have honest hosted prerequisites: a learner-owned GitHub environment repo (OE_ENV_REPO), an authenticated gh CLI, and a Flux/Crossplane-capable cluster (the one from the Hello Pico on Kubernetes lab is sufficient); the review/merge stages can be practised on their own without a cluster. Further Part 2 lessons remain intentionally scaffolded for this wave and are clearly labelled where learner-visible.