waymark-cli 0.1.0__tar.gz → 0.1.1__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 (167) hide show
  1. waymark_cli-0.1.1/.gitignore +38 -0
  2. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/CHANGELOG.md +28 -0
  3. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/PKG-INFO +3 -3
  4. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/README.md +2 -2
  5. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/architecture.md +38 -11
  6. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/assets/banner-dark.svg +1 -1
  7. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/assets/banner-light.svg +1 -1
  8. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/cli.md +3 -3
  9. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/getting-started.md +40 -7
  10. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/multi-repo.md +19 -8
  11. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/smoke-test.md +23 -6
  12. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/__init__.py +1 -1
  13. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/adapters/__init__.py +2 -0
  14. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/adapters/claude_code.py +18 -6
  15. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/cli.py +3 -3
  16. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/hooks/decide.py +37 -4
  17. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/hooks/events.py +9 -2
  18. waymark_cli-0.1.1/src/waymark/record/agents.py +125 -0
  19. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/git.py +23 -7
  20. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/githooks.py +2 -0
  21. waymark_cli-0.1.1/src/waymark/record/ignore.py +66 -0
  22. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/doctor.py +54 -1
  23. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/githooks.py +13 -21
  24. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/integration.py +119 -20
  25. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/setup.py +39 -6
  26. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/adapters/snapshots/settings.json +1 -1
  27. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/adapters/snapshots/wm-implementer.md +1 -1
  28. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/adapters/snapshots/wm-reviewer.md +1 -1
  29. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/adapters/test_claude_code.py +80 -7
  30. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/adapters/test_integration.py +2 -1
  31. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/hooks/test_decide.py +124 -2
  32. waymark_cli-0.1.1/tests/record/test_agents.py +149 -0
  33. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_git.py +26 -1
  34. waymark_cli-0.1.1/tests/record/test_ignore.py +70 -0
  35. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_doctor.py +74 -1
  36. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_githooks.py +122 -12
  37. waymark_cli-0.1.1/tests/services/test_setup.py +497 -0
  38. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_cli.py +57 -0
  39. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_docs.py +29 -2
  40. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_git_cli.py +5 -6
  41. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_lifecycle_cli.py +3 -1
  42. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tools/release.py +29 -3
  43. waymark_cli-0.1.0/.gitignore +0 -21
  44. waymark_cli-0.1.0/tests/services/test_setup.py +0 -189
  45. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/LICENSE +0 -0
  46. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/concepts.md +0 -0
  47. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/docs/json.md +0 -0
  48. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/pyproject.toml +0 -0
  49. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/__main__.py +0 -0
  50. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/__init__.py +0 -0
  51. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/agents/wm-implementer.md +0 -0
  52. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/agents/wm-reviewer.md +0 -0
  53. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-apply/SKILL.md +0 -0
  54. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-archive/SKILL.md +0 -0
  55. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-explore/SKILL.md +0 -0
  56. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-kickoff/SKILL.md +0 -0
  57. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-onboard/SKILL.md +0 -0
  58. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-pr/SKILL.md +0 -0
  59. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-propose/SKILL.md +0 -0
  60. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/assets/skills/wm-update/SKILL.md +0 -0
  61. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/hooks/__init__.py +0 -0
  62. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/hooks/commands.py +0 -0
  63. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/py.typed +0 -0
  64. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/__init__.py +0 -0
  65. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/atlas.py +0 -0
  66. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/changes.py +0 -0
  67. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/charter.py +0 -0
  68. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/commits.py +0 -0
  69. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/config.py +0 -0
  70. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/deltas.py +0 -0
  71. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/design.py +0 -0
  72. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/edits.py +0 -0
  73. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/evidence.py +0 -0
  74. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/explorations.py +0 -0
  75. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/files.py +0 -0
  76. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/fingerprint.py +0 -0
  77. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/links.py +0 -0
  78. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/milestones.py +0 -0
  79. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/moves.py +0 -0
  80. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/names.py +0 -0
  81. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/outline.py +0 -0
  82. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/pointer.py +0 -0
  83. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/problems.py +0 -0
  84. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/project.py +0 -0
  85. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/proposal.py +0 -0
  86. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/record.py +0 -0
  87. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/registry.py +0 -0
  88. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/specs.py +0 -0
  89. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/state.py +0 -0
  90. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/store.py +0 -0
  91. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/tasks.py +0 -0
  92. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/charter.md +0 -0
  93. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/ci-workflow.yml +0 -0
  94. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/config-atlas.toml +0 -0
  95. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/config.toml +0 -0
  96. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/delta.md +0 -0
  97. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/design.md +0 -0
  98. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/exploration.md +0 -0
  99. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/goal.md +0 -0
  100. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/hook-commit-msg +0 -0
  101. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/hook-pre-commit +0 -0
  102. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/proposal.md +0 -0
  103. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/roadmap.md +0 -0
  104. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates/tasks.md +0 -0
  105. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/templates.py +0 -0
  106. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/terms.py +0 -0
  107. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/record/text.py +0 -0
  108. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/__init__.py +0 -0
  109. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/atlas.py +0 -0
  110. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/check.py +0 -0
  111. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/ci.py +0 -0
  112. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/common.py +0 -0
  113. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/context.py +0 -0
  114. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/instructions.py +0 -0
  115. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/lifecycle.py +0 -0
  116. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/migrations.py +0 -0
  117. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/pr.py +0 -0
  118. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/services/references.py +0 -0
  119. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/views/__init__.py +0 -0
  120. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/views/payloads.py +0 -0
  121. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/views/render.py +0 -0
  122. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/views/schemas.py +0 -0
  123. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/src/waymark/views/style.py +0 -0
  124. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/__init__.py +0 -0
  125. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/adapters/__init__.py +0 -0
  126. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/conftest.py +0 -0
  127. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/hooks/__init__.py +0 -0
  128. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/hooks/test_commands.py +0 -0
  129. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/hooks/test_repo_limits.py +0 -0
  130. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/__init__.py +0 -0
  131. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_artifacts.py +0 -0
  132. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_atlas.py +0 -0
  133. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_commits.py +0 -0
  134. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_config.py +0 -0
  135. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_deltas.py +0 -0
  136. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_fingerprint.py +0 -0
  137. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_links.py +0 -0
  138. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_names.py +0 -0
  139. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_platforms.py +0 -0
  140. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_project.py +0 -0
  141. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_registry.py +0 -0
  142. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_specs.py +0 -0
  143. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_state.py +0 -0
  144. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_store.py +0 -0
  145. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_tasks.py +0 -0
  146. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/record/test_text.py +0 -0
  147. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/__init__.py +0 -0
  148. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_agent_interface.py +0 -0
  149. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_archive.py +0 -0
  150. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_atlas.py +0 -0
  151. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_check.py +0 -0
  152. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_ci_and_pr.py +0 -0
  153. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_lifecycle.py +0 -0
  154. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_migrations.py +0 -0
  155. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/services/test_milestones.py +0 -0
  156. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/support.py +0 -0
  157. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_agent_cli.py +0 -0
  158. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_atlas_cli.py +0 -0
  159. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_constraints.py +0 -0
  160. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/test_views_cli.py +0 -0
  161. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/views/__init__.py +0 -0
  162. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/views/test_branches.py +0 -0
  163. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/views/test_style.py +0 -0
  164. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/views/test_views.py +0 -0
  165. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tests/views/validator.py +0 -0
  166. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tools/__init__.py +0 -0
  167. {waymark_cli-0.1.0 → waymark_cli-0.1.1}/tools/docs.py +0 -0
