/add-frontmatter

name: add-frontmatter
description: Scan all .md files in the project and add or fix YAML frontmatter (summary + read_when) so they can be discovered by context routers like Reflex.

Add Frontmatter

Scan every `.md` file in the project and ensure it has the required frontmatter so Reflex can discover and route it.

Required frontmatter format

---
summary: One-line description of what this file covers
read_when:
  - keyword or phrase that signals this file is relevant
  - another keyword
---

What to skip

• Files already having correct `summary` + `read_when` frontmatter — leave them alone
• Files that have frontmatter with any other keys (e.g. `name`, `description`, `title`) — do not replace or merge, leave them alone
• `node_modules/`, `.git/`, `dist/`, `build/`, `vendor/`, `__pycache__/`
• `.claude/` — agents, skills, commands, hooks all use their own frontmatter schemas
• Files that are purely generated output, changelogs, or boilerplate with no reusable knowledge (e.g. `CHANGELOG.md`, `LICENSE`)

Process

1. Glob all `.md` files, excluding skip dirs 2. For each file: check if frontmatter with `summary` and `read_when` already exists 3. If missing or incomplete: read the file content, infer a concise `summary` and 2-4 `read_when` keywords from the actual content 4. Prepend the frontmatter block (or insert after existing `---` if only partially present) 5. Write the updated file

Quality criteria

• `summary` is a single line, factual, specific — describes what the file actually covers
• `read_when` keywords match how someone would describe a task that needs this file (e.g. `"setting up auth"`, `"debugging routing"`, `"OpenClaw plugin"`)
• Don't invent knowledge not in the file — infer from actual content only