waymark-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. waymark_cli-0.1.0/.gitignore +21 -0
  2. waymark_cli-0.1.0/CHANGELOG.md +36 -0
  3. waymark_cli-0.1.0/LICENSE +21 -0
  4. waymark_cli-0.1.0/PKG-INFO +313 -0
  5. waymark_cli-0.1.0/README.md +284 -0
  6. waymark_cli-0.1.0/docs/architecture.md +147 -0
  7. waymark_cli-0.1.0/docs/assets/banner-dark.svg +126 -0
  8. waymark_cli-0.1.0/docs/assets/banner-light.svg +126 -0
  9. waymark_cli-0.1.0/docs/cli.md +345 -0
  10. waymark_cli-0.1.0/docs/concepts.md +152 -0
  11. waymark_cli-0.1.0/docs/getting-started.md +111 -0
  12. waymark_cli-0.1.0/docs/json.md +2233 -0
  13. waymark_cli-0.1.0/docs/multi-repo.md +166 -0
  14. waymark_cli-0.1.0/docs/smoke-test.md +90 -0
  15. waymark_cli-0.1.0/pyproject.toml +117 -0
  16. waymark_cli-0.1.0/src/waymark/__init__.py +3 -0
  17. waymark_cli-0.1.0/src/waymark/__main__.py +8 -0
  18. waymark_cli-0.1.0/src/waymark/adapters/__init__.py +102 -0
  19. waymark_cli-0.1.0/src/waymark/adapters/claude_code.py +238 -0
  20. waymark_cli-0.1.0/src/waymark/assets/__init__.py +43 -0
  21. waymark_cli-0.1.0/src/waymark/assets/agents/wm-implementer.md +45 -0
  22. waymark_cli-0.1.0/src/waymark/assets/agents/wm-reviewer.md +43 -0
  23. waymark_cli-0.1.0/src/waymark/assets/skills/wm-apply/SKILL.md +58 -0
  24. waymark_cli-0.1.0/src/waymark/assets/skills/wm-archive/SKILL.md +32 -0
  25. waymark_cli-0.1.0/src/waymark/assets/skills/wm-explore/SKILL.md +34 -0
  26. waymark_cli-0.1.0/src/waymark/assets/skills/wm-kickoff/SKILL.md +34 -0
  27. waymark_cli-0.1.0/src/waymark/assets/skills/wm-onboard/SKILL.md +27 -0
  28. waymark_cli-0.1.0/src/waymark/assets/skills/wm-pr/SKILL.md +24 -0
  29. waymark_cli-0.1.0/src/waymark/assets/skills/wm-propose/SKILL.md +32 -0
  30. waymark_cli-0.1.0/src/waymark/assets/skills/wm-update/SKILL.md +31 -0
  31. waymark_cli-0.1.0/src/waymark/cli.py +537 -0
  32. waymark_cli-0.1.0/src/waymark/hooks/__init__.py +6 -0
  33. waymark_cli-0.1.0/src/waymark/hooks/commands.py +190 -0
  34. waymark_cli-0.1.0/src/waymark/hooks/decide.py +314 -0
  35. waymark_cli-0.1.0/src/waymark/hooks/events.py +79 -0
  36. waymark_cli-0.1.0/src/waymark/py.typed +0 -0
  37. waymark_cli-0.1.0/src/waymark/record/__init__.py +5 -0
  38. waymark_cli-0.1.0/src/waymark/record/atlas.py +156 -0
  39. waymark_cli-0.1.0/src/waymark/record/changes.py +202 -0
  40. waymark_cli-0.1.0/src/waymark/record/charter.py +75 -0
  41. waymark_cli-0.1.0/src/waymark/record/commits.py +78 -0
  42. waymark_cli-0.1.0/src/waymark/record/config.py +215 -0
  43. waymark_cli-0.1.0/src/waymark/record/deltas.py +318 -0
  44. waymark_cli-0.1.0/src/waymark/record/design.py +80 -0
  45. waymark_cli-0.1.0/src/waymark/record/edits.py +95 -0
  46. waymark_cli-0.1.0/src/waymark/record/evidence.py +58 -0
  47. waymark_cli-0.1.0/src/waymark/record/explorations.py +66 -0
  48. waymark_cli-0.1.0/src/waymark/record/files.py +75 -0
  49. waymark_cli-0.1.0/src/waymark/record/fingerprint.py +73 -0
  50. waymark_cli-0.1.0/src/waymark/record/git.py +167 -0
  51. waymark_cli-0.1.0/src/waymark/record/githooks.py +106 -0
  52. waymark_cli-0.1.0/src/waymark/record/links.py +104 -0
  53. waymark_cli-0.1.0/src/waymark/record/milestones.py +84 -0
  54. waymark_cli-0.1.0/src/waymark/record/moves.py +60 -0
  55. waymark_cli-0.1.0/src/waymark/record/names.py +39 -0
  56. waymark_cli-0.1.0/src/waymark/record/outline.py +144 -0
  57. waymark_cli-0.1.0/src/waymark/record/pointer.py +56 -0
  58. waymark_cli-0.1.0/src/waymark/record/problems.py +20 -0
  59. waymark_cli-0.1.0/src/waymark/record/project.py +118 -0
  60. waymark_cli-0.1.0/src/waymark/record/proposal.py +171 -0
  61. waymark_cli-0.1.0/src/waymark/record/record.py +340 -0
  62. waymark_cli-0.1.0/src/waymark/record/registry.py +158 -0
  63. waymark_cli-0.1.0/src/waymark/record/specs.py +227 -0
  64. waymark_cli-0.1.0/src/waymark/record/state.py +472 -0
  65. waymark_cli-0.1.0/src/waymark/record/store.py +88 -0
  66. waymark_cli-0.1.0/src/waymark/record/tasks.py +415 -0
  67. waymark_cli-0.1.0/src/waymark/record/templates/charter.md +45 -0
  68. waymark_cli-0.1.0/src/waymark/record/templates/ci-workflow.yml +29 -0
  69. waymark_cli-0.1.0/src/waymark/record/templates/config-atlas.toml +8 -0
  70. waymark_cli-0.1.0/src/waymark/record/templates/config.toml +19 -0
  71. waymark_cli-0.1.0/src/waymark/record/templates/delta.md +29 -0
  72. waymark_cli-0.1.0/src/waymark/record/templates/design.md +20 -0
  73. waymark_cli-0.1.0/src/waymark/record/templates/exploration.md +22 -0
  74. waymark_cli-0.1.0/src/waymark/record/templates/goal.md +13 -0
  75. waymark_cli-0.1.0/src/waymark/record/templates/hook-commit-msg +8 -0
  76. waymark_cli-0.1.0/src/waymark/record/templates/hook-pre-commit +8 -0
  77. waymark_cli-0.1.0/src/waymark/record/templates/proposal.md +18 -0
  78. waymark_cli-0.1.0/src/waymark/record/templates/roadmap.md +4 -0
  79. waymark_cli-0.1.0/src/waymark/record/templates/tasks.md +10 -0
  80. waymark_cli-0.1.0/src/waymark/record/templates.py +30 -0
  81. waymark_cli-0.1.0/src/waymark/record/terms.py +51 -0
  82. waymark_cli-0.1.0/src/waymark/record/text.py +197 -0
  83. waymark_cli-0.1.0/src/waymark/services/__init__.py +1 -0
  84. waymark_cli-0.1.0/src/waymark/services/atlas.py +162 -0
  85. waymark_cli-0.1.0/src/waymark/services/check.py +129 -0
  86. waymark_cli-0.1.0/src/waymark/services/ci.py +44 -0
  87. waymark_cli-0.1.0/src/waymark/services/common.py +154 -0
  88. waymark_cli-0.1.0/src/waymark/services/context.py +296 -0
  89. waymark_cli-0.1.0/src/waymark/services/doctor.py +367 -0
  90. waymark_cli-0.1.0/src/waymark/services/githooks.py +132 -0
  91. waymark_cli-0.1.0/src/waymark/services/instructions.py +304 -0
  92. waymark_cli-0.1.0/src/waymark/services/integration.py +170 -0
  93. waymark_cli-0.1.0/src/waymark/services/lifecycle.py +454 -0
  94. waymark_cli-0.1.0/src/waymark/services/migrations.py +90 -0
  95. waymark_cli-0.1.0/src/waymark/services/pr.py +177 -0
  96. waymark_cli-0.1.0/src/waymark/services/references.py +27 -0
  97. waymark_cli-0.1.0/src/waymark/services/setup.py +127 -0
  98. waymark_cli-0.1.0/src/waymark/views/__init__.py +5 -0
  99. waymark_cli-0.1.0/src/waymark/views/payloads.py +568 -0
  100. waymark_cli-0.1.0/src/waymark/views/render.py +506 -0
  101. waymark_cli-0.1.0/src/waymark/views/schemas.py +413 -0
  102. waymark_cli-0.1.0/src/waymark/views/style.py +102 -0
  103. waymark_cli-0.1.0/tests/__init__.py +1 -0
  104. waymark_cli-0.1.0/tests/adapters/__init__.py +1 -0
  105. waymark_cli-0.1.0/tests/adapters/snapshots/settings.json +51 -0
  106. waymark_cli-0.1.0/tests/adapters/snapshots/wm-implementer.md +46 -0
  107. waymark_cli-0.1.0/tests/adapters/snapshots/wm-reviewer.md +44 -0
  108. waymark_cli-0.1.0/tests/adapters/test_claude_code.py +400 -0
  109. waymark_cli-0.1.0/tests/adapters/test_integration.py +283 -0
  110. waymark_cli-0.1.0/tests/conftest.py +55 -0
  111. waymark_cli-0.1.0/tests/hooks/__init__.py +1 -0
  112. waymark_cli-0.1.0/tests/hooks/test_commands.py +179 -0
  113. waymark_cli-0.1.0/tests/hooks/test_decide.py +422 -0
  114. waymark_cli-0.1.0/tests/hooks/test_repo_limits.py +106 -0
  115. waymark_cli-0.1.0/tests/record/__init__.py +1 -0
  116. waymark_cli-0.1.0/tests/record/test_artifacts.py +235 -0
  117. waymark_cli-0.1.0/tests/record/test_atlas.py +152 -0
  118. waymark_cli-0.1.0/tests/record/test_commits.py +100 -0
  119. waymark_cli-0.1.0/tests/record/test_config.py +99 -0
  120. waymark_cli-0.1.0/tests/record/test_deltas.py +207 -0
  121. waymark_cli-0.1.0/tests/record/test_fingerprint.py +154 -0
  122. waymark_cli-0.1.0/tests/record/test_git.py +89 -0
  123. waymark_cli-0.1.0/tests/record/test_links.py +91 -0
  124. waymark_cli-0.1.0/tests/record/test_names.py +39 -0
  125. waymark_cli-0.1.0/tests/record/test_platforms.py +63 -0
  126. waymark_cli-0.1.0/tests/record/test_project.py +199 -0
  127. waymark_cli-0.1.0/tests/record/test_registry.py +89 -0
  128. waymark_cli-0.1.0/tests/record/test_specs.py +102 -0
  129. waymark_cli-0.1.0/tests/record/test_state.py +444 -0
  130. waymark_cli-0.1.0/tests/record/test_store.py +121 -0
  131. waymark_cli-0.1.0/tests/record/test_tasks.py +181 -0
  132. waymark_cli-0.1.0/tests/record/test_text.py +68 -0
  133. waymark_cli-0.1.0/tests/services/__init__.py +1 -0
  134. waymark_cli-0.1.0/tests/services/test_agent_interface.py +439 -0
  135. waymark_cli-0.1.0/tests/services/test_archive.py +373 -0
  136. waymark_cli-0.1.0/tests/services/test_atlas.py +190 -0
  137. waymark_cli-0.1.0/tests/services/test_check.py +124 -0
  138. waymark_cli-0.1.0/tests/services/test_ci_and_pr.py +163 -0
  139. waymark_cli-0.1.0/tests/services/test_doctor.py +189 -0
  140. waymark_cli-0.1.0/tests/services/test_githooks.py +189 -0
  141. waymark_cli-0.1.0/tests/services/test_lifecycle.py +349 -0
  142. waymark_cli-0.1.0/tests/services/test_migrations.py +103 -0
  143. waymark_cli-0.1.0/tests/services/test_milestones.py +90 -0
  144. waymark_cli-0.1.0/tests/services/test_setup.py +189 -0
  145. waymark_cli-0.1.0/tests/support.py +234 -0
  146. waymark_cli-0.1.0/tests/test_agent_cli.py +95 -0
  147. waymark_cli-0.1.0/tests/test_atlas_cli.py +101 -0
  148. waymark_cli-0.1.0/tests/test_cli.py +82 -0
  149. waymark_cli-0.1.0/tests/test_constraints.py +138 -0
  150. waymark_cli-0.1.0/tests/test_docs.py +117 -0
  151. waymark_cli-0.1.0/tests/test_git_cli.py +91 -0
  152. waymark_cli-0.1.0/tests/test_lifecycle_cli.py +291 -0
  153. waymark_cli-0.1.0/tests/test_views_cli.py +142 -0
  154. waymark_cli-0.1.0/tests/views/__init__.py +1 -0
  155. waymark_cli-0.1.0/tests/views/test_branches.py +91 -0
  156. waymark_cli-0.1.0/tests/views/test_style.py +73 -0
  157. waymark_cli-0.1.0/tests/views/test_views.py +395 -0
  158. waymark_cli-0.1.0/tests/views/validator.py +69 -0
  159. waymark_cli-0.1.0/tools/__init__.py +1 -0
  160. waymark_cli-0.1.0/tools/docs.py +431 -0
  161. waymark_cli-0.1.0/tools/release.py +76 -0
