Agent skill
staleness-gate
Automatic index freshness gate. Called before any query command (search, fetch, refs, explore) to ensure the index exists and is up-to-date. Handles first-run setup, incremental re-indexing, and staleness detection — so users never need to manually index.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/staleness-gate
SKILL.md
Staleness Gate Skill
Ensures the codemunch index is fresh before any query runs. This skill is called automatically — users never invoke it directly.
Decision flow
1. Does .claude/codemunch/index.json exist?
NO → First-run: run detect-lsp skill, then full index skill → done
YES → Continue to step 2
2. Get index timestamp from index.json "generated" field
3. Find files changed since index was built:
git diff --name-only --diff-filter=ACMRD $(git log -1 --format=%H --before="$GENERATED_TIMESTAMP") HEAD
Also check for untracked source files:
git ls-files --others --exclude-standard
4. Filter to source files only (exclude non-code files like .md, .txt, images, etc.)
5. Are there changed source files?
NO → Index is fresh, proceed with query
YES → Run incremental re-index (step 6)
6. Incremental re-index:
- For each changed/added file: re-extract symbols using the best available engine
- For each deleted file: remove its symbols from the index
- Update the "generated" timestamp
- Update the "file_hashes" manifest
- Report: "Auto-updated index: +N symbols, -M symbols, K files re-indexed"
Step 1 — Check index exists
# Check for index
if [ -f .claude/codemunch/index.json ]; then
echo "INDEX_EXISTS"
else
echo "NO_INDEX"
fi
If NO_INDEX:
- Check if
.claude/codemunch/config.jsonexists — if not, run the detect-lsp skill first - Run the index skill with full mode
- Report: "First-run: auto-built codemunch index (N symbols across M files)"
- Continue with the original query
Step 2 — Get index timestamp
# Extract the generated timestamp from index
python3 -c "
import json
with open('.claude/codemunch/index.json') as f:
idx = json.load(f)
print(idx.get('generated', ''))
" 2>/dev/null || jq -r '.generated' .claude/codemunch/index.json
Step 3 — Find changed files since index was built
GENERATED="2026-03-11T02:14:00Z"
# Find the commit closest to when the index was built
BASE_COMMIT=$(git log -1 --format=%H --before="$GENERATED" 2>/dev/null)
if [ -z "$BASE_COMMIT" ]; then
# No commit found before timestamp — index predates all commits, do full re-index
echo "FULL_REINDEX_NEEDED"
else
# Get changed files since that commit
git diff --name-only --diff-filter=ACMRD "$BASE_COMMIT" HEAD 2>/dev/null
fi
# Also check untracked files (new files not yet committed)
git ls-files --others --exclude-standard 2>/dev/null
Step 4 — Filter to source files
Only consider files with these extensions (adjust per detected languages in config):
.ts .tsx .js .jsx .mjs .cjs
.py .pyi
.go
.rs
.rb .rake
.java .kt .kts
.cs
.php
.swift
.c .h .cpp .hpp .cc
.lua .zig .sh .bash
Exclude:
- Lock files (
package-lock.json,Cargo.lock,go.sum, etc.) - Generated files (check
.claude/codemunch/config.jsonexclude patterns) - Non-code files (
.md,.txt,.json,.yaml,.yml,.toml, images, etc.)
Step 5 — Decide: fresh or stale
CHANGED_COUNT=$(echo "$CHANGED_FILES" | grep -c '.')
if [ "$CHANGED_COUNT" -eq 0 ]; then
echo "INDEX_FRESH"
else
echo "INDEX_STALE:$CHANGED_COUNT files changed"
fi
If fresh: proceed silently — no output to the user.
Step 6 — Incremental re-index
For each changed file, re-extract symbols using the same engine logic as the index skill:
- Remove old symbols for changed/deleted files from the index
- Extract new symbols for changed/added files
- Merge into the existing index
- Update metadata:
generatedtimestamp,file_hashes,stats
# Remove symbols for changed files
python3 -c "
import json, sys
changed_files = sys.stdin.read().strip().split('\n')
with open('.claude/codemunch/index.json') as f:
idx = json.load(f)
# Remove symbols from changed files
idx['symbols'] = [s for s in idx['symbols'] if s['file'] not in changed_files]
print(json.dumps(idx))
" <<< "$CHANGED_FILES"
Then run the index skill's engine pipeline (LSP → ctags → rg) on only the changed files, and append the new symbols.
Report (brief, inline — not a full index report):
🔄 Auto-updated index: 3 files re-indexed, +12 symbols, -8 symbols (1,251 total)
Performance notes
- The staleness check itself is fast: one
git diff+ one JSON field read - Incremental re-index only processes changed files — not the whole project
- For projects with no changes since last index, this adds <100ms overhead
- If >50 files changed, fall back to full re-index (faster than incremental at that scale)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?