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

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

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:

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

Design

See design-doc.md for the full specification.

Implementation Plan

See implementation-plan.md for the engineering roadmap.