# pi-project-map

Pi skill for hierarchical project analysis.

## What it does

Generates **paired** project-analysis artifacts throughout your project:

- `.pi-map.index.md` — routing-first index for deciding what to open next
- `.pi-map.md` — orientation-first rich map for understanding a directory

This gives Pi agents fast navigation plus deeper architectural context without reading every source file up front.

## Quick Start

```bash
npm install -g pi-project-map
project-map init
```

## Agent operating model

### Tier 0
Always start with:
- `Project Map Protocol`
- root `.pi-map.index.md`

### Tier 1
Load likely relevant directory indexes first, then open the strongest-match rich maps.

### Tier 2
Read actual source, tests, config, and docs before editing or making exact runtime claims.

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

### Retrieval
When you have a specific query (e.g. "authentication logic" or "routing metadata"):
1. Run `project-map context <query>` or use the Pi tool `project_map_context`
2. Read the returned **Context bundle** — it contains relevant indexes, maps, likely files, and symbols
3. Always verify critical behavior from source before editing

## Commands

```bash
project-map init
project-map patch <file>
project-map validate [--fix]
project-map reinit
project-map context <query>
```

### Context retrieval

`project-map context <query>` searches the paired map/index artifacts and returns a compact markdown bundle with the most relevant directories, files, and symbols. No LLM call is needed — it uses deterministic metadata scoring.

## Configuration

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

```json
{
  "ignorePatterns": ["node_modules", ".git"],
  "smallPackageThreshold": 10,
  "contextBudget": 4000,
  "autoInjectPrompt": true,
  "tagCap": 8,
  "workflowHintCap": 5
}
```

## Design

See [design-doc.md](design-doc.md) for the full specification.

## Implementation Plan

See [implementation-plan.md](implementation-plan.md) for the engineering roadmap.