One archetype, one artifact

I called what the archetype generated a "product." I was wrong, and it took me three months to see it. An archetype doesn't produce a product — a product requires market fit, positioning, GTM, a negotiable roadmap, a relationship with users. An archetype produces an artifact: the deterministic output of executing a declaration against a context. Confusing the two led to a sequence of wrong expectations I'm still cleaning up.

The vocabulary mistake was small. The downstream consequences were not. Stakeholders started asking when the next version would ship. Engineers started hand-editing generated files because that's what you do with a product. Roadmaps got drafted for things that don't have roadmaps. None of it was anyone's fault — they were responding correctly to the name I gave them.

The Pattern in One Line: Grammar -> Production

An archetype is a versioned grammar. It declares the expected shape of a certain type of system — what layers it has, what cross-cuts it must include, what contracts it exposes, what tests it must pass.

An artifact is what materializes when you execute the grammar against a concrete context — a specific client, a specific set of templates, a specific deploy target.

The concrete example I keep going back to: the notifications_engine archetype produces rlabs-notifier as one of its artifacts. The artifact is a NestJS service plus Postgres schema plus tests plus docs plus observability plus k8s manifests. One declaration, one production. There are no manual steps in the middle, no "and then a developer wires it up."

Grammar in, production out. That's the whole shape.

Why "Product" Was the Wrong Name

The word product carries commercial weight that misleads the conversation. A product has a market. A product has users. A product is monetized, positioned, negotiated. A product has a roadmap that's argued about in meetings and adjusted based on feedback.

An artifact generated by an archetype has none of that. Its roadmap is the archetype's version number. When the archetype goes from v1.2 to v1.3, the artifact gets regenerated. There isn't a separate negotiation about what the artifact should do next — the artifact does what the current grammar says it does.

The word also implies uniqueness — one product, one proposition. An archetype can generate N artifacts of the same type, deployed to different clients with different configurations, all shaped identically. They aren't N products. They're N artifacts of one grammar.

This is where the stakeholder confusion came from. People started asking "when do we ship rlabs-notifier v2?" The right answer turned out to be "when we publish notifications_engine v2 and regenerate." That answer only makes sense if the vocabulary is right. Otherwise it sounds like deflection.

There's also a quieter consequence on the engineering side. When something is called a product, engineers treat its quirks as features — "oh, that's how rlabs-notifier handles retries, it's intentional." When something is called an artifact, the same quirk reads as drift — "the archetype must be wrong if it produces this." The default disposition toward the same code changes based on the noun. I didn't expect that, and once I saw it I stopped pretending the name was harmless.

What Comes in the Artifact the Archetype Produces

The artifact isn't a code skeleton. It's the whole deployable system, including the parts engineers usually forget the first time. From the notifications_engine archetype, every artifact ships with:

