Skip to main content

The Authoring Workflow

The two preceding pages describe the structure — artifacts and the DAG — and the judgment — epistemic validation. This page is about the practice: how you actually work in Waypoint day to day, and how a coding agent works alongside you.

The short version: you author intent top-down through the DAG, you fix artifacts before you change code, and you let the cascade rule and the validator tell you what your edit touched. For a hands-on first run, start with Author Artifacts in Getting Started.

Author in DAG order, top-down​

Every change starts with intent, authored as artifacts in dependency order. You don't begin with code; you begin at the top of the graph and work down, because each level is a function of the levels above it:

idea ─► discovery ─► requirements ─► architecture ─► interface ─► features
  1. Idea. A single markdown seed: what you're building and why.
  2. Discovery. Who it's for and what hurts — personas, pain points, user goals, product goals.
  3. Requirements. Each capability as a checkable EARS requirement ("When <trigger>, the system shall <response>").
  4. Architecture. The shape of the system — components, bounded contexts, ports and adapters.
  5. Interface. Every user-touchable surface — UI slices and segments, CLI commands, API endpoints, MCP tools.
  6. Features. The end-to-end promises — scenarios, flows, tests, demos, tours.

Stop and iterate at each level​

You don't sprint to the bottom. The discipline is to stop and iterate at each level before descending: get discovery coherent before you write requirements, get requirements coherent before you commit to an architecture. Validation at each level tells you whether you're ready to go deeper. Authoring schema-validates as you write, so a malformed artifact is caught immediately; the fuller coherence check (cross-references, orphans, structural integrity) tells you whether the level hangs together before you build on it.

tip

Working top-down feels slower for the first hour and much faster forever after. An incoherent upstream artifact doesn't just cost you that artifact — it costs you everything downstream that was generated from a wrong premise. Fixing intent before code is the entire point.

Fix artifacts before code, and let the cascade run​

When intent changes, the rule is mutation, not accumulation: you edit the artifact to reflect what you now mean, rather than stacking a new decision on top of the old one. Then the cascade rule takes over — review propagates downward through the DAG to everything that depended on what you changed, and you fix the artifacts before you touch the code.

Concretely, the loop after any change is:

  1. Edit the upstream artifact to reflect current intent.
  2. Run waypoint validate. Because verdicts are memoized by input hash, only the rules that read your changed file recompute — so this is fast even on a large project. The proof tree shows you exactly which downstream conclusions are now in question.
  3. Walk the cascade. Fix each affected downstream artifact so the set is coherent again.
  4. Then, and only then, reconcile the code — regenerate or hand-edit the slices the DAG flagged as touched.

The DAG is what makes this tractable: it tells you the blast radius of your edit, so you reconcile exactly the touched subgraph instead of re-reviewing the whole project. And because waypoint validate is read-only — it never writes source — you can run it as often as you like through this loop without it ever clobbering your work. See Epistemic Validation for how the proof tree and memoization make this loop cheap and honest.

The store model at a glance​

Where do artifacts actually live? Waypoint is content-addressed end to end, and there are two store modes.

  • Customer mode (the canonical path). Artifact content is stored canonically in S3, addressed by content hash. Your repo commits only the waypoint.json manifest — one row per artifact, mapping (workflow, path) → hash. The actual content is pulled on demand into a local cache at ~/.waypoint/cache/.
    • waypoint pull warms that cache, fetching every blob the manifest names.
    • waypoint push uploads every blob the manifest names that S3 doesn't yet have.
  • Dogfood mode (transitional). An on-disk .waypoint/software/artifacts/ mirror, kept while the project's own contributors migrate to customer mode. It will disappear from version control once that migration completes; customer mode is the destination.

In both modes, waypoint.json is the authoritative index — its (path → hash) entries are the source of truth for what artifacts exist. A pre-push git hook runs waypoint push before your push reaches the remote, so a teammate never sees a manifest hash without a blob behind it. Because identity is content-addressed and the manifest is committed, checking out an old commit restores the exact historical artifact state.

note

The manifest is the contract. Whatever store mode you're in, treat waypoint.json as the thing that says what your project's artifacts are — the content is just bytes addressed by the hashes it pins.

The coding agent and MCP tools​

Waypoint is additive, not substitutive — you keep Cursor, Claude Code, or Copilot and add Waypoint on top. The agent doesn't get replaced; it gets a ground truth to anchor against.

The agent authors and reads artifacts the same way you do, through MCP tools that expose the artifact store and the workflow graph. A typical agentic loop looks like:

  1. Discover the workflow — query the live artifact types and the dependency graph so the agent knows what to author and in what order.
  2. Author or edit artifacts in DAG order, top-down, the same discipline a human follows.
  3. Validate — call waypoint validate as a read-only oracle. The proof tree is the agent's answer key: instead of asking "does this look right?", it asks "does the root claim hold, and if not, which node failed?"
  4. Read the failure, fix the named artifact or stub, re-validate. Because the validator localizes failures and never overwrites source, the agent can lean on it as hard as it wants and drive itself down the DAG.

This is the division of labor Waypoint is built for: the human moves up to intent — authoring and curating artifacts and approving the proof tree — and the agent runs long stretches of execution against a fast, read-only, self-explaining oracle. Why Waypoint makes that argument in full.

Where to go next​