Hello Pico as a constructive exemplar

The first concrete Definition → Realization → Element in this course.

This page is the course’s first explicit constructive exemplar. It takes the constructive-realization vocabulary (Definition, Element, Realization, Constraint, Validation) and points each term at a concrete piece of the existing Hello Pico material — the same Rule, pipeline, and executable you build in Part 1 · Introduction and the Hello Pico lab.

Phase 1 is documentation and metadata only. Nothing here changes how you build a Pico; it names, for one worked example, the things you are already doing so lessons, labs, and metadata can point at them consistently.

The Hello Pico Definition

The Hello Pico Definition is: “a minimal Pico that, given a single greeting Rule, produces an executable artifact named hello-world-pico that prints a greeting to standard output.”

Where this Definition already lives in the course:

The Hello Pico Realization

The Realization is the constructive path from that Definition to a running Element. In Hello Pico it is the familiar Rules → Parser → Composer → Pico pipeline, driven by the reference pico CLI shipped at bin/pico.

rules/hello.yaml  ─▶  pico parse  ─▶  build/parsed.json  ─▶  pico compose  ─▶  build/hello-world-pico
   (Definition)          (Realization step 1)                    (Realization step 2)         (Element)

The concrete Rule that seeds the Realization is the one Rule you author in the lab walkthrough:

# rules/hello.yaml
id: rule.hello
kind: greeting
value: "Hello, Pico!"

The two Realization commands are the ones documented in the Hello Pico walkthrough:

pico parse rules/hello.yaml --out build/parsed.json
pico compose build/parsed.json --out build/hello-world-pico

This maps onto the Phase 1 metadata field realization_pattern, for which the label used here is rules-parser-composer-pipeline.

The Hello Pico Element

The Element is the concrete build/hello-world-pico executable produced by pico compose. Its identity — the name hello-world-pico — is the same name the pico course metadata lists under produces, and the same name the Hello Pico lab metadata lists under produces. That shared name is what makes the lab a Realization of the course-level Definition.

Constraints on a valid Hello Pico Element

A valid Hello Pico Element must satisfy all of the following, each directly implied by the existing lab material:

  • Well-formed Rule — rules/hello.yaml uses the flat id / kind / value shape the reference Parser accepts.
  • Supported kind — the Rule’s kind is greeting, the only kind the reference Composer handles.
  • Successful pipeline — both pico parse and pico compose exit with status 0.
  • Produced artifact exists — build/hello-world-pico is created by the Composer and is executable.
  • Observable behavior — running ./build/hello-world-pico prints exactly Hello, Pico! on standard output.

These are the Constraints named in the sense of constructive realization: conditions a valid Element must satisfy. They are natural-language on purpose — Phase 1 does not introduce formal schemas.

Validations that check the Element

Each Constraint above is checked by something a learner already runs. Validations are pointed at by the Phase 1 validated_by field on the Hello Pico lab metadata.

Constraint Validation (what the learner runs)
Well-formed Rule Walkthrough Step 3 — pico parse succeeds.
Supported kind Walkthrough Step 4 — pico compose succeeds.
Successful pipeline Non-zero exit codes surfaced in Troubleshooting.
Produced artifact exists Walkthrough Step 4 — build/hello-world-pico is written.
Observable behavior Walkthrough Step 5 and the Solution — ./build/hello-world-pico prints Hello, Pico!.
Rule shape (learner-authored) The Introduction lesson exercise — pico parse on the learner’s own YAML.
Terminology understanding The Introduction lesson quiz.

Where compose / construct / behave fit

Hello Pico teaches the behave layer of Crossplane composes, Sandcastle constructs, Picos behave:

  • The Element (hello-world-pico) is the behaviour — a runnable Pico that prints its greeting.
  • Sibling courses reuse the same Hello Pico Element as an input to their own Realizations: the Crossplane course composes it onto a control plane, and the Sandcastle course shows how it is constructed inside a sandboxed engineering environment.

The Definition stays the same across all three layers; only the Realization changes.

What Phase 1 does not add here

  • No new Pico pipeline stages, CLI flags, or lab steps.
  • No formal schema validation of metadata.yaml.
  • No retrofit of other courses, lessons, or labs to the Phase 1 vocabulary.

See the constructive-realization reference for the full Phase 1 scope, and templates/README.qmd (in-repo scaffold, not published as a learner page) for the underlying metadata contract. For the full staged Pico → Sandcastle → Crossplane → Kubernetes chain, see The Hello Pico realization chain in the Sandcastle course. For the same path read through the Phase 4 hello-pico-v1 checkable profile — shape rules mapped to concrete metadata.yaml and evidence — see Hello Pico as a checkable realization. For the opt-in Phase 5 workflow that verifies a hello-pico-v1 claim against those shape rules, and the shape of the resulting validation report, see Hello Pico profile validation. For the Phase 6 aggregate view over those reports — the report index across current hello-pico-v1 claimants, the historical-snapshot convention, and the narrow feedback loop back into the governing Definition — see Hello Pico validation history and feedback.