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, in 0.1.1. 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.0

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.0
File Size Uploaded Provenance Actions
waymark_cli-0.1.0.tar.gz 268.6 kB With provenance Details for waymark_cli-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 424.5 kB

Release files / waymark_cli-0.1.0.tar.gz

Download URL waymark_cli-0.1.0.tar.gz
Size 268.6 kB
Tags Source
SHA-256 checksum
How to use checksums
9e9a687bef89bd7ba6e361f35701870f4c07703c54a4f061a0a93108edaacba8
BLAKE2b-256 checksum
How to use checksums
1908a77b29ed82561dbb7e79b3a4b6c57eaa7d38ce61297fa1abf125f4aaedf3
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 13, 2026.

Transparency log

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

Download URL waymark_cli-0.1.0-py3-none-any.whl
Size 155.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
10c5899a8fc1ad9248d85d33e9df4219ebd66800911836a7dfacfa82444f62b7
BLAKE2b-256 checksum
How to use checksums
4cefd54a449839f64369577459b30cb3db29e71fae8a2149afbfec48f622dd17
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 13, 2026.

Transparency log

Security for waymark-cli 0.1.0

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.0.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 13, 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.0 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