pi-project-map

Pi skill for hierarchical project analysis.

What it does

Generates paired project-analysis artifacts throughout your project:

• .pi-map.index.md — routing-first index for deciding what to open next
• .pi-map.md — orientation-first rich map for understanding a directory

This gives Pi agents fast navigation plus deeper architectural context without reading every source file up front.

Quick Start

npm install -g pi-project-map
project-map init

Agent operating model

Tier 0

Always start with:

• Project Map Protocol
• root .pi-map.index.md

Tier 1

Load likely relevant directory indexes first, then open the strongest-match rich maps.

Tier 2

Read actual source, tests, config, and docs before editing or making exact runtime claims.

Trust boundary: index routes, map orients, source decides.

Prompt Injection Policy

The Pi extension can automatically inject lightweight project-map guidance into the agent context according to the configured promptInjectionMode.

Before init

When no .pi-map.md / .pi-map.index.md artifacts exist, only a visible startup hint is injected. It tells the agent that the project-map extension is active and to run project_map_init. No synthetic or fake map content is ever injected before real artifacts exist.

After init

Once real artifacts exist, the runtime guarantees that the root pair is loaded before any budgeted expansion:

• root .pi-map.index.md
• root .pi-map.md

Additional directory pairs are expanded only while the configured context budget allows, in shallow-first order.

Trust boundary

Injected maps and indexes are navigation and orientation aids, not final authority:

index routes, map orients, source decides

If an injected artifact and the source disagree, source wins. Always verify critical behavior from source before editing or making exact runtime claims.

Mode ladder

• off: no automatic injection beyond existing tool/docs discovery.
• advisory: inject startup/init hints and allow optional root-pair preload; use light reminders.
• strong (default): inject the root pair, expand under the configured budget, run reinjection checks on relevant turns, and remind before edits or architecture-sensitive reasoning.
• strict: same as strong, plus require an explicit bypass justification before sensitive edits or architectural claims when the protocol path is missing.

The protocol path is present when the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction. In strict mode, sensitive actions without it are blocked unless the agent includes [PI_MAP_BYPASS: <brief justification>].

Context budget

The default budget is 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 falls back to the absolute cap.

Configure it in .pi-project-map.json:

{
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000
}

Retrieval

When you have a specific query (e.g. "authentication logic" or "routing metadata"):

1. Run project-map context <query> or use the Pi tool project_map_context
2. Read the returned Context bundle — it contains relevant indexes, maps, likely files, and symbols
3. Always verify critical behavior from source before editing

Retrieval via project_map_context (tool) or project-map context (CLI) remains a separate, on-demand path. Use it for targeted navigation when you have a specific query; automatic injection does not replace it.

Integration-test expectations and known limitations

The implementation is validated by integration tests covering:

• pre-init hint behavior,
• post-init root-pair preload,
• budgeted expansion behavior,
• canonical-marker dedupe,
• reinjection after compaction,
• reinjection after root-pair artifact changes,
• mixed visibility behavior,
• guidance-mode differences,
• strict-mode bypass behavior.

Known limitations:

• Token estimation is best-effort (≈ 4 chars per token); actual provider token counts may differ.
• Relevant-turn detection uses explicit event types when available and falls back to heuristics on generic turns.
• Message-layer scanning is preferred; provider-payload serialization quirks require a fallback scan path.

Commands

project-map init
project-map patch <file>
project-map validate [--fix]
project-map reinit
project-map context <query>

Context retrieval

project-map context <query> searches the paired map/index artifacts and returns a compact markdown bundle with the most relevant directories, files, and symbols. No LLM call is needed — it uses deterministic metadata scoring.

Configuration

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

{
  "ignorePatterns": ["node_modules", ".git"],
  "smallPackageThreshold": 10,
  "contextBudget": 4000,
  "autoInjectPrompt": true,
  "tagCap": 8,
  "workflowHintCap": 5,
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000
}

• promptInjectionMode: off, advisory, strong (default), or strict.
• contextBudgetPercent: relative share of the active model context window used for automatic map/index injection.
• contextBudgetMaxTokens: hard absolute cap on the injection budget.

Design

See design-doc.md for the full specification.

Implementation Plan

See implementation-plan.md for the engineering roadmap.