78 lines
2.0 KiB
Markdown
78 lines
2.0 KiB
Markdown
# pi-project-map
|
|
|
|
Pi skill for hierarchical project analysis.
|
|
|
|
## What it does
|
|
|
|
Generates **paired** project-analysis artifacts throughout your project:
|
|
|
|
- `.pi-map.index.md` — routing-first index for deciding what to open next
|
|
- `.pi-map.md` — orientation-first rich map for understanding a directory
|
|
|
|
This gives Pi agents fast navigation plus deeper architectural context without reading every source file up front.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
npm install -g pi-project-map
|
|
project-map init
|
|
```
|
|
|
|
## Agent operating model
|
|
|
|
### Tier 0
|
|
Always start with:
|
|
- `Project Map Protocol`
|
|
- root `.pi-map.index.md`
|
|
|
|
### Tier 1
|
|
Load likely relevant directory indexes first, then open the strongest-match rich maps.
|
|
|
|
### Tier 2
|
|
Read actual source, tests, config, and docs before editing or making exact runtime claims.
|
|
|
|
**Trust boundary:** index routes, map orients, source decides.
|
|
|
|
### Retrieval
|
|
When you have a specific query (e.g. "authentication logic" or "routing metadata"):
|
|
1. Run `project-map context <query>` or use the Pi tool `project_map_context`
|
|
2. Read the returned **Context bundle** — it contains relevant indexes, maps, likely files, and symbols
|
|
3. Always verify critical behavior from source before editing
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
project-map init
|
|
project-map patch <file>
|
|
project-map validate [--fix]
|
|
project-map reinit
|
|
project-map context <query>
|
|
```
|
|
|
|
### Context retrieval
|
|
|
|
`project-map context <query>` searches the paired map/index artifacts and returns a compact markdown bundle with the most relevant directories, files, and symbols. No LLM call is needed — it uses deterministic metadata scoring.
|
|
|
|
## Configuration
|
|
|
|
Create `.pi-project-map.json` in the project root:
|
|
|
|
```json
|
|
{
|
|
"ignorePatterns": ["node_modules", ".git"],
|
|
"smallPackageThreshold": 10,
|
|
"contextBudget": 4000,
|
|
"autoInjectPrompt": true,
|
|
"tagCap": 8,
|
|
"workflowHintCap": 5
|
|
}
|
|
```
|
|
|
|
## Design
|
|
|
|
See [design-doc.md](design-doc.md) for the full specification.
|
|
|
|
## Implementation Plan
|
|
|
|
See [implementation-plan.md](implementation-plan.md) for the engineering roadmap.
|