alex/pi-map
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite documentation system

Browse Source
This commit is contained in:
Alex
2026-06-12 12:04:28 +02:00
parent 842dcc6235
commit fb302a033e
6 changed files with 872 additions and 799 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+121 -95
View File
@@ -1,148 +1,174 @@
# pi-project-map
Pi skill for hierarchical project analysis.
> Pi skill and CLI for hierarchical project analysis.
## What it does
`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.
Generates **paired** project-analysis artifacts throughout your project:
## What it is
- `.pi-map.index.md` — routing-first index for deciding what to open next
- `.pi-map.md` — orientation-first rich map for understanding a directory
For every non-ignored directory, the tool produces two files:
This gives Pi agents fast navigation plus deeper architectural context without reading every source file up front.
| 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. |
## Quick Start
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
```
## Agent operating model
For standalone CLI usage, provide an LLM provider/API key. For example:
### Tier 0
Always start with:
- `Project Map Protocol`
- root `.pi-map.index.md`
```bash
export OPENAI_API_KEY=...
project-map init
```
### Tier 1
Load likely relevant directory indexes first, then open the strongest-match rich maps.
Inside Pi, the extension uses Pi's configured model automatically.
### Tier 2
Read actual source, tests, config, and docs before editing or making exact runtime claims.
## Command overview
**Trust boundary:** index routes, map orients, source decides.
| 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. |
## Prompt Injection Policy
Typical workflow:
The Pi extension can automatically inject lightweight project-map guidance into the agent context according to the configured `promptInjectionMode`.
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
When no `.pi-map.md` / `.pi-map.index.md` artifacts exist, only a visible startup hint is injected. It tells the agent that the project-map extension is active and to run `project_map_init`. No synthetic or fake map content is ever injected before real artifacts exist.
No synthetic map content is injected. The agent sees only a visible startup hint telling it to run `project_map_init`.
### After init
Once real artifacts exist, the runtime guarantees that the root pair is loaded before any budgeted expansion:
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, in shallow-first order.
### Trust boundary
Injected maps and indexes are navigation and orientation aids, not final authority:
> **index routes, map orients, source decides**
If an injected artifact and the source disagree, source wins. Always verify critical behavior from source before editing or making exact runtime claims.
Additional directory pairs are expanded only while the configured context budget allows.
### Mode ladder
- `off`: no automatic injection beyond existing tool/docs discovery.
- `advisory`: inject startup/init hints and allow optional root-pair preload; use light reminders.
- `strong` (default): inject the root pair, expand under the configured budget, run reinjection checks on relevant turns, and remind before edits or architecture-sensitive reasoning.
- `strict`: same as `strong`, plus require an explicit bypass justification before sensitive edits or architectural claims when the protocol path is missing.
The **protocol path** is present when the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction. In `strict` mode, sensitive actions without it are blocked unless the agent includes `[PI_MAP_BYPASS: <brief justification>]`.
| 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
The default budget is **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 falls back to the absolute cap.
Configure it in `.pi-project-map.json`:
Default automatic-injection budget is the smaller of:
- **15%** of the active model context window
- **100,000 tokens** absolute cap
```json
{
"promptInjectionMode": "strong",
"contextBudgetPercent": 15,
"contextBudgetMaxTokens": 100000
}
```
If the runtime cannot discover the model context window, it falls back to the absolute cap.
## 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
## Retrieval is separate
Retrieval via `project_map_context` (tool) or `project-map context` (CLI) remains a separate, on-demand path. Use it for targeted navigation when you have a specific query; automatic injection does not replace it.
`project-map context <query>` and `project_map_context` are **separate, on-demand retrieval** paths. They do **not** replace automatic prompt injection.
### Integration-test expectations and known limitations
The implementation is validated by integration tests covering:
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
- pre-init hint behavior,
- post-init root-pair preload,
- budgeted expansion behavior,
- canonical-marker dedupe,
- reinjection after compaction,
- reinjection after root-pair artifact changes,
- mixed visibility behavior,
- guidance-mode differences,
- strict-mode bypass behavior.
Use retrieval for targeted navigation when you already have a specific question.
Known limitations:
- Token estimation is best-effort (≈ 4 chars per token); actual provider token counts may differ.
- Relevant-turn detection uses explicit event types when available and falls back to heuristics on generic turns.
- Message-layer scanning is preferred; provider-payload serialization quirks require a fallback scan path.
## 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
## Configuration overview
Create `.pi-project-map.json` in the project root:
```json
{
"ignorePatterns": ["node_modules", ".git"],
"smallPackageThreshold": 10,
"contextBudget": 4000,
"autoInjectPrompt": true,
"tagCap": 8,
"workflowHintCap": 5,
"promptInjectionMode": "strong",
"contextBudgetPercent": 15,
"contextBudgetMaxTokens": 100000
"contextBudgetMaxTokens": 100000,
"llmProvider": "openai",
"llmModel": "gpt-4o-mini",
"ignorePatterns": ["node_modules", ".git"],
"tagCap": 8,
"workflowHintCap": 5
}
```
- `promptInjectionMode`: `off`, `advisory`, `strong` (default), or `strict`.
- `contextBudgetPercent`: relative share of the active model context window used for automatic map/index injection.
- `contextBudgetMaxTokens`: hard absolute cap on the injection budget.
Providing `ignorePatterns` replaces the built-in default list, so include any defaults you want to keep.
## Design
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
See [design-doc.md](design-doc.md) for the full specification.
## Documentation map
## Implementation Plan
- [`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
See [implementation-plan.md](implementation-plan.md) for the engineering roadmap.
## 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