Skip to main content

Waymark: leave a trail your agents can follow.

CI PyPI Python 3.11+ License: MIT

Waymark is spec-driven development built on living specs: plain markdown in your repository that says what your system does today. Every change starts as an edit to those specs, and nothing is built until you've approved it. Then each task goes to a fresh agent that works from the written change alone, and the riskier ones are checked by a second agent that never saw how they were built. A small command-line tool, wm, keeps track of where it all stands.

See it in action

# /wm-explore (optional): think the idea through with the agent

$ wm new change add-result-limit
Created the change "add-result-limit" with a proposal to draft.

# /wm-propose: the agent drafts the proposal, a spec delta, the design
# and the task list, with a review level for each task

$ wm status
── Changes in flight ───────────────────────────────────────────────────
  add-result-limit         planned    ░░░░░░░░░░ 0/2    ◆ accept (you)

◆ 1 thing needs you: wm inbox

$ wm accept add-result-limit
Accepted "add-result-limit". Its items can now be applied.

# /wm-apply: a fresh agent builds 1.1 from the change alone and ends with
#   RESULT: done: capped after sorting; the fifty-one-match test passes
# A reviewer agent that never saw the build checks it and ends with
#   VERDICT: pass: cap and order hold; the scenario is covered by the test
# wm writes both under 1.1. Then 1.2 is built; it needs no review.

$ wm status
── Changes in flight ───────────────────────────────────────────────────
  add-result-limit         applied    ██████████ 2/2    ◆ archive (you)

◆ 1 thing needs you: wm inbox

$ wm archive add-result-limit --outcome "Searches return the fifty best matches."
Archived "add-result-limit" as changes/archive/2026-01-15-add-result-limit. Its deltas are now part of the specs.

The files behind it, all plain markdown in waymark/:

changes/add-result-limit/proposal.md
# Add a result limit

Owner: Alex Example
Accepted: 2026-01-15 by Alex Example (fingerprint: 6cec39a287bf99f2)

## Why

Searches that match thousands of documents return all of them,
and the results page slows to a crawl.

## What changes

A search returns at most fifty results, best matches first.

## Non-goals

Paging through the rest.

## Impact

Specs: search.
changes/add-result-limit/specs/search.md, the spec delta
# Search

## Purpose

How a search finds and returns documents.

## Added requirements

### Requirement: Result limit
A search SHALL return at most fifty results.

#### Scenario: Many matches
- GIVEN an index where a query matches more than fifty documents
- WHEN the search runs
- THEN the fifty best matches come back
changes/add-result-limit/design.md
# Design

## Context

Results are sorted by relevance before they are returned.

## Approach

Cut the sorted list at fifty, in the search service.

## Decisions

### Decision: Where to cut

- Options: in the database query, or after sorting
- Choice: after sorting
- Why: the order has to be final before the cut

## Risks and trade-offs

Sorting every match still costs memory on very large result sets.
changes/add-result-limit/tasks.md, with what wm recorded
# Tasks

## 1. Limit

- [x] 1.1 Cap the result count   `review: independent`
  - Criteria: at most fifty results come back, best first
  - Verify: a test searches an index with fifty-one matches
  - (review) 2026-01-15 pass: cap and order hold; the scenario is covered by the test
- [x] 1.2 Name the limit in the help text   `review: none`
  - Criteria: the search help says fifty
specs/search.md, the living spec after archive
# Search

## Purpose

How a search finds and returns documents.

## Requirements

### Requirement: Result limit
A search SHALL return at most fifty results.

#### Scenario: Many matches
- GIVEN an index where a query matches more than fifty documents
- WHEN the search runs
- THEN the fifty best matches come back

Real output of this version of wm on a generic change, generated by tools/docs.py. The comments mark where an agent works.

