waymark-cli 0.1.0__py3-none-any.whl

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 (92) hide show
  1. waymark/__init__.py +3 -0
  2. waymark/__main__.py +8 -0
  3. waymark/adapters/__init__.py +102 -0
  4. waymark/adapters/claude_code.py +238 -0
  5. waymark/assets/__init__.py +43 -0
  6. waymark/assets/agents/wm-implementer.md +45 -0
  7. waymark/assets/agents/wm-reviewer.md +43 -0
  8. waymark/assets/skills/wm-apply/SKILL.md +58 -0
  9. waymark/assets/skills/wm-archive/SKILL.md +32 -0
  10. waymark/assets/skills/wm-explore/SKILL.md +34 -0
  11. waymark/assets/skills/wm-kickoff/SKILL.md +34 -0
  12. waymark/assets/skills/wm-onboard/SKILL.md +27 -0
  13. waymark/assets/skills/wm-pr/SKILL.md +24 -0
  14. waymark/assets/skills/wm-propose/SKILL.md +32 -0
  15. waymark/assets/skills/wm-update/SKILL.md +31 -0
  16. waymark/cli.py +537 -0
  17. waymark/hooks/__init__.py +6 -0
  18. waymark/hooks/commands.py +190 -0
  19. waymark/hooks/decide.py +314 -0
  20. waymark/hooks/events.py +79 -0
  21. waymark/py.typed +0 -0
  22. waymark/record/__init__.py +5 -0
  23. waymark/record/atlas.py +156 -0
  24. waymark/record/changes.py +202 -0
  25. waymark/record/charter.py +75 -0
  26. waymark/record/commits.py +78 -0
  27. waymark/record/config.py +215 -0
  28. waymark/record/deltas.py +318 -0
  29. waymark/record/design.py +80 -0
  30. waymark/record/edits.py +95 -0
  31. waymark/record/evidence.py +58 -0
  32. waymark/record/explorations.py +66 -0
  33. waymark/record/files.py +75 -0
  34. waymark/record/fingerprint.py +73 -0
  35. waymark/record/git.py +167 -0
  36. waymark/record/githooks.py +106 -0
  37. waymark/record/links.py +104 -0
  38. waymark/record/milestones.py +84 -0
  39. waymark/record/moves.py +60 -0
  40. waymark/record/names.py +39 -0
  41. waymark/record/outline.py +144 -0
  42. waymark/record/pointer.py +56 -0
  43. waymark/record/problems.py +20 -0
  44. waymark/record/project.py +118 -0
  45. waymark/record/proposal.py +171 -0
  46. waymark/record/record.py +340 -0
  47. waymark/record/registry.py +158 -0
  48. waymark/record/specs.py +227 -0
  49. waymark/record/state.py +472 -0
  50. waymark/record/store.py +88 -0
  51. waymark/record/tasks.py +415 -0
  52. waymark/record/templates/charter.md +45 -0
  53. waymark/record/templates/ci-workflow.yml +29 -0
  54. waymark/record/templates/config-atlas.toml +8 -0
  55. waymark/record/templates/config.toml +19 -0
  56. waymark/record/templates/delta.md +29 -0
  57. waymark/record/templates/design.md +20 -0
  58. waymark/record/templates/exploration.md +22 -0
  59. waymark/record/templates/goal.md +13 -0
  60. waymark/record/templates/hook-commit-msg +8 -0
  61. waymark/record/templates/hook-pre-commit +8 -0
  62. waymark/record/templates/proposal.md +18 -0
  63. waymark/record/templates/roadmap.md +4 -0
  64. waymark/record/templates/tasks.md +10 -0
  65. waymark/record/templates.py +30 -0
  66. waymark/record/terms.py +51 -0
  67. waymark/record/text.py +197 -0
  68. waymark/services/__init__.py +1 -0
  69. waymark/services/atlas.py +162 -0
  70. waymark/services/check.py +129 -0
  71. waymark/services/ci.py +44 -0
  72. waymark/services/common.py +154 -0
  73. waymark/services/context.py +296 -0
  74. waymark/services/doctor.py +367 -0
  75. waymark/services/githooks.py +132 -0
  76. waymark/services/instructions.py +304 -0
  77. waymark/services/integration.py +170 -0
  78. waymark/services/lifecycle.py +454 -0
  79. waymark/services/migrations.py +90 -0
  80. waymark/services/pr.py +177 -0
  81. waymark/services/references.py +27 -0
  82. waymark/services/setup.py +127 -0
  83. waymark/views/__init__.py +5 -0
  84. waymark/views/payloads.py +568 -0
  85. waymark/views/render.py +506 -0
  86. waymark/views/schemas.py +413 -0
  87. waymark/views/style.py +102 -0
  88. waymark_cli-0.1.0.dist-info/METADATA +313 -0
  89. waymark_cli-0.1.0.dist-info/RECORD +92 -0
  90. waymark_cli-0.1.0.dist-info/WHEEL +4 -0
  91. waymark_cli-0.1.0.dist-info/entry_points.txt +2 -0
  92. waymark_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
