On a Monday morning the security reviewer of the synthetic insurer sends one question to every engineering lead: "Which of our services still accept an expired token on some routes and reject it on others?" The authentication code of the intake services came from one pattern, PAT-INTAKE-API, and the fix is a few lines in its middleware. Writing the fix takes an hour.
Finding who needs it takes the rest of the week. One intake service was built by the factory last month. Another was generated from an older version of the pattern and then edited by hand. A third copied the authentication module from the second. Nobody can say which service runs which version, who owns it, or which build is in production, because none of that was written down in one place. The factory built each service correctly. Nothing around the factory recorded what it built.
The learner's question: what does a factory need from the organization it runs in, what does each of those foundations decide, and what does each one leave undecided?
The platform under the factory#
Plain English. A platform is the set of shared services every team uses instead of building its own: a way to start a repository, a place to store builds, a way to configure environments, and a list of what exists and who owns it. A factory is one heavy user of it.
The previous chapters built factories that stand alone. Example C (examples/c-insurance-service/) assembles the broker intake service from PAT-INTAKE-API 2.1.0 and the product spec SPEC-INTAKE-001 in factory run FR-0003, and writes a rollout manifest that names three environments, a five percent canary and a person with the release-approver role. Its README is explicit that the manifest is "documentation only": nothing deploys, nothing is stored outside the example's out/ folder, and no catalog learns that the service exists. That is the right boundary for a teaching example. In an organization, those missing parts are the platform.
Platform engineering is the discipline of building and running those shared capabilities as a product for the organization's own teams. Guideline (CNCF Platforms White Paper, TAG App Delivery, read 2026-11-20): the paper defines a platform for cloud-native computing as "an integrated collection of capabilities defined and presented according to the needs of the platform's users". It calls such platforms internal because they serve only the enterprise's own users, and it says a platform should provide capabilities without necessarily implementing them; a platform can be as thin as a wiki of standard procedures.
An internal developer platform is the common name for that collection when its users are the organization's engineers. One honest note: the CNCF paper read here uses "internal platform" and "platform engineering" and does not use the phrase "internal developer platform". This site uses the common phrase and means the same thing.
Before AI. A company Maven parent POM that pins plugin versions, a Jenkins shared library every pipeline imports, an internal Spring Initializr with the company's starters preselected, an internal artifact repository, a wiki page titled "how we deploy": that was a platform, often without the name. A factory reuses all of it. It adds one new kind of user that starts many products quickly and never forgets a step it was given, and also never notices a step it was not given.
Six foundations, and what each one decides#
A useful way to understand each foundation is to ask what single question it answers for the factory, and which question it leaves to someone else. The examples below follow Example C's intake service from its first commit to the moment someone asks who owns it.
Golden path: the supported way to do one common job#
A golden path is a bundled, supported workflow for a common job, offered with a template and documentation, that most teams follow because it is the easiest route. Guideline (CNCF Platforms White Paper, read 2026-11-20): the paper describes a golden path as a bundled workflow, for example a supply chain to build, scan, test, deploy and observe a web app, offered with a project template and documentation. Many organizations call the same thing a paved road; this site uses both words for one idea.
For the intake service, the golden path would be: start from the intake repository template, let the factory fill it from the spec, run the organization's standard CI checks, publish the build to the registry, register it in the catalog, promote through the standard environments. It decides the route. It does not decide the product's business rules, the fields of its submission, or whether R-ROOF-03 escalates at five years or six. Those stay in the spec and the product's own rule module.
Organization standards: rules every product must meet#
A standard is a rule that holds for every product regardless of who built it: logs carry a trace id, personal data is masked, every service has an owner. Example C's pattern already encodes some as constraints (logs_mask_pii, human_decision_roles: ["underwriter"]). A standard decides what must be true. It does not decide how a product meets it; the pattern and the product do, and a gate checks it.
Repository template: the first commit#
A repository template is a concrete starting repository (folders, build file, CI configuration, a catalog descriptor) that a new product is created from. It decides the first commit. It does not keep the product aligned afterwards: a template is copied once, and every later change to the template reaches existing products only if someone carries it there. That is the gap between a template and a pattern with versions, which From repetition to a pattern introduced.
Artifact registry: where a build lives, by digest#
An artifact registry is the store where built, versioned artifacts live (packages, container images, generated contracts), each addressable by a version and a content digest. Example C's factory already computes the digest of every file it writes; the manifest of FR-0003 lists openapi.json as sha256:d79646305fc5.... A registry would keep those files immutable and retrievable by that digest. It decides where the artifact lives and that it cannot change in place. It does not decide whether the artifact is good; the gates of CI/CD and deployment do that before anything is published.
Environment configuration: what changes between deployments#
Environment configuration is every value that differs between the places a product runs (development, staging, production): hostnames, credentials, the address of the real provider. Guideline (The Twelve-Factor App, "Config", read 2026-11-20): it defines an app's config as "everything that is likely to vary between deploys" and says a twelve-factor app stores it in environment variables, managed independently per deploy rather than bundled into named groups. Environment configuration decides what differs per environment. It does not decide what the product does; a retry limit of three attempts is product behavior written in the spec, not a per-environment value.
Software catalog: what exists and who owns it#
A software catalog is the system of record for every product, its owner, its pattern and version, and its relationships. Product (Backstage Software Catalog, as documented on 2026-11-20): the documentation describes a centralized system that tracks ownership and metadata for all software in an organization, with metadata YAML files stored with the code as the source of truth. The catalog decides nothing about how a product is built. It answers the Monday question: who has this, which version, and who must approve a change.
Diagram: What the platform runs, what the factory does, what each product keeps
Three lanes. The platform lane holds the shared foundations run once for everyone: the repository template, the standard CI checks, the artifact registry, environment configuration and the software catalog. The factory lane consumes the template and the spec, writes artifacts into the registry by digest and registers what it built in the catalog. The product lane keeps the spec, the business-rule module and the release approval. No platform box holds a business rule.
- Platform team
- repository template: Concrete starting files: folders, build file, CI configuration, catalog descriptor.
- standard checks: The supported route: build, scan, test, publish, register, promote.
- artifact registry + environment config: Immutable builds addressed by digest, and the values that differ per environment.
- software catalog: One record per product: owner, pattern, version, relations.
- Factory
- check the spec: Refuses a spec that leaves an extension point empty.
- generate contracts + service config: Writes the API contract, event schemas and the service configuration.
- push artifacts by digest: Every output with its sha256, ready for the registry.
- register the product: The last station writes the catalog entry from the manifest.
- Product team
- product spec: Fields, roles, routes, workflow, events for one product.
- business-rule module: The product's own decisions, owned by its domain team.
- release approval: A person with the release-approver role signs off before promotion.
Read the three lanes from left to right. The top lane is what the platform team runs once for everyone. The middle lane is the factory: it consumes the template, writes artifacts into the registry and registers what it built. The bottom lane is what stays with each product team: its spec, its rule module and its approval to release. Each arrow crosses a lane boundary at a contract, and none of the platform boxes contains a business rule.
| Foundation | Decides | Does not decide | Example C today |
|---|---|---|---|
| Golden path | the supported route for a common job | the product's rules or fields | not present: the README describes the route only in text |
| Organization standards | what must hold for every product | how a product meets it | partly: constraints in pattern.json |
| Repository template | the first commit | anything after the first commit | not present |
| Artifact registry | where a build lives, immutable, by digest | whether the build is good | digests computed in the manifest; no store |
| Environment configuration | values that differ per deployment | product behavior | three environment names in the rollout manifest; no values |
| Software catalog | what exists, owner, version, relations | how anything is built | not present |
The right-hand column is the useful one. Example C already produces most of what a platform needs (an owner role, a pattern version, a spec hash, digests). What it lacks is a place to put them that outlives the run.
The smallest primitive: a catalog that can answer one question#
A catalog does not need a portal to be useful. It needs one record per product with four facts: the product id, the owner, the pattern it pins, and the version. The blast lab keeps exactly such a catalog. Teaching reconstruction: its eight products on three pattern lines are synthetic, except the names that come from the examples (broker-submission-intake and PAT-INTAKE-API 2.1.0 from Example C, running-sum and clamp-list from Example A); every owner and test count is the lab's own.
The script below was written for this page and run on a scratch copy of examples/labcore/. It prints the catalog, then asks the lab's own function b_blast.radius who receives the authentication fix from the opening story. What it demonstrates: with a catalog, the Monday question is a query. What it does not demonstrate: that the catalog is true. A catalog is only as good as the process that keeps it in step with what is deployed.
import sys
sys.path.insert(0, sys.argv[1])
import b_blast # noqa: E402
cat = b_blast.CATALOG
print("catalog:", len(cat["products"]), "products on", len(cat["patterns"]), "pattern lines")
for p in cat["products"]:
print(f" {p['id']:<28} {p['pattern']} {p['version']:<6} owner: {p['owner']}")
r = b_blast.radius(cat, "auth-middleware")
print()
print("change:", r["label"], "|", r["kind"], "->", r["bump"])
for t in r["patterns"]:
print(f" pattern {t['pattern']} {t['from']} -> {t['to']} (owner: {t['owner']})")
for a in r["affected"]:
print(f" affected {a['product']:<28} {a['tests_selected']} of {a['tests_total']} tests selected")
for n in r["not_affected"]:
print(f" not affected {n['product']}: {n['reason']}")
print(" suite:", r["suite"]["selected"], "of", r["suite"]["total"], "tests")
print(" approvals:", "; ".join(r["approvals"]))
catalog: 8 products on 3 pattern lines
broker-submission-intake PAT-INTAKE-API 2.1.0 owner: submissions team
claim-notice-intake PAT-INTAKE-API 2.1.0 owner: claims team
endorsement-request-intake PAT-INTAKE-API 2.0.0 owner: policy servicing team
loss-run-request-intake PAT-INTAKE-API 1.4.0 owner: claims team
running-sum PAT-ALGO-UNIT 1.3.0 owner: algorithm content team
clamp-list PAT-ALGO-UNIT 1.3.0 owner: algorithm content team
policy-event-relay PAT-EVENT-WORKER 1.4.0 owner: integration team
audit-export-job PAT-EVENT-WORKER 1.4.0 owner: compliance engineering
change: Auth middleware: expired tokens rejected the same way on every route | fix -> patch
pattern PAT-EVENT-WORKER 1.4.0 -> 1.4.1 (owner: integration team)
pattern PAT-INTAKE-API 2.1.0 -> 2.1.1 (owner: platform team)
affected broker-submission-intake 4 of 50 tests selected
affected claim-notice-intake 4 of 40 tests selected
affected endorsement-request-intake 3 of 29 tests selected
affected policy-event-relay 2 of 24 tests selected
affected audit-export-job 2 of 18 tests selected
not affected loss-run-request-intake: pinned to PAT-INTAKE-API 1.4.0, an older major line; it keeps that version until it upgrades
not affected running-sum: PAT-ALGO-UNIT does not ship authentication
not affected clamp-list: PAT-ALGO-UNIT does not ship authentication
suite: 15 of 206 tests
approvals: integration team (owner of PAT-EVENT-WORKER); platform team (owner of PAT-INTAKE-API); security reviewer (authentication is a governed component)
Three lines matter. Five products on two pattern lines receive the fix, and the list names their owners, so the Monday question has an answer with names in it. One intake service is "not affected" only because it is pinned to an older major line: it still has the old behavior, and the catalog is what makes that visible instead of silent. And a security reviewer appears in the approvals because the catalog marks authentication as a governed component. The counts are the lab's synthetic tests, not measurements. How the version bump and the regression suite are computed is the subject of Factory learning loop; this page cares that the question could be asked at all.
The second half of the primitive is the record the factory itself leaves. Example C's manifest for FR-0003 already carries what a catalog entry and a registry need, quoted from a scratch run of run.py:
{
"factory_run_id": "FR-0003",
"pattern_id": "PAT-INTAKE-API",
"pattern_version": "2.1.0",
"spec_id": "SPEC-INTAKE-001",
"specification_hash": "sha256:ecb151ab7f7f7b10e9dfa0922a3fe2eeb174e73cdbf04807abab08a34ed2e2ad",
"artifacts": {
"openapi.json": "sha256:d79646305fc547b1489df9214098ef3d393ec16a389ba8d0e5e3b13acbec6881",
"service_config.json": "sha256:1167f3f8d00ffd4316c0e7f6ece5a5966a21f61bf459f6dde7e3461089c58097"
}
}
(Shortened to two of the five artifacts; the values are as printed.) The integration a platform needs is small: the factory's last station registers this record in the catalog and pushes the files to the registry under their digests. Build the smallest factory is the home of manifests and hashes.
What a platform template looks like in a real tool#
Product (Backstage Software Templates, as documented on 2026-11-20): a template is an entity with apiVersion: scaffolder.backstage.io/v1beta3 and kind: Template, with metadata, a spec.owner and a spec.type. Its spec.parameters are form steps written as JSON Schema plus ui: keys, and its spec.steps are a list of actions such as fetch:template, publish:github and catalog:register. The shape below is assembled from the documented fields for the intake service. Documented shape; not run here, and not checked by this site's build.
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: intake-service
title: Intake service (PAT-INTAKE-API 2.1.0)
description: Starts a repository the factory fills from a product spec.
spec:
owner: platform-team
type: service
parameters:
- title: Product
required: [productName, owner, repoUrl]
properties:
productName:
type: string
owner:
type: string
repoUrl:
type: string
steps:
- id: fetchSkeleton
name: Fetch the skeleton
action: fetch:template
input:
url: ./skeleton
values:
productName: ${{ parameters.productName }}
- id: publishRepo
name: Publish
action: publish:github
input:
repoUrl: ${{ parameters.repoUrl }}
- id: registerEntity
name: Register in the catalog
action: catalog:register
input:
repoContentsUrl: ${{ steps.publishRepo.output.repoContentsUrl }}
catalogInfoPath: /catalog-info.yaml
Two details come from the documentation and save real debugging. The step ids are camelCase because the page warns that dashes in step ids can make expressions return NaN. And the source pack found two Backstage pages that disagree on the template's apiVersion (backstage.io/v1beta2 on the descriptor-format page); the writing-templates page, quoted above, is the one to follow.
Notice what the template does and does not do. It creates the repository and registers the entity in one run. It does not validate a product spec, it does not run the factory's stations, and it does not re-check the repository next month. A template engine such as Cookiecutter, Yeoman or the Backstage scaffolder is the platform's first-commit service; the factory's pattern and gates still own whether the result is right.
What this is not. This page owns the foundations a factory stands on. The release gates, test tiers and canary of one product are CI/CD and deployment; one change's path from review to production is Diff to Deploy. Who approves a pattern and how exceptions are governed is Enterprise governance. The controls around one coding agent's run are Harness Engineering.
Plug into the delivery platform, or build a new one?#
This page owns one of the site's eleven decisions. A team building its first factory is tempted to build everything it touches: a runner, a store, a registry of what it produced, a dashboard. Most organizations already have most of that.
The question. Should the factory integrate into the existing delivery platform, or bring a new platform of its own?
Diagram: Plug into the delivery platform, extend it, or build beside it
Ask the questions on the left in order. If the existing platform already holds this kind of product and can give the factory a scoped identity, the factory plugs in as one more user. If one capability is missing, extend the platform once for every later factory. Build something new beside the platform only when the product kind does not fit and someone commits to own it after the pilot; otherwise a second catalog and registry drift away from the first.
- Ask in order
- does the platform hold this kind of product?: Services, jobs and contracts like the ones the factory will make.
- can the factory get a scoped identity on it?: Create repositories from the template, push to the registry, register in the catalog, nothing else.
- is exactly one capability missing?: For example a runner for station workers with scoped credentials.
- will someone own a new platform after the pilot?: A named team, a budget, an on-call rotation.
- Least new machinery
- integrate: the factory is a platform user: One catalog, one registry, one gate set; reviews already done.
- extend the platform once: Fill the gap for every later factory.
- build beside it, with an owner: Full control during a pilot, at the cost of a second catalog and registry.
- stop: fix ownership first: A platform without an owner fails the factory that depends on it.
Read the questions top to bottom. If the existing platform already runs builds, stores artifacts and records ownership for products like the ones the factory will make, plug in: the factory becomes one more user, and its outputs look like everyone else's. Build something new only for the parts the platform truly cannot provide, and only with an owner who will run it after the pilot.
| Option | Choose it when | It gives you | It costs you |
|---|---|---|---|
| Integrate: the factory is a platform user | the platform covers the product kind (services, jobs) and accepts new producers | one catalog, one registry, one set of gates; security review already done | the platform's pace and constraints; requests to the platform team |
| Extend: add the missing capability to the platform | one capability is missing (for example a station runner with scoped credentials) | the gap filled once, for every later factory | design and run work for the platform team |
| Build new beside the platform | the products are a new kind the platform cannot hold, or the platform has no owner | full control during a pilot | a second catalog, registry and gate set that drift from the first |
The criteria, in order: does the platform already hold this kind of product; can the factory's identity be given scoped credentials on it; who will own any new piece in a year; and whether the security and compliance reviews already done for the platform would have to be repeated for a new one.
The counterexample. WatchAlgo is a case where building nothing beyond a few scripts was right: one author, static files, no external users. The factory needed a queue, validators and checkpoints, and it had them; a catalog and an approval flow would have cost more than they saved. The enterprise case is the opposite, because the catalog and the approvals are what the security reviewer asks for on Monday.
The failure modes. A factory that builds its own registry produces artifacts the deployment tools cannot find. A factory that keeps its own list of products answers "who has this" for its products only, and the hand-edited copies from the opening story stay invisible. And a factory forced through a platform that cannot hold its product kind gets bent into workarounds, which is the moment to extend the platform instead.
Golden path or a justified deviation?#
The second decision on this page is about staying on the path. A golden path is only useful if most products follow it; it is only honest if some can leave it with a reason.
The question. When a product team wants to leave the golden path, is that a defect to block or a deviation to allow, and how is it recorded?
| Option | Choose it when | Failure mode |
|---|---|---|
| Strict compliance, no exceptions | the rule protects something irreversible (who may decide, masking of personal data) | teams work around the gate instead of through it |
| Deviation with a logged exception | the product has a real need the path does not serve | exceptions pile up unread and never expire |
| Change the path | the same exception is requested by several teams | the path grows switches until nobody can test it |
The criteria: how severe the harm is if the rule is broken; whether the deviation can be checked by a gate anyway; and how many teams are asking. The counterexample is in Example C itself: human_decision_roles: ["underwriter"] admits no exception at all, and the factory refuses a spec that opens the decision route to the agent (test_spec_cannot_open_the_decision_route_to_the_agent). A rule like that belongs in the pattern as enforced code, not on a path a team may leave.
For everything else, an exception is a record, not a conversation. Teaching reconstruction: a minimal exception record a catalog could hold, with an owner, a reason, a compensating check and an expiry date:
{
"exception_id": "EXC-0012",
"product": "endorsement-request-intake",
"rule": "golden path: promote through dev, staging, production",
"deviation": "no staging environment until the partner sandbox exists",
"reason": "the partner offers no test system; staging would call production",
"compensating_check": "contract tests against a recorded fake of the partner API on every change",
"approved_by_role": "platform team",
"expires": "2027-03-31",
"status": "approved"
}
The fields that matter are the last four. A compensating check makes the deviation still testable. An approving role makes it someone's decision. An expiry date makes the platform team look again. A status lets the catalog count open exceptions per rule, which is how a team learns that a rule should change. Enterprise governance owns the approval process and its roles.
In a coding agent. A coding agent such as Claude Code or Codex, running headless as a station worker, is a platform user with unusual habits: it follows the template it is given exactly, and it will also edit generated files if nothing stops it. Give it the same golden path as a person: a checkout created from the repository template, credentials scoped to that repository, and the organization's standard checks, not its own, deciding whether the work advances. The runtime controls around that run are Harness Engineering.
Try it#
The lab opens on the platform view of the synthetic catalog: an authentication fix in the shared middleware. Pick other changes to see which products, owners and approvals each one reaches, and read the products the lab lists as not affected, with the reason.
The table holds the same result for a reader without JavaScript. docs/LABS.md has no plain table for this lab yet, so it was written for this page from the scratch run above of examples/labcore/b_blast.py : radius (change auth-middleware). Counts are the lab's synthetic tests.
| Product | Pattern and version | Owner | Result | Tests selected |
|---|---|---|---|---|
| broker-submission-intake | PAT-INTAKE-API 2.1.0 | submissions team | affected | 4 of 50 |
| claim-notice-intake | PAT-INTAKE-API 2.1.0 | claims team | affected | 4 of 40 |
| endorsement-request-intake | PAT-INTAKE-API 2.0.0 | policy servicing team | affected (same major line) | 3 of 29 |
| loss-run-request-intake | PAT-INTAKE-API 1.4.0 | claims team | not affected: older major line, keeps the old behavior | 0 |
| policy-event-relay | PAT-EVENT-WORKER 1.4.0 | integration team | affected | 2 of 24 |
| audit-export-job | PAT-EVENT-WORKER 1.4.0 | compliance engineering | affected | 2 of 18 |
| running-sum, clamp-list | PAT-ALGO-UNIT 1.3.0 | algorithm content team | not affected: no authentication | 0 |
Totals: patch bump on two pattern lines (to 2.1.1 and 1.4.1), 15 of 206 tests selected, three approvals including the security reviewer. No model takes part in this lab. Where the examples put an agent at a station, the agent there is a scripted stand-in, so these results show how the factory mechanics work, not how good any model is.
WatchAlgo in practice#
WatchAlgo ran without a platform in this page's sense, and its repository shows both why that was reasonable and what it cost.
Observed in the repository (zenalgo-frontend, HEAD 1b183564; docs/EVIDENCE.md rows 15 and 16): there is no test suite in the app's package.json (its scripts are dev, build, start and lint); content checks are validators run by the pipeline. Content is published as static JSON from public/content. The remote holds only main (ea250663, 217 visualizations) while the live site serves content of the 2,162-visualization era, and the sitemap generator is untracked. EVIDENCE.md labels the conclusion an inference: consistent with a command-line deploy of the local working tree, with no deployment record inspected.
Read that through this page's table. There was no artifact registry: the published build cannot be tied to a commit. There was no catalog beyond the folders themselves, though the folder scheme wa-NNNNNN and a work list rebuilt from disk (row 11) did the job of one for a single author. There was no environment configuration problem worth the name, because there was one environment.
Reported by the author: the corpus of 3,246 problems was produced by a repeatable process over long sessions (The WatchAlgo story holds the evidence and its limits). Teaching reconstruction: the smallest platform addition that would have paid for itself is the registry rule "publish from a tagged commit and record the commit in the deployment", which is exactly the row EVIDENCE.md lists as missing.
Enterprise translation#
In the insurer's organization, the platform team owns the intake repository template, the registry, the catalog and the environment definitions; it also owns PAT-INTAKE-API, because the pattern is a platform product. Domain teams own the product specs and rule modules: the submissions team owns broker-submission-intake, the claims team owns its own intake products. The factory is a platform user with its own identity, allowed to create repositories from the template, push artifacts to the registry and register entities in the catalog, and nothing else.
What dominates the critical path is rarely the factory. It is the security review of the factory's identity and permissions, the agreement on which standards are enforced by gates and which are guidance, and the migration of the existing hand-built services into the catalog so that "who has this" includes them. A factory that produces new services into a catalog that does not list the old ones answers the Monday question for the easy half only.
Failure test#
The failure: a product team copies the authentication module out of the template into its own code, so its service no longer depends on the pattern's component. The catalog still says it pins PAT-INTAKE-API 2.1.0. When the platform team ships the expired-token fix, the catalog reports the product as affected, the selective tests run against the pattern's middleware, and the team's copy keeps the old behavior.
How the factory catches it: not by the catalog alone, and this is the lesson. A catalog records declared dependencies; it cannot see a copy. What catches the drift is a gate that checks the product against the pattern on every build: a contract check like Example C's gate_contract, which compares the generated contract with the spec and fails on a hand edit (test_contract_gate_catches_a_hand_edited_contract opens the decision route to broker, drops 403 and adds GET /admin, and the gate fails). A platform that only scaffolds and never re-checks has no defense against the copy.
What to run or toggle: in a scratch copy of Example C, run /opt/homebrew/bin/python3 -m unittest tests.test_factory_gates and read the contract-gate test. In the lab, pick the authentication change and read the not-affected row for loss-run-request-intake: a product that is honestly on an older line is visible; a product that silently forked is not.
Where to go deeper#
- Pattern versus configuration versus business logic (next): what goes in the pattern, what in the spec, what in the product's rule module.
- Factory learning loop: how the version bump and the selective regression suite are computed from the catalog.
- CI/CD and deployment: the gates an artifact passes before it reaches the registry and the environments.
- Enterprise governance: approved patterns, roles and the exception process.
- Scaling safely: scoped credentials and isolation for many factory workers on one platform.
- Diff to Deploy: one change's path through review, CI and production.
- Harness Engineering: the controls around one coding agent's run.
Checklist for Monday#
- List the six foundations and write, for each, what your organization already has and who owns it.
- Make the factory's last station register its manifest (pattern version, spec hash, digests, owner) in the catalog.
- Store every factory output in the registry by digest; never let a deployment pull an unregistered build.
- Keep per-environment values out of specs and templates; keep product behavior out of environment configuration.
- Put rules that admit no exception into the pattern as enforced code; give every other deviation an exception record with an expiry date.
- Add a gate that re-checks products against their pattern on every build, so a copied component shows up.
Exercises#
- A team asks to raise the provider retry limit from three to five attempts in production only. Environment configuration or product spec?
Answer 1Product behavior, so the spec
The retry limit is product behavior (Example C declares it in external_systems.roof_assessment_provider.retry in the spec) and is tested by the factory's tests. Changing it per environment would mean production runs behavior that no test environment ran.
- The catalog says nine services pin
PAT-INTAKE-API, but the registry shows builds for eleven. What do the two extra builds tell you?
Answer 2Unregistered producers
Something is publishing builds without registering them: a hand-built service, a forked copy or a second factory. Until they are in the catalog, no change to the pattern will reach them through the normal process.
- Why is "only an underwriter may record a decision" not a candidate for a logged exception?
Answer 3Irreversible harm
Breaking it lets a non-person or an unauthorized role decide an insurance outcome, which no compensating check repairs after the fact. Rules of that kind are enforced in the pattern, and the factory refuses a spec that breaks them.
Advanced perspective#
The platform as a product, and how to tell if it worksUsers, measures, and what the factory adds to them
Guideline (CNCF Platforms White Paper, read 2026-11-20): the paper lists seven attributes of a platform, starting with "platform as a product" and including self-service, reduced cognitive load, optional and composable, and secure by default. It says platform teams own interfaces and experiences (portals, APIs, templates, command-line tools), not necessarily the infrastructure, and should build a capability themselves only when no provider can supply it. For measuring success it names user measures (active users and retention, surveys, SPACE-framework productivity measures) and organizational ones (request-to-fulfillment time, time to deploy a new service, time for a new user to submit a first code change), and it cites the four DORA delivery measures by their older names.
A factory changes what those measures mean. "Time to deploy a new service" can drop sharply when a factory fills a template from a spec, while the time to an accepted, reviewed, approved service barely moves because approval dominates. Measure both. Factory quality engineering is the home of lead time and cost per accepted unit; the platform team should report the platform's measures with the factory's outputs counted separately, so a fast generator does not hide a slow review queue.
The paper also says it should be read alongside the later Platform Engineering Maturity Model; that page was not read for this site.
Where the catalog's truth livesDescriptor files with the code, registration by the factory, drift checks
A catalog that someone edits by hand in a web form drifts within months. Product (Backstage Software Catalog, as documented on 2026-11-20): metadata YAML files stored with the code in source control are the source of truth; entities are registered manually, automatically when created by a Software Template, or through static locations in configuration. The recommended file name is catalog-info.yaml, and a Component requires spec.type, spec.lifecycle and spec.owner.
The factory-specific design follows from that. The descriptor is a generated artifact: the factory writes it from the spec and the pattern (owner, pattern id and version, spec hash), commits it with the product, and the catalog reads it. A hand edit to the descriptor is then a difference between a generated file and its source, which the same contract-style gate that protects the API contract can catch. Two consequences to plan for: products the factory did not build need descriptors written once by people, and the catalog must distinguish "declared" from "verified by the last build", or the Monday answer is a list of claims.
Environment names versus environment valuesWhy the rollout manifest's three names are not configuration
Example C's spec lists environments: ["dev", "staging", "production"] in its rollout section. Those are stages of promotion, a process decision. The values a service needs in each (hostnames, credentials, the provider endpoint) appear nowhere in the example, correctly: the provider is a stub and the tokens are demo strings.
Guideline (The Twelve-Factor App, "Config", read 2026-11-20): config is everything likely to vary between deploys, stored in environment variables, and each variable is managed independently per deploy rather than grouped into named environments, which the page says does not scale cleanly. That is compatible with promotion stages: the stage names say where a build goes next; the variables say how it connects there. The page's test is whether the codebase could be made open source at any moment without compromising any credentials. For a factory the corresponding rule is stricter: no credential may appear in a spec, a template, a generated file or a prompt. Example C's forbidden-secrets gate scans every file for credential shapes and allowlists only tokens with the DEMO-NOT-A-SECRET- prefix; a real platform puts the scan in the standard checks, so every factory gets it.
Who pays for the platform the factory needsAmortizing core assets, and the cost of a second catalog
Guideline (SEI Software Product Lines, read 2026-11-20): the SEI material lists core assets amortized across products, among them architecture, test plans, processes and tools, and names "core asset development" as one of three essential activities, alongside product development and management. A platform is a core asset in that sense, and its cost is justified across many products, not by the first one.
The trap for a factory pilot is to account the other way: the pilot builds its own runner, registry and product list because the platform team's queue is long, and the pilot looks cheap. The cost appears later, as a second catalog that the security reviewer does not trust, artifacts the deployment tools cannot find, and a migration onto the platform after the pilot succeeds. A sounder plan budgets the integration work (an identity for the factory, a registry namespace, a catalog descriptor) into the pilot, and builds new only what the platform truly lacks. Design an enterprise software factory covers pilot selection.
In one breath#
A factory builds products; a platform makes them findable, storable, configurable and owned. Each foundation answers one question and leaves others alone: the golden path sets the route, standards say what must hold, the repository template writes the first commit, the registry keeps builds immutable by digest, environment configuration holds what varies per deployment, and the catalog says what exists and who owns it. None of them decides a business rule, and a catalog without a re-checking gate cannot see a copied component.
The intake service now has a place in the organization: a template to start from, a registry for its builds, a catalog entry with an owner. What the platform cannot tell you is which parts of the service belong to the shared pattern, which are per-product settings, and which are business logic that must never be shared. Pattern versus configuration versus business logic draws those three lines in Example C's own files.