---
name: index-updater
description: Keeps the 3-layer codebase index fresh after file edits. Performs incremental updates by recomputing hashes and re-extracting metadata for only changed files.
---

# Index Updater - Incremental Index Maintenance

Keeps `.claude/crew-index.json` and `.claude/crew-symbols.json` up-to-date after code changes without rebuilding the entire index.

## When to Activate

- After any agent makes file edits (triggered by afterFileEdit hook or agent self-reporting)
- When an agent notices the index is stale (hash mismatch)
- Manually via `/crew reindex` for full rebuild

## Incremental Update Process

### Step 1: Identify changed files
The agent that made changes should report which files were modified. Alternatively, check file hashes:

```
For each file in crew-index.json:
  1. Compute current hash: shasum -a 256 <filepath>
  2. Compare with stored hash
  3. If different → mark for update
  4. If file deleted → mark for removal
```

### Step 2: Update Layer 1 (crew-index.json)
For each changed file:
1. Read the file
2. Recompute: hash, size, lines, exports, imports, functions, classes
3. Regenerate summary
4. Replace the file's entry in crew-index.json

For deleted files:
1. Remove the file's entry from crew-index.json

For new files (detected via Glob that aren't in index):
1. Read and extract full metadata
2. Add new entry to crew-index.json

### Step 3: Update Layer 2 (crew-symbols.json)
For each changed file:
1. Re-extract all symbols (functions, classes, methods) with signatures and line ranges
2. Re-scan for calls to known symbols
3. Update calledBy relationships for affected symbols in other files
4. Replace all symbols for this file in crew-symbols.json
5. Rebuild affected callGraph entries

### Step 4: Update global metadata
1. Recompute contentHash from all file hashes
2. Update stats (totalFiles, totalLines)
3. Update lastIndexed timestamp

## Performance Rules

- **Never rebuild entire index** for a single file change
- **Batch updates**: If 3+ files changed in one edit cycle, update all at once
- **Skip non-source files**: Don't index changes to .json, .md, .yml unless they're in the monitored set
- **Lazy callGraph**: Only rebuild callGraph edges that involve the changed file

## Agent Self-Reporting Protocol

Every agent prompt includes this instruction:
```
After making any file changes, report them for index update:
"FILES_MODIFIED: src/parser.js, src/scraper.js"
The orchestrator will trigger incremental index update for these files.
```

This is more efficient than hash-checking every file after every edit.

## Staleness Detection

If an agent reads the index and finds information that doesn't match reality:
1. The symbol doesn't exist at the listed line range
2. A file listed in the index doesn't exist
3. A function's signature has changed

Then: trigger incremental update for that specific file before proceeding.

## Batch Update from Orchestrator

When called by the execution-orchestrator with a list of modified files after task completion:

**Input**: Deduplicated list of file paths reported by agents via `FILES_MODIFIED`

**Process**:
1. For each file in the list:
   - **If file exists**: Re-read the file, recompute SHA-256 hash, re-extract metadata (exports, imports, functions, classes, lines, summary). Replace the file's entry in `crew-index.json` (Layer 1) and re-extract all symbols with signatures and line ranges for `crew-symbols.json` (Layer 2).
   - **If file was deleted**: Remove the file's entry from both `crew-index.json` and `crew-symbols.json`.
   - **If file is new** (not in index): Read and extract full metadata, add new entry to both Layer 1 and Layer 2.
2. Rebuild affected `callGraph` edges — only edges involving the changed files, not the entire graph
3. Update `calledBy` relationships for symbols in other files that reference changed symbols
4. Update global metadata: recompute `contentHash` from all file hashes, update `stats.totalFiles`, `stats.totalLines`, set `lastIndexed` to current timestamp

**Output**: Report `"{N} files updated, {M} new, {K} removed"` back to the orchestrator

**Performance**: This should complete quickly for typical task outputs (1-10 files). For 10+ files, consider batching the Layer 2 symbol re-extraction.