Waymark CLI Skill
Waymarks are structured comments that capture intent, ownership, and constraints
in code. The wm CLI scans, adds, edits, removes, and validates these
annotations across a codebase.
When to Use This Skill
- Find existing waymarks and summarize project status.
- Add new TODOs, TLDRs, or notes while implementing changes.
- Edit signals (flagged/starred) or content in place.
- Remove completed waymarks with audit history.
- Format or lint waymarks for consistency in CI.
Syntax Quick Reference
[signal][marker] ::: [content] [properties] [#tags] [@mentions]
Signals:
~ flagged (in-progress; must clear before merge)* starred (high priority)
Markers (examples):
- Work: todo, fix, wip, done, review, test, check
- Info: note, context, tldr, about, example, idea, comment
- Caution: warn, alert, deprecated, temp
- Workflow: blocked, needs
- Inquiry: ask
Command Overview
| Command |
Purpose |
Example |
| find |
Scan and filter |
wm find src/ --type todo --json |
| add |
Insert waymarks |
wm add src/auth.ts:42 todo "add retry" |
| edit |
Modify waymarks |
wm edit src/auth.ts:42 --flagged |
| rm |
Remove waymarks |
wm rm src/auth.ts:42 --write |
| fmt |
Format waymarks |
wm fmt src/ --write |
| lint |
Validate structure |
wm lint src/ --json |
| init |
Write config |
wm init --format toml |
| doctor |
Diagnose config |
wm doctor --json |
Quick Start Patterns
- Find open work:
wm find src/ --type todo --json
- Add a tldr for a new file:
wm add src/new.ts:1 tldr "summary"
- Flag a waymark during a refactor:
wm edit src/auth.ts:42 --flagged --write
- Remove completed work safely:
wm rm src/auth.ts:42 --write
Output Formats
- Default: human-readable text
--json: JSON array (best for parsing)--jsonl: JSON lines (streaming)
Safety Model
- Most commands preview by default.
- Use
--write to apply changes.
--no-input fails fast in CI if prompts are required.
Exit Codes
| Code |
Meaning |
| 0 |
Success |
| 1 |
Waymark error |
| 2 |
Usage error |
| 3 |
Configuration error |
| 4 |
I/O error |
Getting More Help
- Command docs:
wm skill show <command>
- References:
wm skill show schemas or wm skill show exit-codes
- Skill format:
wm skill show skill-format
- Project-specific skills:
wm skill show project-skills
- Examples:
wm skill show workflows
- CLI help:
wm <command> --help
1---2name: waymark3description: <!-- tldr ::: core skill documentation for waymark CLI agents -->4---5<!-- tldr ::: core skill documentation for waymark CLI agents -->67# Waymark CLI Skill89Waymarks are structured comments that capture intent, ownership, and constraints10in code. The `wm` CLI scans, adds, edits, removes, and validates these11annotations across a codebase.1213## When to Use This Skill1415- Find existing waymarks and summarize project status.16- Add new TODOs, TLDRs, or notes while implementing changes.17- Edit signals (flagged/starred) or content in place.18- Remove completed waymarks with audit history.19- Format or lint waymarks for consistency in CI.2021## Syntax Quick Reference2223```text24[signal][marker] ::: [content] [properties] [#tags] [@mentions]25```2627Signals:2829- `~` flagged (in-progress; must clear before merge)30- `*` starred (high priority)3132Markers (examples):3334- Work: todo, fix, wip, done, review, test, check35- Info: note, context, tldr, about, example, idea, comment36- Caution: warn, alert, deprecated, temp37- Workflow: blocked, needs38- Inquiry: ask3940## Command Overview4142| Command | Purpose | Example |43| --- | --- | --- |44| find | Scan and filter | `wm find src/ --type todo --json` |45| add | Insert waymarks | `wm add src/auth.ts:42 todo "add retry"` |46| edit | Modify waymarks | `wm edit src/auth.ts:42 --flagged` |47| rm | Remove waymarks | `wm rm src/auth.ts:42 --write` |48| fmt | Format waymarks | `wm fmt src/ --write` |49| lint | Validate structure | `wm lint src/ --json` |50| init | Write config | `wm init --format toml` |51| doctor | Diagnose config | `wm doctor --json` |5253## Quick Start Patterns5455- Find open work:56 `wm find src/ --type todo --json`57- Add a tldr for a new file:58 `wm add src/new.ts:1 tldr "summary"`59- Flag a waymark during a refactor:60 `wm edit src/auth.ts:42 --flagged --write`61- Remove completed work safely:62 `wm rm src/auth.ts:42 --write`6364## Output Formats6566- Default: human-readable text67- `--json`: JSON array (best for parsing)68- `--jsonl`: JSON lines (streaming)6970## Safety Model7172- Most commands preview by default.73- Use `--write` to apply changes.74- `--no-input` fails fast in CI if prompts are required.7576## Exit Codes7778| Code | Meaning |79| --- | --- |80| 0 | Success |81| 1 | Waymark error |82| 2 | Usage error |83| 3 | Configuration error |84| 4 | I/O error |8586## Getting More Help8788- Command docs: `wm skill show <command>`89- References: `wm skill show schemas` or `wm skill show exit-codes`90- Skill format: `wm skill show skill-format`91- Project-specific skills: `wm skill show project-skills`92- Examples: `wm skill show workflows`93- CLI help: `wm <command> --help`
outfitter-dev