waymark

Waymark

Waymark defines and maintains the ::: comment sigil plus supporting tooling so humans and AI agents can leave durable, greppable breadcrumbs in codebases.

Current prerelease: 1.0.0-beta.1 (2025-10-03)

Why Waymarks Exist

• Teams already rely on comment-level anchors (TODO, FIXME, MARK) because they survive refactors and are easy to search. Waymarks unify those patterns under one predictable grammar.
• Modern development needs annotations that speak to humans and agents. Waymarks encode ownership, intent, and constraints directly in comments without requiring AST access.
• A curated marker and property set keeps annotations portable across languages, editors, and automation.

Read the full background in Historical Priors for Waymark-Style Anchors.

Waymarks Are Not Docstrings

Waymarks complement docstrings; they never replace them.

Purpose	Use
Public API contracts	Docstrings (JSDoc/TSDoc/docstrings)
Internal intent + ownership	Waymarks

Place waymarks adjacent to docstrings, never inside them:

/**
 * Authenticates a user and returns a session token.
 * @param request - User login credentials
 * @returns Session token or throws AuthError
 */
// about ::: orchestrates OAuth flow with PKCE #auth/login
// todo ::: @agent add rate limiting #sec:boundary
export async function authenticate(request: AuthRequest) {
  // ...
}

Waymarks in Practice

// tldr ::: managing customer authentication flow

export async function authenticate(request: AuthRequest) {
  // *fix ::: validate OTP length before verifying
  // context ::: callers must pass a sanitized email #security

  const user = await fetchUser(request.email)
  // question ::: should we allow social login here? @product

  // ~todo ::: @agent implement refresh token rotation once backend ships
  return issueSession(user, request) // note ::: returns JWT signed with HS256
}

Signals follow the v1 grammar: only the tilde (~) and a single star (*) prefix are valid. Raised waymarks (~todo) mark work-in-progress that must clear before merging; starred waymarks (*fix) mark high-priority items. Combining them (~*todo) is fine, while doubling (**fix) is not.

Line comments are preferred for waymarks. Use block comments only in languages without line-comment support (for example, CSS).

Start Here

1. Specification: Waymark Specification defines the grammar, tooling scope, and roadmap.
2. Grammar Reference: Waymark Grammar mirrors the specification for quick lookup.
3. Agent Guidelines: AGENTS.md covers collaboration expectations for human and AI contributors.

Quick Demo: Find TLDRs

Get an instant overview of your codebase with file-level tldr summaries:

$ wm find src/ --type tldr

src/auth.ts:1
  tldr ::: handles user authentication and JWT tokens

src/database.ts:1
  tldr ::: postgres connection and query builders

src/routes/users.ts:1
  tldr ::: user CRUD endpoints

src/utils/cache.ts:1
  tldr ::: Redis caching layer with TTL support

TLDR waymarks instantly tell you what every file does - perfect for onboarding developers or giving AI agents context about your codebase architecture.

CLI Usage

The wm command provides a unified interface for all waymark operations:

# Basic scanning and filtering
wm find src/                              # scan and display all waymarks
wm find src/ --type todo                  # filter by waymark type
wm find src/ --flagged                    # show only flagged (~) waymarks (in-progress)
wm find src/ --starred                    # show only starred (*) waymarks (high-priority)
wm find src/ --type todo --mention @agent # combine filters

# Graph mode: relation edges
wm find src/ --graph                      # extract dependency relations
wm find src/ --graph --json               # JSON output for tooling

# Output formats
wm find src/ --json                       # compact JSON array
wm find src/ --jsonl                      # newline-delimited JSON
wm find src/ --text                       # human-readable formatted text

# Standalone commands
wm fmt src/ --write               # format waymarks in a directory
wm lint src/ --json                  # validate waymark types
wm rm src/auth.ts:42 --write     # remove a waymark
wm edit src/auth.ts:42 --flagged --write # adjust an existing waymark
wm config --print                  # print merged configuration

# Agent documentation
wm skill                            # core skill documentation
wm skill show add                   # command-specific docs
wm skill --json                     # structured JSON output

To include codetags (TODO/FIXME/NOTE/etc.) in scans, enable:

scan:
  include_codetags: true