toondex

What this skill does

# ToonDex

> "Oh, I see you've discovered my meticulously organized archive."

Create and maintain semantic folder indexes for efficient LLM codebase navigation.

## Commands

| Command | Purpose |
|---------|---------|
| `/toondex` | Create initial index.toon (interactive) |
| `/redex` | Update index.toon with changes |
| `/toondex --stats` | Show debug mode usage statistics |

### /toondex --stats

Display ToonDex usage statistics (requires `TOONDEX_DEBUG=1`).

**Implementation:** Run the statistics script:

```bash
${CLAUDE_PLUGIN_ROOT}/scripts/show-stats.sh
```

Or directly from project root:

```bash
./plugins/toondex/scripts/show-stats.sh
```

The script will:
- Check if debug mode is enabled
- Display warning if `TOONDEX_DEBUG=1` is not set
- Show hook execution counts, index file reads, and effectiveness metrics
- Format timestamps as relative times (e.g., "2m ago", "5h ago")

## Format Specification

See `docs/INDEX_SPEC.md` for full spec. Summary:

```
# {folder-name}
{child-folder},{summary}
{child-folder},{summary}
```

- **Recursive**: An `index.toon` is created in each scanned folder, not just the root
- Each `index.toon` only lists its **direct child folders** (relative names, not full paths)
- Order = priority (first = most important)
- Summaries describe behavior, not file listings
- State tracked via git (no separate state file)
- Navigating the codebase: start at root `index.toon`, then drill into child `index.toon` files

---

## /toondex - Create Initial Index

**WHEN THIS SKILL IS INVOKED, IMMEDIATELY START WITH STEP 1. EXECUTE THE STEPS - DO NOT JUST DESCRIBE THEM.**

On success, respond with: `"Best. Index. Ever."`

### Step 1: Ask Traversal Depth (DO THIS NOW)

Ask the user how deep to traverse:

```
How many levels deep should I scan? (default: 2)
```

Common choices:
- **2** - Top-level and one sublevel (good for most projects)
- **3** - Deeper scan (monorepos, nested packages)
- **1** - Shallow scan (very large codebases)

### Step 2: Scan Folders

Use the **Bash tool** to scan directories. Detect the platform and use the appropriate command with the user's chosen depth (`$DEPTH`):

**macOS / Linux** (use `/usr/bin/find` to bypass shell aliases):
```bash
/usr/bin/find . -maxdepth $DEPTH -type d \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' \
  -not -path '*/.next/*' \
  -not -path '*/build/*' \
  -not -path '*/coverage/*' \
  -not -path '*/vendor/*' \
  -not -path '*/tmp/*' \
  -not -name '.*' \
  | sort
```

**Windows** (PowerShell):
```powershell
Get-ChildItem -Directory -Recurse -Depth $DEPTH |
  Where-Object { $_.FullName -notmatch 'node_modules|\.git|dist|\.next|build|coverage|vendor|tmp' } |
  Where-Object { -not $_.Name.StartsWith('.') } |
  Sort-Object FullName
```

**Platform detection:** Check the environment info (darwin = macOS, linux = Linux, otherwise assume Windows).

### Step 3: Filter Results (MANDATORY)

**BEFORE analyzing, remove ALL of the following from the scan results. Do NOT analyze or index these:**

- Hidden folders (starting with `.`) — e.g. `.git/`, `.cache/`, `.hive-mind/`, `.specify/`
- Dependencies: `node_modules/`, `vendor/`
- Generated output: `dist/`, `build/`, `.next/`, `coverage/`, `tmp/`
- Single-file folders (describe the parent folder instead)
- Any folder that is purely generated output, cached data, or third-party code

If unsure whether a folder is generated, check for a `.gitignore` entry or absence from version control.

### Step 4: Analyze Each Folder

For each folder, create a summary with confidence score. See `references/scoring-rubric.md` for scoring details.

**Analysis process:**
1. Check for README.md or docs
2. Read 3-5 representative source files
3. Identify frameworks/patterns
4. Assess single responsibility
5. Write 1-3 sentence summary describing *behavior*
6. Calculate confidence score (0.0-1.0)

