# OpenSpec Project Context: pi-project-map

## Product
`pi-project-map` is a Pi skill plus CLI that generates hierarchical `.pi-map.md` files throughout a repository so coding agents can orient quickly without reading every source file.

## Current architecture
- `src/init.ts`: full project discovery and map generation
- `src/patch.ts`: incremental map updates after file edits
- `src/validate.ts`: map freshness and discrepancy checks
- `src/format.ts`: markdown map rendering/parsing
- `pi-extension.ts`: Pi tool registration and prompt guidance

## Conventions
- `.pi-map.md` files are orientation aids, not runtime truth.
- Exact behavior must still be verified from source before editing or making precise claims.
- Tooling changes should preserve the core `init` / `patch` / `validate` / `reinit` workflow unless a spec explicitly changes it.
- Keep review slices small; prefer staged, reviewable changes over one large refactor.

## Active planning theme
Move from "load all maps up front" toward a layered retrieval model where the root artifacts teach the agent how to navigate, then package maps and source files are loaded on demand or by focused auto-selection.