Welcome to the Waymark documentation. This guide helps you find the right resource for your needs.
| I want to... | Start here |
|---|---|
| Use the CLI | CLI Installation → Commands |
| Understand waymark syntax | Grammar |
| See practical examples | How-To Guides |
| Learn development practices | Architecture + Agents |
| Understand design decisions | Historical Priors |
The canonical reference for waymark syntax, structure, and semantics.
Contents:
- Basic syntax and line form
- Signals, types, and markers
- Properties, relations, and canonicals
- Tags, mentions, and actors
- Multi-line waymarks
- Grammar rules (EBNF)
- Examples across languages
Audience: Anyone embedding waymarks in code or building tooling.
Comprehensive guides to the wm command-line tool.
- Installation (npm, Bun, source)
- Shell completions
- Getting started
- Common tasks
- All commands with examples
- Configuration and scopes
- Output formats
- Filtering and searching
- Display modes
- Common workflows
- Troubleshooting
- Add command (insert waymarks)
- Remove command (delete waymarks)
- Edit command (update signals)
- Batch operations
- ID management
Audience: Developers using the Waymark CLI in their projects.
Practical, opinionated guides for common workflows.
Contents:
- Getting started
- Daily workflows (standup, pre-commit, code review)
- Team collaboration
- Agent integration
- Advanced patterns
- Use case examples
- Tips & tricks
Audience: Anyone looking for real-world usage patterns and recipes.
Architectural principles and module organization guidelines.
Contents:
- Modularity over monoliths
- File size guidelines
- Testing strategy
- Type safety principles
- Performance considerations
Audience: Contributors and maintainers of the Waymark codebase.
Guide to AI agent collaboration practices and tooling choices.
Contents:
- Philosophy and principles
- Tooling choices (Bun, TypeScript, Turbo)
- Agent collaboration patterns
- Quality standards
- Pre-commit workflows
Audience: Developers working with AI agents on the Waymark project.
How other ecosystems influenced the waymark grammar.
Contents:
- Comment-level anchors across languages
- IDE navigation patterns
- Build system annotations
- Lessons learned from prior art
Audience: Anyone curious about design decisions and historical context.
Waymark documentation follows these conventions:
- Every doc has a TLDR waymark at the top for grep-based discovery
- Grammar docs are tool-agnostic and vendor-neutral
- CLI docs assume you're using
@waymarks/cli - How-To guides are opinionated and prescriptive
- Development docs target contributors and maintainers
- Add TLDR waymarks: Every doc should start with
<!-- tldr ::: ... #docs/... --> - Use consistent headings: H1 for title, H2 for major sections, H3 for subsections
- Include TOC for long docs: Any doc over 200 lines should have a table of contents
- Link liberally: Cross-reference related docs
- Examples over explanation: Show code examples wherever possible
- Keep grammar layer pure: Grammar docs should not assume CLI usage
Core documentation (grammar, CLI, how-to):
- Discuss approach first via issue or PR
- Update this index when adding new files
How-To guides:
- Add to
howto/directory - Update
howto/README.mdwith link - Use the template provided in
howto/README.md
Development docs:
- Add to
docs/root - Update this index
| Document | Update Trigger | Owner |
|---|---|---|
| GRAMMAR.md | Grammar changes in SPEC | Maintainers |
| cli/README.md | CLI command changes | Maintainers |
| howto/README.md | New workflow patterns | Contributors |
| ARCHITECTURE.md | Architectural decisions | Maintainers |
| AGENTS.md | Tooling/process changes | Maintainers |
- Project README - Project overview and quick start
- Specification - Canonical grammar and tooling scope
- GitHub Repository - Source code
- npm Package - CLI installation