pi-map/SKILL.md

name, description

name	description
pi-map	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

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:

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