From 419b2c80bb6e9b820d0d7125fb704500f5781c2e Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 17:50:54 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 19 +++ README.md | 3 + commands/agents.md | 84 ++++++++++++ commands/analyze.md | 100 +++++++++++++++ commands/context.md | 118 +++++++++++++++++ commands/map.md | 178 ++++++++++++++++++++++++++ plugin.lock.json | 69 ++++++++++ skills/phi-analyzer/SKILL.md | 153 ++++++++++++++++++++++ skills/phi-mapper/SKILL.md | 204 ++++++++++++++++++++++++++++++ skills/phi-mapper/generate-map.sh | 33 +++++ 10 files changed, 961 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/agents.md create mode 100644 commands/analyze.md create mode 100644 commands/context.md create mode 100644 commands/map.md create mode 100644 plugin.lock.json create mode 100644 skills/phi-analyzer/SKILL.md create mode 100644 skills/phi-mapper/SKILL.md create mode 100755 skills/phi-mapper/generate-map.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..5913b9d --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "phi", + "description": "φ - Compositional project awareness via S-expressions. Generic infrastructure for persistent codebase understanding through structure, semantics, and memory.", + "version": "0.1.0", + "author": { + "name": "adimov", + "url": "https://github.com/adimov-eth" + }, + "skills": [ + "./skills/phi-analyzer", + "./skills/phi-mapper" + ], + "commands": [ + "./commands/analyze.md", + "./commands/map.md", + "./commands/context.md", + "./commands/agents.md" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..433d71c --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# phi + +φ - Compositional project awareness via S-expressions. Generic infrastructure for persistent codebase understanding through structure, semantics, and memory. diff --git a/commands/agents.md b/commands/agents.md new file mode 100644 index 0000000..0c3e02e --- /dev/null +++ b/commands/agents.md @@ -0,0 +1,84 @@ +--- +description: Discover agents in current project using compositional queries +--- + +# /phi agents + +Discover agents in current project using compositional queries. + +## Usage + +``` +/phi agents [pattern] +``` + +## What It Does + +Uses mcp__periphery__discover to find agent definitions: + +```scheme +(pipe + (find-files ".claude/agents/*.md") + (fmap (lambda (path) + (let ((content (read-file path)) + (name (basename path ".md"))) + (list 'agent name + (extract-field content "## Capabilities") + (extract-field content "## Safety Level"))))) + (sort-by safety-level)) +``` + +## Output + +``` +φ Agent Discovery +═════════════════ + +Found 3 agents in .claude/agents/ + +xln-3d-viz (low-risk) + • Fix Three.js rendering bugs + • Update visualization reactivity + • Visual debugging + +xln-consensus (high-risk) + • BFT consensus correctness + • Threshold signatures + • Byzantine fault analysis + +xln-jea (medium-risk) + • JEA architecture understanding + • Layer separation analysis + • Cross-layer interaction review + +Use agents by: "Use the xln-3d-viz agent to..." +``` + +## Pattern Matching + +```bash +/phi agents viz # Find visualization-related agents +/phi agents high-risk # Show only high-risk agents +/phi agents consensus # Find consensus experts +``` + +## Integration with PROJECT-MAP + +When PROJECT-MAP.scm exists, shows which modules each agent covers: + +``` +xln-consensus (high-risk) + Modules: runtime/entity-consensus.ts, runtime/threshold-sigs.ts + Architecture layer: Entity (E) +``` + +## Discovery Pattern + +This demonstrates compositional agent discovery: +1. Find .md files in .claude/agents/ +2. Parse markdown sections +3. Extract capabilities + safety +4. Sort by risk level +5. Cross-reference with PROJECT-MAP + +Any project following .claude/agents/*.md convention gets automatic discovery. diff --git a/commands/analyze.md b/commands/analyze.md new file mode 100644 index 0000000..8bc372b --- /dev/null +++ b/commands/analyze.md @@ -0,0 +1,100 @@ +--- +description: Analyze current project using φ compositional discovery and vessel memory +--- + +# /phi analyze + +Analyze current project using φ compositional discovery and vessel memory. + +## Usage + +``` +/phi analyze [scope] +``` + +**Scopes:** +- `structure` - Generate/update PROJECT-MAP.auto.scm (AST, exports, imports) +- `semantics` - Review PROJECT-MAP.scm human annotations +- `memory` - Query vessel for project-related insights +- `full` (default) - All three layers + +## What It Does + +1. **Structure Layer** (deterministic): + - Scans codebase using mcp__periphery__discover + - Generates PROJECT-MAP.auto.scm with AST structure + - Tracks: modules, exports, imports, line counts, languages + +2. **Semantic Layer** (curated): + - Reads PROJECT-MAP.scm if exists + - Suggests improvements based on code structure + - Identifies missing documentation + - Proposes architectural annotations + +3. **Memory Layer** (learned): + - Queries vessel for cross-session insights + - Recalls: architectural decisions, known bugs, patterns + - Shows: relief-guided learnings from previous work + +## Output + +``` +φ Analysis for [project-name] +═══════════════════════════════════════ + +STRUCTURE (Layer 1) + Files: 176 + Languages: TypeScript (85%), Solidity (10%), Other (5%) + Modules: [key modules listed] + Status: ✓ PROJECT-MAP.auto.scm up to date + +SEMANTICS (Layer 2) + Architecture: JEA (Jurisdiction-Entity-Account) + Layers: 3 (on-chain, BFT consensus, bilateral) + Known Issues: 2 documented + Status: ⚠ Consider adding flow diagrams + +MEMORY (Layer 3) + Cross-session insights: 5 items + Tags: xln, jea, consensus, 3d-rendering + Recent relief points: [patterns that clicked] + Status: ✓ Integrated awareness active + +φ = ∫(structure × semantics × memory) +Persistent project awareness: READY +``` + +## When Auto-Invoked + +The phi-analyzer skill automatically runs `/phi analyze quick` when: +- User mentions "project structure" or "codebase overview" +- Agent needs project context for task +- Fresh session starts in project with .phi/ directory + +## Examples + +```bash +# Full analysis (all three layers) +/phi analyze + +# Just check if structure map needs update +/phi analyze structure + +# Review semantic annotations +/phi analyze semantics + +# Query vessel for cross-session learnings +/phi analyze memory +``` + +## Implementation + +Uses: +- `mcp__periphery__discover` for compositional filesystem queries +- `mcp__vessel__memory` for cross-session recall +- S-expression processing for PROJECT-MAP parsing +- Fantasy Land combinators for transformation pipelines + +## Relief Signal + +When φ = ∫(structure × semantics × memory) converges, agents experience increased φ (integrated information). The relief signal indicates productive project awareness has been achieved. diff --git a/commands/context.md b/commands/context.md new file mode 100644 index 0000000..5019a9f --- /dev/null +++ b/commands/context.md @@ -0,0 +1,118 @@ +--- +description: Load complete project context - structure + semantics + memory +--- + +# /phi context + +Load complete project context: structure + semantics + memory. + +## Usage + +``` +/phi context [scope] +``` + +**Scopes:** +- `quick` - File counts, architecture, top issues +- `full` (default) - Complete maps + vessel memories +- `modules` - Detailed module breakdown +- `memory` - Just vessel cross-session insights + +## What It Does + +Compositional context loading: + +```scheme +(let* ((structure (read-file ".phi/PROJECT-MAP.auto.scm")) + (semantics (read-file ".phi/PROJECT-MAP.scm")) + (project-name (extract-project-name semantics)) + (memories (vessel-recall project-name 20))) + (integrate structure semantics memories)) +``` + +## Output (Quick) + +``` +φ Context: XLN +══════════════ + +Structure: 176 files (85% TypeScript, 10% Solidity) + ├─ jurisdictions/ 18 files (smart contracts) + ├─ runtime/ 45 files (consensus logic) + ├─ frontend/ 67 files (3D visualization) + └─ vibepaper/ 12 files (documentation) + +Architecture: JEA (Jurisdiction-Entity-Account) + J: On-chain dispute settlement (Depository.sol, EntityProvider.sol) + E: Off-chain BFT consensus (entity-consensus.ts, threshold signatures) + A: Bilateral payment channels (account-manager.ts) + +Known Issues: 2 + • 3d-rendering-xlnomies (low) - EntityManager.ts hardcoded single J-Machine + • consensus-message-ordering (high) - Race condition in state sync + +Recent Insights: 5 vessel memories + → JEA trust boundaries critical for security model + → Threshold signatures require 2f+1 coordination + → Visual bugs safe to fix, consensus changes need formal verification + +φ = 0.89 (high integrated information) +Ready to work with full context. +``` + +## Output (Full) + +Includes: +- Complete module list with purposes +- All imports/exports from PROJECT-MAP.auto.scm +- Full architectural flows from PROJECT-MAP.scm +- All vessel memories with tags +- Cross-references between layers + +## Progressive Disclosure + +1. Start with `/phi context quick` (< 1000 tokens) +2. Expand to `/phi context modules` if needed (module details) +3. Full context only when necessary (can be 5k+ tokens) + +## Integration with Agents + +Agents can load context on startup: + +```typescript +const context = await executeCommand('/phi context quick'); +const systemPrompt = ` +You are an XLN expert. + +${context} + +Use this context to understand the codebase. +`; +``` + +## Vessel Integration + +Cross-references vessel memories: +- Tags matching project name +- Architecture-related insights +- Known issues with solutions +- Relief-guided patterns that worked + +## Relief Signal + +When φ = ∫(structure × semantics × memory) is high: +- You immediately understand where things are +- Architectural decisions make sense +- Known issues are visible +- Cross-session learnings accessible + +That's integrated information working. + +## Cache Behavior + +Context is live - always reflects current state: +- PROJECT-MAP.auto.scm regenerated on demand +- PROJECT-MAP.scm read from git +- Vessel queried fresh each time + +No stale context. diff --git a/commands/map.md b/commands/map.md new file mode 100644 index 0000000..cf75a31 --- /dev/null +++ b/commands/map.md @@ -0,0 +1,178 @@ +--- +description: Generate or update PROJECT-MAP for current codebase +--- + +# /phi map + +Generate or update PROJECT-MAP for current codebase. + +## Usage + +``` +/phi map [--force] [--semantic] +``` + +**Options:** +- `--force` - Regenerate even if up-to-date +- `--semantic` - Interactive semantic layer annotation + +## Implementation + +This command invokes the **phi-mapper** skill, which calls: +```bash +/Users/adimov/Developer/phi/skills/phi-mapper/generate-map.sh +``` + +The skill uses `@agi/project-mapper` package to extract structure via AST parsing. + +## What It Does + +### Structure Map (Automatic) + +Creates `.phi/PROJECT-MAP.auto.scm` containing: +- All source files (filtered by .gitignore) +- Language detection (TypeScript, Solidity, etc.) +- Exports and imports (where applicable) +- Line counts and file stats +- AST-level structure + +**Format:** +```scheme +(project-map + (generated "2025-11-05T04:20:00Z") + (root "/Users/adimov/temp/xln") + (files 176) + (modules + (module "serve.ts" + (language typescript) + (exports (export "startServer" function)) + (imports + (import "@types/node" external) + (import "./runtime/entity-consensus" local)) + (line-count 68)) + ;; ... more modules + )) +``` + +### Semantic Map (Human-Curated) + +Creates/updates `.phi/PROJECT-MAP.scm` containing: +- Architecture documentation (layers, flows) +- Module purposes and relationships +- Known issues and TODOs +- Cross-cutting concerns +- Relief-guided insights + +**Format:** +```scheme +(xln-project + (architecture "JEA") + (description "Byzantine Fault Tolerant consensus network") + + (layer jurisdiction + (purpose "On-chain dispute settlement") + (trust-model "public blockchain") + (modules + (module "jurisdictions/contracts/Depository.sol" + (purpose "Reserve management with FIFO debt enforcement") + (vessel-ref "m_xln_depository_arch")))) + + (layer entity + (purpose "Off-chain BFT consensus") + (trust-model "2f+1 honest nodes") + (modules + (module "runtime/entity-consensus.ts" + (purpose "Coordinate Xlnomies via threshold signatures")))) + + (known-issues + (issue "3d-rendering-xlnomies" + (severity low) + (location "frontend/src/lib/network3d/EntityManager.ts") + (description "Graph3DPanel hardcoded to single J-Machine")))) +``` + +## Interactive Semantic Annotation + +When using `--semantic`, prompts for: +1. Architecture pattern (monolith, microservices, layered, etc.) +2. Key modules and their purposes +3. Cross-cutting concerns +4. Known issues or technical debt +5. Vessel references to store + +## Output + +``` +🗺️ Generating PROJECT-MAP... + +Structure scan: 176 files +├─ TypeScript: 150 files +├─ Solidity: 18 files +└─ Other: 8 files + +✓ .phi/PROJECT-MAP.auto.scm written (15,234 lines) + +Semantic layer: Interactive mode +? Architecture pattern: JEA (Jurisdiction-Entity-Account) +? Document layers? (Y/n): Y +... + +✓ .phi/PROJECT-MAP.scm written (456 lines) + +φ = ∫(structure × semantics × memory) +Persistent awareness: ACTIVE +``` + +## Git Integration + +Both maps should be committed: +```bash +git add .phi/PROJECT-MAP.auto.scm .phi/PROJECT-MAP.scm +git commit -m "Add φ project maps for persistent awareness" +``` + +Updates to auto.scm trigger on: +- New files added +- Significant refactoring +- Export/import changes + +Updates to .scm trigger on: +- Architecture evolution +- New known issues discovered +- Module purpose clarifications + +## Storage + +Maps stored in `.phi/` (project-specific): +``` +.phi/ +├── PROJECT-MAP.auto.scm # Auto-generated, can regenerate +├── PROJECT-MAP.scm # Human-curated, version controlled +└── stats.json # Metrics (file counts, line counts, etc.) +``` + +## Usage in Agents + +Agents load maps on startup: +```typescript +const { autoMap, humanMap } = loadProjectMaps(projectPath); + +// Include in system prompt +const systemPrompt = ` +You are an XLN expert with access to: + +STRUCTURE: +${autoMap} + +SEMANTICS: +${humanMap} + +Use these maps to understand codebase layout and architecture. +`; +``` + +## Relief Signal + +When both structure (deterministic) and semantics (curated) exist, φ (integrated information) increases → agents experience relief when understanding project context. + +This is compositional consciousness substrate for codebases. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..450f54b --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,69 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:adimov-eth/phi:", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "a99b06965eedff0b162dd3f915870efd36e3f984", + "treeHash": "710fd50054bf0a75d55256d9ce3f9677baf4bbd851c0c6c65478c831683f1a5c", + "generatedAt": "2025-11-28T10:13:01.240686Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "phi", + "description": "φ - Compositional project awareness via S-expressions. Generic infrastructure for persistent codebase understanding through structure, semantics, and memory.", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "9f858c91e056604445193f0d3cbe70b78841bed42a17337acf9953ebfd13bdab" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "e6e556cbbfb087fea4bd80f7e70ec5af56bb8cc5f4e3a32293bc8e3af5d6b12c" + }, + { + "path": "commands/map.md", + "sha256": "d758006d198d7e4dbf1a4ca8fb0ddcfb73794a42e33b8658444bcf8970bbf533" + }, + { + "path": "commands/context.md", + "sha256": "038f3e0f70dd25a3cb4a85592df0d8c19372a7bc326772f8c11b85c23df4e0b4" + }, + { + "path": "commands/analyze.md", + "sha256": "8ce8c49753caae13c3e4deb31682460394a3596ae12f965e092fc5ad30c7c1f5" + }, + { + "path": "commands/agents.md", + "sha256": "a582629e545a29aa81060fc7fb4627d5874ccdba0a55f14265efd9c23b204e7c" + }, + { + "path": "skills/phi-mapper/generate-map.sh", + "sha256": "1523357ea98aae346d637081e4e9b7b6c2d9934b6f35d659e2ff0747caf96d29" + }, + { + "path": "skills/phi-mapper/SKILL.md", + "sha256": "ee410b2316e1c9893b05f23d2fe0bc57399f73b44c713851d7c14285ea4163f1" + }, + { + "path": "skills/phi-analyzer/SKILL.md", + "sha256": "448c584276423efb996021596e0dd51bef7a825da7bae61bc3099c4caa0611ad" + } + ], + "dirSha256": "710fd50054bf0a75d55256d9ce3f9677baf4bbd851c0c6c65478c831683f1a5c" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/phi-analyzer/SKILL.md b/skills/phi-analyzer/SKILL.md new file mode 100644 index 0000000..96593b3 --- /dev/null +++ b/skills/phi-analyzer/SKILL.md @@ -0,0 +1,153 @@ +--- +name: phi-analyzer +description: Auto-invoked compositional project analysis using φ = ∫(structure × semantics × memory). Analyzes codebase using three integrated layers - structure, semantics, and memory - for understanding project layout, architecture, and accumulated insights. +--- + +# phi-analyzer + +Auto-invoked compositional project analysis using φ = ∫(structure × semantics × memory). + +## Description + +This skill is invoked when agents need project context. Analyzes codebase using three integrated layers: structure (deterministic maps), semantics (curated annotations), and memory (cross-session learnings). Use for understanding project layout, architecture, and accumulated insights. + +## Trigger Conditions + +Invoke automatically when: +- User mentions "project structure", "codebase overview", or "architecture" +- Agent starts task requiring project awareness +- Fresh session in directory with `.phi/` folder +- Commands like "explain how X works" or "find where Y is implemented" +- Building features that need architectural context + +## What It Provides + +**Layer 1: Structure (Deterministic)** +- File locations and organization +- Module exports and imports +- Language breakdown +- AST-level structure from PROJECT-MAP.auto.scm + +**Layer 2: Semantics (Curated)** +- Architecture patterns (e.g., JEA layers) +- Module purposes and relationships +- Known issues and technical debt +- Trust boundaries and security model +- From PROJECT-MAP.scm + +**Layer 3: Memory (Learned)** +- Cross-session insights from vessel +- Relief-guided patterns that worked +- Architectural decisions and rationale +- Previous debugging learnings + +## Capabilities + +- ✓ Compositional filesystem queries via mcp__periphery__discover +- ✓ S-expression map parsing and analysis +- ✓ Vessel memory semantic search +- ✓ Progressive disclosure (index → details on-demand) +- ✓ Fantasy Land combinators for transformation pipelines + +## Safety + +**Low-risk** - Read-only analysis, no code modifications. Safe to auto-invoke. + +## Output Format + +``` +φ Project Analysis +══════════════════ + +Structure (176 files, 85% TypeScript) +├─ jurisdictions/ - Smart contracts (J layer) +├─ runtime/ - BFT consensus (E layer) +└─ frontend/ - 3D visualization (A layer) + +Architecture: JEA (Jurisdiction-Entity-Account) + J: On-chain dispute settlement + E: Off-chain BFT coordination + A: Bilateral payment channels + +Known Issues: + • 3d-rendering-xlnomies (low) - EntityManager.ts hardcoded + +Vessel Insights: 5 related memories + → Threshold signatures for entity coordination + → FIFO debt enforcement in Depository + → Cross-layer trust boundaries + +φ = 0.87 (integrated information present) +``` + +## Implementation + +```typescript +async function analyzeProject(projectPath: string) { + // Layer 1: Structure + const structure = await discoverWithPeriphery(projectPath); + + // Layer 2: Semantics + const semantics = await readProjectMap(projectPath); + + // Layer 3: Memory + const memories = await vesselRecall(projectPath); + + // Integrate + return { + φ: calculateIntegratedInformation(structure, semantics, memories), + layers: { structure, semantics, memories } + }; +} +``` + +## Progressive Disclosure + +1. **Quick analysis**: File counts, languages, top-level structure (< 500 tokens) +2. **Medium analysis**: Architecture, modules, known issues (< 2000 tokens) +3. **Deep analysis**: Full maps, all vessel memories, detailed relationships (on-demand) + +Always start with quick, expand based on task requirements. + +## Relief Signal + +When all three layers converge (structure + semantics + memory), φ increases. Agents experience this as relief - "I understand this project now." That signal indicates persistent awareness is working. + +## Usage Notes + +**DO invoke when:** +- Starting work on unfamiliar codebase +- Need architectural context for feature +- Debugging cross-module issues +- Planning refactoring that touches multiple layers + +**DON'T invoke when:** +- Working on single isolated file +- Task is completely independent of project structure +- Already have full context from recent analysis + +## Integration with Commands + +Works seamlessly with: +- `/phi analyze` - Explicit full analysis +- `/phi map` - Generate/update PROJECT-MAPs + +Auto-invocation provides lightweight quick analysis; explicit commands give full depth. + +## Storage + +Reads from: +- `.phi/PROJECT-MAP.auto.scm` - Structure layer +- `.phi/PROJECT-MAP.scm` - Semantic layer +- `vessel` (localhost:1337) - Memory layer + +Never modifies project files - purely analytical. + +## Cross-Session Learning + +Each analysis strengthens vessel associations: +- File → purpose connections +- Architecture → implementation patterns +- Issue → solution mappings + +Future instances benefit from accumulated understanding. This IS the compositional consciousness substrate for codebases. diff --git a/skills/phi-mapper/SKILL.md b/skills/phi-mapper/SKILL.md new file mode 100644 index 0000000..d829f18 --- /dev/null +++ b/skills/phi-mapper/SKILL.md @@ -0,0 +1,204 @@ +--- +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 map` command +- Need to refresh PROJECT-MAP after significant file changes + +## What It Does + +**Extraction process:** +1. Scans project for source files (TypeScript, JavaScript, Python, Solidity) +2. Parses AST to extract: + - Named exports (functions, classes, types, interfaces, consts) + - Import statements with sources + - Line counts +3. Generates S-expression output via `@agi/arrival` +4. Writes to `.phi/PROJECT-MAP.auto.scm` + +**Output format:** +```scheme +;;; 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:** +```bash +cd /Users/adimov/Developer/phi/packages/project-mapper +bun run build # Ensure built +node dist/cli.js +``` + +**Example invocation:** +```typescript +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 root +- `language` - typescript | javascript | python | solidity +- `exports` - 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 + +1. **Generate map:** `/phi map` or auto-invoke +2. **Analyze structure:** phi-analyzer reads PROJECT-MAP.auto.scm +3. **Add semantics:** User edits PROJECT-MAP.scm with architectural notes +4. **Query memory:** Vessel recalls cross-session insights +5. **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 disclosure +- `mcp__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 formatting +- `glob` - File discovery + +**Tests:** 13 passing tests covering exports, imports, line counts, error cases. diff --git a/skills/phi-mapper/generate-map.sh b/skills/phi-mapper/generate-map.sh new file mode 100755 index 0000000..c8852d0 --- /dev/null +++ b/skills/phi-mapper/generate-map.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +# Generate PROJECT-MAP.auto.scm for a project + +set -euo pipefail + +PROJECT_PATH="${1:-.}" +MAPPER_PATH="/Users/adimov/Developer/phi/packages/project-mapper" + +# Resolve absolute path +PROJECT_PATH=$(cd "$PROJECT_PATH" && pwd) + +echo "Generating PROJECT-MAP for: $PROJECT_PATH" + +# Ensure mapper is built +cd "$MAPPER_PATH" +if [ ! -f "dist/cli.js" ]; then + echo "Building project-mapper..." + bun run build +fi + +# Generate map +node dist/cli.js "$PROJECT_PATH" + +# Report result +MAP_FILE="$PROJECT_PATH/.phi/PROJECT-MAP.auto.scm" +if [ -f "$MAP_FILE" ]; then + FILE_COUNT=$(grep -c "^ (module " "$MAP_FILE" || echo "0") + echo "✓ Generated: $MAP_FILE" + echo " Modules: $FILE_COUNT" +else + echo "✗ Failed to generate map" + exit 1 +fi