auto-doc-index

# Auto Doc Index — Derived Indexes from Frontmatter

Replaces hand-maintained index tables in `README.md` with auto-generated
tables derived from structured frontmatter in individual doc files.

## Why This Matters — Real Evidence

In a real project with 13 ADR files, comparing hand-maintained index vs
auto-generated index revealed **8 discrepancies (62% error rate)**:

| Issue Type | Example | Count |
|------------|---------|-------|
| **Title truncated** | "activate none" vs actual "activate none **by default**" | 2 |
| **Status fabricated** | Index said "Decided" but file said "Accepted" | 3 |
| **Date invented** | Index showed "2026-01-28" but file had no Date field | 1 |
| **Metadata lost** | "(revised 2026-01-28)" stripped from status | 1 |
| **Case "normalized"** | `decided` silently changed to `Decided` | 4 |

These aren't hypothetical risks — they were **already present and invisible**
in a well-maintained project. Hand-editing creates a false sense of
correctness while the index silently diverges from its source files.

## When to Use

- Setting up a new documentation directory (ADR, RFC, Pitfall, Design Doc, etc.)
- Adding a new document to an existing indexed directory
- Onboarding a project that has hand-maintained doc indexes showing signs of drift
- Resolving recurring merge conflicts in shared `README.md` index tables
- Migrating from hand-maintained indexes to auto-generated ones

## Boundaries

- This skill generates **index tables only** — it does not create or modify the content of individual documents.
- The generator script replaces content **only between `<!-- INDEX:START -->` and `<!-- INDEX:END -->` markers**. All other README.md content is preserved verbatim.
- Do NOT use this for indexes that require editorial curation (e.g., "recommended reading order"). Auto-generation is for factual, exhaustive catalogs.
- Do NOT introduce YAML frontmatter parsing libraries — the regex-based approach is intentional to keep the script zero-dependency.
-...

# auto-doc-index

**Auto-generate document index tables from file frontmatter.**

AI agent skill that replaces hand-maintained `README.md` index tables with auto-generated ones derived from structured frontmatter in individual doc files. Eliminates merge conflicts, silent data drift, and stale indexes in multi-agent / multi-contributor documentation workflows.

## The Problem

Hand-maintained index tables in `README.md` are **shared mutable state**. In a real project with 13 ADR files, we measured an **62% error rate** in the hand-maintained index — titles truncated, statuses fabricated, dates invented. Nobody noticed because the index *looked* correct.

## The Solution

Each document is self-describing via frontmatter. A zero-dependency generator script scans the directory, parses frontmatter, and injects a fresh index table between `<!-- INDEX:START -->` / `<!-- INDEX:END -->` markers. The index becomes a **derived view** — a stateless pure function of the source files.

```
OLD: Write doc → Hand-edit README.md → Merge conflict risk
NEW: Write doc → Run generator → Idempotent rebuild, zero conflicts
```

## Quick Start

1. **Install as a Cursor skill:**
   ```bash
   skillkit install zjlpaul/auto-doc-index
   ```

2. **Or install via ClawHub:**
   ```bash
   openclaw install auto-doc-index
   ```

3. **Or just copy the template script:**
   Copy `template/generate-doc-index.ts` to your project's `scripts/` directory and run:
   ```bash
   npx tsx scripts/generate-doc-index.ts all
   ```

## Supported Formats

| Format | Agent |
|--------|-------|
| SKILL.md | Claude Code, Codex, Gemini CLI, 30+ agents |
| Cursor MDC | Cursor |
| Markdown Rules | Windsurf, GitHub Copilot |

Use [SkillKit](https://github.com/nicholasbarger/skillkit) to translate between formats:
```bash
skillkit translate --to cursor SKILL.md
skillkit translate --to windsurf SKILL.md
```

## Frontmatter Patterns

**ADR/RFC style (inline metadata):**
```markdown
# ADR-001: Title Here
Status: Decided...