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

Implement layered maps and context retrieval

Browse Source
This commit is contained in:
Alex
2026-06-11 12:56:18 +02:00
parent 010e4b83eb
commit c6064f8d94
35 changed files with 4410 additions and 383 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SKILL.md
+39 -112
View File
@@ -1,108 +1,45 @@
---
name: pi-map
description: Generates and maintains hierarchical, machine-readable project analysis files (.pi-map.md) for instant codebase comprehension. Use when working with medium-to-large codebases where understanding architecture, file relationships, and exports without reading every file is valuable. Automatically extracts symbols via AST and LLM heuristics.
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 hierarchical, machine-readable analysis of a software project. Each directory gets a `.pi-map.md` file containing architectural context, exported symbols, and dependencies.
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 entire project and creates one `.pi-map.md` per directory
- **Extracts** exports, imports, and dependencies via AST parsing (TypeScript, Python, Go) and LLM heuristics
- **Updates** incrementally when files change (full rewrite for small packages, section-level patch for large)
- **Validates** detects stale entries, missing files, orphaned entries, and changed signatures
- **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
# Install globally
npm install -g pi-project-map
# Generate analysis files for the entire project
project-map init
# After editing a file, update its directory's analysis
project-map patch src/components/Button.tsx
# Check for staleness
project-map validate
# Force full regeneration
project-map reinit
project-map context "authentication logic"
```
## Format
## Operating Model
Each `.pi-map.md` uses dense markdown optimized for LLM consumption:
### Tier 0
Read the root `.pi-map.index.md` and the `Project Map Protocol` first.
```markdown
# pkg/auth
## role
Auth layer: JWT issuance, validation, refresh. Stateless. Dep: pkg/crypto, pkg/db.
## files
- tokens.ts | JWT gen/val | exp: issueToken, verifyToken, refreshToken | dep: crypto/hmac, db/sessions
- middleware.ts | HTTP auth guard | exp: requireAuth, requireRole | dep: tokens/verifyToken
## arch
Guard pattern on routes. Tokens short-lived (15m), refresh long-lived (7d). Rotation on every use.
## dirty
-
```
### Tier 1
Use indexes first for routing. Open the strongest-match `.pi-map.md` files next.
### Abbreviations
### Tier 2
Read actual source before editing or asserting exact behavior.
| Abbreviation | Meaning |
|-------------|---------|
| `exp:` | Exported symbols |
| `dep:` | Dependencies |
| `pkg/` | Internal package reference |
## Tools
### `project-map:init [root]`
Runs a full project scan and generates `.pi-map.md` files in every directory.
**Example:**
```bash
project-map init
project-map init ~/my-project
```
### `project-map:patch <file-path>`
Updates the `.pi-map.md` for the directory containing the given file.
**Behavior:**
- Small packages (< 10 files): full rewrite
- Large packages (>= 10 files): section-level patch
**Example:**
```bash
project-map patch src/components/Button.tsx
```
### `project-map:validate [root]`
Checks all `.pi-map.md` files for staleness.
**Detects:**
- Missing files (new files not yet in `.pi-map.md`)
- Orphaned entries (files listed but deleted)
- Stale signatures (exports changed since last scan)
- Dirty markers (packages flagged for reconciliation)
**Example:**
```bash
project-map validate
```
### `project-map:reinit [path]`
Force full re-initialization. Clears all dirty markers.
**Example:**
```bash
project-map reinit
project-map reinit src/components
```
**Trust boundary:** index routes, map orients, source decides.
## Configuration
@@ -110,43 +47,33 @@ Create `.pi-project-map.json` in the project root:
```json
{
"ignorePatterns": ["node_modules", ".git"],
"smallPackageThreshold": 10,
"contextBudget": 4000,
"autoInjectPrompt": true
"tagCap": 8,
"workflowHintCap": 5
}
```
| Option | Default | Description |
|--------|---------|-------------|
| `ignorePatterns` | `node_modules`, `.git`, `dist`, etc. | Additional ignore patterns |
| `smallPackageThreshold` | `10` | File count threshold for full rewrite vs patch |
| `contextBudget` | `4000` | Max tokens to spend on analysis files |
| `autoInjectPrompt` | `true` | Auto-inject maintenance instructions |
## Agent Instructions
When `.pi-map.md` files exist in the project:
When project map artifacts exist in the repo:
1. **Read them at session start** to build project understanding without scanning every file
2. **Run `project-map:patch <path>`** after editing any source file
3. **Run `project-map:validate`** if you suspect staleness before making architectural decisions
4. **Trust the analysis** for orientation, but verify critical details by reading source when needed
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. 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.
## Best Practices
## Retrieval Model
- Run `project-map:init` after cloning a new repository
- Run `project-map:reinit` periodically (daily/weekly) to catch changes made outside the agent
- Add `.pi-map.md` to `.gitignore` — they are derived artifacts
- For very large projects (> 1000 directories), consider running `init` on subdirectories
`project_map_context` and `project-map context` implement **index-first retrieval**:
## Supported Languages
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>`
| Language | AST Parsing | Heuristic Extraction |
|----------|------------|---------------------|
| TypeScript / TSX | Full | Full |
| JavaScript / JSX | Full | Full |
| Python | Partial | Full |
| Go | Partial | Full |
| Rust | Partial | Full |
| Other | - | Full (filename + regex patterns) |
**Trust boundary still applies:** the bundle routes and orients, but source decides. Always read actual source before editing.