199 lines
6.5 KiB
Markdown
199 lines
6.5 KiB
Markdown
# pi-project-map Usage Guide
|
||
|
||
For Pi agents and advanced users who want predictable, low-friction navigation and maintenance of project-map artifacts.
|
||
|
||
## When to use each command
|
||
|
||
| Situation | Command |
|
||
|-----------|---------|
|
||
| New project, no `.pi-map.md` files yet, or artifacts are severely outdated | `project_map_init` / `project-map init` |
|
||
| You just edited one or more source files | `project_map_patch <file>` / `project-map patch <file>` |
|
||
| You suspect stale data, or you are about to make an architectural decision | `project_map_validate` / `project-map validate` |
|
||
| Validation shows widespread staleness, or you pulled major changes from version control | `project_map_reinit` / `project-map reinit` |
|
||
| You have a specific question like "where is auth handled?" | `project_map_context <query>` / `project-map context <query>` |
|
||
|
||
## Command behavior
|
||
|
||
### init
|
||
Run once when you start work on a repo, or after large restructuring. It discovers every non-ignored directory, analyzes files with LLM + AST, and writes both `.pi-map.md` and `.pi-map.index.md` for every directory.
|
||
|
||
### patch
|
||
Run **immediately after editing a source file**. The command regenerates the pair for that file’s directory and refreshes ancestor artifacts.
|
||
|
||
Patch mode is chosen automatically:
|
||
- **small** — refresh ancestor indexes only
|
||
- **structural** — refresh ancestor map/index pairs
|
||
|
||
You can force a mode with `project-map patch <file> --patch-mode=small|structural`.
|
||
`auto` remains the default.
|
||
|
||
### validate
|
||
Run before architectural decisions, broad refactors, or final handoff. It checks for:
|
||
- missing/orphaned files
|
||
- stale signatures
|
||
- dirty markers
|
||
- broken parent/children/sibling links
|
||
- map/index disagreements
|
||
|
||
Use `project-map validate --fix` to repair affected chains. `--fix` requires an LLM client.
|
||
|
||
### reinit
|
||
Use sparingly. It regenerates every pair from scratch and is the blunt instrument for widespread staleness.
|
||
|
||
### context
|
||
Use when you know what you are looking for:
|
||
|
||
```bash
|
||
project-map context "authentication logic"
|
||
project-map context "routing metadata generation"
|
||
project-map context "LLM client error handling"
|
||
```
|
||
|
||
The returned bundle is deterministic and ranked. Read indexes first, then strongest-match maps, then the actual source files.
|
||
|
||
## Practical workflows
|
||
|
||
### Starting a new task in a mapped project
|
||
|
||
1. read the root `.pi-map.index.md` and the `Project Map Protocol`
|
||
2. use the root index to find the relevant child directory
|
||
3. read that directory’s `.pi-map.index.md`, then its `.pi-map.md`
|
||
4. read the relevant source files
|
||
5. edit source
|
||
6. run `project_map_patch <changed-file>`
|
||
7. run tests/build
|
||
8. run `project_map_validate` before architectural summary or handoff
|
||
|
||
### Exploring an unfamiliar area
|
||
|
||
```bash
|
||
project-map context "how is validation implemented"
|
||
```
|
||
|
||
Treat the returned bundle as a ranked entry point, not as truth.
|
||
|
||
### After pulling changes from version control
|
||
|
||
```bash
|
||
project-map validate
|
||
# if many discrepancies:
|
||
project-map reinit
|
||
```
|
||
|
||
### Before a big refactor
|
||
|
||
```bash
|
||
project-map validate
|
||
# if needed:
|
||
project-map reinit
|
||
```
|
||
|
||
## Prompt injection behavior before and after init
|
||
|
||
### Before init
|
||
If no paired artifacts exist:
|
||
- `off`: nothing happens
|
||
- `advisory`, `strong`, `strict`: a visible hint appears telling you to run `project_map_init`
|
||
|
||
No map content is fabricated.
|
||
|
||
### After init
|
||
Once the root pair exists:
|
||
- `off`: no automatic injection
|
||
- `advisory`: a visible reminder that maps are available, but the root pair is **not** auto-loaded
|
||
- `strong`: root pair is auto-loaded; additional pairs are added within the budget; reinjection happens on relevant turns
|
||
- `strict`: same as `strong`, plus enforcement of the protocol path for sensitive actions
|
||
|
||
Relevant turns that trigger reinjection in `strong`/`strict`:
|
||
- agent start
|
||
- edit intent
|
||
- architecture-sensitive reasoning
|
||
- compaction
|
||
- root-pair artifact changes
|
||
|
||
## Advisory vs strong vs strict in practice
|
||
|
||
| Concern | Use |
|
||
|---------|-----|
|
||
| You want maps available but do not want automatic context expansion | `advisory` |
|
||
| Normal daily work; you want routing/orientation preloaded without friction | `strong` (default) |
|
||
| High-stakes codebase or you want explicit justification before bypassing context discipline | `strict` |
|
||
| You prefer fully manual control | `off` |
|
||
|
||
In `strict`, if you attempt a sensitive edit or architectural claim without the protocol path in context, a guard appears. To proceed, either restore the project-map context or include:
|
||
|
||
```text
|
||
[PI_MAP_BYPASS: editing a one-line comment, map context not needed]
|
||
```
|
||
|
||
Use bypass markers sparingly.
|
||
|
||
## Example task flows
|
||
|
||
### Fix a bug in `src/utils/validation.ts`
|
||
|
||
```text
|
||
1. project-map context "validation utilities"
|
||
2. Read src/utils/.pi-map.index.md and .pi-map.md
|
||
3. Read src/utils/validation.ts
|
||
4. Edit the file
|
||
5. project_map_patch src/utils/validation.ts
|
||
6. Run tests
|
||
7. project_map_validate
|
||
```
|
||
|
||
### Add a new file to `src/llm/`
|
||
|
||
```text
|
||
1. Create src/llm/new-client.ts
|
||
2. Implement the file
|
||
3. project_map_patch src/llm/new-client.ts
|
||
4. project_map_validate
|
||
```
|
||
|
||
### Review architecture before approving a PR
|
||
|
||
```text
|
||
1. project-map validate
|
||
2. If clean, read root .pi-map.md and key directory maps
|
||
3. Cross-check claims against source
|
||
4. If stale, run project-map reinit first
|
||
```
|
||
|
||
## Retrieval vs automatic injection
|
||
|
||
| | Automatic injection | `project_map_context` / `project-map context` |
|
||
|---|---|---|
|
||
| Trigger | Configured mode + relevant turn | Explicit request |
|
||
| Content | Root pair + budgeted expansion | Top-ranked directories for a query |
|
||
| Cost | No LLM call; reads artifacts | No LLM call; deterministic scoring |
|
||
| Best use | Maintain baseline orientation | Targeted navigation for a specific task |
|
||
|
||
Use both together: injection for baseline orientation, retrieval for focused entry points.
|
||
|
||
## Keeping artifacts fresh
|
||
|
||
- patch after every edit
|
||
- validate before architectural claims
|
||
- reinit when many artifacts are stale or after large merges
|
||
- watch for the Pi extension warning about dirty packages on session start
|
||
|
||
## Configuration quick reference
|
||
|
||
```json
|
||
{
|
||
"promptInjectionMode": "strong",
|
||
"contextBudgetPercent": 15,
|
||
"contextBudgetMaxTokens": 100000,
|
||
"tagCap": 8,
|
||
"workflowHintCap": 5,
|
||
"ignorePatterns": ["node_modules", ".git", "dist", "build"]
|
||
}
|
||
```
|
||
|
||
Providing `ignorePatterns` replaces the built-in default list, so include any defaults you want to keep.
|
||
|
||
- lower `contextBudgetPercent` / `contextBudgetMaxTokens` to reduce token use
|
||
- raise them if you want deeper auto-loaded context in large projects
|
||
- `strict` is the safest enforcement mode; `strong` is the best default for everyday work
|