114 lines
4.8 KiB
Markdown
114 lines
4.8 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.
|
|
|
|
## Prompt Injection Policy
|
|
|
|
This skill can automatically inject lightweight project-map guidance into your context. The behavior is controlled by `promptInjectionMode` in `.pi-project-map.json`.
|
|
|
|
### Before init
|
|
When no `.pi-map.md` / `.pi-map.index.md` artifacts exist, you see a visible startup hint telling you to run `project_map_init`. No synthetic map content is injected before real artifacts exist.
|
|
|
|
### After init
|
|
Once artifacts exist, the runtime guarantees that the root pair is loaded first:
|
|
|
|
- root `.pi-map.index.md`
|
|
- root `.pi-map.md`
|
|
|
|
Additional directory pairs may be added while the configured context budget allows.
|
|
|
|
### Mode ladder
|
|
- `off`: no automatic injection beyond existing tool/docs discovery.
|
|
- `advisory`: startup/init hints are shown; you may read the root pair manually when you want routing/orientation context.
|
|
- `strong` (default): the root pair is injected automatically, expansion stays within the context budget, and reinjection checks run on relevant turns (agent start, before edits, before architecture-sensitive reasoning, after compaction, after root-pair artifact changes).
|
|
- `strict`: same as `strong`, but before sensitive edits or architectural claims you must either have the protocol path in context or include an explicit bypass marker: `[PI_MAP_BYPASS: <brief justification>]`.
|
|
|
|
The **protocol path** means the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction (`index routes, map orients, source decides`).
|
|
|
|
### Context budget
|
|
Default budget: **15% of the active model context window**, capped at **100k tokens**. The smaller of the relative and absolute values wins. If the runtime cannot discover the active model's context window, it uses the absolute cap.
|
|
|
|
## Configuration
|
|
|
|
Create `.pi-project-map.json` in the project root:
|
|
|
|
```json
|
|
{
|
|
"tagCap": 8,
|
|
"workflowHintCap": 5,
|
|
"promptInjectionMode": "strong",
|
|
"contextBudgetPercent": 15,
|
|
"contextBudgetMaxTokens": 100000
|
|
}
|
|
```
|
|
|
|
- `promptInjectionMode`: `off`, `advisory`, `strong` (default), or `strict`.
|
|
- `contextBudgetPercent`: relative share of the active model context window to use for automatic map/index injection.
|
|
- `contextBudgetMaxTokens`: hard absolute cap on the injection budget.
|
|
|
|
## 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. In `strict` mode, include `[PI_MAP_BYPASS: <brief justification>]` only when you deliberately need to proceed without the protocol path
|
|
7. 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.
|