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.
wmworks 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-kickoffdrafts your project's charter with you./wm-onboardtakes 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
- Getting started: from install to your first change
- Concepts: the workflow, the files, the roles, and a glossary
- Multi-repo guide: one record for several repositories
- CLI and JSON references, generated from the code
- Architecture: for contributors, including how to add an agent tool
- Changelog
Works with Claude Code. Version last verified: 2.1.325, on Windows.
License
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.