• Service code organized as a pure hexagonal domain (zero framework imports inside the domain layer) plus adapters for TypeORM, NestJS, nodemailer
• A database schema with versioned migrations
• A three-layer test suite: unit tests against the domain, integration tests against the adapters, contract tests against the API
• Generated documentation: the .atalaya/*.md files, a minimal README, an OpenAPI spec
• Observability: structured logs in the project's standard shape, Prometheus metrics, healthchecks
• k8s manifests targeted at Cloud Run or k3s depending on the deploy context, a secrets template, a CI pipeline
• The cross-cuts ADR 0009 declares mandatory: idempotency, audit log, consent integration

That last category — the cross-cuts — is what separates an artifact from a code generator. A code generator would emit the skeleton and let the engineer remember to add idempotency. An archetype declares idempotency as part of the shape, and the generated artifact has it whether the engineer remembered or not.

The First-Generation Test: rlabs-notifier in X Hours

The first time I ran this end-to-end, I wanted to prove the loop closed. So I declared the notifications_engine archetype with concrete specs — 34 templates, multi-channel delivery, logical opt-out semantics — and ran the AgentGuard pipeline once. Four stages: skeleton, contracts, wiring, logic.

The output was rlabs-notifier, deployable on Cloud Run, with a domain layer that had zero framework imports when I grepped it. The integration tests passed against a docker-compose Postgres on the first run. The OpenAPI spec described what the service actually did.

What the archetype did not do is worth naming. It didn't decide the template copy — the actual text of the emails. It didn't design the brand. It didn't negotiate Google Workspace SMTP pricing. None of those are grammar. All of them are product decisions, and they happened in parallel with humans doing the work humans should do.

The Second Artifact From the Same Archetype

The proof the pattern was real came on the second artifact. An internal client needed another notifications service — different templates, different SMTP from their own workspace, different deploy target.

I re-ran the archetype with the different context. Out came a second artifact, deployed separately, identical in shape, different in configuration. Zero code copy-paste between the two. Divergence is controlled at the archetype level, not at the artifact level.

The property this gives you is the one I cared about most. When I find a bug — say, an idempotency edge case — I fix it in the archetype. Then I regenerate both artifacts. Neither artifact has a special patch. Neither one drifts. Both inherit the fix at the next regeneration. That's the discipline cost paying off.

The inverse property matters too. If a client asks for a feature that's specific to them, it does not go in the archetype. It goes in their configuration, or it stays out. The archetype is what's shared across all artifacts. Polluting it with client-specific logic destroys the whole pattern — within three or four artifacts you've rebuilt a fork-and-modify codebase with extra ceremony. The discipline is constant: every change request gets the question "is this a grammar change or a context change?" before anything gets edited.

What I Learned From the Vocabulary Shift

The vocabulary change had real organizational effects that I didn't predict.

Platform teams responded differently to the word artifact than to the word product. They understood immediately that this was regenerable output, not an MVP they should treat as a precious thing. The disposability is built into the name.

Commercial teams stopped asking the artifact for feature requests. They learned to redirect those requests upstream, to the archetype. "This needs to support webhooks" became "can we add webhook support to the notifications_engine archetype?" The framing put the conversation in the right place.

Onboarding improved. New engineers learned "this is an artifact, don't touch the generated files — propose changes to the archetype." The default behavior with generated code is to hand-tune it the first time a small thing is wrong. The name resists that.

The name disciplines you. When you call it an artifact, you don't hand-tune the generated code. When you call it a product, you do. Same code, different psychology.

What Does Require Human Intervention (And Why)

There's a clean line between what belongs in the archetype and what doesn't. The rule I settled on is small: if the decision depends on the market or the client, it does not go in the archetype.

Things that stay outside the archetype, that humans own:

• Pricing, positioning, market fit, negotiable roadmap — the actual product layer
• Runtime configuration: secrets, client-specific environment variables, integrations with their identity providers
• Anything you can't infer from the grammar: the brand voice in templates, promised SLAs, the legal contracts that govern the service

The archetype isn't trying to replace these. It's trying to make sure they're the only things humans are working on. Everything else — the layers, the wiring, the cross-cuts, the observability — comes out of the grammar.

The boundary is sharper than it sounds. The moment you put market-shaped logic into the archetype, you've made it impossible to reuse for the next client. The moment you put grammar-shaped logic into the artifact, you've made it impossible to regenerate. Keeping the two cleanly separated is a daily discipline, not a one-time decision.

Transferable Principle

If you call "product" something that's the deterministic output of a declaration, you'll confuse yourself and your team. The mismatch shows up as wrong roadmap conversations, hand-edits of generated files, version-number conflicts, and a vague sense that the artifact never quite acts like a product should.

Archetype is grammar. Artifact is production. Product is still the commercial thing — the wrapping around the artifact that gives it a market.

When you can regenerate something from a versioned declaration, it's no longer a product — it's an artifact. And that changes how you govern it, how you version it, and what you ask of it. The change is in the vocabulary first; the rest follows.

What in your org do you call "product" when it's really the deterministic output of a declaration — a terraform module, a helm chart, a generated service? Changing the name can save you a quarter of confused conversations. Send me a DM or reach out via the contact channels at rlabs.cl.

#AgentGuard #MetaSoftware #Architecture #Engineering #DeveloperExperience