@@ -0,0 +1,38 @@
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
+ # Agent tool setup: per machine, written by "wm init"
15
+ /.claude/
16
+ /CLAUDE.md
17
+ /AGENTS.md
18
+ /.codex/
19
+ /.cursor/
20
+ /.opencode/
21
+ /.windsurf/
22
+ /.gemini/
23
+ /.agents/skills/wm-*/
24
+ /.waymark/
25
+
26
+ # Editors and operating systems
27
+ .idea/
28
+ .vscode/
29
+ .DS_Store
30
+ Thumbs.db
31
+
32
+ # Waymark: this machine's agent tool files and git hooks, written by wm
33
+ /.agents/skills/wm-*/
34
+ /.claude/skills/wm-*/
35
+ /.claude/agents/wm-*.md
36
+ /.claude/settings.json
37
+ /.waymark/hooks/
38
+ # end of Waymark
@@ -3,6 +3,34 @@
3
3
  All notable changes to Waymark, one entry per release. A release that changes
4
4
  the record's format says what `wm update` migrates.
5
5
 
6
+ ## [0.1.1] - 2026-11-15
7
+
8
+ Each machine sets itself up, and background agents' results are recorded.
9
+ Waymark is now developed with its own record.
10
+
11
+ - **Behavior change: the agent tool files and git hooks belong to each
12
+ machine.** `wm init`, `wm update` and `wm git-hooks` keep them out of git with
13
+ a marked block in `.gitignore`, and the git hooks are no longer staged. Commit
14
+ `waymark/` and `.gitignore`; after cloning, run `wm init`.
15
+ - **`wm init` in a clone that has a record** sets up this machine instead of
16
+ refusing, and leaves the record alone. It needs the pinned `wm`, and says to
17
+ run `wm update` when the record needs migrating.
18
+ - **`wm doctor`** warns when files `wm` writes for a machine are tracked in git,
19
+ with the `git rm -r --cached` command that stops sharing them. Its message for
20
+ missing agent files says to run `wm init`.
21
+ - **`wm update`** asks you to commit only when the record, `.gitignore` or the
22
+ CI workflow changed.
23
+ - **Fix: results from agents run in the background are recorded.** In Claude
24
+ Code, an implementer's or reviewer's report handed back through
25
+ `SubagentHandback` is read by the hooks, so ticks and verdicts are written
26
+ without the planner. The agents may now use that tool.
27
+ - **Upgrading from 0.1.0:** change the pin to 0.1.1, install it, and run
28
+ `wm update`. It adds the `.gitignore` block. Then run `wm doctor` and the
29
+ `git rm -r --cached` command it gives, and commit. The record format is
30
+ unchanged (format 1); nothing is migrated.
31
+
32
+ Smoke test: passed on 2026-11-15 with Claude Code 2.1.325 on Windows.
33
+
6
34
  ## [0.1.0] - 2026-11-13
7
35
 
8
36
  The first release: the foundation.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: waymark-cli
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: Spec-driven development for developers who stay in charge of their project while agents write the code.
5
5
  Project-URL: Repository, https://github.com/noahnkr/waymark
6
6
  Project-URL: Documentation, https://github.com/noahnkr/waymark/tree/main/docs
@@ -272,8 +272,8 @@ organizations that need access control or approval chains.
272
272
  Agents write every artifact and all the code, on your own agent tool and plan;
273
273
  `wm` never calls a model. You approve each change twice, and settle what
274
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.
275
+ token figures will come from using Waymark on itself; none are claimed before
276
+ they're measured.
277
277
 
278
278
  </details>
279
279
 
@@ -243,8 +243,8 @@ organizations that need access control or approval chains.
243
243
  Agents write every artifact and all the code, on your own agent tool and plan;
244
244
  `wm` never calls a model. You approve each change twice, and settle what
245
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.
246
+ token figures will come from using Waymark on itself; none are claimed before
247
+ they're measured.
248
248
 
249
249
  </details>
250
250
 
@@ -65,16 +65,20 @@ access outside `record/` and `assets/`.
65
65
 
66
66
  Claude Code runs `wm hook claude-code <Event>` with its JSON on standard input.
67
67
 
68
- 1. **The adapter translates** the payload into one of six neutral events:
68
+ 1. **The adapter translates** the payload into one of seven neutral events:
69
69
  session start, delegate (starting a subagent), edit (before an edit), edited
