index

name	index
description	Generate or update a PROJECT_INDEX.md for fast session orientation
argument-hint	[update]
user-invocable	true
allowed-tools	Read, Glob, Grep, Bash(wc *), Bash(git log*), Bash(git rev-parse*), Bash(git remote*)

Generate a PROJECT_INDEX.md at the project root that maps the entire codebase for fast session orientation. This eliminates the need for Claude to rediscover project structure each session.

When to Run

• At project start (after initial setup)
• After significant structural changes (new modules, renamed directories, added dependencies)
• If $ARGUMENTS is "update": refresh the existing index rather than regenerating from scratch

What to Capture

Scan the project and build a structured index covering:

1. Project Overview

• Project name and description (from README.md or CLAUDE.md)
• Language/framework (detect from config files: pyproject.toml, package.json, go.mod, Cargo.toml)
• Last indexed date

2. Directory Structure

• ASCII tree of the top-level layout (2 levels deep max)
• Purpose annotation for each major directory

3. Entry Points

• Main executable / entry point files
• CLI commands (if any)
• API routes or server startup (if applicable)

4. Core Modules

For each significant module/package:

• Path: where it lives
• Purpose: one-line description
• Key exports: main functions, classes, or types
• Dependencies: what it imports from other modules

5. Configuration Files

• List all config files with their purpose (linter, formatter, build, CI, etc.)

6. Test Commands

• How to run tests (from Makefile or package scripts)
• Test file locations
• Coverage status (if known from tasks/tests.md)

7. Dependencies

• Core dependencies (from lock files or config)
• Dev dependencies

8. Key Decisions

• Link to tasks/todo.md for architectural decisions
• Link to tasks/lessons.md for accumulated knowledge

Output Format

Write to PROJECT_INDEX.md at the project root:

# Project Index — {project name}

> Auto-generated by /index. Last updated: {date}
> Read this file at session start for fast project orientation.

## Overview
{language} project — {description}

## Structure
{ascii tree}

## Entry Points
{entry points}

## Modules
{module table}

## Configuration
{config files table}

## How to Run
| Command | What It Does |
|---------|-------------|
| ... | ... |

## Dependencies
{dependency list}

## Key References
- Plan: tasks/todo.md
- Lessons: tasks/lessons.md
- Tests: tasks/tests.md

Rules

• Keep the index concise — this is a map, not documentation. One line per module, not paragraphs.
• Don't include file contents — just paths, purposes, and relationships.
• Skip generated files, build artifacts, and node_modules/venv/target directories.
• If the project is small (<20 files), keep the index to under 100 lines.
• If the project is large (>100 files), focus on the top-level architecture and key modules — don't index every file.
• Update tasks/tests.md coverage summary if test structure has changed.