---
name: pi-map
description: Generates and maintains hierarchical, machine-readable project analysis files (.pi-map.md) for instant codebase comprehension. Use when working with medium-to-large codebases where understanding architecture, file relationships, and exports without reading every file is valuable. Automatically extracts symbols via AST and LLM heuristics.
---

# pi-project-map

A Pi skill that generates and maintains a hierarchical, machine-readable analysis of a software project. Each directory gets a `.pi-map.md` file containing architectural context, exported symbols, and dependencies.

## What It Does

- **Scans** your entire project and creates one `.pi-map.md` per directory
- **Extracts** exports, imports, and dependencies via AST parsing (TypeScript, Python, Go) and LLM heuristics
- **Updates** incrementally when files change (full rewrite for small packages, section-level patch for large)
- **Validates** detects stale entries, missing files, orphaned entries, and changed signatures

## Quick Start

```bash
# Install globally
npm install -g pi-project-map

# Generate analysis files for the entire project
project-map init

# After editing a file, update its directory's analysis
project-map patch src/components/Button.tsx

# Check for staleness
project-map validate

# Force full regeneration
project-map reinit
```

## Format

Each `.pi-map.md` uses dense markdown optimized for LLM consumption:

```markdown
# pkg/auth
## role
Auth layer: JWT issuance, validation, refresh. Stateless. Dep: pkg/crypto, pkg/db.
## files
- tokens.ts | JWT gen/val | exp: issueToken, verifyToken, refreshToken | dep: crypto/hmac, db/sessions
- middleware.ts | HTTP auth guard | exp: requireAuth, requireRole | dep: tokens/verifyToken
## arch
Guard pattern on routes. Tokens short-lived (15m), refresh long-lived (7d). Rotation on every use.
## dirty
-
```

### Abbreviations

| Abbreviation | Meaning |
|-------------|---------|
| `exp:` | Exported symbols |
| `dep:` | Dependencies |
| `pkg/` | Internal package reference |

## Tools

### `project-map:init [root]`
Runs a full project scan and generates `.pi-map.md` files in every directory.

**Example:**
```bash
project-map init
project-map init ~/my-project
```

### `project-map:patch <file-path>`
Updates the `.pi-map.md` for the directory containing the given file.

**Behavior:**
- Small packages (< 10 files): full rewrite
- Large packages (>= 10 files): section-level patch

**Example:**
```bash
project-map patch src/components/Button.tsx
```

### `project-map:validate [root]`
Checks all `.pi-map.md` files for staleness.

**Detects:**
- Missing files (new files not yet in `.pi-map.md`)
- Orphaned entries (files listed but deleted)
- Stale signatures (exports changed since last scan)
- Dirty markers (packages flagged for reconciliation)

**Example:**
```bash
project-map validate
```

### `project-map:reinit [path]`
Force full re-initialization. Clears all dirty markers.

**Example:**
```bash
project-map reinit
project-map reinit src/components
```

## Configuration

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

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

| Option | Default | Description |
|--------|---------|-------------|
| `ignorePatterns` | `node_modules`, `.git`, `dist`, etc. | Additional ignore patterns |
| `smallPackageThreshold` | `10` | File count threshold for full rewrite vs patch |
| `contextBudget` | `4000` | Max tokens to spend on analysis files |
| `autoInjectPrompt` | `true` | Auto-inject maintenance instructions |

## Agent Instructions

When `.pi-map.md` files exist in the project:

1. **Read them at session start** to build project understanding without scanning every file
2. **Run `project-map:patch <path>`** after editing any source file
3. **Run `project-map:validate`** if you suspect staleness before making architectural decisions
4. **Trust the analysis** for orientation, but verify critical details by reading source when needed

## Best Practices

- Run `project-map:init` after cloning a new repository
- Run `project-map:reinit` periodically (daily/weekly) to catch changes made outside the agent
- Add `.pi-map.md` to `.gitignore` — they are derived artifacts
- For very large projects (> 1000 directories), consider running `init` on subdirectories

## Supported Languages

| Language | AST Parsing | Heuristic Extraction |
|----------|------------|---------------------|
| TypeScript / TSX | Full | Full |
| JavaScript / JSX | Full | Full |
| Python | Partial | Full |
| Go | Partial | Full |
| Rust | Partial | Full |
| Other | - | Full (filename + regex patterns) |