Skip to main content

Author your first artifacts

With your project created, you're ready to author its intent. The things you author are artifacts (sometimes called waypoints, after the nodes in the workflow DAG). They are small, schema-validated documents — a persona, a requirement, a bounded context, a feature — not free-form prose.

note

"Artifact" and "waypoint" mean the same thing here. The word token in Waypoint refers to an authentication credential (the bootstrap token / API key from earlier steps), not to the documents you author. Don't conflate the two.

How authoring actually works​

You author artifacts by working with your coding agent, not by hand-editing files one at a time. waypoint init already installed the Waypoint MCP server into your agent client and added a mode-specific agent skill plus an AGENTS.md working block. So the loop is:

  1. Open your agent in the repository. For example, run claude (Claude Code), cursor ., or zed . in the project directory.

  2. Let the agent walk the DAG. Guided by the installed skill, the agent authors artifacts top-down in dependency order, stopping to iterate with you at each level:

    idea
      → personas / pain points / user goals / product goals
        → requirements (EARS)
          → architecture (components, data flows, integrations, bounded contexts…)
            → interfaces (UI apps, CLI commands, MCP tools, API endpoints…)
              → features (and their flows)

  3. The agent writes each artifact through the Waypoint MCP tools. The MCP server exposes four CRUD tools — artifact.put, artifact.get, artifact.list, and artifact.delete. A put writes the artifact's content and atomically updates waypoint.json in the same step.

The metagraph is the source of truth for the type catalog and dependency order. You can enumerate the types for the software workflow at any time:

waypoint workflow types software

See Artifacts & the DAG and The Workflow for the deeper model.

Prove coherence with waypoint validate​

As you author, run validation to confirm your artifacts are coherent:

waypoint validate

This checks schema conformance, cross-reference integrity, orphan detection, structural integrity, and requirement coverage, and emits a proof certificate (waypoint.proof.json) recording why the verdict holds. Run it before you commit. See Validation for the model and the CLI validation reference for every flag.

Cache, upload, and render​

A few CLI commands keep your local cache and the hosted service in sync:

  • waypoint pull warms your local cache (~/.waypoint/cache/) by downloading only the artifact blobs that waypoint.json names and that you don't already have. Run it after git pull brought in a teammate's artifacts, so the next validate doesn't make per-artifact round trips.
  • waypoint push uploads every artifact blob that waypoint.json names and the service lacks. You rarely run this by hand — the pre-push git hook installed by init runs it automatically, so other users never see a hash without its content.

Commit and push​

Finish by committing and pushing. The git hooks validate your artifacts and upload their content; once the push lands, the web app renders your graph:

git add . && git commit -m "feat: initial waypoint artifacts" && git push

That's the full loop: author with your agent, waypoint validate to prove coherence, commit and push to render. From here: