80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
---
|
|
name: pi-map
|
|
description: 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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.
|