Showcase: scaffold and ship a Java service¶

Goal: see what a real Engineering Capability does — one Markdown file that scaffolds a Maven service into a GitHub repository, commits it, pushes it, and triggers CI, every step governed and audited.

files/notes-roundtrip proves the mechanism in two steps. This one shows the point: 18 steps crossing two providers and the Command Engine, described in Markdown, executed deterministically by the runtime.

This is not the first thing to run

It needs a write-scoped GitHub token and it creates real commits. Start with Run Your First Capability, which needs no credentials at all. Come here when you want to see the ceiling.

What it does¶

Steps	Provider / binary	What happens
1–3	`github`	Seed `src/main/java/…`, `src/main/resources/` and `.github/workflows/` via the GitHub contents API
4	`git`	Clone the repository into your working directory
5–10	`files`	Write `pom.xml`, the application source, the CI workflow, `README`, `.gitignore`
11	`git`	Remove the `.gitkeep` seeds now that real files exist
12	`files`	List the tree, so the run shows what was produced
13–15	`git`	`add -A`, commit, push
16–18	`github`	List workflows, trigger `java-ci.yml`, then list the runs

18 steps: 6 github, 7 files, 5 git. Counted from the capability file, not estimated.

Why this is the interesting one¶

One capability spans two Runtime Providers and the Command Engine. The github operations pick their own transport (REST, GraphQL or gh), files writes locally, and git runs through the Command Engine under policy.
It ends by triggering CI and reading the result back — the workflow is scaffolded, dispatched and observed in the same run.
Every step is audited. runtime audit tail shows all 18, and a policy denial would stop the run and be recorded rather than silently skipped.
It is Markdown. No plugin, no SDK — a file you can read, diff and review.

Prerequisites¶

Three, and none of them is optional:

Must be true	Why	Check
The capability is on your machine	It does not ship with the binary — it lives in the public capability store	`ls $RUNTIME_CAPABILITIES_DIR/github/`
Your token has write scope	It creates commits and dispatches a workflow	`runtime auth status`
An empty repository exists	It scaffolds into a repo; it does not create one	—

Get the capability¶

It is published in the public engineering-runtime-capabilities store. Point the runtime at a clone — the same pattern a company uses for its own store, see Sharing a capability directory:

git clone https://github.com/kishore-gutta/engineering-runtime-capabilities.git
export RUNTIME_CAPABILITIES_DIR="$PWD/engineering-runtime-capabilities/capabilities"

This replaces the seeded set

RUNTIME_CAPABILITIES_DIR relocates the capabilities directory rather than adding to it, so the binary's own examples are not visible while it is set. Unset it to get them back.

Inspect it without running it¶

Do this first. Validation resolves all 18 steps against the operations your installed binary actually has — and touches nothing:

runtime capability validate github/java-service-scaffold-and-ship

Expected output:

capability is valid: .../capabilities/github/java-service-scaffold-and-ship.md

That single line means every provider operation, every binary, and every input reference in the file resolves against this binary. A capability that does not validate does not run.

Inputs¶

All five are required:

Input	Example	Notes
`repository`	`my-org/my-service`	`<owner>/<repo>` — must already exist
`workdir`	`./my-service`	Must not already exist — it is a clone target
`service_name`	`my-service`	Maven `artifactId`, and used in the README
`java_package`	`com.example.demo`	Dotted form
`java_package_path`	`com/example/demo`	The same package in path form

The last two are the same value in two notations — the capability needs both, and getting them out of step is the most likely mistake.

Run it¶

runtime capability execute github/java-service-scaffold-and-ship \
  --input repository=my-org/my-service \
  --input workdir=./my-service \
  --input service_name=my-service \
  --input java_package=com.example.demo \
  --input java_package_path=com/example/demo

Each step reports its provider, transport and result, and the run ends with capability completed: 18 step(s).

Then prove it¶

runtime audit tail -n 20

Every one of the 18 steps is there, with its transport and outcome — which is the difference between a script that did something and an operation you can account for.

Common failures¶

Symptom	Cause	Fix
`capability not found`	`RUNTIME_CAPABILITIES_DIR` is not set, or points at the wrong level	It must point at the `capabilities/` directory inside the clone
A `github api PUT` step fails `403`	Token lacks write scope	Reissue with write access to the repo
The `git clone` step fails	`workdir` already exists	Choose a path that does not exist yet
The workflow-run step fails	`java-ci.yml` is not on the default branch yet	The push must land before the dispatch — re-run after the push completes

Next¶

Create a Capability