waymark/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """Waymark: spec-driven development with a deterministic command-line tool, ``wm``."""
2
+
3
+ __version__ = "0.1.0"
waymark/__main__.py ADDED
@@ -0,0 +1,8 @@
1
+ """Run ``wm`` as ``python -m waymark``."""
2
+
3
+ import sys
4
+
5
+ from waymark.cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
@@ -0,0 +1,102 @@
1
+ """Adapters: one per agent tool.
2
+
3
+ An adapter renders the files its tool needs and translates the tool's hook
4
+ events to and from wm's neutral ones. It holds no rules: every decision is
5
+ made by the core, so it is the same in every tool.
6
+ """
7
+
8
+ import datetime
9
+ from abc import ABC, abstractmethod
10
+ from collections.abc import Mapping, Sequence
11
+ from dataclasses import dataclass
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class Capabilities:
18
+ """What an agent tool offers. The workflow adapts to what is missing."""
19
+
20
+ skills: bool
21
+ subagents: bool
22
+ hooks: bool
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class HookReply:
27
+ """What a hook command prints and exits with, in the tool's own protocol."""
28
+
29
+ stdout: str = ""
30
+ stderr: str = ""
31
+ code: int = 0
32
+
33
+
34
+ class Adapter(ABC):
35
+ """An agent tool's adapter.
36
+
37
+ ``reads`` names the project files the adapter merges its settings into;
38
+ their current text is handed to ``files``. Paths are relative to the
39
+ project's top folder, with forward slashes.
40
+ """
41
+
42
+ name: str
43
+ title: str
44
+ capabilities: Capabilities
45
+ reads: tuple[str, ...] = ()
46
+ local_reads: tuple[str, ...] = ()
47
+ """Per-machine files the adapter merges into; never committed."""
48
+
49
+ @abstractmethod
50
+ def files(self, existing: Mapping[str, str | None]) -> dict[str, str]:
51
+ """The files Waymark owns for this tool, with their full text."""
52
+
53
+ def local_files(
54
+ self, existing: Mapping[str, str | None], folders: Sequence[Path]
55
+ ) -> dict[str, str]:
56
+ """Per-machine files that attach an atlas's code repo folders to the tool's sessions.
57
+
58
+ A tool that can't attach folders through a file writes nothing.
59
+ """
60
+ del existing, folders
61
+ return {}
62
+
63
+ def hook(
64
+ self, event: str, payload: Mapping[str, Any], cwd: Path, today: datetime.date
65
+ ) -> HookReply:
66
+ """Answer one of the tool's hook events. A tool without hooks answers nothing."""
67
+ del event, payload, cwd, today
68
+ return HookReply()
69
+
70
+
71
+ class UnknownToolError(Exception):
72
+ """No adapter has this name."""
73
+
74
+
75
+ _REGISTRY: dict[str, Adapter] = {}
76
+
77
+
78
+ def register(adapter: Adapter) -> None:
79
+ """Add an adapter. Adding a tool needs nothing else from the core."""
80
+ _REGISTRY[adapter.name] = adapter
81
+
82
+
83
+ def names() -> tuple[str, ...]:
84
+ """Every registered adapter's name."""
85
+ return tuple(sorted(_REGISTRY))
86
+
87
+
88
+ def get(name: str) -> Adapter:
89
+ """The adapter for a tool."""
90
+ try:
91
+ return _REGISTRY[name]
92
+ except KeyError:
93
+ raise UnknownToolError(name) from None
94
+
95
+
96
+ def _register_built_in() -> None:
97
+ from waymark.adapters.claude_code import ClaudeCodeAdapter # noqa: PLC0415
98
+
99
+ register(ClaudeCodeAdapter())
100
+
101
+
102
+ _register_built_in()
@@ -0,0 +1,238 @@
1
+ """The Claude Code adapter.
2
+
3
+ It copies the skills into ``.claude/skills/``, writes the two agent
4
+ definitions into ``.claude/agents/``, and merges wm's hooks into
5
+ ``.claude/settings.json``. Its hook handler turns Claude Code's hook payloads
6
+ into wm's neutral events and the decisions back into Claude Code's replies.
7
+ It decides nothing itself.
8
+ """
9
+
10
+ import datetime
11
+ import json
12
+ from collections.abc import Mapping, Sequence
13
+ from pathlib import Path
14
+ from typing import Any
15
+
16
+ from waymark import assets
17
+ from waymark.adapters import Adapter, Capabilities, HookReply
18
+ from waymark.hooks.decide import decide
19
+ from waymark.hooks.events import Decision, Event, EventKind, Replacement, Role
20
+
21
+ NAME = "claude-code"
22
+ SETTINGS = ".claude/settings.json"
23
+ LOCAL_SETTINGS = ".claude/settings.local.json"
24
+ """Per-machine settings, never committed; the code repos of an atlas are attached here."""
25
+ HOOK_COMMAND = f"wm hook {NAME}"
26
+ HOOK_TIMEOUT = 60
27
+
28
+ _EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
29
+ _SHELL_TOOLS = ("Bash", "PowerShell")
30
+ _ROLES = {assets.IMPLEMENTER: Role.IMPLEMENTER, assets.REVIEWER: Role.REVIEWER}
31
+ _AGENT_TOOLS = {
32
+ assets.IMPLEMENTER: "Agent, SubagentHandback",
33
+ assets.REVIEWER: "Edit, Write, MultiEdit, NotebookEdit, Agent, SubagentHandback",
34
+ }
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."""
38
+
39
+ _HOOKS: dict[str, str | None] = {
40
+ "SessionStart": None,
41
+ "PreToolUse": "|".join(("Agent", *_EDIT_TOOLS, *_SHELL_TOOLS)),
42
+ "PostToolUse": "Edit|Write|MultiEdit",
43
+ "SubagentStop": "|".join(assets.AGENTS),
44
+ }
45
+ """The hook events wm listens to, each with the matcher that selects what it handles."""
46
+
47
+
48
+ def _agent_file(name: str) -> str:
49
+ description, body = assets.agent(name)
50
+ header = [
51
+ "---",
52
+ f"name: {name}",
53
+ f"description: {description}",
54
+ f"disallowedTools: {_AGENT_TOOLS[name]}",
55
+ "---",
56
+ ]
57
+ return "\n".join(header) + "\n\n" + body
58
+
59
+
60
+ def _is_ours(handler: Any) -> bool:
61
+ command = handler.get("command", "") if isinstance(handler, dict) else ""
62
+ return isinstance(command, str) and command.startswith("wm hook ")
63
+
64
+
65
+ def merge_settings(existing: str | None) -> str:
66
+ """The settings file with wm's hooks in place and everything else as it was.
67
+
68
+ Only hook entries whose command starts with ``wm hook`` are replaced. The
69
+ file is written back as JSON with two-space indentation.
70
+ """
71
+ settings = json.loads(existing) if existing and existing.strip() else {}
72
+ if not isinstance(settings, dict):
73
+ raise ValueError("the top level is not an object")
74
+ hooks = settings.get("hooks", {})
75
+ if not isinstance(hooks, dict):
76
+ raise ValueError('"hooks" is not an object')
77
+ merged: dict[str, list[Any]] = {}
78
+ for event, groups in hooks.items():
79
+ kept: list[Any] = []
80
+ for group in groups if isinstance(groups, list) else []:
81
+ handlers = group.get("hooks") if isinstance(group, dict) else None
82
+ if not isinstance(handlers, list):
83
+ kept.append(group)
84
+ continue
85
+ theirs = [handler for handler in handlers if not _is_ours(handler)]
86
+ if theirs:
87
+ kept.append({**group, "hooks": theirs})
88
+ if kept:
89
+ merged[event] = kept
90
+ for event, matcher in _HOOKS.items():
91
+ handler = {"type": "command", "command": f"{HOOK_COMMAND} {event}", "timeout": HOOK_TIMEOUT}
92
+ ours: dict[str, Any] = {"hooks": [handler]}
93
+ if matcher is not None:
94
+ ours = {"matcher": matcher, **ours}
95
+ merged.setdefault(event, []).append(ours)
96
+ return json.dumps({**settings, "hooks": merged}, indent=2, ensure_ascii=False) + "\n"
97
+
98
+
99
+ def merge_local_settings(existing: str | None, folders: Sequence[Path]) -> str:
100
+ """The per-machine settings with the code repo folders attached, everything else kept.
101
+
102
+ Folders are added to ``permissions.additionalDirectories`` when missing.
103
+ Nothing is removed: the file can't tell wm's entries from the person's own.
104
+ """
105
+ settings = json.loads(existing) if existing and existing.strip() else {}
106
+ if not isinstance(settings, dict):
107
+ raise ValueError("the top level is not an object")
108
+ permissions = settings.get("permissions", {})
109
+ if not isinstance(permissions, dict):
110
+ raise ValueError('"permissions" is not an object')
111
+ listed = permissions.get("additionalDirectories", [])
112
+ if not isinstance(listed, list):
113
+ raise ValueError('"permissions.additionalDirectories" is not a list')
114
+ seen = {Path(entry) for entry in listed if isinstance(entry, str)}
115
+ added = [str(folder) for folder in folders if folder not in seen]
116
+ permissions = {**permissions, "additionalDirectories": [*listed, *added]}
117
+ return json.dumps({**settings, "permissions": permissions}, indent=2, ensure_ascii=False) + "\n"
118
+
119
+
120
+ def _role(payload: Mapping[str, Any]) -> Role:
121
+ return _ROLES.get(str(payload.get("agent_type") or ""), Role.PLANNER)
122
+
123
+
124
+ def _path(value: Any, cwd: Path) -> Path | None:
125
+ if not isinstance(value, str) or not value:
126
+ return None
127
+ path = Path(value).expanduser()
128
+ return path if path.is_absolute() else cwd / path
129
+
130
+
131
+ def _edit_event(kind: EventKind, payload: Mapping[str, Any], cwd: Path) -> Event:
132
+ tool_input = payload.get("tool_input") or {}
133
+ path = _path(tool_input.get("file_path") or tool_input.get("notebook_path"), cwd)
134
+ content = tool_input.get("content") if payload.get("tool_name") == "Write" else None
135
+ edits = tool_input.get("edits") or [tool_input]
136
+ replacements = tuple(
137
+ Replacement(
138
+ str(edit["old_string"]), str(edit.get("new_string", "")), bool(edit.get("replace_all"))
139
+ )
140
+ for edit in edits
141
+ if isinstance(edit, dict) and "old_string" in edit
142
+ )
143
+ return Event(
144
+ kind,
145
+ cwd,
146
+ _role(payload),
147
+ path=path,
148
+ content=content if isinstance(content, str) else None,
149
+ replacements=replacements,
150
+ )
151
+
152
+
153
+ def _event( # noqa: PLR0911 - one return per hook event
154
+ name: str, payload: Mapping[str, Any], cwd: Path
155
+ ) -> Event | None:
156
+ """Claude Code's hook payload as one of wm's neutral events; None when it isn't ours."""
157
+ tool = str(payload.get("tool_name") or "")
158
+ tool_input = payload.get("tool_input") or {}
159
+ role = _role(payload)
160
+ if name == "SessionStart":
161
+ return Event(EventKind.SESSION_START, cwd)
162
+ if name == "SubagentStop":
163
+ return Event(
164
+ EventKind.AGENT_STOP,
165
+ cwd,
166
+ role,
167
+ message=str(payload.get("last_assistant_message") or ""),
168
+ retried=bool(payload.get("stop_hook_active")),
169
+ )
170
+ if name == "PreToolUse" and tool == "Agent":
171
+ return Event(
172
+ EventKind.DELEGATE,
173
+ cwd,
174
+ role,
175
+ agent=str(tool_input.get("subagent_type") or ""),
176
+ prompt=str(tool_input.get("prompt") or ""),
177
+ )
178
+ if name == "PreToolUse" and tool in _SHELL_TOOLS:
179
+ return Event(EventKind.COMMAND, cwd, role, command=str(tool_input.get("command") or ""))
180
+ if name == "PreToolUse" and tool in _EDIT_TOOLS:
181
+ return _edit_event(EventKind.EDIT, payload, cwd)
182
+ if name == "PostToolUse" and tool in _EDIT_TOOLS:
183
+ return _edit_event(EventKind.EDITED, payload, cwd)
184
+ return None
185
+
186
+
187
+ def _reply(name: str, decision: Decision) -> HookReply:
188
+ """A decision in the form Claude Code expects for this hook event."""
189
+ reply: dict[str, Any] = {}
190
+ if name == "PreToolUse" and not decision.allow:
191
+ reply["hookSpecificOutput"] = {
192
+ "hookEventName": name,
193
+ "permissionDecision": "deny",
194
+ "permissionDecisionReason": decision.reason,
195
+ }
196
+ elif not decision.allow:
197
+ reply["decision"] = "block"
198
+ reply["reason"] = decision.reason
199
+ if decision.context:
200
+ reply["hookSpecificOutput"] = {"hookEventName": name, "additionalContext": decision.context}
201
+ if decision.notice:
202
+ reply["systemMessage"] = decision.notice
203
+ return HookReply(stdout=json.dumps(reply, ensure_ascii=True) if reply else "")
204
+
205
+
206
+ class ClaudeCodeAdapter(Adapter):
207
+ """Renders the Claude Code files and answers its hooks."""
208
+
209
+ name = NAME
210
+ title = "Claude Code"
211
+ capabilities = Capabilities(skills=True, subagents=True, hooks=True)
212
+ reads = (SETTINGS,)
213
+ local_reads = (LOCAL_SETTINGS,)
214
+
215
+ def local_files(
216
+ self, existing: Mapping[str, str | None], folders: Sequence[Path]
217
+ ) -> dict[str, str]:
218
+ if not folders:
219
+ return {}
220
+ return {LOCAL_SETTINGS: merge_local_settings(existing.get(LOCAL_SETTINGS), folders)}
221
+
222
+ def files(self, existing: Mapping[str, str | None]) -> dict[str, str]:
223
+ rendered = {
224
+ f".claude/skills/{name}/{assets.SKILL_FILE}": assets.skill(name)
225
+ for name in assets.SKILLS
226
+ }
227
+ rendered.update({f".claude/agents/{name}.md": _agent_file(name) for name in assets.AGENTS})
228
+ rendered[SETTINGS] = merge_settings(existing.get(SETTINGS))
229
+ return rendered
230
+
231
+ def hook(
232
+ self, event: str, payload: Mapping[str, Any], cwd: Path, today: datetime.date
233
+ ) -> HookReply:
234
+ where = _path(payload.get("cwd"), cwd) or cwd
235
+ neutral = _event(event, payload, where)
236
+ if neutral is None:
237
+ return HookReply()
238
+ return _reply(event, decide(neutral, today))
@@ -0,0 +1,43 @@
1
+ """The skills and agent definitions wm installs into a project.
2
+
3
+ They are written once, tool-neutral: they use only what every agent tool has,
4
+ which is reading and editing files, running commands and calling ``wm``.
5
+ Adapters copy them into each tool's folders.
6
+ """
7
+
8
+ from importlib import resources
9
+
10
+ SKILLS = (
11
+ "wm-kickoff",
12
+ "wm-explore",
13
+ "wm-propose",
14
+ "wm-update",
15
+ "wm-apply",
16
+ "wm-archive",
17
+ "wm-onboard",
18
+ "wm-pr",
19
+ )
20
+ """Every skill, by the name it is installed under."""
21
+
22
+ IMPLEMENTER = "wm-implementer"
23
+ REVIEWER = "wm-reviewer"
24
+ AGENTS = (IMPLEMENTER, REVIEWER)
25
+ """The agents a change's items are delegated to."""
26
+
27
+ SKILL_FILE = "SKILL.md"
28
+
29
+
30
+ def skill(name: str) -> str:
31
+ """A skill's file, as it is installed."""
32
+ source = resources.files("waymark.assets").joinpath("skills", name, SKILL_FILE)
33
+ return source.read_text(encoding="utf-8")
34
+
35
+
36
+ def agent(name: str) -> tuple[str, str]:
37
+ """An agent definition: its one-line description, and its instructions."""
38
+ source = resources.files("waymark.assets").joinpath("agents", f"{name}.md")
39
+ text = source.read_text(encoding="utf-8")
40
+ _, header, body = text.split("---\n", 2)
41
+ fields = dict(line.split(": ", 1) for line in header.strip().split("\n"))
42
+ assert fields["name"] == name
43
+ return fields["description"], body.lstrip("\n")
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: wm-implementer
3
+ description: Builds one Waymark task item from the written record alone. Start it with exactly "<change> <item>", for example "add-search-limit 1.2", and nothing else.
4
+ ---
5
+
6
+ You are an implementer. You build one task item of one change, from the project's written record and nothing else. You have no earlier conversation to rely on, and you don't need one.
7
+
8
+ ## How you start
9
+
10
+ Your prompt is a change name and an item number, such as `add-search-limit 1.2`.
11
+
12
+ 1. Run `wm context <change> <item> --for implement`.
13
+ 2. Read the whole context pack. It holds your item and its criteria, the proposal, the deltas, the design, the requirements the deltas touch as they stand today, the project's context, and the rules for this step.
14
+
15
+ If the command is refused, don't work around it: end with a `RESULT: blocked` line that quotes the refusal.
16
+
17
+ ## How you work
18
+
19
+ - Build exactly what your item asks for, so that its criteria hold and the scenarios in the deltas pass. Do the verification the item names.
20
+ - Follow the project's context and rules from the pack.
21
+ - Stay inside your item. If you see other work that is needed, say so in your note; don't do it.
22
+ - If your item names a repo, the pack gives that repo's folder. Edit only inside that folder; work in other repos belongs to other items.
23
+ - You may add notes for whoever comes next as ` - Note: <text>` lines under your own item in the change's `tasks.md`.
24
+
25
+ ## What you must not do
26
+
27
+ - Don't edit any other file in the record: not the proposal, the deltas, the design, the specs or the charter.
28
+ - Don't tick your item, and don't write `Blocked:`, `Spec gap:` or review lines. `wm` writes those from your result.
29
+ - Don't run `wm` commands that write. Reading commands such as `wm show` and `wm context` are fine.
30
+ - Don't commit and don't push.
31
+ - Don't guess. If the record doesn't say enough to build the item, that is a spec gap: stop and report it.
32
+
33
+ ## How you finish
34
+
35
+ End your reply with these two lines, and nothing after them:
36
+
37
+ ```
38
+ ITEM: <change> <item>
39
+ RESULT: <done | partial | spec-gap | blocked>: <a short note>
40
+ ```
41
+
42
+ - `done`: the criteria hold and you verified them. Say how.
43
+ - `partial`: you built part of it. Say what is left.
44
+ - `spec-gap`: the record isn't enough. Say exactly what is missing.
45
+ - `blocked`: something outside the item stops you. Say what.
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: wm-reviewer
3
+ description: Reviews one Waymark task item against its criteria and scenarios, read-only and without seeing how it was built. Start it with exactly "<change> <item>", for example "add-search-limit 1.2", and nothing else.
4
+ ---
5
+
6
+ You are a reviewer. You check one task item of one change against what was agreed, and you change nothing. You were not told how the item was built, on purpose: judge the result, not the reasoning.
7
+
8
+ ## How you start
9
+
10
+ Your prompt is a change name and an item number, such as `add-search-limit 1.2`.
11
+
12
+ 1. Run `wm context <change> <item> --for review`.
13
+ 2. Read the whole context pack. It holds the item with its criteria and verification, the deltas with their scenarios, the project's context, and the rules for this step.
14
+
15
+ If the command is refused, end with a `VERDICT: spec-gap` line that quotes the refusal.
16
+
17
+ ## How you review
18
+
19
+ - Read the code as it now stands. Find where the item was built.
20
+ - Check each criterion, and each scenario in the deltas that the item serves: is the work complete, is it correct, and does it fit with the rest?
21
+ - Run the verification the item names, and the tests. Read-only commands only.
22
+ - Be specific. A finding names the file, what is wrong, and which criterion or scenario it breaks.
23
+
24
+ ## What you must not do
25
+
26
+ - Don't edit anything: not the code, not the record.
27
+ - Don't run commands that change state: no writes, installs, commits or pushes.
28
+ - Don't read the implementer's notes or ask how the item was built.
29
+ - Don't run `wm` commands that write. `wm` records your verdict from your final lines.
30
+ - Don't pass work because it is close. If a criterion doesn't hold, the verdict is `changes`.
31
+
32
+ ## How you finish
33
+
34
+ End your reply with these two lines, and nothing after them:
35
+
36
+ ```
37
+ ITEM: <change> <item>
38
+ VERDICT: <pass | changes | spec-gap>: <your reasons, in one line>
39
+ ```
40
+
41
+ - `pass`: every criterion holds and the scenarios are met.
42
+ - `changes`: something must be fixed. Say what, precisely enough to act on.
43
+ - `spec-gap`: the record isn't enough to judge the item. Say what is missing.
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: wm-apply
3
+ description: Build an accepted Waymark change item by item - delegate each item to an implementer, run its review, handle the verdict and commit. Use when a change is accepted and ready to build.
4
+ ---
5
+
6
+ # Apply
7
+
8
+ You are the planner. You don't write the code yourself: each item is built by a fresh implementer that sees only the record, and checked at its review level. You delegate, review, record and commit.
9
+
10
+ ## Before you start
11
+
12
+ 1. Find the change. If the human didn't name it, run `wm ls changes` and ask which one.
13
+ 2. Run `wm instructions --change <name> --json`. If the step is not `apply`, `review`, `resolve-items` or `archive`, the change isn't ready: say what the step is and stop.
14
+ 3. Make sure you are on the change's branch: its name is the branch name. Create it if it doesn't exist. In an atlas, the same branch name is used in the atlas and in every code repo the change's items name; `wm status` shows each one's branch and warns when one differs. If `wm` says a repo isn't on this machine, ask the human to clone it and run `wm atlas register`.
15
+
16
+ ## The loop
17
+
18
+ Repeat until `wm instructions --change <name> --json` says the step is `archive`:
19
+
20
+ ### Step `apply`
21
+
22
+ - If the commands start with `wm reopen`, run it first: a review asked for changes.
23
+ - Start the `wm-implementer` agent with a prompt of exactly `<name> <item>` and nothing else, for example `add-search-limit 1.2`. It builds its own context from the record.
24
+ - When it returns, run `wm show <name> --json` and look at the item:
25
+ - ticked: go on to its review;
26
+ - a `Blocked:` or `Spec gap:` line: that item waits on the human; go on to the next step;
27
+ - neither, and the agent reported `partial`: delegate the item again;
28
+ - neither, and your tool recorded nothing: record the result yourself with `wm tick`, `wm block` or `wm gap`, using the agent's own words.
29
+
30
+ ### Step `review`
31
+
32
+ `wm instructions` tells you which kind:
33
+
34
+ - **Self-review.** Check the item against its criteria and the scenarios it serves: is it complete, correct and coherent with the rest? Read the code and run the verification. Then run `wm review <name> <item> --self "<summary>"`. If it isn't right, don't record a review: delegate the item again.
35
+ - **Independent review.** Start the `wm-reviewer` agent with a prompt of exactly `<name> <item>`. When it returns, look at the item with `wm show`:
36
+ - `pass`: the item is reviewed;
37
+ - `changes`: the next `apply` step reopens it and delegates it again;
38
+ - a second `changes`, or `spec-gap`: it goes to the human.
39
+ If your tool recorded nothing, run `wm verdict <name> <item> <verdict> "<the reviewer's reasons>"` with the reviewer's own words.
40
+
41
+ ### After a review passes
42
+
43
+ Commit the item's work, in the repository it belongs to, with a conventional commit message such as `feat(api): add the result limit`. If the project lists commit scopes, use one of them or none. When a git hook stops the commit, fix what it says; don't skip the hooks. At review level `none`, commit once the item is ticked. Don't push and don't open a pull request unless the human asks.
44
+
45
+ ### Step `resolve-items`
46
+
47
+ Only items that wait on the human are left. Run `wm inbox` and bring each one to them: the blocker, the spec gap, or the verdict. A spec gap is fixed by revising the change with the `wm-update` skill. Once they have decided, run `wm resolve <name> <item> "<what was decided>"`.
48
+
49
+ ## When the step is `archive`
50
+
51
+ Every item is built and reviewed. Tell the human, and offer the `wm-pr` skill and then the `wm-archive` skill.
52
+
53
+ ## Rules
54
+
55
+ - Never run `wm accept` or `wm archive --override`.
56
+ - Delegate with the change and item only. Don't explain the task in the prompt: what the implementer needs is in the record, and if it isn't, that is a spec gap.
57
+ - Record a reviewer's verdict in the reviewer's words, never your retelling.
58
+ - If your tool has no isolated agents, build the item yourself from `wm context <name> <item> --for implement`, and review it as a self-review.
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: wm-archive
3
+ description: Archive an applied Waymark change - check it is applied, write its outcome, merge its deltas into the specs and move it to the archive. Use when a change is built, reviewed and merged.
4
+ ---
5
+
6
+ # Archive
7
+
8
+ You are the planner. Archiving completes a change: its deltas become part of the living specs, its outcome is written down, and its folder moves to the dated archive. It is the human's decision, and it comes after the code is merged.
9
+
10
+ ## Steps
11
+
12
+ 1. Find the change. If the human didn't name it, run `wm ls changes` and ask which one.
13
+ 2. Run `wm instructions --change <name> --json`. If the step is not `archive`, the change isn't applied: say what is still missing and stop.
14
+ 3. Confirm with the human that the code is merged. `wm` can't see a remote merge.
15
+ 4. Draft the outcome with the human: what was built, and anything that differs from the proposal. Two or three sentences.
16
+ 5. Ask the human to run `wm archive <name> --outcome "<the outcome>"`, or run it when they tell you to.
17
+ 6. Run `wm check` and `wm status`.
18
+ 7. If the change belongs to a milestone, ask whether the milestone's path changed: does the roadmap still fit, and is the milestone ready to close with `wm close <milestone>`?
19
+ 8. Commit the record: the specs, the archived change and anything else `wm` rewrote.
20
+
21
+ ## If the archive is refused
22
+
23
+ `wm` says why:
24
+
25
+ - **Not accepted, items not ticked, or a conflict.** These can't be overridden. Go back to the `wm-apply` or `wm-update` skill.
26
+ - **A review record is missing.** Review the item. Only the human may archive anyway, with `wm archive <name> --override "<reason>"`; the reason is written into the outcome. Never run the override yourself.
27
+
28
+ ## Rules
29
+
30
+ - Never run `wm archive --override`.
31
+ - Don't edit files under `waymark/specs/` by hand; the archive merges the deltas.
32
+ - To put the deltas into the specs before the change can be archived, use `wm sync <name>`.
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: wm-explore
3
+ description: Think an idea through with the human before anything is proposed, from the project's written record. Writes nothing unless the human asks. Use when an idea is still fuzzy.
4
+ ---
5
+
6
+ # Explore
7
+
8
+ You are the planner. Exploring is thinking, not building: you help the human get from a fuzzy idea to a clear one. You write nothing unless they take one of the closing offers.
9
+
10
+ ## Steps
11
+
12
+ 1. Run `wm context --for explore`. It gives you the charter and an index of the specs, the changes in flight, the open milestones and the saved explorations. Run `wm instructions explore` for the project's rules for this step.
13
+ 2. Read what bears on the idea: `wm show <spec>` for a spec, `wm show <change>` for a change in flight, a saved exploration on the same topic. When the pack lists specs from another atlas the project references, read one with `wm show <spec> --from <atlas>`; those specs are read only.
14
+ 3. Work the idea through with the human:
15
+ - what problem it solves, and for whom;
16
+ - what the specs already say about it, and which requirements it would add, change or remove;
17
+ - two or three approaches, with what speaks for and against each;
18
+ - what is still unknown, as questions.
19
+ 4. Look at the code when it helps, but don't change it.
20
+
21
+ ## Closing offers
22
+
23
+ When the idea is clear enough, or the human wants to stop, offer exactly these:
24
+
25
+ 1. **Do nothing.** The conversation was enough.
26
+ 2. **Save an exploration.** Run `wm new exploration <name>` and fill in its sections: Context, Questions, Approaches, Related. Leave Conclusion empty while it is open, or write `Parked: <reason>` when the idea is kept for later.
27
+ 3. **Start a proposal.** Hand over to the `wm-propose` skill. If an exploration was saved, its Conclusion becomes a link to the new change.
28
+ 4. **Start a milestone**, when the goal is too big or too uncertain for one change. Run `wm new milestone <name>`, draft its goal with the human, and list the likely changes on its roadmap as plain lines.
29
+
30
+ ## Rules
31
+
32
+ - Don't write to the record before the human picks an offer.
33
+ - Don't edit specs; they change only when a change is archived.
34
+ - Say plainly when the record doesn't answer a question. Don't fill the gap with a guess.
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: wm-kickoff
3
+ description: Interview the human and draft the project's charter and settings for Waymark. Use right after "wm init", or when the charter is still a skeleton.
4
+ ---
5
+
6
+ # Kickoff
7
+
8
+ You are the planner. Your job here is to turn what the human knows about the project into a charter that every later agent can work from. The human decides; you draft.
9
+
10
+ ## Steps
11
+
12
+ 1. Run `wm status --json` and read `waymark/charter.md` and `waymark/config.toml`. If the charter is already filled in, ask whether to revise it instead of starting over.
13
+ 2. Interview the human, a few questions at a time. Cover:
14
+ - what the project is and who it is for (Vision);
15
+ - what it must achieve, and what it deliberately leaves out (Goals, Non-goals);
16
+ - limits every change must respect: platforms, dependencies, budgets (Constraints);
17
+ - the project's own terms (Glossary);
18
+ - facts every agent needs: where things live, how to build, run and test, who owns what (Context);
19
+ - any rules for a workflow step, such as "run the full test suite before reporting" for apply (Rules).
20
+ 3. Look at the repository yourself to fill in Context: the layout, the test command, the conventions already in use. State what you found; don't guess.
21
+ 4. Draft the charter by editing `waymark/charter.md`. Keep every heading. Put a step's rules under its own heading in Rules, and leave a step's heading empty when there are none.
22
+ 5. Settings, in `waymark/config.toml`: confirm the default review level with the human, and offer a list of commit scopes if the project uses them. In an atlas, add one `[atlas.repos.<name>]` table per code repository, with a relative `path` hint when the repositories sit side by side. Then run `wm atlas register` so this machine knows where they are, and `wm atlas doctor` to check the setup. If the project reads another atlas's specs, add a `[references.<atlas>]` table for it.
23
+ 6. Run `wm check`. Fix what it reports in the files you wrote.
24
+ 7. Show the human the charter and ask for their approval. Revise until they approve.
25
+
26
+ ## Rules
27
+
28
+ - Write only what the human said or what you verified in the repository. Mark anything uncertain as a question for them.
29
+ - The charter states facts and rules. Requirements belong in specs, which come from changes.
30
+ - Don't create a change here.
31
+
32
+ ## When done
33
+
34
+ Offer the `wm-onboard` skill: it runs one real, small change through the whole workflow on the human's own code.