waymark

MCP server exposing a codebase's OKF knowledge bundle (okf/) to Claude Code — three schema-enforced query tools instead of raw Read/Grep over hand-written docs.

Tools

• list_concepts(type?, tags?) — frontmatter-only summaries. tags matches any-of the given tags.
• read_concept(path) — full frontmatter + body for one concept, by the path a list_concepts call returned.
• find_concept_by_resource(file_path) — reverse lookup: which concept(s) describe a given source file.

The server is stateless — it re-reads okf/ from process.cwd() on every call, so there's nothing to invalidate when concept files change.

Setup (per project)

npx -y @aleburrascano/waymark init

This registers everything a repo needs in one step:

• Adds a waymark entry to .mcp.json (creating it if missing).
• Installs a pre-commit hook at .git/hooks/pre-commit that blocks commits when a resource-mapped file changes without its okf/ concept being updated. Safe to re-run — it upgrades its own hook on later waymark versions but never overwrites a hook it didn't install.
• Installs two skills to .claude/skills/: okf-staleness-fix (the writer/judge playbook Claude Code uses to resolve a blocked commit) and okf-bootstrap (the propose/approve/generate/judge playbook Claude Code uses to seed an initial okf/ bundle).
• Adds (or refreshes) an ## OKF context section in the repo's CLAUDE.md.

Run it again any time to pick up updates from a newer waymark version.

Bootstrapping an existing codebase

okf/ bundles don't have to be hand-written from scratch. After running waymark init, ask Claude Code to bootstrap one:

"Bootstrap okf for this repo"

This invokes the okf-bootstrap skill, which:

1. Runs waymark bootstrap — a deterministic scan (git ls-files-based, respects .gitignore) that lists every candidate source file.
2. Proposes a candidate concept list grouped by domain (one concept per named unit you'd naturally ask "what is X" about) — nothing is written yet.
3. Waits for your approval, or feedback to re-group/rename/split candidates.
4. Generates each approved concept, verified by a judge subagent before it's written to disk.
5. Stages the new files with git add and reports what was generated — committing is left to you.

This is a one-time, human-supervised pass. Ongoing drift after that is caught by the pre-commit hook and okf-staleness-fix skill, not by re-running bootstrap.

Local development

npm install
npm test
npm run build && npm link   # then `waymark` runs the built CLI

npm test runs vitest against TypeScript source directly — no build step required for the test suite.