docs: rewrite documentation system
This commit is contained in:
@@ -1,71 +1,93 @@
|
||||
---
|
||||
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.
|
||||
description: Generates and maintains hierarchical paired project-analysis artifacts (`.pi-map.index.md` + `.pi-map.md`) so Pi agents can navigate and orient in a codebase without reading every source file.
|
||||
---
|
||||
|
||||
# pi-project-map
|
||||
|
||||
A Pi skill that generates and maintains a paired analysis for each non-ignored directory:
|
||||
A Pi skill that creates and maintains one paired analysis artifact set per non-ignored directory:
|
||||
|
||||
- `.pi-map.index.md` for routing
|
||||
- `.pi-map.md` for orientation
|
||||
- `.pi-map.index.md` — routing-first index
|
||||
- `.pi-map.md` — orientation-first rich map
|
||||
|
||||
## What It Does
|
||||
## 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
|
||||
- scans the project and emits one paired map/index set per directory
|
||||
- extracts per-file purpose, dependencies, and concepts via an LLM
|
||||
- extracts exact exports/imports via AST parsing where supported
|
||||
- patches artifacts incrementally after source edits
|
||||
- validates stale, missing, broken, or inconsistent paired artifacts
|
||||
- retrieves relevant context on demand via deterministic metadata scoring
|
||||
- injects lightweight project-map guidance into agent context according to a configurable mode ladder
|
||||
|
||||
## Quick Start
|
||||
## Operating model
|
||||
|
||||
```bash
|
||||
project-map init
|
||||
project-map patch src/components/Button.tsx
|
||||
project-map validate
|
||||
project-map reinit
|
||||
project-map context "authentication logic"
|
||||
```
|
||||
### Tier 0 — protocol
|
||||
Always read the root `.pi-map.index.md` and the `Project Map Protocol` first.
|
||||
|
||||
## Operating Model
|
||||
### Tier 1 — routing
|
||||
Use indexes first to decide where to go next. Open the strongest-match `.pi-map.md` files for orientation.
|
||||
|
||||
### Tier 0
|
||||
Read the root `.pi-map.index.md` and the `Project Map Protocol` first.
|
||||
### Tier 2 — source
|
||||
Read actual source, tests, config, and docs before editing or asserting exact runtime behavior.
|
||||
|
||||
### Tier 1
|
||||
Use indexes first for routing. Open the strongest-match `.pi-map.md` files next.
|
||||
**Trust boundary:**
|
||||
|
||||
### Tier 2
|
||||
Read actual source before editing or asserting exact behavior.
|
||||
> **index routes, map orients, source decides**
|
||||
|
||||
**Trust boundary:** index routes, map orients, source decides.
|
||||
## Agent instructions
|
||||
|
||||
## Prompt Injection Policy
|
||||
When project-map artifacts exist in the repo:
|
||||
|
||||
This skill can automatically inject lightweight project-map guidance into your context. The behavior is controlled by `promptInjectionMode` in `.pi-project-map.json`.
|
||||
1. start with the root `.pi-map.index.md` and the `Project Map Protocol`
|
||||
2. use indexes first to route into the right directory
|
||||
3. read the local `.pi-map.md` plus relevant source before editing
|
||||
4. run `project_map_patch <file>` (tool) or `project-map patch <file>` (CLI) after each source edit
|
||||
5. run `project_map_validate` (tool) or `project-map validate` (CLI) before freshness-sensitive architectural decisions or final handoff
|
||||
6. for targeted exploration, use `project_map_context <query>` (tool) or `project-map context <query>` (CLI)
|
||||
7. in `strict` mode, only bypass the protocol-path guard with an explicit marker: `[PI_MAP_BYPASS: <brief justification>]`
|
||||
|
||||
## Prompt injection modes
|
||||
|
||||
The Pi extension can inject project-map guidance automatically. 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.
|
||||
If no `.pi-map.md` / `.pi-map.index.md` artifacts exist, the extension emits a lightweight visible hint to run `project_map_init`. No synthetic or fake map content is injected.
|
||||
|
||||
### After init
|
||||
Once artifacts exist, the runtime guarantees that the root pair is loaded first:
|
||||
Once real 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.
|
||||
Additional directory pairs may be expanded while the configured context budget allows, in shallow-first order.
|
||||
|
||||
### 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`).
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `off` | No automatic injection. Use tools/CLI manually. |
|
||||
| `advisory` | Startup/init hints are shown. Root pair is not auto-loaded; read it manually when needed. |
|
||||
| `strong` (default) | Root pair is auto-loaded, expansion stays within budget, and reinjection runs on relevant turns. |
|
||||
| `strict` | Same as `strong`, but sensitive edits or architectural claims are guarded unless the protocol path is present or a bypass marker is provided. |
|
||||
|
||||
The **protocol path** means the outgoing context contains the canonical injected root-pair block and the trust-boundary text.
|
||||
|
||||
### 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.
|
||||
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 context window, it uses the absolute cap.
|
||||
|
||||
## Retrieval usage
|
||||
|
||||
`project_map_context` (tool) and `project-map context` (CLI) are **on-demand retrieval**, separate from automatic injection.
|
||||
|
||||
They do not call the LLM. They score paired metadata against the query and return a compact markdown bundle with:
|
||||
|
||||
- relevant indexes
|
||||
- relevant maps
|
||||
- likely files
|
||||
- relevant symbols when useful
|
||||
|
||||
Always read the suggested indexes first, then maps, then verify critical behavior from source.
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -73,41 +95,32 @@ Create `.pi-project-map.json` in the project root:
|
||||
|
||||
```json
|
||||
{
|
||||
"tagCap": 8,
|
||||
"workflowHintCap": 5,
|
||||
"promptInjectionMode": "strong",
|
||||
"contextBudgetPercent": 15,
|
||||
"contextBudgetMaxTokens": 100000
|
||||
"contextBudgetMaxTokens": 100000,
|
||||
"tagCap": 8,
|
||||
"workflowHintCap": 5,
|
||||
"llmProvider": "openai",
|
||||
"llmModel": "gpt-4o-mini",
|
||||
"ignorePatterns": ["node_modules", ".git", "dist", "build"]
|
||||
}
|
||||
```
|
||||
|
||||
- `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.
|
||||
Providing `ignorePatterns` replaces the built-in default list, so include any defaults you want to keep.
|
||||
|
||||
## Agent Instructions
|
||||
Knobs that matter in practice:
|
||||
- `promptInjectionMode` — `off` | `advisory` | `strong` | `strict`
|
||||
- `contextBudgetPercent` / `contextBudgetMaxTokens` — caps automatic map/index injection
|
||||
- `tagCap` / `workflowHintCap` — caps routing metadata per directory
|
||||
- `llmProvider` / `llmModel` / `llmBaseUrl` — standalone CLI only
|
||||
- `ignorePatterns` — discovery exclusions
|
||||
|
||||
When project map artifacts exist in the repo:
|
||||
## Tools and commands
|
||||
|
||||
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.
|
||||
| Tool (Pi) | CLI command | Purpose |
|
||||
|-----------|-------------|---------|
|
||||
| `project_map_init` | `project-map init [path]` | Generate all paired artifacts. |
|
||||
| `project_map_patch` | `project-map patch <file>` | Regenerate the pair for the changed file's directory and refresh ancestors. |
|
||||
| `project_map_validate` | `project-map validate [--fix]` | Check paired artifacts for staleness and discrepancies; optionally repair. |
|
||||
| `project_map_reinit` | `project-map reinit [path]` | Force full regeneration. |
|
||||
| `project_map_context` | `project-map context <query>` | Retrieve a ranked context bundle for a natural-language query. |
|
||||
|
||||
Reference in New Issue
Block a user