70
- (after an edit), command (a shell command) and agent stop. It works out who
71
- is acting from the agent type: the implementer, the reviewer, or anyone else,
72
- who counts as the planner.
70
+ (after an edit), command (a shell command), handback (a subagent handing its
71
+ report back through a tool, as Claude Code's background agents do) and agent
72
+ stop. It works out who is acting from the agent type: the implementer, the
73
+ reviewer, or anyone else, who counts as the planner.
73
74
  2. **The core decides** (`hooks/decide.py`): allow, refuse with a reason that
74
75
  says what to do instead, add context for the agent, or record evidence. For
75
- example, at an agent stop it reads the `ITEM:` and `RESULT:` or `VERDICT:`
76
- lines and writes the tick, blocker, spec gap, note or review record through the
77
- same lifecycle service the commands use.
76
+ example, at a handback or an agent stop it reads the `ITEM:` and `RESULT:` or
77
+ `VERDICT:` lines and writes the tick, blocker, spec gap, note or review record
78
+ through the same lifecycle service the commands use. An agent's ending is
79
+ recorded once: a per-agent marker in the clone's git folder
80
+ (`record/agents.py`) lets the stop after a recorded handback through without
81
+ asking for the ending again.
78
82
  3. **The adapter translates the decision back** into the tool's reply format.
79
83
 
80
84
  The adapter holds no rules, so a decision is the same in every tool. A hook that
@@ -113,6 +117,27 @@ uv run --no-sync codespell # spelling, American English
113
117
  uv run --no-sync python -m tools.docs # regenerate the CLI and JSON references and the README's evidence
114
118
  ```
115
119
 
120
+ **Waymark is developed with Waymark.** Its record is in `waymark/`: the charter,
121
+ the specs, and every change since 0.1.0. Work starts as a change there, through
122
+ the skills, like in any other project. After cloning:
123
+
124
+ ```
125
+ uv tool install --editable . --force # wm on PATH runs this checkout, so it matches the pin
126
+ wm init # this machine's agent tool files and git hooks
127
+ ```
128
+
129
+ Agent tool files (`.claude/`, `CLAUDE.md`, `AGENTS.md`, `.codex/`, `.cursor/`
130
+ and the like), wm's own skills in `.agents/skills/wm-*/` and `.waymark/` are per
131
+ machine and kept out of git. The skills for working on Waymark itself are
132
+ committed in `.agents/skills/`:
133
+
134
+ | Skill | For |
135
+ |---|---|
136
+ | `waymark-draft-docs` | Planning and drafting a new or rewritten docs page with the maintainer |
137
+ | `waymark-write-docs` | The house style and fact rules for any docs edit |
138
+ | `waymark-check-docs` | Checking docs against the code, on request |
139
+ | `waymark-release` | Cutting a release, from audit to tag |
140
+
116
141
  CI runs the tests on Windows, macOS and Linux, each on Python 3.11 and the newest
117
142
  release, plus lint, format, strict type and spelling checks, and builds the wheel.
118
143
  A test fails when a generated doc is out of date.
@@ -136,11 +161,13 @@ scoped by component (`record`, `services`, `views`, `hooks`, `adapter-claude`,
136
161
 
137
162
  ## Releasing
138
163
 
139
- The maintainer releases. Before each release, the [smoke-test checklist](smoke-test.md)
140
- is run by hand, and its result goes into the changelog's entry. Then:
164
+ The maintainer releases, with the `waymark-release` skill. Before each release, the
165
+ [smoke-test checklist](smoke-test.md) is run by hand, and its result goes into the
166
+ changelog's entry. The skill:
141
167
 
142
- 1. set the version in `src/waymark/__init__.py` and date the entry in `CHANGELOG.md`;
143
- 2. merge, and push a tag `v<version>` on `main`.
168
+ 1. sets the version in `src/waymark/__init__.py` and the pin in `waymark/config.toml`,
169
+ and writes and dates the entry in `CHANGELOG.md`, on a release branch;
170
+ 2. opens the pull request; after it is merged, pushes a tag `v<version>` on `main`.
144
171
 
145
172
  The release workflow checks that the tag, the version, the changelog entry and the
146
173
  smoke-test record agree, runs the tests, builds, publishes to PyPI through trusted
@@ -80,7 +80,7 @@
80
80
  <path transform="translate(41.41 0.00) scale(0.00610 -0.00610)" d="M172.437744140625 0.0V1490.0H415.883544921875L999.2868041992188 570.1298828125Q1025.267333984375 529.6188354492188 1059.8074951171875 469.99835205078125Q1094.34765625 410.37786865234375 1133.6676025390625 335.7123718261719Q1172.987548828125 261.046875 1211.07763671875 174.53582763671875H1183.357421875Q1174.717529296875 260.085693359375 1170.4024658203125 341.1064453125Q1166.08740234375 422.127197265625 1164.63720703125 491.5032043457031Q1163.18701171875 560.8792114257812 1163.18701171875 609.1298828125V1490.0H1373.533203125V0.0H1128.267333984375L607.0830078125 820.6318359375Q568.3724975585938 882.6927490234375 530.42236328125 946.813232421875Q492.47222900390625 1010.9337158203125 445.2374572753906 1096.8388671875Q398.002685546875 1182.743896484375 328.80322265625 1308.023681640625H364.43341064453125Q369.7034912109375 1197.56396484375 374.0185852050781 1102.6636962890625Q378.33367919921875 1007.7633666992188 381.01373291015625 936.0528564453125Q383.69378662109375 864.3423461914062 383.69378662109375 822.4517822265625V0.0H172.437744140625Z"/></g>
81
81
  </g>
82
82
  <path d="M1128 -6 C1140 34 1192 58 1192 104 S1176 176 1118 182 S1034 128 984 138 S936 214 878 236 S784 196 724 214 S660 290 580 286 S486 252 412 262 S318 300 250 292 S150 296 124 252 S108 196 108 168" fill="none" stroke="#8a9299" stroke-width="2.2" stroke-dasharray="7 8" stroke-linecap="round"/>
83
- <path d="M108 88 L149.6 160 L66.4 160 Z M100 136.0 a8 8 0 1 0 16 0 a8 8 0 1 0 -16 0Z" fill="#f2efe8" fill-rule="evenodd" stroke="#f2efe8" stroke-width="4" stroke-linejoin="round"/>
83
+ <path d="M108 88 L115.07 116.93 L144 124 L115.07 131.07 L108 160 L100.93 131.07 L72 124 L100.93 116.93 Z M103 124 a5 5 0 1 0 10 0 a5 5 0 1 0 -10 0Z" fill="#f2efe8" fill-rule="evenodd" stroke="#f2efe8" stroke-width="4" stroke-linejoin="round"/>
84
84
  <g fill="#f2efe8">
85
85
  <path transform="translate(170.00 158.00) scale(0.04492 -0.04492)" d="M341.583740234375 0.0 15.311767578125 1056.0H297.857421875L401.9129638671875 668.033203125Q431.1849365234375 555.84912109375 458.17291259765625 436.28900146484375Q485.160888671875 316.7288818359375 512.432861328125 200.9527587890625H475.9046630859375Q504.9046630859375 316.7288818359375 534.1206665039062 436.28900146484375Q563.336669921875 555.84912109375 593.9046630859375 668.033203125L701.55224609375 1056.0H947.3134765625L1053.8250732421875 668.033203125Q1084.39306640625 555.84912109375 1113.3250732421875 436.28900146484375Q1142.257080078125 316.7288818359375 1171.257080078125 200.9527587890625H1133.888916015625Q1161.296875 316.7288818359375 1188.204833984375 436.072998046875Q1215.11279296875 555.4171142578125 1243.520751953125 668.033203125L1347.55224609375 1056.0H1633.553955078125L1307.281982421875 0.0H1028.1923828125L902.152587890625 431.615234375Q884.3126220703125 495.4071044921875 866.97265625 561.4149780273438Q849.6326904296875 627.4228515625 832.792724609375 694.5787353515625Q815.9527587890625 761.734619140625 798.11279296875 827.2545166015625H851.3209228515625Q833.9129638671875 761.734619140625 816.572998046875 694.5787353515625Q799.2330322265625 627.4228515625 782.1090698242188 561.4149780273438Q764.985107421875 495.4071044921875 746.1451416015625 431.615234375L618.4013671875 0.0H341.583740234375Z"/>
86
86
  <path transform="translate(243.59 158.00) scale(0.04492 -0.04492)" d="M431.583740234375 -17.2960205078125Q326.1517333984375 -17.2960205078125 244.0157470703125 17.8399658203125Q161.8797607421875 52.9759521484375 114.45977783203125 123.39593505859375Q67.039794921875 193.81591796875 67.039794921875 298.81591796875Q67.039794921875 388.951904296875 100.59576416015625 447.89593505859375Q134.1517333984375 506.8399658203125 191.9237060546875 542.364013671875Q249.6956787109375 577.8880615234375 324.54766845703125 596.4000854492188Q399.399658203125 614.912109375 480.99169921875 623.18408203125Q578.53564453125 633.72802734375 635.8876342773438 642.2400512695312Q693.2396240234375 650.7520751953125 717.9556274414062 667.6160888671875Q742.671630859375 684.4801025390625 742.671630859375 719.72802734375V727.135986328125Q742.671630859375 770.0157470703125 720.5717163085938 802.6355590820312Q698.4718017578125 835.25537109375 657.2039794921875 853.84326171875Q615.9361572265625 872.43115234375 557.92041015625 872.43115234375Q499.608642578125 872.43115234375 455.204833984375 853.7632446289062Q410.801025390625 835.0953369140625 384.86114501953125 801.9514770507812Q358.9212646484375 768.8076171875 354.9212646484375 725.311767578125H98.5439453125Q105.27197265625 832.2479248046875 162.4320068359375 911.2039794921875Q219.592041015625 990.1600341796875 321.72015380859375 1033.944091796875Q423.8482666015625 1077.72802734375 564.83251953125 1077.72802734375Q669.792724609375 1077.72802734375 752.5008544921875 1052.944091796875Q835.208984375 1028.1600341796875 892.4610595703125 981.2960205078125Q949.713134765625 934.4320068359375 979.441162109375 868.0559692382812Q1009.169189453125 801.679931640625 1009.169189453125 718.495849609375V0.0H745.263671875V149.135986328125H741.263671875Q715.3515625 100.3358154296875 674.8955078125 62.6998291015625Q634.439453125 25.0638427734375 574.9635009765625 3.8839111328125Q515.487548828125 -17.2960205078125 431.583740234375 -17.2960205078125ZM501.37646484375 176.608642578125Q579.0240478515625 176.608642578125 633.4398803710938 205.0364990234375Q687.855712890625 233.46435546875 716.127685546875 281.3681640625Q744.399658203125 329.27197265625 744.399658203125 388.767822265625V500.031494140625Q732.2396240234375 492.759521484375 710.0596923828125 486.0555419921875Q687.8797607421875 479.3515625 657.8038940429688 473.1475830078125Q627.72802734375 466.943603515625 592.5161743164062 461.02362060546875Q557.3043212890625 455.1036376953125 519.6484375 449.53564453125Q467.28857421875 441.9676513671875 423.5887451171875 424.84368896484375Q379.888916015625 407.7197265625 353.6650390625 378.48382568359375Q327.441162109375 349.2479248046875 327.441162109375 303.504150390625Q327.441162109375 264.00830078125 348.97308349609375 235.42041015625Q370.5050048828125 206.83251953125 409.56884765625 191.7205810546875Q448.6326904296875 176.608642578125 501.37646484375 176.608642578125Z"/>
@@ -80,7 +80,7 @@
80
80
  <path transform="translate(41.41 0.00) scale(0.00610 -0.00610)" d="M172.437744140625 0.0V1490.0H415.883544921875L999.2868041992188 570.1298828125Q1025.267333984375 529.6188354492188 1059.8074951171875 469.99835205078125Q1094.34765625 410.37786865234375 1133.6676025390625 335.7123718261719Q1172.987548828125 261.046875 1211.07763671875 174.53582763671875H1183.357421875Q1174.717529296875 260.085693359375 1170.4024658203125 341.1064453125Q1166.08740234375 422.127197265625 1164.63720703125 491.5032043457031Q1163.18701171875 560.8792114257812 1163.18701171875 609.1298828125V1490.0H1373.533203125V0.0H1128.267333984375L607.0830078125 820.6318359375Q568.3724975585938 882.6927490234375 530.42236328125 946.813232421875Q492.47222900390625 1010.9337158203125 445.2374572753906 1096.8388671875Q398.002685546875 1182.743896484375 328.80322265625 1308.023681640625H364.43341064453125Q369.7034912109375 1197.56396484375 374.0185852050781 1102.6636962890625Q378.33367919921875 1007.7633666992188 381.01373291015625 936.0528564453125Q383.69378662109375 864.3423461914062 383.69378662109375 822.4517822265625V0.0H172.437744140625Z"/></g>
81
81
  </g>
82
82
  <path d="M1128 -6 C1140 34 1192 58 1192 104 S1176 176 1118 182 S1034 128 984 138 S936 214 878 236 S784 196 724 214 S660 290 580 286 S486 252 412 262 S318 300 250 292 S150 296 124 252 S108 196 108 168" fill="none" stroke="#8a9299" stroke-width="2.2" stroke-dasharray="7 8" stroke-linecap="round"/>
83
- <path d="M108 88 L149.6 160 L66.4 160 Z M100 136.0 a8 8 0 1 0 16 0 a8 8 0 1 0 -16 0Z" fill="#1c1f22" fill-rule="evenodd" stroke="#1c1f22" stroke-width="4" stroke-linejoin="round"/>
83
+ <path d="M108 88 L115.07 116.93 L144 124 L115.07 131.07 L108 160 L100.93 131.07 L72 124 L100.93 116.93 Z M103 124 a5 5 0 1 0 10 0 a5 5 0 1 0 -10 0Z" fill="#1c1f22" fill-rule="evenodd" stroke="#1c1f22" stroke-width="4" stroke-linejoin="round"/>
84
84
  <g fill="#1c1f22">
85
85
  <path transform="translate(170.00 158.00) scale(0.04492 -0.04492)" d="M341.583740234375 0.0 15.311767578125 1056.0H297.857421875L401.9129638671875 668.033203125Q431.1849365234375 555.84912109375 458.17291259765625 436.28900146484375Q485.160888671875 316.7288818359375 512.432861328125 200.9527587890625H475.9046630859375Q504.9046630859375 316.7288818359375 534.1206665039062 436.28900146484375Q563.336669921875 555.84912109375 593.9046630859375 668.033203125L701.55224609375 1056.0H947.3134765625L1053.8250732421875 668.033203125Q1084.39306640625 555.84912109375 1113.3250732421875 436.28900146484375Q1142.257080078125 316.7288818359375 1171.257080078125 200.9527587890625H1133.888916015625Q1161.296875 316.7288818359375 1188.204833984375 436.072998046875Q1215.11279296875 555.4171142578125 1243.520751953125 668.033203125L1347.55224609375 1056.0H1633.553955078125L1307.281982421875 0.0H1028.1923828125L902.152587890625 431.615234375Q884.3126220703125 495.4071044921875 866.97265625 561.4149780273438Q849.6326904296875 627.4228515625 832.792724609375 694.5787353515625Q815.9527587890625 761.734619140625 798.11279296875 827.2545166015625H851.3209228515625Q833.9129638671875 761.734619140625 816.572998046875 694.5787353515625Q799.2330322265625 627.4228515625 782.1090698242188 561.4149780273438Q764.985107421875 495.4071044921875 746.1451416015625 431.615234375L618.4013671875 0.0H341.583740234375Z"/>
86
86
  <path transform="translate(243.59 158.00) scale(0.04492 -0.04492)" d="M431.583740234375 -17.2960205078125Q326.1517333984375 -17.2960205078125 244.0157470703125 17.8399658203125Q161.8797607421875 52.9759521484375 114.45977783203125 123.39593505859375Q67.039794921875 193.81591796875 67.039794921875 298.81591796875Q67.039794921875 388.951904296875 100.59576416015625 447.89593505859375Q134.1517333984375 506.8399658203125 191.9237060546875 542.364013671875Q249.6956787109375 577.8880615234375 324.54766845703125 596.4000854492188Q399.399658203125 614.912109375 480.99169921875 623.18408203125Q578.53564453125 633.72802734375 635.8876342773438 642.2400512695312Q693.2396240234375 650.7520751953125 717.9556274414062 667.6160888671875Q742.671630859375 684.4801025390625 742.671630859375 719.72802734375V727.135986328125Q742.671630859375 770.0157470703125 720.5717163085938 802.6355590820312Q698.4718017578125 835.25537109375 657.2039794921875 853.84326171875Q615.9361572265625 872.43115234375 557.92041015625 872.43115234375Q499.608642578125 872.43115234375 455.204833984375 853.7632446289062Q410.801025390625 835.0953369140625 384.86114501953125 801.9514770507812Q358.9212646484375 768.8076171875 354.9212646484375 725.311767578125H98.5439453125Q105.27197265625 832.2479248046875 162.4320068359375 911.2039794921875Q219.592041015625 990.1600341796875 321.72015380859375 1033.944091796875Q423.8482666015625 1077.72802734375 564.83251953125 1077.72802734375Q669.792724609375 1077.72802734375 752.5008544921875 1052.944091796875Q835.208984375 1028.1600341796875 892.4610595703125 981.2960205078125Q949.713134765625 934.4320068359375 979.441162109375 868.0559692382812Q1009.169189453125 801.679931640625 1009.169189453125 718.495849609375V0.0H745.263671875V149.135986328125H741.263671875Q715.3515625 100.3358154296875 674.8955078125 62.6998291015625Q634.439453125 25.0638427734375 574.9635009765625 3.8839111328125Q515.487548828125 -17.2960205078125 431.583740234375 -17.2960205078125ZM501.37646484375 176.608642578125Q579.0240478515625 176.608642578125 633.4398803710938 205.0364990234375Q687.855712890625 233.46435546875 716.127685546875 281.3681640625Q744.399658203125 329.27197265625 744.399658203125 388.767822265625V500.031494140625Q732.2396240234375 492.759521484375 710.0596923828125 486.0555419921875Q687.8797607421875 479.3515625 657.8038940429688 473.1475830078125Q627.72802734375 466.943603515625 592.5161743164062 461.02362060546875Q557.3043212890625 455.1036376953125 519.6484375 449.53564453125Q467.28857421875 441.9676513671875 423.5887451171875 424.84368896484375Q379.888916015625 407.7197265625 353.6650390625 378.48382568359375Q327.441162109375 349.2479248046875 327.441162109375 303.504150390625Q327.441162109375 264.00830078125 348.97308349609375 235.42041015625Q370.5050048828125 206.83251953125 409.56884765625 191.7205810546875Q448.6326904296875 176.608642578125 501.37646484375 176.608642578125Z"/>
@@ -2,13 +2,13 @@
2
2
 
3
3
  <!-- Generated by tools/docs.py from the code. Don't edit it by hand. -->
4
4
 
5
- Every command of `wm` 0.1.0. Read commands take `--json`; their payloads are described in the [JSON schema reference](json.md).
5
+ Every command of `wm` 0.1.1. Read commands take `--json`; their payloads are described in the [JSON schema reference](json.md).
6
6
 
7
7
  Exit codes: `0` success; `1` refused, or problems found; `2` usage error.
8
8
 
9
9
  ## wm init
10
10
 
11
- Create the record in this git repository.
11
+ Create the record, or set up this machine in a clone that has one.
12
12
 
13
13
  ```
14
14
  wm init [--atlas NAME] [--tool NAME]
@@ -37,7 +37,7 @@ wm doctor [--json]
37
37
 
38
38
  ## wm git-hooks
39
39
 
40
- Put the committed git hooks in this repository and point this clone's git at them.
40
+ Write the git hooks, keep them out of git, and point this clone's git at them.
41
41
 
42
42
  ```
43
43
  wm git-hooks
@@ -37,17 +37,43 @@ This writes:
37
37
  - the git hooks in `.waymark/hooks/`, which check commit messages and run
38
38
  `wm check` on commits that touch the record. `wm init` points this clone's git
39
39
  at them. If the repository already uses a hook manager, nothing is installed
40
- and `wm` prints the two lines to add to it.
40
+ and `wm` prints the two lines to add to it;
41
+ - a block in `.gitignore` that keeps the agent tool files and the git hooks out
42
+ of git. They belong to each machine, not to the project.
41
43
 
42
- Commit all of it, so anyone who clones the repository gets the same setup. Then
43
- run `wm doctor` to check that everything is in place; it changes nothing.
44
+ Commit `waymark/` and `.gitignore`. They are the only files `wm init` wrote
45
+ that `git status` shows. Then run `wm doctor` to check that everything is in place; it
46
+ changes nothing.
47
+
48
+ The block sits between two marker lines. `wm` rewrites what is between them, and
49
+ leaves the rest of `.gitignore` alone. With Claude Code, the block lists:
50
+
51
+ | Pattern | What it ignores |
52
+ |---|---|
53
+ | `/.agents/skills/wm-*/` | the skills `wm` writes |
54
+ | `/.claude/skills/wm-*/` | their copies for Claude Code |
55
+ | `/.claude/agents/wm-*.md` | the agent definitions |
56
+ | `/.claude/settings.json` | Claude Code's settings, with the hooks |
57
+ | `/.waymark/hooks/` | the git hooks |
58
+
59
+ Your own skills and agents, `CLAUDE.md` and `AGENTS.md` are not in the block.
60
+ Commit or ignore them as you choose.
44
61
 
45
62
  Optional: `wm ci` adds a GitHub Actions workflow that installs the pinned `wm`
46
63
  and runs `wm check` on every push and pull request.
47
64
 
48
- > Each clone points git at the hooks itself (`core.hooksPath` is a per-clone
49
- > setting). After cloning a project, run `wm git-hooks`; `wm doctor` and
50
- > `wm status` warn when a clone hasn't.
65
+ ### After cloning a project
66
+
67
+ Install the `wm` version the project pins, then run `wm init` in the clone. It
68
+ finds the record and sets up this machine: it writes the agent tool files,
69
+ installs the git hooks, points this clone's git at them, and adds the
70
+ `.gitignore` block if it is missing. It doesn't change anything in `waymark/`.
71
+ Run it again and it says the machine is already set up.
72
+
73
+ `wm init` is refused in a clone when the installed `wm` isn't the pinned
74
+ version; the message gives the command that installs it. It is also refused
75
+ when the record needs migrating; run `wm update` for that. Until a clone runs
76
+ `wm init`, `wm doctor` and `wm status` warn that it doesn't run the git hooks.
51
77
 
52
78
  ## 3. Write the charter: the `wm-kickoff` skill
53
79
 
@@ -102,7 +128,14 @@ When you come back after a break, in a fresh session or on another machine,
102
128
  Each project pins one exact `wm` version in `waymark/config.toml`. With another
103
129
  version installed, reading works and writing is refused, with the command that
104
130
  installs the pinned one. To upgrade a project: change the pin, install that
105
- version, run `wm update`, review what it changed, and commit.
131
+ version, and run `wm update`. When it changes the record, `.gitignore` or the CI
132
+ workflow, it names them and asks you to review and commit the changes. It never
133
+ asks you to commit the agent tool files or the git hooks.
134
+
135
+ A project set up with `wm` 0.1.0 committed the agent tool files and the git
136
+ hooks. `wm update` adds the `.gitignore` block, but git keeps tracking files it
137
+ already tracks. `wm doctor` warns about them, and gives the `git rm -r --cached`
138
+ command that stops tracking them and keeps your copies. Run it, then commit.
106
139
 
107
140
  ## Next
108
141
 
@@ -47,8 +47,10 @@ wm init --atlas notes
47
47
  ```
48
48
 
49
49
  This writes the record, the agent tool files and the git hooks into the atlas,
50
- and registers the atlas on this machine. Skills, agents and hooks live only in
51
- the atlas; the code repos never need them.
50
+ adds the `.gitignore` block that keeps the agent tool files and hooks out of git
51
+ (see [Getting started](getting-started.md#2-set-up-your-repository)), and
52
+ registers the atlas on this machine. Skills, agents and hooks live only in the
53
+ atlas; the code repos never need them.
52
54
 
53
55
  ## 2. Name the code repos
54
56
 
@@ -76,7 +78,8 @@ listing their folders in `.claude/settings.local.json`, a per-machine file that
76
78
  is kept out of git. `wm atlas doctor` checks the registry, each repo's folder and
77
79
  branch, and the pins; it changes nothing.
78
80
 
79
- Commit the atlas, then start Claude Code in it and run `/wm-kickoff`.
81
+ Commit the atlas's `waymark/` and `.gitignore`, then start Claude Code in it and
82
+ run `/wm-kickoff`.
80
83
 
81
84
  ## 3. Optional: pointers and git hooks in the code repos
82
85
 
@@ -87,8 +90,11 @@ wm atlas point notes # writes .waymark/atlas.toml: the atlas's name, a path hi
87
90
  wm git-hooks # adds the commit-message check, and points this clone at it
88
91
  ```
89
92
 
90
- Commit what they write if the repo's other users should have it too. A repo you
91
- don't own, such as a client's, can stay untouched: the atlas works without both.
93
+ `wm git-hooks` writes the hooks in `.waymark/hooks/` and adds a `.gitignore`
94
+ block that lists only them. The hooks belong to each clone. Commit `.gitignore`,
95
+ and `.waymark/atlas.toml` if the repo's other users should have the pointer; the
96
+ block doesn't ignore the pointer. A repo you don't own, such as a client's, can
97
+ stay untouched: the atlas works without both.
92
98
 
93
99
  ## 4. A change that spans both repos
94
100
 
@@ -147,9 +153,14 @@ messages are checked locally, by the git hooks.
147
153
 
148
154
  ## Another machine, or a teammate
149
155
 
150
- Clone the atlas and the code repos. Side by side, as the hints expect, everything
151
- works at once; run `wm atlas register` to record them anyway. In other places,
152
- register each one with its folder. `wm atlas doctor` says what is missing.
156
+ Clone the atlas and the code repos, and install the `wm` version the atlas pins.
157
+ Then run `wm init` in the atlas. It sets up this machine: the agent tool files
158
+ and the git hooks. It doesn't change the record.
159
+
160
+ Side by side, as the hints expect, the code repos are found at once; run
161
+ `wm atlas register` to record them anyway. In other places, register each one with its folder. In a code repo
162
+ that uses the git hooks, run `wm git-hooks` to install them in this clone.
163
+ `wm atlas doctor` says what is missing.
153
164
 
154
165
  ## Reading another atlas's specs
155
166
 
@@ -14,9 +14,17 @@ Allow about an hour. Work in a scratch repository, never in a real project.
14
14
  wheel, and check `wm --version`.
15
15
  - [ ] Note the Claude Code version: `claude --version`.
16
16
  - [ ] Make a scratch git repository with a little code in it (a small script and
17
- a test are enough). Run `wm init`, commit, and run `wm doctor`: no errors.
18
- - [ ] Commit with a message that isn't conventional, such as `wip`: the commit
19
- is stopped with the reason. Commit again as `chore: set up waymark`.
17
+ a test are enough), and commit it. Run `wm init`: nothing is staged, and
18
+ `git status` shows only `waymark/` and `.gitignore` as new. Run
19
+ `wm doctor`: no errors.
20
+ - [ ] Stage `waymark/` and `.gitignore`, and commit with a message that isn't
21
+ conventional, such as `wip`: the commit is stopped with the reason. Commit
22
+ again as `chore: set up waymark`.
23
+ - [ ] **A fresh clone.** Clone the scratch repository into another folder and
24
+ run `wm init` there: it sets up this machine and changes nothing in
25
+ `waymark/`. `git status` is clean, and `wm doctor` has no errors.
26
+ `git commit --allow-empty -m wip` in the clone is stopped too. Delete the
27
+ clone.
20
28
 
21
29
  ## Session start and kickoff
22
30
 
@@ -48,9 +56,18 @@ Allow about an hour. Work in a scratch repository, never in a real project.
48
56
  - [ ] **Edits are read correctly (G46).** After an agent edits a record file, a
49
57
  deliberately malformed line is reported back right away (ask the planner to
50
58
  add a stray line under an item in `tasks.md`).
51
- - [ ] **The ending is in the final message (G46).** When the implementer stops,
52
- its `ITEM:` and `RESULT:` lines are recorded: the item is ticked in
53
- `tasks.md` without anyone running `wm tick`.
59
+ - [ ] **The ending is recorded in the background (G46).** Claude Code runs
60
+ agents in the background by default, and they hand their report back
61
+ through `SubagentHandback`. Let the planner start an implementer as it
62
+ chooses. When the implementer hands back its report, its `ITEM:` and
63
+ `RESULT:` lines are recorded: the item is ticked in `tasks.md` without
64
+ anyone running `wm tick`. The agent then stops without being asked for
65
+ its ending again.
66
+ - [ ] **The ending is recorded in the foreground (G46).** Ask the planner to run
67
+ the next implementer in the foreground and wait for it. When the
68
+ implementer stops, the `ITEM:` and `RESULT:` lines in its final message are
69
+ recorded: the item is ticked in `tasks.md` without anyone running
70
+ `wm tick`.
54
71
  - [ ] The independent item is reviewed by the `wm-reviewer` agent, and its
55
72
  verdict is written under the item as a `(review)` line in the reviewer's
56
73
  own words. The reviewer can't edit files (ask it to fix something; it is
@@ -1,3 +1,3 @@
1
1
  """Waymark: spec-driven development with a deterministic command-line tool, ``wm``."""
2
2
 
3
- __version__ = "0.1.0"
3
+ __version__ = "0.1.1"
@@ -45,6 +45,8 @@ class Adapter(ABC):
45
45
  reads: tuple[str, ...] = ()
46
46
  local_reads: tuple[str, ...] = ()
47
47
  """Per-machine files the adapter merges into; never committed."""
48
+ ignored: tuple[str, ...] = ()
49
+ """``.gitignore`` patterns for every file ``files`` writes, and nothing the project owns."""
48
50
 
49
51
  @abstractmethod
50
52
  def files(self, existing: Mapping[str, str | None]) -> dict[str, str]:
@@ -27,18 +27,20 @@ HOOK_TIMEOUT = 60
27
27
 
28
28
  _EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
29
29
  _SHELL_TOOLS = ("Bash", "PowerShell")
30
+ _HANDBACK_TOOL = "SubagentHandback"
31
+ """The tool an agent run in the background hands its report back through."""
30
32
  _ROLES = {assets.IMPLEMENTER: Role.IMPLEMENTER, assets.REVIEWER: Role.REVIEWER}
31
33
  _AGENT_TOOLS = {
32
- assets.IMPLEMENTER: "Agent, SubagentHandback",
33
- assets.REVIEWER: "Edit, Write, MultiEdit, NotebookEdit, Agent, SubagentHandback",
34
+ assets.IMPLEMENTER: "Agent",
35
+ assets.REVIEWER: "Edit, Write, MultiEdit, NotebookEdit, Agent",
34
36
  }
35
- """The tools each agent goes without. Neither may start agents of its own, and
36
- neither hands its report back through a tool: the report must be its final
37
- message, where the stop hook reads its ending."""
37
+ """The tools each agent goes without. Neither may start agents of its own. Both
38
+ may hand their report back through a tool when run in the background: the
39
+ PreToolUse hook reads the ending there, as the stop hook does from a final message."""
38
40
 
39
41
  _HOOKS: dict[str, str | None] = {
40
42
  "SessionStart": None,
41
- "PreToolUse": "|".join(("Agent", *_EDIT_TOOLS, *_SHELL_TOOLS)),
43
+ "PreToolUse": "|".join(("Agent", *_EDIT_TOOLS, *_SHELL_TOOLS, _HANDBACK_TOOL)),
42
44
  "PostToolUse": "Edit|Write|MultiEdit",
43
45
  "SubagentStop": "|".join(assets.AGENTS),
44
46
  }
@@ -166,6 +168,15 @@ def _event( # noqa: PLR0911 - one return per hook event
166
168
  role,
167
169
  message=str(payload.get("last_assistant_message") or ""),
168
170
  retried=bool(payload.get("stop_hook_active")),
171
+ agent_id=str(payload.get("agent_id") or ""),
172
+ )
173
+ if name == "PreToolUse" and tool == _HANDBACK_TOOL:
174
+ return Event(
175
+ EventKind.HANDBACK,
176
+ cwd,
177
+ role,
178
+ message=str(tool_input.get("message") or ""),
179
+ agent_id=str(payload.get("agent_id") or ""),
169
180
  )
170
181
  if name == "PreToolUse" and tool == "Agent":
171
182
  return Event(
@@ -211,6 +222,7 @@ class ClaudeCodeAdapter(Adapter):
211
222
  capabilities = Capabilities(skills=True, subagents=True, hooks=True)
212
223
  reads = (SETTINGS,)
213
224
  local_reads = (LOCAL_SETTINGS,)
225
+ ignored = ("/.claude/skills/wm-*/", "/.claude/agents/wm-*.md", f"/{SETTINGS}")
214
226
 
215
227
  def local_files(
216
228
  self, existing: Mapping[str, str | None], folders: Sequence[Path]
@@ -75,7 +75,7 @@ def _atlas_point(args: argparse.Namespace) -> int:
75
75
 
76
76
 
77
77
  def _git_hooks(_: argparse.Namespace) -> int:
78
- return _report(githooks_service.git_hooks(_here()))
78
+ return _report(integration.git_hooks(_here()))
79
79
 
80
80
 
81
81
  def _run_hook(args: argparse.Namespace) -> int:
@@ -304,7 +304,7 @@ def build_parser() -> argparse.ArgumentParser: # noqa: PLR0915 - one flat list
304
304
  parser.add_argument("--version", action="version", version=f"{PROG} {__version__}")
305
305
  commands = parser.add_subparsers(title="commands", metavar="<command>")
306
306
 
307
- summary = "Create the record in this git repository."
307
+ summary = "Create the record, or set up this machine in a clone that has one."
308
308
  init = commands.add_parser("init", help=summary, description=summary)
309
309
  init.add_argument(
310
310
  "--atlas",
@@ -327,7 +327,7 @@ def build_parser() -> argparse.ArgumentParser: # noqa: PLR0915 - one flat list
327
327
  commands, "doctor", _doctor, "Check wm, git and this project's setup; changes nothing."
328
328
  )
329
329
 
330
- summary = "Put the committed git hooks in this repository and point this clone's git at them."
330
+ summary = "Write the git hooks, keep them out of git, and point this clone's git at them."
331
331
  commands.add_parser("git-hooks", help=summary, description=summary).set_defaults(
332
332
  handler=_git_hooks
333
333
  )
@@ -11,6 +11,7 @@ from pathlib import Path
11
11
  from waymark import assets
12
12
  from waymark.hooks import commands
13
13
  from waymark.hooks.events import ALLOW, Decision, Event, EventKind, Role
14
+ from waymark.record import agents
14
15
  from waymark.record.atlas import contains
15
16
  from waymark.record.changes import TASKS_FILE
16
17
  from waymark.record.evidence import evidence_changes, only_adds_notes
@@ -37,6 +38,8 @@ _RESULT = re.compile(r"^\s*RESULT:\s*(done|partial|spec-gap|blocked)\b[^\w\n]*(.
37
38
  _VERDICT = re.compile(r"^\s*VERDICT:\s*(pass|changes|spec-gap)\b[^\w\n]*(.*)$", re.MULTILINE)
38
39
 
39
40
  _AGENT_ROLES = {assets.IMPLEMENTER: IMPLEMENT, assets.REVIEWER: REVIEW}
41
+ _HANDBACK_TRIES = 2
42
+ """Refused handbacks before the agent is let go and the planner told to record its result."""
40
43
  _EVIDENCE_COMMANDS = (
41
44
  "wm tick, wm block, wm gap, wm review, wm verdict, wm reopen or wm resolve; "
42
45
  "accepting is for the human, with wm accept"
@@ -280,18 +283,46 @@ def _record(project: Project, role: Role, message: str, today: datetime.date) ->
280
283
  return lifecycle.add_note(root, name, number, f"partial: {note}" if note else "partial")
281
284
 
282
285
 
286
+ def _gave_up(role: Role, refusal: Refusal) -> Decision:
287
+ return Decision(
288
+ notice=f"Waymark recorded nothing for the {role.value}: {refusal} "
289
+ "Record its result yourself with the wm commands."
290
+ )
291
+
292
+
293
+ def _handback(project: Project, event: Event, today: datetime.date) -> Decision:
294
+ """An agent hands its report back through its tool: record its ending from the report.
295
+
296
+ A report without an ending is refused, so the agent hands back again with
297
+ one; the second refusal lets it through with a notice for the planner.
298
+ """
299
+ if event.role is Role.PLANNER:
300
+ return ALLOW
301
+ try:
302
+ done = _record(project, event.role, event.message, today)
303
+ except Refusal as refusal:
304
+ if agents.count_attempt(project.root, event.agent_id) >= _HANDBACK_TRIES:
305
+ return _gave_up(event.role, refusal)
306
+ return _refuse(f"wm could not record your result. {refusal}")
307
+ agents.mark_recorded(project.root, event.agent_id)
308
+ return Decision(notice=f"Waymark: {done.message}")
309
+
310
+
283
311
  def _agent_stop(project: Project, event: Event, today: datetime.date) -> Decision:
284
312
  if event.role is Role.PLANNER:
285
313
  return ALLOW
314
+ marker = agents.read_marker(project.root, event.agent_id)
315
+ if marker is not None and (marker.recorded or marker.attempts >= _HANDBACK_TRIES):
316
+ agents.remove_marker(project.root, event.agent_id)
317
+ return ALLOW
286
318
  try:
287
319
  done = _record(project, event.role, event.message, today)
288
320
  except Refusal as refusal:
289
321
  if event.retried:
290
- return Decision(
291
- notice=f"Waymark recorded nothing for the {event.role.value}: {refusal} "
292
- "Record its result yourself with the wm commands."
293
- )
322
+ agents.remove_marker(project.root, event.agent_id)
323
+ return _gave_up(event.role, refusal)
294
324
  return _refuse(f"wm could not record your result. {refusal}")
325
+ agents.remove_marker(project.root, event.agent_id)
295
326
  return Decision(notice=f"Waymark: {done.message}")
296
327
 
297
328
 
@@ -311,4 +342,6 @@ def decide(event: Event, today: datetime.date) -> Decision: # noqa: PLR0911
311
342
  return _edited(project, event)
312
343
  if event.kind is EventKind.COMMAND:
313
344
  return _command(event)
345
+ if event.kind is EventKind.HANDBACK:
346
+ return _handback(project, event, today)
314
347
  return _agent_stop(project, event, today)
@@ -22,6 +22,7 @@ class EventKind(StrEnum):
22
22
  EDITED = "edited"
23
23
  COMMAND = "command"
24
24
  AGENT_STOP = "agent-stop"
25
+ HANDBACK = "handback"
25
26
 
26
27
 
27
28
  @dataclass(frozen=True)
@@ -44,8 +45,13 @@ class Event:
44
45
  ``replacements`` the edit makes;
45
46
  - ``EDITED``: ``path``;
46
47
  - ``COMMAND``: ``command``;
47
- - ``AGENT_STOP``: ``message`` (the agent's final words) and ``retried``
48
- (it was already asked once to fix its ending).
48
+ - ``AGENT_STOP``: ``message`` (the agent's final words), ``retried``
49
+ (it was already asked once to fix its ending) and ``agent_id``;
50
+ - ``HANDBACK``: ``message`` (the report an agent hands back through its
51
+ tool instead of a final message) and ``agent_id``.
52
+
53
+ ``agent_id`` names one run of a delegated agent, so its stop can tell
54
+ whether its handback was already recorded.
49
55
  """
50
56
 
51
57
  kind: EventKind
@@ -59,6 +65,7 @@ class Event:
59
65
  command: str = ""
60
66
  message: str = ""
61
67
  retried: bool = False
68
+ agent_id: str = ""
62
69
 
63
70
 
64
71
  @dataclass(frozen=True)