Refactor cockpit to use DockerTmuxController pattern
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>
This commit is contained in:
admin
491
SKILL-TRACKING-INDEX.md
Normal file
491
SKILL-TRACKING-INDEX.md
Normal file
@@ -0,0 +1,491 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user