---
name: pi-map
description: Generates and maintains hierarchical, machine-readable paired project analysis artifacts (.pi-map.index.md and .pi-map.md) for fast codebase navigation and orientation.
---

# pi-project-map

A Pi skill that generates and maintains a paired analysis for each non-ignored directory:

- `.pi-map.index.md` for routing
- `.pi-map.md` for orientation

## What It Does

- **Scans** your project and creates one paired map/index artifact set per directory
- **Extracts** exports, imports, and dependencies via AST parsing and LLM heuristics
- **Updates** generated artifacts after source edits
- **Validates** stale, missing, broken, or inconsistent paired artifacts
- **Retrieves** relevant context on demand via deterministic metadata scoring over the paired artifacts

## Quick Start

```bash
project-map init
project-map patch src/components/Button.tsx
project-map validate
project-map reinit
project-map context "authentication logic"
```

## Operating Model

### Tier 0
Read the root `.pi-map.index.md` and the `Project Map Protocol` first.

### Tier 1
Use indexes first for routing. Open the strongest-match `.pi-map.md` files next.

### Tier 2
Read actual source before editing or asserting exact behavior.

**Trust boundary:** index routes, map orients, source decides.

## Configuration

Create `.pi-project-map.json` in the project root:

```json
{
  "tagCap": 8,
  "workflowHintCap": 5
}
```

## Agent Instructions

When project map artifacts exist in the repo:

1. Start with the root `.pi-map.index.md`
2. Use indexes first to route into the right directory
3. Read the local `.pi-map.md` plus source before editing
4. Run `project-map patch <path>` after editing source
5. Run `project-map validate` before freshness-sensitive architectural decisions
6. For **targeted navigation**, use `project_map_context` (Pi tool) or `project-map context` (CLI) with a natural-language query. It returns a compact markdown bundle with the strongest-match indexes, maps, likely files, and symbols.

## Retrieval Model

`project_map_context` and `project-map context` implement **index-first retrieval**:

1. Score every directory's paired map/index metadata against the query
2. Keep the top 3 strongest matches
3. Expand those matches into:
   - Relevant indexes (routing-first)
   - Relevant maps (orientation-first)
   - Likely files
   - Relevant symbols (only when useful)
4. Return a stable markdown bundle titled `# Context bundle: <query>`

**Trust boundary still applies:** the bundle routes and orients, but source decides. Always read actual source before editing.