**Group results by parent folder.** Each parent will get its own `index.toon` listing only its direct children:

```
Root level:
  src,Application source code. [0.8]
  docs,Documentation and specs. [0.9]
  scripts,Build and deploy scripts. [0.7]

Inside src/:
  app,Next.js App Router. Page routes layouts and API handlers. [0.9]
  components,UI component library. Shadcn-based. [0.8]
  legacy,Old code, purpose unclear. [0.2]
```

For messy/unclear folders, you may comment: `"Worst. Folder structure. Ever."`

### Step 5: Determine Priority Order

Rank children within each parent folder by importance:
1. Entry points (app/, pages/, main/)
2. Core business logic
3. Shared components
4. Data layer (api/, stores/)
5. Utilities
6. Types/config
7. Tests/scripts

### Step 6: Write index.toon files (initial)

**Write an `index.toon` in every scanned folder that has children**, starting from the root. Do this NOW — before reviewing low-confidence items. This ensures files exist even if the review is interrupted.

Each `index.toon` lists only its **direct child folders** (relative names). Strip confidence scores:

```
# project-root/index.toon
# {project-name}
src,Application source code.
docs,Documentation and specs.
scripts,Build and deploy scripts.
```

```
# src/index.toon
# src
app,Next.js App Router. Page routes layouts and API handlers.
components,UI component library. Shadcn-based.
legacy,Old code, purpose unclear.
```

For `/redex`, only rewrite the `index.toon` files in folders that changed.

### Step 7: Review Low-Confidence Items

Batch all items with confidence < 0.5 and present to user:

```
These summaries need review (low confidence):

| # | Path | Summary | Confidence |
|---|------|---------|------------|
| 1 | src/legacy | Old code, purpose unclear | 0.2 |
| 2 | src/utils/internal | Helper functions | 0.3 |
| 3 | lib/compat | Compatibility layer | 0.4 |

Edit summaries or confirm? Provide corrections as: "1: Correct summary here"
```

If there are NO low-confidence items, skip the review.

### Step 8: Update index.toon files (final)

If the user edited any summaries during review, update the affected `index.toon` files with the corrected entries.

Confirm to the user: `"Best. Index. Ever."` and list how many `index.toon` files were created.

### Step 9: Add Reference to AGENTS.md

After creating index.toon, ensure it's referenced so agents know to use it.

**Check for existing file** (in order of preference):
1. `AGENTS.md`
2. `CLAUDE.md`
3. `.claude/AGENTS.md`

**If file exists:** Add the index reference section if not already present:

```markdown
## Folder Index
`index.toon` files contain semantic folder summaries (child,summary format, ordered by importance).
Start at the root `index.toon` and drill into subfolders as needed.
```

**If no file exists:** Create `AGENTS.md` with minimal content:

```markdown
# {project-name}

## Folder Index
`index.toon` files contain semantic folder summaries (child,summary format, ordered by importance).
Start at the root `index.toon` and drill into subfolders as needed.
```

**Important:** Only add the reference once. Check for existing "index.toon" mention before adding.

---

## /redex - Update Existing Index

### Step 1: Detect Changes

Run the detection script or manually check:

```bash
./scripts/detect-changes.sh
```

Or compute manually:
```bash
LAST_REF=$(git log -1 --format="%H" -- index.toon)
git diff --name-only $LAST_REF..HEAD | cut -d'/' -f1-2 | sort -u
```

### Step 2: Identify What Changed

- **New folders**: Add to end of index (or prompt for position)
- **Deleted folders**: Remove from index
- **Modified folders**: Re-analyze summary

### Step 3: Re-analyze Changed Folders Only

For each changed folder:
1. Re-run analysis (same as /toondex Step 2)
2. Compare old vs new summary
3. Calculate confidence score

### Step 4: Present Diff to User

```
index.toon changes:

MODIFIED:
  src/auth:
    old: "JWT-based authentication."
    new: "Clerk-based authentication. Role middleware." [0.8]

NEW:
  src/analytics: "PostHog integration for user tracking." [0.7]

DELETED:
  src/leg