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
design-doc.md
+56 -25
View File
@@ -19,19 +19,49 @@ Enable a Pi coding agent to understand a software project's architecture and cod
- **Dense markdown**: Hierarchical headings, bullet points, and abbreviations are natively understood by LLMs and extremely token-efficient.
### Structure
Each directory in the project gets one analysis file named `.pi-map.md` (hidden by default, excluded from git via `.gitignore`).
Each non-ignored directory in the project gets **two** hidden analysis files:
- `.pi-map.index.md` — routing-first index
- `.pi-map.md` — orientation-first rich map
```markdown
# <relative-path> (index)
dir: <relative-path>
## role
<short routing summary>
## parent
<parent links or ->
## children
<child links or ->
## files
<likely files>
## links
index: <self-index>
map: <self-map>
## workflows
<compact task -> route hints>
## dirty
<timestamp or ->
```
```markdown
# <relative-path>
dir: <relative-path>
index: <sibling-index>
## role
<one-line package role> | Dep: <comma-separated upstream deps>
<one-line package role>
## files
- <filename> | <one-line purpose> | exp: <exported symbols> | dep: <internal/external deps>
- <filename> | <one-line purpose> | exp: <exported symbols> | dep: <internal/external deps>
## arch
<free-form architectural notes: patterns, data flow, invariants, design decisions>
<free-form architectural notes>
## tags
<compact tags>
## symbols
<prioritized symbols>
## workflows
<compact workflow hints>
## dirty
<timestamp or flag indicating staleness>
<timestamp or ->
```
### Abbreviation Conventions
@@ -152,16 +182,14 @@ For each directory (depth-first):
### Patch Pipeline
```
When agent edits file(s) in directory:
1. Determine patch strategy:
- If directory has < 10 files: full rewrite.
- Else: section-level patch for changed file(s) only.
2. For each changed file:
a. Recompute SHA-256.
b. Check cache. If miss or stale, call LLM with retries/backoff.
3. Re-run AST extraction on changed file(s) if applicable.
4. Update `## files` section (rewrite or patch).
5. Update `## dirty` flag if full regeneration is deferred.
When agent edits file(s):
1. Classify patch mode: auto, small, or structural.
2. Always regenerate the changed directory pair:
- `.pi-map.md`
- `.pi-map.index.md`
3. For small changes: refresh ancestor indexes.
4. For structural changes: refresh ancestor map/index pairs.
5. Use `validate --fix` to repair affected chains when paired artifacts are stale or missing.
```
## 4. LLM Prompt Design
@@ -220,18 +248,20 @@ The LLM client's response is parsed to extract `PURPOSE`, `DEPS`, `CONCEPTS`, `R
## 5. Consumption Model
### Session Start
1. Agent discovers all `.pi-map.md` files (e.g., via `find . -name ".pi-map.md"`).
2. Agent reads **all** files into context. This is a one-time cost at session start.
3. Agent constructs an internal mental model of the project hierarchy.
1. Agent reads the root `Project Map Protocol` and root `.pi-map.index.md`.
2. For architecture/system or ambiguous tasks, agent also reads the root `.pi-map.md`.
3. Agent does **not** preload every directory map by default.
### During Session
- An **auto-injected summary** stays in context (e.g., a condensed top-level `.pi-map.md` or a synthesized project overview).
- When the agent needs deeper detail about a specific package, it already has the full `.pi-map.md` in memory from step 2.
- If the agent enters a new package not yet loaded, it reads that package's `.pi-map.md` on demand.
- Use directory indexes first to decide what to open next.
- For **targeted queries**, run `project_map_context` (tool) or `project-map context` (CLI). The retrieval engine scores all paired metadata and returns a compact markdown bundle with the top-3 strongest matches: indexes, maps, likely files, and symbols.
- Open the strongest-match `.pi-map.md` files for richer orientation.
- Read actual source before editing or making exact runtime claims.
### Context Management
- For very large projects, the agent may summarize or prune the initial read, keeping only the top N levels of the hierarchy in active context.
- The skill can provide a "context budget" parameter: max tokens to spend on analysis files.
- Tier 0 stays tiny and stable.
- Tier 1 loads only likely relevant indexes/maps.
- Tier 2 is real source, tests, config, and docs.
## 6. Stale Data Mitigation
@@ -297,9 +327,10 @@ pi-project-map/
```
### Custom Tools
- `project-map:init` — Run full project scan. Creates all `.pi-map.md` files.
- `project-map:init` — Run full project scan. Creates all paired map/index artifacts.
- `project-map:patch <file-path>` — Update analysis for a specific file/directory.
- `project-map:validate` — Run consistency check across all `.pi-map.md` files.
- `project-map:validate` — Run consistency check across all paired artifacts.
- `project-map:context <query>` — Retrieve a compact markdown bundle of the most relevant directories, files, and symbols for a natural-language query.
- `project-map:reinit [path]` — Force re-initialization of entire project or subtree.
### Prompt Hook