---
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.

## Prompt Injection Policy

This skill can automatically inject lightweight project-map guidance into your context. The behavior is controlled by `promptInjectionMode` in `.pi-project-map.json`.

### Before init
When no `.pi-map.md` / `.pi-map.index.md` artifacts exist, you see a visible startup hint telling you to run `project_map_init`. No synthetic map content is injected before real artifacts exist.

### After init
Once artifacts exist, the runtime guarantees that the root pair is loaded first:

- root `.pi-map.index.md`
- root `.pi-map.md`

Additional directory pairs may be added while the configured context budget allows.

### Mode ladder
- `off`: no automatic injection beyond existing tool/docs discovery.
- `advisory`: startup/init hints are shown; you may read the root pair manually when you want routing/orientation context.
- `strong` (default): the root pair is injected automatically, expansion stays within the context budget, and reinjection checks run on relevant turns (agent start, before edits, before architecture-sensitive reasoning, after compaction, after root-pair artifact changes).
- `strict`: same as `strong`, but before sensitive edits or architectural claims you must either have the protocol path in context or include an explicit bypass marker: `[PI_MAP_BYPASS: <brief justification>]`.

The **protocol path** means the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction (`index routes, map orients, source decides`).

### Context budget
Default budget: **15% of the active model context window**, capped at **100k tokens**. The smaller of the relative and absolute values wins. If the runtime cannot discover the active model's context window, it uses the absolute cap.

## Configuration

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

```json
{
  "tagCap": 8,
  "workflowHintCap": 5,
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000
}
```

- `promptInjectionMode`: `off`, `advisory`, `strong` (default), or `strict`.
- `contextBudgetPercent`: relative share of the active model context window to use for automatic map/index injection.
- `contextBudgetMaxTokens`: hard absolute cap on the injection budget.

## 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. In `strict` mode, include `[PI_MAP_BYPASS: <brief justification>]` only when you deliberately need to proceed without the protocol path
7. 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.