@@ -0,0 +1,21 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+
8
+ # Environments and tool caches
9
+ .venv/
10
+ .mypy_cache/
11
+ .pytest_cache/
12
+ .ruff_cache/
13
+
14
+ # Per-machine agent tool settings
15
+ .claude/settings.local.json
16
+
17
+ # Editors and operating systems
18
+ .idea/
19
+ .vscode/
20
+ .DS_Store
21
+ Thumbs.db
@@ -0,0 +1,36 @@
1
+ # Changelog
2
+
3
+ All notable changes to Waymark, one entry per release. A release that changes
4
+ the record's format says what `wm update` migrates.
5
+
6
+ ## [0.1.0] - 2026-11-13
7
+
8
+ The first release: the foundation.
9
+
10
+ - **The record:** charter, settings, living specs, changes (proposal, deltas,
11
+ design, tasks), milestones, explorations and a dated archive, all plain
12
+ markdown in `waymark/`. Record format 1.
13
+ - **The workflow:** propose, specs, design, tasks, accept, apply, review and
14
+ archive, with a short path for small changes. Acceptance is fingerprinted, and
15
+ editing an accepted change withdraws it.
16
+ - **Review:** levels `self`, `independent` and `none`; evidence written only by
17
+ `wm`; the accept, delegation and archive gates; `wm archive --override` for a
18
+ missing review, with the reason recorded.
19
+ - **Commands:** setup (`init`, `update`, `doctor`), authoring (`new`), the agent
20
+ interface (`instructions`, `context`), the lifecycle commands, and the views
21
+ (`status`, `inbox`, `show`, `ls`, `check`), with `--json` and versioned
22
+ schemas. Styled output with an ASCII fallback.
23
+ - **Claude Code:** eight skills, the implementer and reviewer agents, and hooks
24
+ that enforce the agent-side rules and record results from agents' final lines.
25
+ - **Teams:** change owners, branch-safe merges, overlaps reported by `wm check`
26
+ and mismatches blocked at archive.
27
+ - **Multi-repo:** atlases, a per-machine registry, pointer files in code repos,
28
+ read-only references to other atlases, edit limits across repositories, and
29
+ `wm atlas doctor`.
30
+ - **Git and CI:** committed git hooks (commit-message check, and `wm check` on
31
+ commits that touch the record), a GitHub Actions workflow (`wm ci`), and pull
32
+ request text from a change (`wm pr`).
33
+ - Runs on Windows, macOS and Linux, on Python 3.11 and newer, with no
34
+ dependencies beyond the standard library.
35
+
36
+ Smoke test: passed on 2026-11-13 with Claude Code 2.1.325 on Windows.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Noah Roberts
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,313 @@
1
+ Metadata-Version: 2.5
2
+ Name: waymark-cli
3
+ Version: 0.1.0
4
+ Summary: Spec-driven development for developers who stay in charge of their project while agents write the code.
5
+ Project-URL: Repository, https://github.com/noahnkr/waymark
6
+ Project-URL: Documentation, https://github.com/noahnkr/waymark/tree/main/docs
7
+ Project-URL: Issues, https://github.com/noahnkr/waymark/issues
8
+ Project-URL: Changelog, https://github.com/noahnkr/waymark/blob/main/CHANGELOG.md
9
+ Author: Noah Roberts
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: cli,coding-agents,spec-driven-development
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Operating System :: Microsoft :: Windows
18
+ Classifier: Operating System :: POSIX :: Linux
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Programming Language :: Python :: 3.15
25
+ Classifier: Topic :: Software Development
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.11
28
+ Description-Content-Type: text/markdown
29
+
30
+ <p align="center">
31
+ <picture>
32
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
33
+ <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner-light.svg">
34
+ <img alt="Waymark: leave a trail your agents can follow." src="docs/assets/banner-light.svg" width="100%">
35
+ </picture>
36
+ </p>
37
+
38
+ <p align="center">
39
+ <a href="https://github.com/noahnkr/waymark/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/noahnkr/waymark/actions/workflows/ci.yml/badge.svg"></a>
40
+ <a href="https://pypi.org/project/waymark-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/waymark-cli?label=pypi&color=3a4046"></a>
41
+ <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-5b6268">
42
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-8a9299"></a>
43
+ </p>
44
+
45
+ Waymark is spec-driven development built on **living specs**: plain markdown in
46
+ your repository that says what your system does today. Every change starts as an
47
+ edit to those specs, and nothing is built until you've approved it. Then each
48
+ task goes to a fresh agent that works from the written change alone, and the
49
+ riskier ones are checked by a second agent that never saw how they were built.
50
+ A small command-line tool, `wm`, keeps track of where it all stands.
51
+
52
+ ## See it in action
53
+
54
+ <!-- generated: evidence -->
55
+
56
+ ```text
57
+ # /wm-explore (optional): think the idea through with the agent
58
+
59
+ $ wm new change add-result-limit
60
+ Created the change "add-result-limit" with a proposal to draft.
61
+
62
+ # /wm-propose: the agent drafts the proposal, a spec delta, the design
63
+ # and the task list, with a review level for each task
64
+
65
+ $ wm status
66
+ ── Changes in flight ───────────────────────────────────────────────────
67
+ add-result-limit planned ░░░░░░░░░░ 0/2 ◆ accept (you)
68
+
69
+ ◆ 1 thing needs you: wm inbox
70
+
71
+ $ wm accept add-result-limit
72
+ Accepted "add-result-limit". Its items can now be applied.
73
+
74
+ # /wm-apply: a fresh agent builds 1.1 from the change alone and ends with
75
+ # RESULT: done: capped after sorting; the fifty-one-match test passes
76
+ # A reviewer agent that never saw the build checks it and ends with
77
+ # VERDICT: pass: cap and order hold; the scenario is covered by the test
78
+ # wm writes both under 1.1. Then 1.2 is built; it needs no review.
79
+
80
+ $ wm status
81
+ ── Changes in flight ───────────────────────────────────────────────────
82
+ add-result-limit applied ██████████ 2/2 ◆ archive (you)
83
+
84
+ ◆ 1 thing needs you: wm inbox
85
+
86
+ $ wm archive add-result-limit --outcome "Searches return the fifty best matches."
87
+ Archived "add-result-limit" as changes/archive/2026-01-15-add-result-limit. Its deltas are now part of the specs.
88
+ ```
89
+
90
+ The files behind it, all plain markdown in `waymark/`:
91
+
92
+ <details>
93
+ <summary><code>changes/add-result-limit/proposal.md</code></summary>
94
+
95
+ ```markdown
96
+ # Add a result limit
97
+
98
+ Owner: Alex Example
99
+ Accepted: 2026-01-15 by Alex Example (fingerprint: 6cec39a287bf99f2)
100
+
101
+ ## Why
102
+
103
+ Searches that match thousands of documents return all of them,
104
+ and the results page slows to a crawl.
105
+
106
+ ## What changes
107
+
108
+ A search returns at most fifty results, best matches first.
109
+
110
+ ## Non-goals
111
+
112
+ Paging through the rest.
113
+
114
+ ## Impact
115
+
116
+ Specs: search.
117
+ ```
118
+
119
+ </details>
120
+ <details>
121
+ <summary><code>changes/add-result-limit/specs/search.md</code>, the spec delta</summary>
122
+
123
+ ```markdown
124
+ # Search
125
+
126
+ ## Purpose
127
+
128
+ How a search finds and returns documents.
129
+
130
+ ## Added requirements
131
+
132
+ ### Requirement: Result limit
133
+ A search SHALL return at most fifty results.
134
+
135
+ #### Scenario: Many matches
136
+ - GIVEN an index where a query matches more than fifty documents
137
+ - WHEN the search runs
138
+ - THEN the fifty best matches come back
139
+ ```
140
+
141
+ </details>
142
+ <details>
143
+ <summary><code>changes/add-result-limit/design.md</code></summary>
144
+
145
+ ```markdown
146
+ # Design
147
+
148
+ ## Context
149
+
150
+ Results are sorted by relevance before they are returned.
151
+
152
+ ## Approach
153
+
154
+ Cut the sorted list at fifty, in the search service.
155
+
156
+ ## Decisions
157
+
158
+ ### Decision: Where to cut
159
+
160
+ - Options: in the database query, or after sorting
161
+ - Choice: after sorting
162
+ - Why: the order has to be final before the cut
163
+
164
+ ## Risks and trade-offs
165
+
166
+ Sorting every match still costs memory on very large result sets.
167
+ ```
168
+
169
+ </details>
170
+ <details>
171
+ <summary><code>changes/add-result-limit/tasks.md</code>, with what wm recorded</summary>
172
+
173
+ ```markdown
174
+ # Tasks
175
+
176
+ ## 1. Limit
177
+
178
+ - [x] 1.1 Cap the result count `review: independent`
179
+ - Criteria: at most fifty results come back, best first
180
+ - Verify: a test searches an index with fifty-one matches
181
+ - (review) 2026-01-15 pass: cap and order hold; the scenario is covered by the test
182
+ - [x] 1.2 Name the limit in the help text `review: none`
183
+ - Criteria: the search help says fifty
184
+ ```
185
+
186
+ </details>
187
+ <details>
188
+ <summary><code>specs/search.md</code>, the living spec after archive</summary>
189
+
190
+ ```markdown
191
+ # Search
192
+
193
+ ## Purpose
194
+
195
+ How a search finds and returns documents.
196
+
197
+ ## Requirements
198
+
199
+ ### Requirement: Result limit
200
+ A search SHALL return at most fifty results.
201
+
202
+ #### Scenario: Many matches
203
+ - GIVEN an index where a query matches more than fifty documents
204
+ - WHEN the search runs
205
+ - THEN the fifty best matches come back
206
+ ```
207
+
208
+ </details>
209
+
210
+ <sub>Real output of this version of <code>wm</code> on a generic change, generated by <code>tools/docs.py</code>. The comments mark where an agent works.</sub>
211
+
212
+ <!-- end of generated evidence -->
213
+
214
+ ## Why Waymark
215
+
216
+ - **Agents only know what's written down.** Each task is built by a fresh agent
217
+ from the written change alone. When something is missing, it reports a spec
218
+ gap instead of guessing.
219
+ - **Review is recorded.** Each task is checked against its criteria, by your
220
+ session for routine work or by an independent reviewer agent that never saw
221
+ the build, and the result is written right under the task.
222
+ - **Pick up anywhere.** `wm` works out where things stand from the files and
223
+ git, in any session, on any machine.
224
+ - **Two sign-offs, both yours.** Agents draft every file and write the code. You
225
+ approve each change before it's built, and again when it's archived.
226
+ - **Light for small changes, thorough for big ones.** A small change takes the
227
+ short path: a proposal, a task list and a quick self-check. A bigger one adds
228
+ a design, and its riskier tasks get a second agent as an independent reviewer.
229
+
230
+ In Claude Code, these rules are enforced by hooks, not just asked for. See
231
+ [what's enforced, and where](#whats-enforced-and-where).
232
+
233
+ ## Quick start
234
+
235
+ ```
236
+ pipx install waymark-cli # or: uv tool install waymark-cli
237
+ cd your-project
238
+ wm init
239
+ ```
240
+
241
+ Then, in Claude Code:
242
+
243
+ - **`/wm-kickoff`** drafts your project's charter with you.
244
+ - **`/wm-onboard`** takes one real, small change on your own code through every step.
245
+
246
+ From then on: `/wm-propose` to start a change, `/wm-apply` to build it,
247
+ `/wm-archive` to finish it. `wm status` shows where things stand, and `wm inbox`
248
+ shows what needs you. Note that the package is `waymark-cli`; the command is `wm`.
249
+
250
+ <details>
251
+ <summary><strong>Who it's for</strong></summary>
252
+
253
+ <br>
254
+
255
+ - **Solo developers** building real projects with coding agents.
256
+ - **Small teams** (roughly two to five) sharing one record across branches.
257
+ - **Projects split across repositories,** such as a frontend and a backend, with
258
+ one record in an *atlas* ([guide](docs/multi-repo.md)).
259
+ - **New and existing codebases.** Specs grow where work happens; nothing is
260
+ reverse-engineered up front.
261
+
262
+ It's not for handing over a goal and walking away, for throwaway scripts, or for
263
+ organizations that need access control or approval chains.
264
+
265
+ </details>
266
+
267
+ <details>
268
+ <summary><strong>What it costs</strong></summary>
269
+
270
+ <br>
271
+
272
+ Agents write every artifact and all the code, on your own agent tool and plan;
273
+ `wm` never calls a model. You approve each change twice, and settle what
274
+ `wm inbox` lists: spec gaps, blocked items, reviews that failed twice. Time and
275
+ token figures will come from using Waymark on itself, in 0.1.1. None are
276
+ claimed before they're measured.
277
+
278
+ </details>
279
+
280
+ <details>
281
+ <summary><strong>What's enforced, and where</strong></summary>
282
+
283
+ <br>
284
+
285
+ | Enforced by | What | Holds in |
286
+ |---|---|---|
287
+ | `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 |
288
+ | 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 |
289
+
290
+ These are guard rails against mistakes and shortcuts, not security against
291
+ someone set on getting around them.
292
+
293
+ **Teams:** each change has one owner and its own branch. Two changes that touch
294
+ the same requirement are reported, and the second must be revised before it's
295
+ archived. Conflicts are caught on the merged tree, not before merge. The
296
+ independent reviewer is always an agent.
297
+
298
+ </details>
299
+
300
+ ## Learn more
301
+
302
+ - **[Getting started](docs/getting-started.md)**: from install to your first change
303
+ - **[Concepts](docs/concepts.md)**: the workflow, the files, the roles, and a glossary
304
+ - **[Multi-repo guide](docs/multi-repo.md)**: one record for several repositories
305
+ - **[CLI](docs/cli.md)** and **[JSON](docs/json.md)** references, generated from the code
306
+ - **[Architecture](docs/architecture.md)**: for contributors, including how to add an agent tool
307
+ - **[Changelog](CHANGELOG.md)**
308
+
309
+ Works with Claude Code. Version last verified: **2.1.325**, on Windows.
310
+
311
+ ## License
312
+
313
+ [MIT](LICENSE)
@@ -0,0 +1,284 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
4
+ <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner-light.svg">
5
+ <img alt="Waymark: leave a trail your agents can follow." src="docs/assets/banner-light.svg" width="100%">
6
+ </picture>
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://github.com/noahnkr/waymark/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/noahnkr/waymark/actions/workflows/ci.yml/badge.svg"></a>
11
+ <a href="https://pypi.org/project/waymark-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/waymark-cli?label=pypi&color=3a4046"></a>
12
+ <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-5b6268">
13
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-8a9299"></a>
14
+ </p>
15
+
16
+ Waymark is spec-driven development built on **living specs**: plain markdown in
17
+ your repository that says what your system does today. Every change starts as an
18
+ edit to those specs, and nothing is built until you've approved it. Then each
19
+ task goes to a fresh agent that works from the written change alone, and the
20
+ riskier ones are checked by a second agent that never saw how they were built.
21
+ A small command-line tool, `wm`, keeps track of where it all stands.
22
+
23
+ ## See it in action
24
+
25
+ <!-- generated: evidence -->
26
+
27
+ ```text
28
+ # /wm-explore (optional): think the idea through with the agent
29
+
30
+ $ wm new change add-result-limit
31
+ Created the change "add-result-limit" with a proposal to draft.
32
+
33
+ # /wm-propose: the agent drafts the proposal, a spec delta, the design
34
+ # and the task list, with a review level for each task
35
+
36
+ $ wm status
37
+ ── Changes in flight ───────────────────────────────────────────────────
38
+ add-result-limit planned ░░░░░░░░░░ 0/2 ◆ accept (you)
39
+
40
+ ◆ 1 thing needs you: wm inbox
41
+
42
+ $ wm accept add-result-limit
43
+ Accepted "add-result-limit". Its items can now be applied.
44
+
45
+ # /wm-apply: a fresh agent builds 1.1 from the change alone and ends with
46
+ # RESULT: done: capped after sorting; the fifty-one-match test passes
47
+ # A reviewer agent that never saw the build checks it and ends with
48
+ # VERDICT: pass: cap and order hold; the scenario is covered by the test
49
+ # wm writes both under 1.1. Then 1.2 is built; it needs no review.
50
+
51
+ $ wm status
52
+ ── Changes in flight ───────────────────────────────────────────────────
53
+ add-result-limit applied ██████████ 2/2 ◆ archive (you)
54
+
55
+ ◆ 1 thing needs you: wm inbox
56
+
57
+ $ wm archive add-result-limit --outcome "Searches return the fifty best matches."
58
+ Archived "add-result-limit" as changes/archive/2026-01-15-add-result-limit. Its deltas are now part of the specs.
59
+ ```
60
+
61
+ The files behind it, all plain markdown in `waymark/`:
62
+
63
+ <details>
64
+ <summary><code>changes/add-result-limit/proposal.md</code></summary>
65
+
66
+ ```markdown
67
+ # Add a result limit
68
+
69
+ Owner: Alex Example
70
+ Accepted: 2026-01-15 by Alex Example (fingerprint: 6cec39a287bf99f2)
71
+
72
+ ## Why
73
+
74
+ Searches that match thousands of documents return all of them,
75
+ and the results page slows to a crawl.
76
+
77
+ ## What changes
78
+
79
+ A search returns at most fifty results, best matches first.
80
+
81
+ ## Non-goals
82
+
83
+ Paging through the rest.
84
+
85
+ ## Impact
86
+
87
+ Specs: search.
88
+ ```
89
+
90
+ </details>
91
+ <details>
92
+ <summary><code>changes/add-result-limit/specs/search.md</code>, the spec delta</summary>
93
+
94
+ ```markdown
95
+ # Search
96
+
97
+ ## Purpose
98
+
99
+ How a search finds and returns documents.
100
+
101
+ ## Added requirements
102
+
103
+ ### Requirement: Result limit
104
+ A search SHALL return at most fifty results.
105
+
106
+ #### Scenario: Many matches
107
+ - GIVEN an index where a query matches more than fifty documents
108
+ - WHEN the search runs
109
+ - THEN the fifty best matches come back
110
+ ```
111
+
112
+ </details>
113
+ <details>
114
+ <summary><code>changes/add-result-limit/design.md</code></summary>
115
+
116
+ ```markdown
117
+ # Design
118
+
119
+ ## Context
120
+
121
+ Results are sorted by relevance before they are returned.
122
+
123
+ ## Approach
124
+
125
+ Cut the sorted list at fifty, in the search service.
126
+
127
+ ## Decisions
128
+
129
+ ### Decision: Where to cut
130
+
131
+ - Options: in the database query, or after sorting
132
+ - Choice: after sorting
133
+ - Why: the order has to be final before the cut
134
+
135
+ ## Risks and trade-offs
136
+
137
+ Sorting every match still costs memory on very large result sets.
138
+ ```
139
+
140
+ </details>
141
+ <details>
142
+ <summary><code>changes/add-result-limit/tasks.md</code>, with what wm recorded</summary>
143
+
144
+ ```markdown
145
+ # Tasks
146
+
147
+ ## 1. Limit
148
+
149
+ - [x] 1.1 Cap the result count `review: independent`
150
+ - Criteria: at most fifty results come back, best first
151
+ - Verify: a test searches an index with fifty-one matches
152
+ - (review) 2026-01-15 pass: cap and order hold; the scenario is covered by the test
153
+ - [x] 1.2 Name the limit in the help text `review: none`
154
+ - Criteria: the search help says fifty
155
+ ```
156
+
157
+ </details>
158
+ <details>
159
+ <summary><code>specs/search.md</code>, the living spec after archive</summary>
160
+
161
+ ```markdown
162
+ # Search
163
+
164
+ ## Purpose
165
+
166
+ How a search finds and returns documents.
167
+
168
+ ## Requirements
169
+
170
+ ### Requirement: Result limit
171
+ A search SHALL return at most fifty results.
172
+
173
+ #### Scenario: Many matches
174
+ - GIVEN an index where a query matches more than fifty documents
175
+ - WHEN the search runs
176
+ - THEN the fifty best matches come back
177
+ ```
178
+
179
+ </details>
180
+
181
+ <sub>Real output of this version of <code>wm</code> on a generic change, generated by <code>tools/docs.py</code>. The comments mark where an agent works.</sub>
182
+
183
+ <!-- end of generated evidence -->
184
+
185
+ ## Why Waymark
186
+
187
+ - **Agents only know what's written down.** Each task is built by a fresh agent
188
+ from the written change alone. When something is missing, it reports a spec
189
+ gap instead of guessing.
190
+ - **Review is recorded.** Each task is checked against its criteria, by your
191
+ session for routine work or by an independent reviewer agent that never saw
192
+ the build, and the result is written right under the task.
193
+ - **Pick up anywhere.** `wm` works out where things stand from the files and
194
+ git, in any session, on any machine.
195
+ - **Two sign-offs, both yours.** Agents draft every file and write the code. You
196
+ approve each change before it's built, and again when it's archived.
197
+ - **Light for small changes, thorough for big ones.** A small change takes the
198
+ short path: a proposal, a task list and a quick self-check. A bigger one adds
199
+ a design, and its riskier tasks get a second agent as an independent reviewer.
200
+
201
+ In Claude Code, these rules are enforced by hooks, not just asked for. See
202
+ [what's enforced, and where](#whats-enforced-and-where).
203
+
204
+ ## Quick start
205
+
206
+ ```
207
+ pipx install waymark-cli # or: uv tool install waymark-cli
208
+ cd your-project
209
+ wm init
210
+ ```
211
+
212
+ Then, in Claude Code:
213
+
214
+ - **`/wm-kickoff`** drafts your project's charter with you.
215
+ - **`/wm-onboard`** takes one real, small change on your own code through every step.
216
+
217
+ From then on: `/wm-propose` to start a change, `/wm-apply` to build it,
218
+ `/wm-archive` to finish it. `wm status` shows where things stand, and `wm inbox`
219
+ shows what needs you. Note that the package is `waymark-cli`; the command is `wm`.
220
+
221
+ <details>
222
+ <summary><strong>Who it's for</strong></summary>
223
+
224
+ <br>
225
+
226
+ - **Solo developers** building real projects with coding agents.
227
+ - **Small teams** (roughly two to five) sharing one record across branches.
228
+ - **Projects split across repositories,** such as a frontend and a backend, with
229
+ one record in an *atlas* ([guide](docs/multi-repo.md)).
230
+ - **New and existing codebases.** Specs grow where work happens; nothing is
231
+ reverse-engineered up front.
232
+
233
+ It's not for handing over a goal and walking away, for throwaway scripts, or for
234
+ organizations that need access control or approval chains.
235
+
236
+ </details>
237
+
238
+ <details>
239
+ <summary><strong>What it costs</strong></summary>
240
+
241
+ <br>
242
+
243
+ Agents write every artifact and all the code, on your own agent tool and plan;
244
+ `wm` never calls a model. You approve each change twice, and settle what
245
+ `wm inbox` lists: spec gaps, blocked items, reviews that failed twice. Time and
246
+ token figures will come from using Waymark on itself, in 0.1.1. None are
247
+ claimed before they're measured.
248
+
249
+ </details>
250
+
251
+ <details>
252
+ <summary><strong>What's enforced, and where</strong></summary>
253
+
254
+ <br>
255
+
256
+ | Enforced by | What | Holds in |
257
+ |---|---|---|
258
+ | `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 |
259
+ | 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 |
260
+
261
+ These are guard rails against mistakes and shortcuts, not security against
262
+ someone set on getting around them.
263
+
264
+ **Teams:** each change has one owner and its own branch. Two changes that touch
265
+ the same requirement are reported, and the second must be revised before it's
266
+ archived. Conflicts are caught on the merged tree, not before merge. The
267
+ independent reviewer is always an agent.
268
+
269
+ </details>
270
+
271
+ ## Learn more
272
+
273
+ - **[Getting started](docs/getting-started.md)**: from install to your first change
274
+ - **[Concepts](docs/concepts.md)**: the workflow, the files, the roles, and a glossary
275
+ - **[Multi-repo guide](docs/multi-repo.md)**: one record for several repositories
276
+ - **[CLI](docs/cli.md)** and **[JSON](docs/json.md)** references, generated from the code
277
+ - **[Architecture](docs/architecture.md)**: for contributors, including how to add an agent tool
278
+ - **[Changelog](CHANGELOG.md)**
279
+
280
+ Works with Claude Code. Version last verified: **2.1.325**, on Windows.
281
+
282
+ ## License
283
+
284
+ [MIT](LICENSE)