arch

codeindex:arch — Code Architecture Query

Query code architecture using README_AI.md index files generated by the codeindex CLI.

Prereq: codeindex CLI must be on PATH. If not, install with pipx install ai-codeindex (the plugin's SessionStart hook prints this hint).

Workflow

Step 1: Check Project Index

cat PROJECT_INDEX.md 2>/dev/null || cat PROJECT_SYMBOLS.md 2>/dev/null

If exists, this gives you the project overview with all modules listed.

Step 2: Find Directory Indexes

find . -name "README_AI.md" -type f | head -10

Step 3: Read Relevant Module Index

Based on user's question, locate the relevant module and read its README_AI.md:

# Example: user asks about parser
cat src/parser/README_AI.md

Step 4: Trace Dependencies

Check the Consumes and Provides sections (or Symbols / Dependencies) in README_AI.md to understand module relationships.

Step 5: Deep Dive (if needed)

Only read actual source files when README_AI.md doesn't have enough detail. The README's HTML comment at the top explicitly says it's a navigation index, not authoritative source — drill into the real files for precise mechanism.

Response Format

When answering architecture questions:

1. Start with the module location — "The parser is in src/codeindex/parser.py"
2. Explain its purpose — From the Purpose / blockquote description
3. Show relationships — From Symbols / Dependencies
4. Provide code reference — Line numbers if relevant

Example

User: "Where is the parser implemented?"

Response:

Based on README_AI.md, the parser is in `src/codeindex/parser.py`.

**Purpose**: Tree-sitter based parser that extracts Symbol
(classes, functions, methods) and Import statements into ParseResult.

**Key exports**:
- `parse_file()` — Parse a single file
- `ParseResult` — Container for parsed data
- `Symbol` — Represents a code symbol

**Dependencies**: tree-sitter, tree-sitter-python

When No Index Exists

If README_AI.md files don't exist, suggest:

This directory is not indexed. Run:
  codeindex scan ./path/to/dir

Or for the entire project:
  codeindex scan-all

Then ask if they want the codeindex:index skill to walk them through full setup.