Why Waymark

  • Agents only know what's written down. Each task is built by a fresh agent from the written change alone. When something is missing, it reports a spec gap instead of guessing.
  • Review is recorded. Each task is checked against its criteria, by your session for routine work or by an independent reviewer agent that never saw the build, and the result is written right under the task.
  • Pick up anywhere. wm works out where things stand from the files and git, in any session, on any machine.
  • Two sign-offs, both yours. Agents draft every file and write the code. You approve each change before it's built, and again when it's archived.
  • Light for small changes, thorough for big ones. A small change takes the short path: a proposal, a task list and a quick self-check. A bigger one adds a design, and its riskier tasks get a second agent as an independent reviewer.

In Claude Code, these rules are enforced by hooks, not just asked for. See what's enforced, and where.

Quick start

pipx install waymark-cli     # or: uv tool install waymark-cli
cd your-project
wm init

Then, in Claude Code:

  • /wm-kickoff drafts your project's charter with you.
  • /wm-onboard takes one real, small change on your own code through every step.

From then on: /wm-propose to start a change, /wm-apply to build it, /wm-archive to finish it. wm status shows where things stand, and wm inbox shows what needs you. Note that the package is waymark-cli; the command is wm.

Who it's for
  • Solo developers building real projects with coding agents.
  • Small teams (roughly two to five) sharing one record across branches.
  • Projects split across repositories, such as a frontend and a backend, with one record in an atlas (guide).
  • New and existing codebases. Specs grow where work happens; nothing is reverse-engineered up front.

It's not for handing over a goal and walking away, for throwaway scripts, or for organizations that need access control or approval chains.

What it costs

Agents write every artifact and all the code, on your own agent tool and plan; wm never calls a model. You approve each change twice, and settle what wm inbox lists: spec gaps, blocked items, reviews that failed twice. Time and token figures will come from using Waymark on itself; none are claimed before they're measured.

What's enforced, and where
Enforced by What Holds in
wm, the git hooks and CI Nothing is built before acceptance; archive refuses unbuilt or unreviewed items; conflicting changes are caught; record health; commit-message format Every agent tool
Claude Code's hooks Only you accept a change or override a missing review; implementers edit only code (in their item's repo) and their notes; reviewers edit nothing; delegated agents can't commit, push or write the record; results are recorded from the agents' own words Claude Code

These are guard rails against mistakes and shortcuts, not security against someone set on getting around them.

Teams: each change has one owner and its own branch. Two changes that touch the same requirement are reported, and the second must be revised before it's archived. Conflicts are caught on the merged tree, not before merge. The independent reviewer is always an agent.

Learn more

Works with Claude Code. Version last verified: 2.1.325, on Windows.

License

MIT

Metadata

Release files for waymark-cli 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for waymark-cli 0.1.1
File Size Uploaded Provenance Actions
waymark_cli-0.1.1.tar.gz 284.2 kB With provenance Details for waymark_cli-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for waymark-cli 0.1.1
File Interpreter ABI Platform Actions
waymark_cli-0.1.1-py3-none-any.whl Python 3 none any Details for waymark_cli-0.1.1-py3-none-any.whl

Total release size: 446.1 kB

Release files / waymark_cli-0.1.1.tar.gz

Download URL waymark_cli-0.1.1.tar.gz
Size 284.2 kB
Tags Source
SHA-256 checksum
How to use checksums
0a6519c6200d96e1b76c6e64130fa6c28fe934a50341ed530a665f3b09556179
BLAKE2b-256 checksum
How to use checksums
9bfed5f8f4804e96e8d13e39e2dd103d7c6d394ba3647a314f8e7b006f12f3a8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / waymark_cli-0.1.1-py3-none-any.whl

Download URL waymark_cli-0.1.1-py3-none-any.whl
Size 161.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d803e6ff1b90725c0de2fbad2e358479df3e40c5b12b6c6daa9897be01ab7642
BLAKE2b-256 checksum
How to use checksums
65fa4e9b47c2cc847dafe1ac8c1631362be8c2b12365a2503917a358dc12dfe6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for waymark-cli 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for waymark_cli-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page