Help us improve
Share bugs, ideas, or general feedback.
From waymark
This skill should be used when the user asks about "waymark syntax", "writing waymarks", "::: sigil", "tldr waymarks", "about waymarks", searching waymarks with ripgrep, or mentions waymark grammar, signals, markers, or properties. Provides comprehensive guidance for authoring and searching waymarks without requiring CLI tools.
npx claudepluginhub outfitter-dev/waymarkHow this skill is triggered — by the user, by Claude, or both
Slash command
/waymark:using-waymarksThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- tldr ::: comprehensive waymark authoring and search patterns for agents without CLI access -->
Adds structured AI-DEV-NOTE comments, categorized TODOs (ai/refactor, ai/performance), and decision records to code for preserving context, decisions, and incomplete work in AI-assisted development.
Provides semantic search, code navigation, and conversation memory via a local RAG index. Includes tools for searching code, finding usages, navigating dependencies, recalling past discussions, and creating checkpoints.
Writes AI-optimized docs like README, CLAUDE.md, AGENTS.md, commit messages, PR descriptions using tables, checklists, absolute paths, invariants for cold project starts.
Share bugs, ideas, or general feedback.
Waymarks are structured code annotations using the ::: sigil that enable humans and AI agents to leave durable, greppable breadcrumbs in codebases. This skill provides comprehensive guidance for authoring and searching waymarks without requiring the wm CLI tool.
A waymark is a comment containing the ::: sigil that embeds machine-readable context directly adjacent to code. Waymarks unify decades of ad-hoc comment patterns (TODO, FIXME, MARK, etc.) into one predictable grammar that works across all programming languages.
Core properties:
rg ':::'Every waymark follows this structure:
[comment leader] [signals][marker] ::: [content]
Components:
//, #, <!--, --, etc.)~ (flagged/in-progress), * (starred/priority)::: sigil (required): Exactly three ASCII colons with spaces around themExamples:
// todo ::: implement rate limiting
// *fix ::: security vulnerability in auth handler
// ~todo ::: refactoring in progress on this branch
// ~*fix ::: critical bug I am actively working on
Two signals are available:
~): Flagged, indicating work actively in progress on the current branch. Clear all flagged waymarks before merging.*): Starred, indicating high priority or importance.When combining signals, use ~* (flagged first, then starred). Double signals (**, ~~) are invalid.
| Waymark | Meaning |
|---|---|
todo | A task |
*todo | An important task |
~todo | A task actively being worked on |
~*todo | An important task actively being worked on |
See references/grammar.md for the complete grammar specification.
Markers categorize waymark intent. Only blessed markers are recognized by default; custom markers require configuration.
todo - Task to completefix (alias: fixme) - Bug to addresswip - Work in progressdone - Completed task (temporary handoff marker)review - Needs code reviewtest - Needs testingcheck - Needs verificationnote - General observationcontext (alias: why) - Background or reasoningtldr - File-level summary (one per file, at top)about - Section or block summaryexample - Usage exampleidea - Suggestion or proposalcomment - General commentarywarn - Warning about behavioralert - Critical attention neededdeprecated - Outdated codetemp (alias: tmp) - Temporary codehack (alias: stub) - Workaround or temporary solutionblocked - Cannot proceedneeds - Dependency requiredquestion (alias: ask) - Needs clarificationSee references/markers.md for the complete marker list with usage guidance.
TLDR waymarks provide file-level summaries that help humans and agents quickly understand file purpose. They are the most important waymark in any file.
tldr ::: per fileThe TLDR must be the first waymark in the file:
// tldr ::: handles user authentication and session management
import { hash } from 'bcrypt';
After language preambles:
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tldr ::: manages database migrations and schema versioning
import sqlite3
For documentation files, use HTML comments with #docs tag:
---
title: API Guide
---
<!-- tldr ::: REST API reference with authentication examples #docs -->
# API Guide
Write one sentence, 8-14 words, active voice:
| Pattern | Example |
|---|---|
[verb] [domain] [via/using/with] [technology] | validates payment webhooks using Stripe signature verification |
[component] [action] [scope] | React hooks exposing authentication state and methods |
[capability] for [purpose] | rate limiting middleware for API endpoints |
Avoid:
Use *tldr for critical files that must be read first (entry points, core infrastructure). Audit periodically with rg '\*tldr\s*:::'.
See references/tldr-patterns.md for extended patterns and examples.
about ::: markers describe the code section immediately following them. They provide quick breadcrumbs for classes, functions, and major blocks.
Place about ::: on the comment line directly above the construct:
// about ::: validates JWT tokens and extracts claims
export function validateToken(token: string): Claims {
// ...
}
Focus on the upcoming section only. Do not restate the file-level TLDR:
// tldr ::: user authentication service
// about ::: validates password against security policy
function validatePassword(password: string) {}
// about ::: hashes password with bcrypt
function hashPassword(password: string) {}
Write short, active-voice sentences (6-12 words):
| Construct | Pattern | Example |
|---|---|---|
| Class | "encapsulates/manages [domain] [state/behavior]" | encapsulates session lifecycle state |
| Function | "validates/transforms/fetches [input] [action]" | validates webhook signatures before processing |
| Component | "renders [element] with [feature]" | renders account overview with metrics |
Update about ::: markers when behavior changes. Delete stale markers rather than leaving inaccurate guidance.
See references/about-waymarks.md for detailed patterns by language.
Properties use key:value pairs in the content:
// todo ::: implement caching owner:@alice priority:high
// note ::: reason:"waiting for API approval" status:blocked
Key format: [A-Za-z][A-Za-z0-9_-]*
Value format: Unquoted token (no spaces) or double-quoted string
Any # followed by non-whitespace is a tag:
// todo ::: optimize query #perf:hotpath
// fix ::: XSS vulnerability #sec:boundary
Use namespaces for organization:
#docs/* - Documentation (#docs/guide, #docs/api)#perf:* - Performance (#perf:hotpath, #perf:slow)#sec:* - Security (#sec:boundary, #sec:auth)#arch/* - Architecture (#arch/entrypoint, #arch/state)Before inventing a new tag, search for existing usage: rg '#perf'
Mentions start with @ followed by a lowercase letter:
// todo ::: @agent implement OAuth flow
// review ::: @alice check security implications
Valid mentions:
@agent - Any capable AI assistant@alice, @bob - Named individuals@dev-team - Groups (defined in config)Place the actor immediately after ::: to assign ownership. Mentions later in the sentence indicate involvement without ownership.
Invalid patterns (not extracted as mentions):
user@example.com - Email addresses@Component - Decorators (uppercase)@angular/core - Scoped packagesDeclare the authoritative anchor for a concept with ref:#token:
// tldr ::: authentication service ref:#auth/service
Reference elsewhere via relation properties:
see:#token - Related referencedocs:#token - Documentation referencefrom:#token - Depends on or derived fromreplaces:#token - Supersedes another waymark// todo ::: implement refunds from:#payments/charge
// note ::: supersedes old implementation see:#legacy/auth
Waymarks complement docstrings; they never replace them. Place waymarks outside docstrings, adjacent to them:
TypeScript/JavaScript:
/**
* 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) {
// ...
}
Python:
def send_email(message: Email) -> None:
"""Send an email using the configured transport."""
# about ::: orchestrates outbound email delivery #comm/email
transport.send(message)
Go:
// sanitize normalizes webhook payloads before verification.
// about ::: ensures Stripe event payload conforms to canonical schema #payments/stripe
func sanitize(event Event) Event { /* ... */ }
When the wm CLI is unavailable, use ripgrep to search for waymarks.
# All waymarks
rg ':::'
# By marker type
rg 'todo\s*:::'
rg 'fix\s*:::'
rg 'tldr\s*:::'
rg 'about\s*:::'
# By signal
rg '\*\w+\s*:::' # Starred (high-priority)
rg '~\w+\s*:::' # Flagged (in-progress)
rg '~\*\w+\s*:::' # Both signals
# By mention
rg ':::\s*@agent'
rg ':::\s*@\w+'
# By tag
rg ':::.+#perf'
rg ':::.+#sec'
rg ':::.+#docs'
Before merging, verify no flagged waymarks remain:
# Check for flagged items (must clear before merge)
rg '~\w+\s*:::'
# Check for starred items (should address before merge)
rg '\*\w+\s*:::' && echo "Has starred items!"
# Check for WIP markers
rg 'wip\s*:::' && echo "Has WIP markers!"
# All doc TLDRs
rg 'tldr\s*:::.*#docs' -g '*.md'
# In HTML comments
rg '<!--\s*tldr\s*:::' -g '*.md'
See references/ripgrep.md for comprehensive search patterns.
Continue waymarks using markerless ::: lines:
// todo ::: refactor authentication flow to support OAuth 2.0
// ::: coordinate with @backend team on token format
// ::: update documentation when complete
Align continuation ::: with the parent waymark's sigil for readability. Properties can appear on continuation lines:
// tldr ::: payment processor service
// see ::: #payments/core
// owner ::: @alice
// since ::: 2025-01-01
The wm CLI provides additional capabilities beyond what ripgrep patterns offer:
[[a1b2c3d|my-feature]]) for cross-referenceswm fmtwm find --type todo --mention @agentwm find --graphFor projects with the CLI installed, consider loading the waymark-cli skill for CLI-specific guidance.
// Basic waymarks
// todo ::: implement validation
// fix ::: memory leak in handler
// note ::: assumes UTC timestamps
// With signals
// *fix ::: critical security vulnerability
// ~todo ::: refactoring in progress
// ~*todo ::: urgent fix I am actively working on
// With properties and tags
// todo ::: priority:high implement caching #perf
// warn ::: validates all inputs #security
// With mentions
// todo ::: @agent implement OAuth flow #auth
// review ::: @alice check authorization logic
// Section summary
// about ::: orchestrates email delivery #comm
// Relations
// todo ::: from:#auth/login add rate limiting
// note ::: see:#payments/stripe for webhook handling
references/grammar.md - Complete grammar specificationreferences/markers.md - Full marker list with categories and aliasesreferences/tldr-patterns.md - Extended TLDR patterns by file typereferences/about-waymarks.md - Section summary patterns by languagereferences/ripgrep.md - Comprehensive search patternswaymark-cli - CLI usage, commands, and auditing workflows