pi-map/SKILL.md

name, description

name	description
pi-map	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 paired analysis for each non-ignored directory:

• .pi-map.index.md for routing
• .pi-map.md for orientation

What It Does

• 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

project-map init
project-map patch src/components/Button.tsx
project-map validate
project-map reinit
project-map context "authentication logic"

Operating Model

Tier 0

Read the root .pi-map.index.md and the Project Map Protocol first.

Tier 1

Use indexes first for routing. Open the strongest-match .pi-map.md files next.

Tier 2

Read actual source before editing or asserting exact behavior.

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

Prompt Injection Policy

This skill can automatically inject lightweight project-map guidance into your context. The behavior is controlled by promptInjectionMode in .pi-project-map.json.

Before init

When no .pi-map.md / .pi-map.index.md artifacts exist, you see a visible startup hint telling you to run project_map_init. No synthetic map content is injected before real artifacts exist.

After init

Once artifacts exist, the runtime guarantees that the root pair is loaded first:

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

Additional directory pairs may be added while the configured context budget allows.

Mode ladder

• off: no automatic injection beyond existing tool/docs discovery.
• advisory: startup/init hints are shown; you may read the root pair manually when you want routing/orientation context.
• strong (default): the root pair is injected automatically, expansion stays within the context budget, and reinjection checks run on relevant turns (agent start, before edits, before architecture-sensitive reasoning, after compaction, after root-pair artifact changes).
• strict: same as strong, but before sensitive edits or architectural claims you must either have the protocol path in context or include an explicit bypass marker: [PI_MAP_BYPASS: <brief justification>].

The protocol path means the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction (index routes, map orients, source decides).

Context budget

Default budget: 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 uses the absolute cap.

Configuration

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

{
  "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 to use for automatic map/index injection.
• contextBudgetMaxTokens: hard absolute cap on the injection budget.

Agent Instructions

When project map artifacts exist in the repo:

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. In strict mode, include [PI_MAP_BYPASS: <brief justification>] only when you deliberately need to proceed without the protocol path
7. 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.

Retrieval Model

project_map_context and project-map context implement index-first retrieval:

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>

Trust boundary still applies: the bundle routes and orients, but source decides. Always read actual source before editing.