Skip to content
Wayland Docs

AGENTS.md and Project Context

Wayland Core loads project-specific instructions automatically. Before a run, it walks the working directory up toward the filesystem root and concatenates every project-context file it finds along the way, so the engine knows your conventions without you pasting them into every prompt.

What gets loaded

Section titled “What gets loaded”

At each directory from the working directory up to the filesystem root, the engine reads any of these files it finds:

  1. WAYLAND.md
  2. AGENTS.md
  3. .wayland/context.md
  4. CLAUDE.md

Every file found is concatenated, root first, so instructions from a repository root and a subdirectory both apply rather than one overriding the other. AGENTS.md is the open, shared convention; the engine reads it the same way it reads WAYLAND.md, so a repository that already has an AGENTS.md works without extra setup.

See what will be loaded

Section titled “See what will be loaded”

The project-context subcommand prints the resolved context for the current directory, so you can confirm what the engine will inject:

Terminal window
wayland-core project-context

Run it from different directories in a repository to see which file the walk resolves to from there.

Scaffold a new project

Section titled “Scaffold a new project”

init writes a starter .wayland/config.toml plus a WAYLAND.md template at the project root:

Terminal window
wayland-core init

It is non-interactive and idempotent: existing files are preserved and reported as skipped. To overwrite, pass --force. To set the starter model, pass --model (otherwise it reads WAYLAND_MODEL, then falls back to a placeholder). To write only the config and skip the context template, pass --skip-context:

Terminal window
wayland-core init --model claude-sonnet-4-6
wayland-core init --skip-context
wayland-core init --force

What goes in the context file

Section titled “What goes in the context file”

Keep WAYLAND.md (or AGENTS.md) focused on what the engine needs to know about this project: build and test commands, directory layout, house style, and anything it should never do. Because the file is loaded fresh on each run, edits take effect on the next invocation with no restart.

Next

Section titled “Next”