Implement layered maps and context retrieval

openspec/project.md

@@ -0,0 +1,20 @@
+# 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.