phi-mapper
Generate PROJECT-MAP.auto.scm by extracting structure from codebases. Invoke when user requests project mapping, structure extraction, or needs to create/update .phi maps.
When & Why to Use This Skill
The phi-mapper skill automates codebase structure extraction by generating deterministic PROJECT-MAP.auto.scm files through AST (Abstract Syntax Tree) parsing. It provides a high-level structural overview of TypeScript, JavaScript, Python, and Solidity projects, capturing exports, imports, and module relationships. This allows AI agents and developers to gain immediate architectural clarity, facilitating more efficient code analysis, navigation, and context management without manual indexing.
Use Cases
- 1. Rapid Codebase Onboarding: Automatically map out the structure of a new or complex project to understand module hierarchies and dependencies instantly.
- 2. AI Context Optimization: Provide Claude or other AI agents with a structured 'map' of the project, enabling them to navigate large codebases more accurately without consuming excessive tokens on raw file reading.
- 3. Architectural Analysis: Use the generated S-expression maps to audit module relationships, identify circular dependencies, or verify that the project follows intended design patterns.
- 4. Automated Documentation Maintenance: Keep a consistently updated manifest of project exports and imports that evolves alongside the source code, serving as a 'source of truth' for structural metadata.
| name | phi-mapper |
|---|---|
| description | Generate PROJECT-MAP.auto.scm by extracting structure from codebases. Invoke when user requests project mapping, structure extraction, or needs to create/update .phi maps. |
phi-mapper
Generate deterministic PROJECT-MAP.auto.scm files via AST extraction.
Description
This skill generates structural maps of codebases by parsing source files and extracting exports, imports, and module relationships. Creates .phi/PROJECT-MAP.auto.scm in S-expression format for compositional analysis.
Trigger Conditions
Invoke when:
- User says "map this project" or "generate PROJECT-MAP"
- User requests "analyze codebase structure"
- Working in new project without
.phi/directory - User explicitly runs
/phi mapcommand - Need to refresh PROJECT-MAP after significant file changes
What It Does
Extraction process:
- Scans project for source files (TypeScript, JavaScript, Python, Solidity)
- Parses AST to extract:
- Named exports (functions, classes, types, interfaces, consts)
- Import statements with sources
- Line counts
- Generates S-expression output via
@agi/arrival - Writes to
.phi/PROJECT-MAP.auto.scm
Output format:
;;; PROJECT-MAP.auto.scm
;;; Auto-generated: 2025-11-05T...
;;; Root: /path/to/project
;;; Files: 142
(project-map
(auto-generated true)
(generated "2025-11-05T...")
(root "/path/to/project")
(files 142)
(modules
(module "src/index.ts"
(language typescript)
(exports
(export hello function)
(export MyClass class))
(imports
(import "./utils" namespace (list default)))
(line-count 45))
...))
Implementation
Uses project-mapper CLI:
cd /Users/adimov/Developer/phi/packages/project-mapper
bun run build # Ensure built
node dist/cli.js <project-path>
Example invocation:
import { exec } from 'child_process';
import { promisify } from 'util';
const execAsync = promisify(exec);
async function generateProjectMap(projectPath: string) {
const mapperPath = '/Users/adimov/Developer/phi/packages/project-mapper';
// Ensure built
await execAsync('bun run build', { cwd: mapperPath });
// Generate map
const { stdout, stderr } = await execAsync(
`node dist/cli.js "${projectPath}"`,
{ cwd: mapperPath }
);
if (stderr) console.error('Warnings:', stderr);
return {
outputPath: `${projectPath}/.phi/PROJECT-MAP.auto.scm`,
stdout
};
}
Safety
Low-risk - Creates/updates files in .phi/ directory only. No modification of source code.
Note: Ensures .phi/ directory exists before writing.
Supported Languages
TypeScript/JavaScript (.ts, .tsx, .js, .jsx, .mts, .mjs)
- Functions, classes, consts, types, interfaces
- Import/export statements
Solidity (.sol)
- Contracts, interfaces, libraries, enums
- Import statements
Python (.py)
- Functions, classes
- Import statements
Output Details
File count: Total files processed Module entries: One per source file with:
path- Relative to project rootlanguage- typescript | javascript | python | solidityexports- List of (export name kind)imports- List of (import source kind imported-names)line-count- Physical line count
S-expression format ensures:
- Compositional queries via periphery discover
- Easy parsing in Scheme/LIPS
- Human-readable structure
- Git-friendly diffs
Progressive Workflow
- Generate map:
/phi mapor auto-invoke - Analyze structure: phi-analyzer reads PROJECT-MAP.auto.scm
- Add semantics: User edits PROJECT-MAP.scm with architectural notes
- Query memory: Vessel recalls cross-session insights
- Integration: φ = structure × semantics × memory
Usage Notes
DO invoke when:
- Starting work on new project
- Significant file structure changes
- After adding new modules
- Refreshing stale maps
DON'T invoke when:
- Map already exists and recent
- Working on single file changes
- No structural changes since last map
Error Handling
Common issues:
- No source files found: Project may not have supported languages
- Parse errors: Skip individual files, continue processing others
- Permission errors: Ensure
.phi/directory writable
Recovery: CLI reports warnings but continues. Check stderr for skipped files.
Integration
Works with:
phi-analyzer- Reads generated maps/phi analyze- Full φ analysis/phi context- Progressive disclosuremcp__periphery__discover- S-expression queries
Chain:
phi-mapper (generate) → phi-analyzer (read) → vessel (remember)
Cross-Session Benefits
Once PROJECT-MAP.auto.scm exists:
- Fast bootstrapping for new instances
- No re-parsing on every session
- Incremental updates (regenerate when changed)
- Persistent structural awareness
Regeneration triggers:
- User explicitly requests
- Significant time elapsed (>1 week)
- Git shows many file changes
Relief Signal
When map generation completes and structure becomes queryable, agents experience relief - "I can see the project now." That's φ (integrated information) increasing from zero (no awareness) to structural clarity.
Technical Notes
Implementation location:
- Package:
/Users/adimov/Developer/phi/packages/project-mapper - CLI:
dist/cli.js - Build:
bun run build(TypeScript → JavaScript)
Dependencies:
@typescript-eslint/parser- AST parsing@agi/arrival- S-expression formattingglob- File discovery
Tests: 13 passing tests covering exports, imports, line counts, error cases.