ways-tests

ways-tests: Way Matching & Vocabulary Tool

Test how well a way matches sample prompts, or analyze its vocabulary for gaps.

Usage

The user invokes /ways-tests with one of these patterns:

Score mode: test a way against prompts

/ways-tests score <path/to/{name}.md> "sample prompt here"
/ways-tests score security "how do i hash passwords with bcrypt"

Score all ways: rank all ways against a prompt

/ways-tests score-all "sample prompt here"

Suggest mode: analyze vocabulary gaps

/ways-tests suggest <path/to/{name}.md>
/ways-tests suggest security
/ways-tests suggest --all

Suggest + apply: update vocabulary in-place

/ways-tests suggest <path/to/{name}.md> --apply
/ways-tests suggest --all --apply

Lint mode: validate way frontmatter

/ways-tests lint <path/to/{name}.md>
/ways-tests lint --all

Implementation

Resolving way paths

When the user gives a short name like "security" instead of a full path:

1. Check $CLAUDE_PROJECT_DIR/.claude/ways/ first (project-local)
2. Then check ~/.claude/hooks/ways/ recursively for */security/security.md
3. If multiple matches, list them and ask the user to pick

Score mode

Use the ways match subcommand:

# Score with BM25
ways match \
  --description "$description" \
  --vocabulary "$vocabulary" \
  --query "$prompt" \
  --threshold "${threshold:-2.0}"
# Exit code: 0 = match, 1 = no match
# Stderr: "match: score=X.XXXX threshold=Y.YYYY"

Display the score, threshold, and match/no-match result. If the way has no vocabulary, note that semantic matching is unavailable — only pattern matching applies.

Score-all mode

For each way file found (project-local + global), extract description+vocabulary and run way-match pair. Display results as a ranked table:

Score   Threshold  Match  Way
------  ---------  -----  ---
4.7570  2.0        YES    softwaredev/security
2.3573  2.0        YES    softwaredev/api
1.6812  2.0        no     softwaredev/debugging
0.0000  2.0        no     softwaredev/design