pi-map/SKILL.md

name, description

name	description
pi-project-map	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

# 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:

# 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:

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:

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:

project-map validate

project-map:reinit [path]

Force full re-initialization. Clears all dirty markers.

Example:

project-map reinit
project-map reinit src/components

Configuration

Create .pi-project-map.json in the project root:

{
  "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)