rebuild-guidelines-index

Files (1)

• SKILL.md

SKILL.md (first lines)

> **Pipeline position:** maintenance task; not part of the main pipeline — see [`../../reference/pipeline-flow.md`](../../reference/pipeline-flow.md).

# Rebuild Guidelines Index

Generate navigational index files for `reference/coding-guidelines/` so explorer agents can efficiently locate relevant guidelines without reading every file.

## Process

### Step 1: Discover Structure

Traverse `reference/coding-guidelines/` using Glob or ls. Map:

- All language directories (e.g., `rust/`, `python/`)
- All topic directories within each language (e.g., `rust/general/`, `rust/errors/`)
- All `.md` files in each topic directory, **excluding** any existing `index.md`

Handle empty directories gracefully — they get noted as empty in the index.

### Step 2: Generate Per-Folder Indexes (Leaf Level First)

For each topic folder that contains `.md` files (not `index.md`):

1. **Dispatch one Explore subagent per folder.** The subagent reads all `.md` files in that folder and returns a structured summary per file:
   - Filename
   - Line count
   - 2–4 sentence dense summary listing major topics, sections, and rule identifiers (e.g., P-MOD, F-OUT, M-DESIGN-FOR-AI)

2. **Fallback:** If a folder exceeds ~4000 total lines across all files, dispatch one subagent per file instead.

3. **Write `index.md`** in each folder using this exact format:

```markdown
# {language}/{topic}/ — Guidelines Index

> Auto-generated by rebuild-guidelines-index. Do not edit manually.
> Last rebuilt: YYYY-MM-DD HH:MM

## {filename}.md ({N} lines)
{2-4 sentence dense summary. List major topics, section headings, and rule identifiers
covered. Be specific enough that an agent can decide whether to read the full file
based on this summary alone.}

## {another-file}.md ({N} lines)
{Summary...}
```

### Step 3: Generate Per-Language Indexes

For each language directory:

1. **Read the per-folder indexes** just created in Step 2 (do NOT re-read source files).
2. **Write `{language}/index.md`** using this exact format:

```markdown
# {Language} Guidelines Index

> Auto-generated by rebuild-guidelines-index. Do not edit manually.
> Last rebuilt: YYYY-MM-DD HH:MM

## Topic Folders

### {topic}/ ({N} files)
{2-3 sentence overview of what this topic folder covers, synthesized from the
per-folder index.}

**Key topics by file:**
| File | Covers |
|------|--------|
| {filename}.md | {comma-separated list of major topics and rule identifiers} |
| {filename}.md | {comma-separated list} |

### {another-topic}/ ({N} files)
{Overview...}

| File | Covers |
|------|--------|
| ... | ... |
```

If a topic folder is empty (no `.md` files other than `index.md`), note it:

```
### {topic}/ (empty)
No guideline files yet.
```

### Step 4: Generate Root Index

1. **Read per-language indexes** from Step 3 (do NOT re-read lower-level files).
2. **Write `reference/coding-guidelines/index.md`** using this exact format:

```markdown
# Coding Guidelines Index

> Auto-generated by rebuild-guidelines-index. Do not edit manually.
> Last rebuilt: YYYY-MM-DD HH:MM

## Languages

### {language}/
{2-3 sentence overview of what this language's guidelines cover.}
Topics: {topic1} ({N} files), {topic2} ({N} files), ...

### {language}/
{Overview or note that no content files exist yet, with list of empty topic dirs.}
```

### Step 5: Report

List all index files created or updated:

```
Index files updated:
- reference/coding-guidelines/index.md
- reference/coding-guidelines/rust/index.md
- reference/coding-guidelines/rust/general/index.md
- ...
```

From Fleron/Claude-plugins, MIT.

More from Fleron/Claude-plugins