Artifacts & the DAG

Everything in Waypoint starts with an artifact. An artifact is a small, schema-validated document — JSON in nearly every case, plus a single markdown idea seed — that captures one unit of intent. A persona. A pain point. A requirement. A bounded context. A feature. A flow. Each is pure data with no logic, and each conforms to a JSON Schema that defines exactly what fields it may carry and what they mean.

Artifacts are never a freeform pile of documents. They are nodes in a workflow DAG — a directed acyclic graph whose edges encode which artifacts depend on which. That graph is the spine of the whole system: it determines the order you author things, what "coherent" means, and, when you change one thing, exactly what else is now in question.

What an artifact is

A single artifact is deliberately small. The discipline is one-unit-of-intent-per-document: a persona artifact describes one persona; a requirement artifact states one requirement. This granularity is what makes the rest of the machinery work — references between artifacts resolve to a specific node, and a change to one artifact has a precise, traceable blast radius rather than a diffuse one.

Every artifact is identified by a content hash. The repo-root waypoint.json manifest maps each artifact's (workflow, path) to its hash and is the authoritative committed index of what artifacts exist. Because identity is content-addressed, checking out an old commit restores the exact historical artifact state — the manifest pins everything by hash.

:::note Terminology "Artifact" and "waypoint" refer to two sides of the same thing. A waypoint is a type of deliverable — a node type in the workflow DAG with defined input/output schemas. An artifact is a concrete instance of that type, the actual data you author. The glossary in Validation and the CLI Reference use both terms. :::

The workflow DAG (the embedded metagraph)

The set of artifact types, the dependency edges between them, and the validation rules over those edges are declared together in a single structure called the metagraph. It is embedded directly into the CLI binary, so the definition of "what a valid project looks like" ships with the tool rather than living loose in a config you could drift from.

One workflow describes one domain. The software workflow — the one these docs cover — currently defines dozens of artifact types organized into five sections that read top-to-bottom as the narrative of building a system, preceded by a single human-authored input.

You can always discover the live, authoritative types for your installed CLI:

waypoint workflow types software

See the CLI Reference for the full command surface. The sections below describe the shape of the graph; the CLI is the source of truth for the exact current set.

The sections and their types

The software workflow groups its artifact types like this. Representative types are listed for each section — not every type, since the catalog evolves.

Section	What it asserts	Representative artifact types
Input	the human's seed	idea (markdown)
Discovery	we understand the user and the problem	persona, pain_point, user_goal, product_goal
Requirements	every claim we make is checkable	requirement (EARS-based)
Architecture	the system has the shape we say it has	architecture, component, data_flow, plus the bounded-context / hexagonal subtree
Interface	every user-touchable surface exists in code	ui_app, slice, segment, cli_command, mcp_tool, api_endpoint
Features	every promise is demonstrable end-to-end	feature, scenario, flow, test, demo, tour

Input is the one human-authored seed: a single idea markdown document that every other artifact ultimately traces back to.

Discovery establishes who the system is for and what hurts: persona, pain_point, user_goal, product_goal.

Requirements turns those goals into checkable statements. The requirement type is EARS-based — the Easy Approach to Requirements Syntax, the "When <trigger>, the system shall <response>" template — so each requirement is a precise, testable claim rather than a vague wish.

Architecture is the largest section. Beyond the top-level architecture, component, data_flow, and integration types, it contains a Domain-Driven Design / hexagonal subtree describing the intended shape of the code:

• A bounded-context core: bounded_context, domain, application, aggregate, entity, domain_event, domain_service, domain_error, and a values collection.
• An application layer: command, query, command_handler, query_handler, event_subscriber, saga.
• Ports and adapters (the hexagonal boundary): driving_port, driven_port, driving_adapter, driven_adapter.
• Architecture tests: aggregate_test, port_contract_test, architectural_test.

Interface covers every surface a user or another system can touch. It uses Feature-Sliced Design for UIs — a ui_app is the composition root, a slice is a vertical page/widget/command cut, and a segment is the per-concern leaf (ui / api / model / lib / config) — alongside cli_command, mcp_tool, and api_endpoint for non-UI surfaces.

Features ties everything back to demonstrable behavior: feature, scenario, flow, test, demo, tour. A feature must have flows; a scenario leads to tests and demos; a flow yields a tour.

Dependency edges: downstream depends on upstream

An edge in the DAG means "this artifact requires that one to exist first." Read top-down, the edges are the generation order — you author intent from the top and each level is a function of the levels above it. A few illustrative chains:

idea ─► persona ─► pain_point ─► user_goal ─► feature ─► scenario ─► test ─► demo
                                          │
idea + product_goal + user_goal ─► architecture ─► component
                                              └──► bounded_context ─► domain ─► aggregate
architecture ─► driving_port ─► driving_adapter
architecture ─► driven_port  ─► driven_adapter
command ─► command_handler          query ─► query_handler
interface ─► ui_app ─► slice ─► segment
flow ─► tour

This ordering is what makes "regenerate only what an edit touches" possible. Because the graph records exactly what depends on what, Waypoint can compute the blast radius of any change: edit one upstream artifact and it knows precisely which downstream artifacts — and which slices of code — are now in question.

The principles the DAG enforces

The graph is not just an ordering convenience. Several properties are checked over it, and they are what "coherent" actually means in Waypoint.

Schema conformance

Every JSON artifact must validate against its schema. This is the floor: an artifact that doesn't conform isn't a valid node at all.

Cross-reference integrity

Artifacts reference each other by slug (a pain_point cites the persona that feels it; a requirement traces to a user_goal). Every such reference must resolve to an artifact that actually exists. Dangling references are a coherence failure.

Orphan detection

The graph is checked for orphans — nodes with no path connecting them to the rest of the intent. A persona nobody designs a flow for, a pain point that leads to no user goal, a user goal that connects to no feature: each is a sign that the intent is incomplete, and each is flagged.

Mutation, not accumulation

This is a philosophical stance, and it matters. The artifact set is not an append-only log of every decision ever made. It is a live, normalized model of present intent — always "what we mean right now." The git history is the history; the artifacts are the current truth. When intent changes, you mutate the artifact rather than stacking a new one on top, and let the consequences propagate.

The coherence / cascade rule

The propagation is the cascade rule: when an upstream artifact changes, review cascades downward through the DAG, and you fix artifacts before changing code. A change to a user_goal invites review of the features that depend on it, the requirements that trace to it, and so on down the graph. The DAG tells you exactly how far the review has to reach — which is the same blast radius the validator uses.

tip

The cascade rule is the day-to-day heart of working in Waypoint. The Authoring Workflow walks through it in practice, and Epistemic Validation explains how the validator turns these principles into a machine-checkable proof.

Where to go next

• Epistemic Validation — how waypoint validate turns these coherence principles into a signed, machine-checkable proof certificate.
• The Authoring Workflow — authoring artifacts in DAG order and living with the cascade rule.
• CLI Reference: Projects & Artifacts — the commands for listing types, reading, and authoring artifacts.