175 lines
6.0 KiB
Markdown
175 lines
6.0 KiB
Markdown
# pi-project-map
|
|
|
|
> Pi skill and CLI for hierarchical project analysis.
|
|
|
|
`pi-project-map` generates and maintains paired, machine-readable analysis artifacts throughout a codebase so agents can navigate quickly, orient themselves, and then verify details from source.
|
|
|
|
## What it is
|
|
|
|
For every non-ignored directory, the tool produces two files:
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `.pi-map.index.md` | Routing-first index for deciding what to open next. |
|
|
| `.pi-map.md` | Orientation-first rich map for understanding a directory. |
|
|
|
|
Together they form a **paired artifact model**:
|
|
- indexes are small and routing-optimized
|
|
- maps are denser and architecture-optimized
|
|
- source remains the final authority
|
|
|
|
`pi-project-map` runs as both:
|
|
- a **CLI** (`project-map`)
|
|
- a **Pi extension** (`pi-extension.ts`) that registers tools and optional runtime prompt injection
|
|
|
|
## Quick start
|
|
|
|
Install:
|
|
|
|
```bash
|
|
npm install -g pi-project-map
|
|
```
|
|
|
|
Generate paired artifacts in a repo:
|
|
|
|
```bash
|
|
cd my-project
|
|
project-map init
|
|
```
|
|
|
|
For standalone CLI usage, provide an LLM provider/API key. For example:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY=...
|
|
project-map init
|
|
```
|
|
|
|
Inside Pi, the extension uses Pi's configured model automatically.
|
|
|
|
## Command overview
|
|
|
|
| CLI command | Pi tool | Purpose |
|
|
|-------------|---------|---------|
|
|
| `project-map init [path]` | `project_map_init` | Generate paired artifacts for the whole project or a subdirectory. |
|
|
| `project-map patch <file>` | `project_map_patch` | Regenerate artifacts for the directory containing the changed file and refresh ancestors appropriately. |
|
|
| `project-map validate [--fix]` | `project_map_validate` | Check paired artifacts for staleness or inconsistency. |
|
|
| `project-map reinit [path]` | `project_map_reinit` | Force full regeneration of all artifacts. |
|
|
| `project-map context <query>` | `project_map_context` | Return a ranked context bundle for a natural-language query. |
|
|
|
|
Typical workflow:
|
|
|
|
1. `project-map init` on first use
|
|
2. after editing source, `project-map patch <changed-file>`
|
|
3. before broad architectural decisions, `project-map validate`
|
|
4. for targeted exploration, `project-map context "<query>"`
|
|
|
|
## Operating model
|
|
|
|
Follow a three-tier model when consuming project maps:
|
|
|
|
1. **Tier 0 — Protocol and root index**
|
|
Start with the root `Project Map Protocol` and root `.pi-map.index.md`.
|
|
2. **Tier 1 — Indexes and maps**
|
|
Use indexes to route, then open the strongest-match `.pi-map.md` files for orientation.
|
|
3. **Tier 2 — Source and tests**
|
|
Read actual source, config, tests, and docs before editing or making exact runtime claims.
|
|
|
|
The trust boundary is always:
|
|
|
|
> **index routes, map orients, source decides.**
|
|
|
|
## Prompt injection policy
|
|
|
|
The Pi extension can automatically inject lightweight project-map guidance into the agent context. Behavior is controlled by `promptInjectionMode` in `.pi-project-map.json`.
|
|
|
|
### Before init
|
|
|
|
No synthetic map content is injected. The agent sees only a visible startup hint telling it to run `project_map_init`.
|
|
|
|
### After init
|
|
|
|
The root pair is guaranteed to load first:
|
|
- root `.pi-map.index.md`
|
|
- root `.pi-map.md`
|
|
|
|
Additional directory pairs are expanded only while the configured context budget allows.
|
|
|
|
### Mode ladder
|
|
|
|
| Mode | Behavior |
|
|
|------|----------|
|
|
| `off` | No automatic injection. |
|
|
| `advisory` | Visible hints/reminders only; maps are read manually. |
|
|
| `strong` | Root pair injection, budgeted expansion, reinjection on relevant turns. |
|
|
| `strict` | Same as `strong`, plus a visible guard for sensitive turns when the protocol path is missing. |
|
|
|
|
The **protocol path** is present when outgoing context contains:
|
|
- the canonical root-pair marker/block
|
|
- the trust-boundary instruction
|
|
|
|
In `strict` mode, a sensitive action can be bypassed explicitly with:
|
|
|
|
```text
|
|
[PI_MAP_BYPASS: <brief justification>]
|
|
```
|
|
|
|
### Context budget
|
|
|
|
Default automatic-injection budget is the smaller of:
|
|
- **15%** of the active model context window
|
|
- **100,000 tokens** absolute cap
|
|
|
|
If the runtime cannot discover the model context window, it falls back to the absolute cap.
|
|
|
|
## Retrieval is separate
|
|
|
|
`project-map context <query>` and `project_map_context` are **separate, on-demand retrieval** paths. They do **not** replace automatic prompt injection.
|
|
|
|
Retrieval is deterministic and metadata-driven:
|
|
1. score every directory's paired map/index metadata against the query
|
|
2. keep the top matches (default: 3)
|
|
3. return a compact markdown bundle with indexes, maps, likely files, and symbols
|
|
|
|
Use retrieval for targeted navigation when you already have a specific question.
|
|
|
|
## Configuration overview
|
|
|
|
Create `.pi-project-map.json` in the project root:
|
|
|
|
```json
|
|
{
|
|
"promptInjectionMode": "strong",
|
|
"contextBudgetPercent": 15,
|
|
"contextBudgetMaxTokens": 100000,
|
|
"llmProvider": "openai",
|
|
"llmModel": "gpt-4o-mini",
|
|
"ignorePatterns": ["node_modules", ".git"],
|
|
"tagCap": 8,
|
|
"workflowHintCap": 5
|
|
}
|
|
```
|
|
|
|
Providing `ignorePatterns` replaces the built-in default list, so include any defaults you want to keep.
|
|
|
|
Key knobs:
|
|
- `promptInjectionMode` — `off`, `advisory`, `strong`, `strict`
|
|
- `contextBudgetPercent` — relative share of model context used for automatic injection
|
|
- `contextBudgetMaxTokens` — hard absolute cap on automatic injection
|
|
- `llmProvider` / `llmModel` / `llmBaseUrl` — standalone CLI provider settings
|
|
- `ignorePatterns` — directories/files to skip
|
|
- `tagCap` / `workflowHintCap` — routing metadata limits
|
|
|
|
## Documentation map
|
|
|
|
- [`SKILL.md`](SKILL.md) — skill definition and agent/operator instructions
|
|
- [`usage-guide.md`](usage-guide.md) — practical workflows and examples
|
|
- [`design-doc.md`](design-doc.md) — architecture and implementation details
|
|
- [`troubleshooting.md`](troubleshooting.md) — common issues and recovery steps
|
|
|
|
## Known limitations
|
|
|
|
- token budgeting is best-effort, not tokenizer-exact
|
|
- relevant-turn detection uses explicit event types plus heuristics
|
|
- provider payload fallback depends on runtime serialization shapes
|
|
- retrieval routes and orients; it never replaces source verification
|