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):
- Bash:
curl -s https://camoa.github.io/dev-guides/llms.hash — save the hash
- Bash:
curl -s https://camoa.github.io/dev-guides/llms.txt — save the content
- Write both to cache file
Cache exists:
- Bash:
curl -s https://camoa.github.io/dev-guides/llms.hash (tiny, fast)
- 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 topicnot — if the task matches a not term, this is the WRONG topic, go back to step 2requires — load prerequisite topics firstcomplements — note related topics for the user
| Example Task |
Correct Topic |
Wrong Topic |
Why |
| story.yml props |
drupal/ui-patterns |
drupal/storybook |
"story.yml" in ui-patterns concepts, "storybook" in not |
| stories.yml preview |
drupal/storybook |
drupal/ui-patterns |
reverse |
| inline blocks |
drupal/layout-builder |
drupal/blocks |
"inline blocks" in blocks' not |
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:
- Identify the relevant section(s) for the current task
- Extract decision criteria, patterns, and code examples
- Apply them directly to the implementation
- Reference the guide in architecture docs if in design phase
Quick Reference
| Step |
Action |
| Cache check |
curl -s llms.hash, compare with cached hash |
| Find topic |
Match task keywords in cached llms.txt |
| Get routing table |
curl -s raw GitHub URL for topic index.md |
| Disambiguate |
Check guide-meta: concepts/not fields |
| Get guide |
curl -s raw GitHub URL for specific guide .md |
| Apply |
Extract patterns and implement, don't summarize |
Common Mistakes
| Mistake |
Fix |
| Using WebFetch instead of curl |
Always use curl -s — WebFetch returns AI summaries or 400KB HTML shells |
| Reading guide and only summarizing |
Extract patterns and apply to current task |
| Grabbing first keyword match |
Check guide-meta not fields for disambiguation |
| Fetching llms.txt every time |
Check llms.hash first, use cache |
Ignoring requires |
Load prerequisites first |
Examples
| User says |
Action |
| "I need to create a Drupal form" |
Match "form" → drupal/forms/ → fetch index.md → pick guide for form creation |
| "Add a story.yml for my component" |
Match "story.yml" → check guide-meta → drupal/ui-patterns/ (NOT storybook) |
| "Set up responsive images" |
Match "responsive image" → drupal/image-styles/ (NOT drupal/media) |
| "How do I use Config Split?" |
Match "Config Split" → drupal/config-management/ |
| "I need SOLID architecture for my module" |
Drupal context → drupal/solid/ (NOT generic dev-solid-principles) |
Troubleshooting
| Problem |
Fix |
curl fails (network error) |
Fall back to references/guide-index.md for keyword-to-URL lookup |
| No topic matches the task |
Broaden keywords, check category sections in llms.txt, or task may not need a guide |
| Cache file path unknown |
Use Bash: echo ~/.claude/projects/*/memory/ to find the project memory directory |
| Guide content too large for context |
Request only the specific section from the routing table, not the entire guide |
See Also
references/cache-format.md — cache file formatreferences/manifest-schema.md — build output (llms.txt + llms.hash)references/guide-index.md — fallback keyword table (offline/network failure)
1---2name: dev-guides-navigator3description: Use when ANY development task might benefit from a guide. Use when user says "how do I", "best practice", "pattern for", "guide for", "Drupal form", "entity type", "plugin type", "routing", "caching", "config management", "SDC component", "design system", "Bootstrap mapping", "Radix theme", "JSX to Twig", "Tailwind tokens", "SOLID", "DRY", "TDD", "security", "CSS", "Next.js". Use PROACTIVELY before any design, architecture, or implementation work. MUST be invoked before writing code that touches Drupal APIs, theming, design systems, or security. NEVER skip guide check — patterns prevent bugs.4---5
6# Dev-Guides Navigator
7
8Route to the correct online guide and enforce guide application.
9
10## When to Use
11
12- Any Drupal, Next.js, design system, or dev-practice task where a guide might help
13- When another skill or agent needs domain knowledge beyond its bundled references
14- When the user mentions a specific guide topic
15- NOT for: plugin methodology references (those are in drupal-dev-framework/references/)
16
17## Core Workflow
18
19### 1. Get llms.txt (with caching)
20
21Check for cache at `~/.claude/projects/{project-hash}/memory/dev-guides-cache.json`.
22
23**NEVER use WebFetch in this workflow.** All fetches use `curl -s` via Bash:
24- WebFetch summarizes content through AI, destroying structured formats needed for matching
25- MkDocs GitHub Pages URLs return 400KB+ HTML navigation shells, not guide content
26- Guides are atomic and small enough for `curl` — no summarization needed
27
28**No cache (first time):**
291. Bash: `curl -s https://camoa.github.io/dev-guides/llms.hash` — save the hash
302. Bash: `curl -s https://camoa.github.io/dev-guides/llms.txt` — save the content
313. Write both to cache file
32
33**Cache exists:**
341. Bash: `curl -s https://camoa.github.io/dev-guides/llms.hash` (tiny, fast)
352. Compare with cached hash
36 - **Same** → use cached `llms.txt`, skip re-fetch
37 - **Different** → Bash: `curl -s https://camoa.github.io/dev-guides/llms.txt`, update cache
38
39### 2. Match Task to Topic
40
41Scan `llms.txt` for the topic that matches the current task. Each line has a topic title, URL, guide count, and description.
42
43The 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.
44
45### 3. Fetch Topic Index
46
47**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.
48
49```bash
50curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/{topic-path}/index.md
51```
52
53Example: `curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/drupal/forms/index.md`
54
55This returns the raw markdown containing:
56
57- **"I need to..." routing table** — maps user intent to specific guide
58- **`guide-meta:` frontmatter** — KG metadata for disambiguation and relationships
59
60### 4. Use KG Metadata (from index.md)
61
62The `guide-meta:` in the topic's frontmatter provides:
63
64- **`concepts`** — confirms this is the right topic
65- **`not`** — if the task matches a `not` term, this is the WRONG topic, go back to step 2
66- **`requires`** — load prerequisite topics first
67- **`complements`** — note related topics for the user
68
69| Example Task | Correct Topic | Wrong Topic | Why |
70|--------------|---------------|-------------|-----|
71| story.yml props | drupal/ui-patterns | drupal/storybook | "story.yml" in ui-patterns concepts, "storybook" in not |
72| stories.yml preview | drupal/storybook | drupal/ui-patterns | reverse |
73| inline blocks | drupal/layout-builder | drupal/blocks | "inline blocks" in blocks' not |
74
75### 5. Fetch Specific Guide
76
77From the "I need to..." routing table, select the guide that matches the task. The routing table lists guide filenames. Fetch the raw markdown:
78
79```bash
80curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/{topic-path}/{guide-filename}.md
81```
82
83Example: `curl -s https://raw.githubusercontent.com/camoa/dev-guides/main/docs/drupal/forms/form-validation.md`
84
85**Do NOT use WebFetch on GitHub Pages URLs** — you'll get rendered HTML, not the guide content.
86
87### 6. Apply the Guide (Critical)
88
89**Do NOT just read and summarize.** Extract and apply:
90
911. Identify the relevant section(s) for the current task
922. Extract decision criteria, patterns, and code examples
933. Apply them directly to the implementation
944. Reference the guide in architecture docs if in design phase
95
96## Quick Reference
97
98| Step | Action |
99|------|--------|
100| Cache check | `curl -s` llms.hash, compare with cached hash |
101| Find topic | Match task keywords in cached `llms.txt` |
102| Get routing table | `curl -s` raw GitHub URL for topic `index.md` |
103| Disambiguate | Check `guide-meta:` concepts/not fields |
104| Get guide | `curl -s` raw GitHub URL for specific guide `.md` |
105| Apply | Extract patterns and implement, don't summarize |
106
107## Common Mistakes
108
109| Mistake | Fix |
110|---------|-----|
111| Using WebFetch instead of curl | **Always use `curl -s`** — WebFetch returns AI summaries or 400KB HTML shells |
112| Reading guide and only summarizing | Extract patterns and apply to current task |
113| Grabbing first keyword match | Check guide-meta `not` fields for disambiguation |
114| Fetching llms.txt every time | Check llms.hash first, use cache |
115| Ignoring `requires` | Load prerequisites first |
116
117## Examples
118
119| User says | Action |
120|-----------|--------|
121| "I need to create a Drupal form" | Match "form" → `drupal/forms/` → fetch index.md → pick guide for form creation |
122| "Add a story.yml for my component" | Match "story.yml" → check guide-meta → `drupal/ui-patterns/` (NOT storybook) |
123| "Set up responsive images" | Match "responsive image" → `drupal/image-styles/` (NOT drupal/media) |
124| "How do I use Config Split?" | Match "Config Split" → `drupal/config-management/` |
125| "I need SOLID architecture for my module" | Drupal context → `drupal/solid/` (NOT generic dev-solid-principles) |
126
127## Troubleshooting
128
129| Problem | Fix |
130|---------|-----|
131| `curl` fails (network error) | Fall back to `references/guide-index.md` for keyword-to-URL lookup |
132| No topic matches the task | Broaden keywords, check category sections in llms.txt, or task may not need a guide |
133| Cache file path unknown | Use Bash: `echo ~/.claude/projects/*/memory/` to find the project memory directory |
134| Guide content too large for context | Request only the specific section from the routing table, not the entire guide |
135
136## See Also
137
138- `references/cache-format.md` — cache file format
139- `references/manifest-schema.md` — build output (llms.txt + llms.hash)
140- `references/guide-index.md` — fallback keyword table (offline/network failure)
majiayu000