153 lines
4.6 KiB
Markdown
153 lines
4.6 KiB
Markdown
---
|
|
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.
|
|
---
|
|
|
|
# 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.
|
|
|
|
## 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
|
|
|
|
## 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
|
|
```
|
|
|
|
## Format
|
|
|
|
Each `.pi-map.md` uses dense markdown optimized for LLM consumption:
|
|
|
|
```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
|
|
-
|
|
```
|
|
|
|
### Abbreviations
|
|
|
|
| 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
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create `.pi-project-map.json` in the project root:
|
|
|
|
```json
|
|
{
|
|
"ignorePatterns": ["node_modules", ".git"],
|
|
"smallPackageThreshold": 10,
|
|
"contextBudget": 4000,
|
|
"autoInjectPrompt": true
|
|
}
|
|
```
|
|
|
|
| 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:
|
|
|
|
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
|
|
|
|
## Best Practices
|
|
|
|
- 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
|
|
|
|
## Supported Languages
|
|
|
|
| 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) |
|