Initial commit
This commit is contained in:
Zhongwei Li
84
commands/agents.md
Normal file
84
commands/agents.md
Normal file
@@ -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.
|
||||
100
commands/analyze.md
Normal file
100
commands/analyze.md
Normal file
@@ -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.
|
||||
118
commands/context.md
Normal file
118
commands/context.md
Normal file
@@ -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.
|
||||
178
commands/map.md
Normal file
178
commands/map.md
Normal file
@@ -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 <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.
|
||||
Reference in New Issue
Block a user