ec33ac1936
Based on claude-code-tools TmuxCLIController, this refactor: - Added DockerTmuxController class for robust tmux session management - Implements send_keys() with configurable delay_enter - Implements capture_pane() for output retrieval - Implements wait_for_prompt() for pattern-based completion detection - Implements wait_for_idle() for content-hash-based idle detection - Implements wait_for_shell_prompt() for shell prompt detection Also includes workflow improvements: - Pre-task git snapshot before agent execution - Post-task commit protocol in agent guidelines Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
492 lines
12 KiB
Markdown
492 lines
12 KiB
Markdown
# Luzia Skill & Documentation Tracking System - Index
|
|
|
|
**Version:** 1.0
|
|
**Status:** ✅ Complete
|
|
**Date:** 2026-01-09
|
|
|
|
## 📚 Documentation Structure
|
|
|
|
### Quick Start (5 minutes)
|
|
1. **DELIVERABLES-SUMMARY.md** - Overview of what was built
|
|
- Executive summary
|
|
- 5 key deliverables
|
|
- Usage metrics & findings
|
|
- Current system status
|
|
|
|
### Implementation Details (20 minutes)
|
|
2. **SKILL-TRACKING-IMPLEMENTATION-GUIDE.md** - How-to guide
|
|
- Architecture and components
|
|
- Current implementation status
|
|
- Usage examples
|
|
- Troubleshooting tips
|
|
- Extension guide
|
|
|
|
### Complete Technical Reference (60 minutes)
|
|
3. **SKILL-AND-DOCS-TRACKING.md** - Comprehensive documentation
|
|
- Full architecture explanation
|
|
- All tracking mechanisms
|
|
- Storage locations
|
|
- Integration points
|
|
- Best practices
|
|
- Future enhancements
|
|
|
|
---
|
|
|
|
## 🛠️ Tools & Deliverables
|
|
|
|
### 1. Analysis Tool
|
|
**File:** `lib/skill_usage_analyzer.py`
|
|
|
|
**Purpose:** Generate reports on skill and documentation usage
|
|
|
|
**Usage:**
|
|
```bash
|
|
# Print summary
|
|
python3 lib/skill_usage_analyzer.py
|
|
|
|
# JSON output
|
|
python3 lib/skill_usage_analyzer.py json
|
|
|
|
# Save report
|
|
python3 lib/skill_usage_analyzer.py save FILE.json
|
|
```
|
|
|
|
**Methods:**
|
|
- `analyze_queue_entries()` - Analyze pending queue
|
|
- `analyze_job_metadata(hours)` - Analyze execution history
|
|
- `detect_skills_in_tasks()` - Detect skills from prompts
|
|
- `analyze_documentation_usage()` - Track doc files
|
|
- `generate_report()` - Complete report
|
|
- `print_summary()` - Console output
|
|
|
|
---
|
|
|
|
### 2. JSON Report
|
|
**File:** `skill-usage-report.json`
|
|
|
|
**Content:**
|
|
- Queue analysis (pending tasks, skills found)
|
|
- Job analysis (93 jobs, 36 debug tasks)
|
|
- Skill detection (keyword-based)
|
|
- Documentation usage (4 files tracked)
|
|
- Project distribution (5 active projects)
|
|
|
|
**Update:**
|
|
```bash
|
|
python3 lib/skill_usage_analyzer.py save skill-usage-report.json
|
|
```
|
|
|
|
---
|
|
|
|
### 3. Interactive Dashboard
|
|
**File:** `skill-usage-dashboard.html`
|
|
|
|
**Features:**
|
|
- 6 key statistics cards
|
|
- Visual charts (projects, priorities)
|
|
- Skill list with counts
|
|
- Documentation file listing
|
|
- Usage insights and patterns
|
|
- Responsive design
|
|
|
|
**Access:**
|
|
```bash
|
|
# Open in browser
|
|
open skill-usage-dashboard.html
|
|
|
|
# Or serve locally
|
|
python3 -m http.server 8000
|
|
# Visit: http://localhost:8000/skill-usage-dashboard.html
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Key Metrics
|
|
|
|
### Current Status (24-hour window)
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| Total Jobs | 93 |
|
|
| Claude Dev Tasks | 36 (38.7%) |
|
|
| Active Projects | 5 |
|
|
| Pending Queue Tasks | 0 |
|
|
| Unique Skills | 0 (dynamic) |
|
|
| Doc Files | 4 |
|
|
|
|
### Project Distribution
|
|
|
|
```
|
|
Admin 36 jobs (38.7%)
|
|
Musica 32 jobs (34.4%)
|
|
LibreChat 11 jobs (11.8%)
|
|
Luzia 8 jobs (8.6%)
|
|
DSS 6 jobs (6.5%)
|
|
```
|
|
|
|
### Skill Detection Keywords
|
|
|
|
**20+ Keywords Detected:**
|
|
- Claude skills: `skill`, `plugin`, `command`
|
|
- MCP: `mcp`, `mcp server`, `mcp config`
|
|
- Agents: `agent`, `agent framework`
|
|
- Tools: `tool`, `tool specification`, `integration`
|
|
- Config: `.claude`, `slash command`, `skill file`
|
|
- API: `anthropic`, `claude-code`
|
|
|
|
---
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
### Task Flow with Skill Tracking
|
|
|
|
```
|
|
User Input
|
|
↓
|
|
is_claude_dev_task() - Keyword Analysis
|
|
↓
|
|
Queue Controller enqueue()
|
|
├─ Stores: skill_match (optional)
|
|
├─ Priority: 1-3 (high) or 4-10 (normal)
|
|
└─ Location: /var/lib/luzia/queue/pending/
|
|
↓
|
|
Queue Daemon dispatch()
|
|
├─ Reads: skill_match from queue entry
|
|
├─ Creates: Conductor directory
|
|
└─ Writes: meta.json with skill field
|
|
↓
|
|
Agent Execution
|
|
├─ Reads: meta.json
|
|
├─ Uses: Skill in prompt context
|
|
└─ Updates: heartbeat, progress, dialogue
|
|
↓
|
|
KG Sync
|
|
├─ Persists: Task metadata to KG
|
|
├─ Location: /etc/luz-knowledge/projects.db
|
|
└─ Access: Via `luzia docs` command
|
|
```
|
|
|
|
### Components Involved
|
|
|
|
| Component | Location | Role |
|
|
|-----------|----------|------|
|
|
| **Dispatcher** | `/opt/server-agents/orchestrator/bin/luzia` | Skill detection |
|
|
| **Queue Controller** | `lib/queue_controller.py` | Skill tracking |
|
|
| **Docker Bridge** | `lib/docker_bridge.py` | Container mgmt |
|
|
| **Knowledge Graph** | `lib/knowledge_graph.py` | Persistence |
|
|
| **Analyzer** | `lib/skill_usage_analyzer.py` | Analysis |
|
|
|
|
---
|
|
|
|
## 📁 File Locations
|
|
|
|
### Documentation
|
|
```
|
|
/opt/server-agents/orchestrator/
|
|
├── README.md [Quick reference]
|
|
├── IMPLEMENTATION-SUMMARY.md [Technical overview]
|
|
├── STRUCTURAL-ANALYSIS.md [Code structure]
|
|
├── SKILL-AND-DOCS-TRACKING.md [Complete guide]
|
|
├── SKILL-TRACKING-IMPLEMENTATION-GUIDE.md [How-to guide]
|
|
├── SKILL-TRACKING-INDEX.md [This file]
|
|
└── DELIVERABLES-SUMMARY.md [Project summary]
|
|
```
|
|
|
|
### Tools
|
|
```
|
|
/opt/server-agents/orchestrator/
|
|
├── lib/
|
|
│ ├── skill_usage_analyzer.py [Analysis tool]
|
|
│ ├── queue_controller.py [Queue mgmt]
|
|
│ ├── knowledge_graph.py [KG storage]
|
|
│ └── docker_bridge.py [Container mgmt]
|
|
├── bin/
|
|
│ └── luzia [Main dispatcher]
|
|
└── config.json [Configuration]
|
|
```
|
|
|
|
### Data/Reports
|
|
```
|
|
/opt/server-agents/orchestrator/
|
|
├── skill-usage-report.json [JSON report]
|
|
├── skill-usage-dashboard.html [Web dashboard]
|
|
└── structure-analysis-*.json [Analysis data]
|
|
```
|
|
|
|
### State
|
|
```
|
|
/var/lib/luzia/queue/
|
|
├── pending/
|
|
│ ├── high/ [High priority tasks]
|
|
│ └── normal/ [Normal priority tasks]
|
|
└── capacity.json [System capacity]
|
|
|
|
/var/log/luz-orchestrator/jobs/
|
|
└── {job_id}/
|
|
├── meta.json [Job metadata with skill]
|
|
├── heartbeat.json [Last heartbeat]
|
|
├── progress.md [Progress tracking]
|
|
└── dialogue/ [Agent dialogue]
|
|
|
|
/etc/luz-knowledge/
|
|
├── sysadmin.db [System admin docs]
|
|
├── users.db [User management]
|
|
├── projects.db [Project docs]
|
|
└── research.db [Research data]
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start Commands
|
|
|
|
### Generate Reports
|
|
```bash
|
|
# Console summary
|
|
cd /opt/server-agents/orchestrator
|
|
python3 lib/skill_usage_analyzer.py
|
|
|
|
# JSON report
|
|
python3 lib/skill_usage_analyzer.py save skill-usage-report.json
|
|
|
|
# JSON output (pipe)
|
|
python3 lib/skill_usage_analyzer.py json | jq '.job_analysis'
|
|
```
|
|
|
|
### View Dashboard
|
|
```bash
|
|
# Open in browser (from terminal)
|
|
open /opt/server-agents/orchestrator/skill-usage-dashboard.html
|
|
|
|
# Or serve locally
|
|
cd /opt/server-agents/orchestrator
|
|
python3 -m http.server 8000
|
|
# Visit: http://localhost:8000/skill-usage-dashboard.html
|
|
```
|
|
|
|
### Query Knowledge Graph
|
|
```bash
|
|
# Search for skills
|
|
luzia docs skill
|
|
|
|
# Show specific entity
|
|
luzia docs --show "Skill Detection System"
|
|
|
|
# Get statistics
|
|
luzia docs --stats
|
|
|
|
# Sync documentation
|
|
luzia docs --sync
|
|
```
|
|
|
|
### Monitor System
|
|
```bash
|
|
# Check queue status
|
|
luzia jobs
|
|
|
|
# View maintenance status
|
|
luzia maintenance
|
|
|
|
# List recent jobs
|
|
ls -lt /var/log/luz-orchestrator/jobs/ | head -20
|
|
|
|
# View job metadata
|
|
cat /var/log/luz-orchestrator/jobs/*/meta.json | jq '.debug'
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 What Gets Tracked
|
|
|
|
### At Queue Level
|
|
- Task ID, project, prompt, priority
|
|
- **skill_match** (optional, for future explicit routing)
|
|
- Enqueued timestamp and user
|
|
- Status (pending → dispatched)
|
|
|
|
### At Conductor Level
|
|
- Task metadata with **skill** field
|
|
- Started timestamp, execution status
|
|
- Priority level and dispatcher info
|
|
- Zen continuation ID (for multi-turn)
|
|
|
|
### In Job Logs
|
|
- Full metadata from conductor
|
|
- Task description (first 100 chars)
|
|
- **debug** flag (indicates Claude dev task)
|
|
- Status: running, completed, failed
|
|
|
|
### In Knowledge Graph
|
|
- Task ID, project, prompt, status
|
|
- **skill** field (persisted)
|
|
- Timestamp information
|
|
- Domain: projects (searchable)
|
|
|
|
---
|
|
|
|
## 📊 Analysis Capabilities
|
|
|
|
### Available Analyses
|
|
|
|
1. **Queue Analysis**
|
|
- Pending task count (high vs normal)
|
|
- Skills in queue entries
|
|
- By-project distribution
|
|
- Priority breakdown
|
|
|
|
2. **Job History Analysis**
|
|
- Total jobs executed
|
|
- Debug mode task count
|
|
- Skills used
|
|
- By-project breakdown
|
|
- Time window filtering (default 24h)
|
|
|
|
3. **Skill Detection**
|
|
- Keyword-based detection from prompts
|
|
- Pattern matching (20+ keywords)
|
|
- Detected by task category
|
|
- By project
|
|
|
|
4. **Documentation Analysis**
|
|
- Available doc files
|
|
- File sizes and dates
|
|
- Reference patterns
|
|
- Sync status
|
|
|
|
5. **Statistics & Distribution**
|
|
- Skill usage percentage
|
|
- Project distribution
|
|
- Time-based metrics
|
|
- Correlation analysis
|
|
|
|
---
|
|
|
|
## 🔗 Integration Points
|
|
|
|
### MCP Servers
|
|
- **Zen MCP** - Deep reasoning, code review
|
|
- **Sarlo-Admin MCP** - System administration
|
|
|
|
### Knowledge Graph Domains
|
|
- **sysadmin** - System procedures
|
|
- **users** - User management
|
|
- **projects** - Project info
|
|
- **research** - Research data
|
|
|
|
### Storage Systems
|
|
- **Queue** - `/var/lib/luzia/queue/pending/`
|
|
- **Conductor** - `/home/{project}/conductor/active/`
|
|
- **Job Logs** - `/var/log/luz-orchestrator/jobs/`
|
|
- **KG Databases** - `/etc/luz-knowledge/`
|
|
|
|
---
|
|
|
|
## 🔍 Troubleshooting
|
|
|
|
### "Analyzer shows 0 skills in queue"
|
|
**Reason:** skill_match parameter is optional
|
|
**Solution:** Skills detected via debug flag in jobs (36 out of 93)
|
|
|
|
### "Documentation not in KG"
|
|
**Reason:** Sync not run
|
|
**Solution:** Run `luzia docs --sync`
|
|
|
|
### "No JSON report generated"
|
|
**Reason:** Analyzer not run
|
|
**Solution:** Run `python3 lib/skill_usage_analyzer.py save FILE.json`
|
|
|
|
### "Dashboard not loading"
|
|
**Reason:** Report missing or path wrong
|
|
**Solution:** Generate report first, ensure it's in same directory
|
|
|
|
---
|
|
|
|
## 📈 Future Enhancements
|
|
|
|
### Proposed Features
|
|
1. **Real-time Dashboard** - WebSocket live updates
|
|
2. **Skill Performance Metrics** - Success rate per skill
|
|
3. **Auto-skill Suggestion** - ML-based prediction
|
|
4. **Documentation Correlation** - Link skills to docs
|
|
5. **Skill Profiling** - Identify underutilized skills
|
|
|
|
### Expansion Areas
|
|
- Extend keyword list as new skills added
|
|
- Add ML-based skill classification
|
|
- Implement skill performance dashboard
|
|
- Create skill recommendation engine
|
|
- Build documentation coverage reports
|
|
|
|
---
|
|
|
|
## 📞 Usage Support
|
|
|
|
### For Questions About:
|
|
|
|
**Architecture & Design**
|
|
→ See: `SKILL-AND-DOCS-TRACKING.md` (Section 1-4)
|
|
|
|
**How to Use Tools**
|
|
→ See: `SKILL-TRACKING-IMPLEMENTATION-GUIDE.md` (Section 9)
|
|
|
|
**Current Status & Metrics**
|
|
→ See: `DELIVERABLES-SUMMARY.md` (Metrics section)
|
|
|
|
**Implementation Details**
|
|
→ See: `SKILL-TRACKING-IMPLEMENTATION-GUIDE.md` (Section 2-3)
|
|
|
|
**Troubleshooting**
|
|
→ See: `SKILL-TRACKING-IMPLEMENTATION-GUIDE.md` (Section 10)
|
|
|
|
---
|
|
|
|
## ✅ Completion Checklist
|
|
|
|
- [x] Skill detection system documented
|
|
- [x] Documentation tracking explained
|
|
- [x] Queue-level tracking implemented
|
|
- [x] Conductor-level tracking verified
|
|
- [x] Knowledge graph integration complete
|
|
- [x] Analysis tool created
|
|
- [x] JSON report generated
|
|
- [x] Dashboard built
|
|
- [x] All documentation written
|
|
- [x] Facts stored in shared KG
|
|
- [x] Examples provided
|
|
- [x] Troubleshooting guide included
|
|
|
|
---
|
|
|
|
## 📚 Document Summary
|
|
|
|
| Document | Purpose | Read Time | Audience |
|
|
|----------|---------|-----------|----------|
|
|
| DELIVERABLES-SUMMARY.md | Quick overview | 5 min | Everyone |
|
|
| SKILL-TRACKING-IMPLEMENTATION-GUIDE.md | How to use | 15 min | Users |
|
|
| SKILL-AND-DOCS-TRACKING.md | Full reference | 45 min | Developers |
|
|
| SKILL-TRACKING-INDEX.md | Navigation | 10 min | Everyone |
|
|
|
|
---
|
|
|
|
## 🎉 Project Completion
|
|
|
|
**Status:** ✅ COMPLETE AND OPERATIONAL
|
|
|
|
**Deliverables:** 6 documents + 1 analysis tool + 1 dashboard
|
|
**Knowledge Graph Facts:** 5 stored relationships
|
|
**Test Data:** 93 real jobs analyzed
|
|
**Documentation:** ~40KB across 6 files
|
|
**Code:** ~500 lines (skill_usage_analyzer.py)
|
|
|
|
The Luzia Skill & Documentation Tracking System is ready for:
|
|
- Immediate use in production
|
|
- Further development and enhancement
|
|
- Integration with other Luzia components
|
|
- Extension with new features
|
|
|
|
---
|
|
|
|
**Created:** 2026-01-09
|
|
**Version:** 1.0
|
|
**Status:** Production Ready ✅
|
|
**Maintained By:** Luzia Documentation System
|