Help us improve
Share bugs, ideas, or general feedback.
Share bugs, ideas, or general feedback.
Share bugs, ideas, or general feedback.
npx claudepluginhub outfitter-dev/waymark<!-- tldr ::: guide interactive waymark addition to files with proper syntax -->
<!-- tldr ::: apply pending waymarks from plan document with interactive review -->
<!-- tldr ::: audit waymark coverage quality and accuracy across codebase files -->
<!-- tldr ::: guided project initialization for waymark setup with strategy selection -->
Inject all waymarks as JSON for full codebase context
You are a waymarker specializing in code annotation and documentation through waymarks.
Use this agent when you need to perform comprehensive testing of the wm (Waymark) CLI tool after code changes, before releases, or when verifying functionality across all commands and output formats. This agent should be invoked proactively after: <example> Context: User has just completed implementing a new CLI command or flag. user: "I just added a --jsonl flag to wm scan" assistant: "Great! Let me verify the implementation works correctly." <commentary> Since new CLI functionality was added, use the Task tool to launch the wm-tester agent to validate the new flag works correctly and doesn't break existing functionality. </commentary> assistant: "Now let me use the wm-tester agent to run comprehensive tests on the CLI" </example> <example> Context: User is preparing for a release. user: "Waymark 1.0.0-beta.2 is ready to ship" assistant: "Before we proceed with the release, let me run comprehensive CLI tests to ensure everything is working." <commentary> Before any release, use the wm-tester agent to validate all CLI functionality is working correctly across all commands and output formats. </commentary> assistant: "I'm going to use the Task tool to launch the wm-tester agent for pre-release validation" </example> <example> Context: User has made changes to formatting, scanning, or ID management. user: "I refactored the formatter and tweaked ID reservation logic" assistant: "Let me verify the formatting changes work correctly across all commands." <commentary> Since core formatting and record management changed, use the wm-tester agent to exercise formatting, scanning, insert/modify/remove flows, and JSON/text outputs. </commentary> assistant: "Now let me use the wm-tester agent to validate the formatting and ID changes" </example>
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.
This skill should be used when the user asks about "wm command", "waymark cli", "wm find", "wm add", "wm edit", "wm rm", "wm fmt", "wm lint", or needs to use waymark tooling. Requires `using-waymarks` skill for syntax fundamentals. Provides comprehensive CLI command reference and workflows.
<!-- tldr ::: command guide for wm skill -->
Uses power tools
Uses Bash, Write, or Edit tools
Has parse errors
Some configuration could not be fully parsed
Runs pre-commands
Contains inline bash commands via ! syntax
Share bugs, ideas, or general feedback.
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claimBased on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
Collect all TODO and FIXME comments from your project
AST-aware code search, symbol navigation, and dependency graph analysis
CodeDNA protocol — in-source AI context and inter-agent communication for any codebase. Adds /codedna:init and /codedna:check (implemented) plus automatic annotation enforcement. /codedna:manifest and /codedna:impact are planned.
Persistent project memory for AI coding agents — semantic search, AST-aware chunking, dependency graphs, and conversation history
Optimized file search, semantic indexing, and persistent memory for Claude Code — with optional sync to a self-hosted web dashboard
Fast and token-friendly code reading for AI coding agents. Symbol-aware MCP tools that replace cat/grep with ~85% fewer tokens, sub-millisecond search, and a raw fallback that preserves cat/grep parity byte-for-byte.
Fast local documentation search with llms.txt indexing. Search 12K+ line docs in 6ms with line-accurate citations. One command (/blz) and one agent (@blz:blazer) for all documentation operations.
Skills and workflows for working with @outfitter/* packages. Patterns, templates, compliance checking, and debugging for Outfitter.
Internal Outfitter team skills for docs, voice, and conventions
Development methodology fieldguides for Claude Code. TDD, debugging, architecture, research, multi-agent coordination, plus authoring skills for plugins, agents, commands, and hooks.
Build with the Trails framework — contract-first trails, trailheads, testing, and governance for agent-assisted development.
Bash prerequisite issue
Uses bash pre-commands but Bash not in allowed tools
Bash prerequisite issue
Uses bash pre-commands but Bash not in allowed tools
Share bugs, ideas, or general feedback.
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)
TODO, FIXME, MARK) because they survive refactors and are easy to search. Waymarks unify those patterns under one predictable grammar.Read the full background in Historical Priors for Waymark-Style Anchors.
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) {
// ...
}
// 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).
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.
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