Dev-Guides Navigator

Route to the correct online guide and enforce guide application.

When to Use

• Any Drupal, Next.js, design system, or dev-practice task where a guide might help
• When another skill or agent needs domain knowledge beyond its bundled references
• When the user mentions a specific guide topic
• NOT for: plugin methodology references (those are in drupal-dev-framework/references/)

Core Workflow

1. Get llms.txt (with caching)

Check for cache at ~/.claude/projects/{project-hash}/memory/dev-guides-cache.json.

NEVER use WebFetch in this workflow. All fetches use curl -s via Bash:

• WebFetch summarizes content through AI, destroying structured formats needed for matching
• MkDocs GitHub Pages URLs return 400KB+ HTML navigation shells, not guide content
• Guides are atomic and small enough for curl — no summarization needed

No cache (first time):

1. Bash: curl -s https://camoa.github.io/dev-guides/llms.hash — save the hash
2. Bash: curl -s https://camoa.github.io/dev-guides/llms.txt — save the content
3. Write both to cache file

Cache exists:

1. Bash: curl -s https://camoa.github.io/dev-guides/llms.hash (tiny, fast)
2. Compare with cached hash
   • Same → use cached llms.txt, skip re-fetch
   • Different → Bash: curl -s https://camoa.github.io/dev-guides/llms.txt, update cache

2. Match Task to Topic

Scan llms.txt for the topic that matches the current task. Each line has a topic title, URL, guide count, and description.

The URL in llms.txt is a GitHub Pages URL like https://camoa.github.io/dev-guides/drupal/forms/. Extract the topic path (e.g., drupal/forms) from this URL for use in raw GitHub fetches below.

3. Fetch Topic Index

IMPORTANT: Do NOT use WebFetch on GitHub Pages URLs — MkDocs renders them into 400KB+ HTML pages with navigation shells, hiding the actual content. Use curl with raw GitHub URLs instead.

curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/{topic-path}/index.md

Example: curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/drupal/forms/index.md

This returns the raw markdown containing:

• "I need to..." routing table — maps user intent to specific guide
• guide-meta: frontmatter — KG metadata for disambiguation and relationships

4. Use KG Metadata (from index.md)

The guide-meta: in the topic's frontmatter provides:

• concepts — confirms this is the right topic
• not — if the task matches a not term, this is the WRONG topic, go back to step 2
• requires — load prerequisite topics first
• complements — note related topics for the user

5. Fetch Specific Guide

From the "I need to..." routing table, select the guide that matches the task. The routing table lists guide filenames. Fetch the raw markdown:

curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/{topic-path}/{guide-filename}.md

Example: curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/drupal/forms/form-validation.md

Do NOT use WebFetch on GitHub Pages URLs — you'll get rendered HTML, not the guide content.

6. Apply the Guide (Critical)

Do NOT just read and summarize. Extract and apply:

1. Identify the relevant section(s) for the current task
2. Extract decision criteria, patterns, and code examples
3. Apply them directly to the implementation
4. Reference the guide in architecture docs if in design phase

Quick Reference

Common Mistakes

Examples

Troubleshooting

See Also

• references/cache-format.md — cache file format
• references/manifest-schema.md — build output (llms.txt + llms.hash)
• references/guide-index.md — fallback keyword table (offline/network failure)