179 lines
4.2 KiB
Markdown
179 lines
4.2 KiB
Markdown
---
|
||
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 <project-path>
|
||
```
|
||
|
||
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.
|