shipkit-codebase-index

shipkit-codebase-index - Codebase Navigation Index

Purpose: Generate a lightweight index so Claude can navigate your codebase without wasteful exploration.

---

When to Invoke

User triggers:

• "Index the codebase"
• "Create a project map"
• "Generate codebase index"

Auto-suggested when:

• Session hook detects no index exists
• Index is older than 14 days

---

Process

Completion Tracking (MANDATORY)

Before starting analysis, create tasks for each index section:

1. TaskCreate: "Run generator script (base index)"
2. TaskCreate: "Detect framework"
3. TaskCreate: "Identify entry points"
4. TaskCreate: "Map concepts to files (with verification)"
5. TaskCreate: "Identify core files (with import counts)"
6. TaskCreate: "Determine skip list"
7. TaskCreate: "Write completed codebase-index.json"
8. TaskCreate: "Verify all 5 Claude-filled fields are populated"

Rules:

• TaskUpdate each task to completed only after the section has verified data (not guesses)
• The final verification task requires reading the written file and confirming: framework, entryPoints, concepts, coreFiles, and skip are all non-empty
• Do NOT declare done if any field is empty or contains placeholder values

Step 1: Run Generator Script

python ${CLAUDE_SKILL_DIR}/scripts/generate_index.py

Script provides (100% reliable data):

• scripts — from package.json
• recentlyActive — files from git history (last 14 days)
• directories — which common directories exist
• configFiles — which config files exist

Script leaves empty (Claude fills in):

• framework
• entryPoints
• concepts
• coreFiles
• skip

Step 2: Claude Analyzes and Completes Index

Read the generated index, then fill in the empty fields.

USE SUBAGENT FOR CONCEPT MAPPING - Launch Explore subagent for efficient parallel scanning:

Agent tool with subagent_type: "Explore"
Prompt: "Scan codebase to build navigation index. Find and report:

1. FRAMEWORK: Check for next.config.*, vite.config.*, nuxt.config.*, etc.
2. ENTRY POINTS: Find main app entry, layout, API routes directory, database schema
3. CONCEPTS: Map these concepts to files:
   - auth: files handling authentication, sessions, login
   - database: db connections, models, schema
   - payments: billing, subscriptions, checkout
   - api: API route handlers
   - components: reusable UI components
4. CORE FILES: Files imported by 5+ other files (high fan-in)

For each concept, list the actual file paths found.
For core files, include import count."