pi-map/openspec/project.md

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.