Engineering adoption
The deliverable is the standard running in the repository: gates that fail a pull request, and the
six facets the CI publishes from the default branch. A dashboard is optional and comes after.
Read
before you add anything. Two different
things produce engineering signals, they come from two different places, and mixing them is the
failure this skill exists to prevent.
1. Interview
Read the repository first, then ask one decision per call with the host's question tool, following
. Every question has a recommendation first, and
the person answers by selecting, not by typing.
- Host: GitHub, Azure DevOps, GitLab, or another. Which system holds the code and runs the CI.
- Scope: everything, or engineering only. Everything means delivery and agent metrics too.
- Standard: the Platform standard (Foundations ), or a generic quality bar the
team chooses.
- Modules: which of coverage, complexity, mutation, hygiene, security, SBOM, PR gates and the
scorecard to install. This is a multi-select, split into two questions of four, and it offers
only what the repository can produce.
- Dashboard and, if one will be built, its look: see step 6.
A decision with several valid answers is never asked with a single-select control. If the tool has no
multi-select, number the options and ask for the numbers.
Finish by printing the plan (host, scope, standard, modules, dashboard, look, files to add) and asking
for a go-ahead. Change nothing before it.
Done when every question is answered or the person said "you decide" and you stated the
recommendation you took, and the plan was confirmed.
2. Pick the shape
| Host | Scope | What to do |
|---|
| GitHub | everything | Stop. This is not an adoption: it is one entry in an existing Project Health instance. Follow the add-project skill in that repository, or ask whoever runs it |
| GitHub | engineering only | Continue to step 3 on the family template, then step 6 |
| Any other | either | Continue to step 3 with host wiring, then step 6 only if they want a dashboard |
Anything except the first row means this repository needs its own CI wiring, because no family
template exists for that host.
Done when you have named the row and read the reference it points at.
3. Put the producer in the repository
The producer reads report files that the build already writes (Cobertura XML,
,
,
,
,
, a CycloneDX BOM). It never calls a
host API, so the same script works everywhere; only the wiring differs.
Vendoring rule, in this order:
- If the repository is a Copier consumer ( exists), the producer belongs to a
platform-owned path in , and it arrives with . Do not copy it
into the tree by hand.
- Otherwise vendor
scripts/engineering-excellence.mjs
, , the schema copy and the
gates it needs, with a header pointing back to the source. Record the commit it came from.
Write down which rule you used, in the pull request or in the repository's decisions folder.
Done when the script runs locally against a real report and writes a
that
validates against the vendored copy of the facet schema.
4. Wire the host
- GitHub: the family template already runs the gates. Facets go in a separate workflow file that
reads the reports its CI uploaded, or in after taking ownership of that file. See
for what taking ownership costs.
- Azure DevOps:
references/azure-pipelines.md
.
- GitLab: .
Only the modules chosen in the interview, and of those only the facets the repository can actually
produce. Two or three is a good first release; six is rare, and a facet invented from a tool that
does not run is worse than a missing one. If a chosen module turns out to have no input, say so and
drop it from the plan instead of faking it.
Done when one run on the default branch published the chosen facets, and a pull-request run
published none.
5. Verify
- Upload happens on the default branch and on a failed gate, never only on success. A drop is the
sample most worth keeping.
- Every facet names this repository in and this branch in ; a mismatch is ignored by the
consumer and must be ignored, not papered over.
- The gates fail a pull request that breaks them, and the facets still upload. Facets never gate;
the repository's own CI decides what fails.
- is the one the consumer knows. An unknown version is ignored by design, so bumping
it without the consumer is a silent data loss.
- One deliberate failure is recorded: break a gate on a branch, confirm the facet still exists, and
confirm the dashboard or the reader shows the drop rather than a zero.
- Each module the person selected is accounted for: installed and verified, or dropped with the
reason. Nothing selected is silently missing from the result.
Done when every line above is checked against a real run, not against the workflow file.
6. The dashboard, if they asked for one
Read
. It covers the four ways to publish. A
non-GitHub host can now write the month files with
, so option 3 is a commit
rather than a piece of work; what it cannot do is collect deployments, agents or pull requests.
Done when the person knows which publishing path they have, and what remains to build for the
other one.
If a site will be built, its experience is Project Health's and its identity is the person's. Read
references/dashboard-ux.md
, ask the look question of the interview
(Project Health's palette, a brand they provide, a site to take inspiration from, or colours by
hand), and apply the identity as tokens only. Open the result in a browser, in both themes and at
phone width, and run the checklist in that file before you call it finished.
Done when the site renders, matches that checklist, and the person has seen it in a browser.
What "done" does not mean
A green pipeline is not adoption. Every facet degrades to an absent block with a reason when its
input is missing, so a run that published nothing can still be green. Adoption is the run that
produced a number somebody checked against the tool that measured it.