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>
2026-01-14 10:42:16 -03:00
commit ec33ac1936
265 changed files with 92011 additions and 0 deletions
--- a/AGENT-AUTONOMY-INDEX.md
+++ b/AGENT-AUTONOMY-INDEX.md
@@ -0,0 +1,551 @@
+# Agent Autonomy Research - Complete Index
+## Navigation Guide to Research Documents
+
+**Research Date:** 2026-01-09
+**Status:** ✅ Complete & Ready for Adoption
+**Total Documentation:** 2,565 lines across 4 documents
+
+---
+
+## 📚 Document Overview
+
+### Quick Navigation by Use Case
+
+**I want to...**
+
+- **Understand how Luzia prevents blocking** → Read `AGENT-AUTONOMY-RESEARCH.md` Section 1
+- **Learn the 5 core patterns** → Read `AGENT-CLI-PATTERNS.md` "Quick Reference"
+- **Design an autonomous agent prompt** → Read `AGENT-CLI-PATTERNS.md` "Prompt Patterns"
+- **See copy-paste ready templates** → Read `AUTONOMOUS-AGENT-TEMPLATES.md`
+- **Troubleshoot a blocking agent** → Read `AGENT-AUTONOMY-RESEARCH.md` Section 11
+- **Get executive summary** → Read `RESEARCH-SUMMARY.md`
+- **Find code examples** → Read `AUTONOMOUS-AGENT-TEMPLATES.md` (6 templates)
+
+---
+
+## 📖 Document Descriptions
+
+### 1. AGENT-AUTONOMY-RESEARCH.md (881 lines)
+**Comprehensive Technical Research**
+
+The foundational research document covering all aspects of agent autonomy.
+
+**Sections:**
+1. **How Luzia Prevents Agent Blocking** (lines 35-165)
+   - Core pattern: detached spawning
+   - Permission bypass strategy
+   - Full agent spawn flow
+   - Why it's safe
+
+2. **Handling Clarification Without Blocking** (lines 167-265)
+   - AskUserQuestion problem
+   - Solutions: context-first design, structured tasks, async fallback
+   - Why AskUserQuestion fails for async agents
+
+3. **Job State Machine and Exit Codes** (lines 267-333)
+   - Job lifecycle states
+   - Exit code capturing
+   - Status determination
+
+4. **Handling Approval Prompts** (lines 335-387)
+   - How approval prompts work
+   - Prevention mechanism (3 layers)
+   - Safe execution model
+
+5. **Async Communication Patterns** (lines 389-476)
+   - File-based job queue
+   - Notification log pattern
+   - Job directory as IPC channel
+   - Example: monitoring job completion
+
+6. **Prompt Patterns for Autonomy** (lines 478-575)
+   - Ideal autonomous prompt structure
+   - Good vs bad prompt examples
+   - Prompt template used in Luzia
+
+7. **Pattern Summary** (lines 577-665)
+   - Five patterns overview
+   - Interactive vs autonomous comparison
+   - When to use each pattern
+
+8. **Real Implementation Examples** (lines 667-753)
+   - Running tests autonomously
+   - Code analysis autonomously
+
+9. **Best Practices** (lines 755-829)
+   - Prompt design guidelines
+   - Environment setup
+   - Failure recovery
+
+10. **Advanced Patterns** (lines 831-887)
+    - Multi-phase tasks
+    - Knowledge graph integration
+    - Cross-agent coordination
+
+11. **Failure Cases and Solutions** (lines 889-929)
+    - Common blocking issues with solutions
+    - Debugging techniques
+
+12. **Conclusion** (lines 931-976)
+    - Core principle
+    - Implementation checklist
+    - When blocks still occur
+
+**Use this document for:** Understanding the "why" behind patterns, deep technical knowledge, debugging complex issues
+
+---
+
+### 2. AGENT-CLI-PATTERNS.md (629 lines)
+**Practical Pattern Guide**
+
+Hands-on guide with patterns, anti-patterns, and examples.
+
+**Contents:**
+1. **Quick Reference: 5 Critical Patterns** (lines 1-75)
+   - Detached spawning (with code)
+   - Permission bypass (with code)
+   - File-based I/O (with code)
+   - Exit code signaling (with code)
+   - Context-first prompts (with code)
+
+2. **Prompt Patterns for Autonomy** (lines 77-310)
+   - Pattern 1: Analysis Task (read-only)
+   - Pattern 2: Execution Task (run & report)
+   - Pattern 3: Implementation Task (read + modify)
+   - Pattern 4: Multi-Phase Task (sequential)
+   - Pattern 5: Decision Task (branch logic)
+   - Each with complete example
+
+3. **Anti-Patterns: What NOT to Do** (lines 312-436)
+   - ❌ Anti-Pattern 1: Ambiguous tasks (with fix)
+   - ❌ Anti-Pattern 2: Vague success criteria (with fix)
+   - ❌ Anti-Pattern 3: Implicit constraints (with fix)
+   - ❌ Anti-Pattern 4: Interactive questions (with fix)
+   - ❌ Anti-Pattern 5: Requiring approval (with fix)
+
+4. **Handling Edge Cases** (lines 438-488)
+   - File not found
+   - Ambiguous state
+   - Partial success
+
+5. **Prompt Template** (lines 490-522)
+   - Complete template with all sections
+
+6. **Real-World Examples** (lines 524-629)
+   - Code quality scan
+   - Database migration
+   - Deployment check
+
+**Use this document for:** Writing prompts, designing agents, avoiding common mistakes
+
+---
+
+### 3. AUTONOMOUS-AGENT-TEMPLATES.md (666 lines)
+**Production-Ready Code Templates**
+
+Six complete, copy-paste ready agent templates.
+
+**Templates:**
+
+1. **Simple Task Agent** (lines 1-78)
+   - Use case: Read-only analysis
+   - Prompt template (complete)
+   - Expected output (JSON example)
+   - Lines: 78
+
+2. **Test Execution Agent** (lines 80-157)
+   - Use case: Run tests & report
+   - Prompt template (complete)
+   - Expected output (JSON example)
+   - Lines: 77
+
+3. **Code Modification Agent** (lines 159-253)
+   - Use case: Modify code & verify
+   - Prompt template (complete with constraints)
+   - Expected output files (3 examples)
+   - Lines: 94
+
+4. **Multi-Step Workflow Agent** (lines 255-353)
+   - Use case: Multi-phase orchestration
+   - Prompt template (6 phases)
+   - Expected output (JSON example)
+   - Lines: 98
+
+5. **Diagnostic Agent** (lines 355-459)
+   - Use case: Troubleshoot issues
+   - Prompt template (6 investigation steps)
+   - Expected output (comprehensive JSON)
+   - Lines: 104
+
+6. **Integration Test Agent** (lines 461-566)
+   - Use case: Validate multiple components
+   - Prompt template (6 test suites)
+   - Expected output (detailed report)
+   - Lines: 105
+
+**Usage Pattern** (lines 568-615)
+- How to spawn agent
+- How to monitor completion
+- How to retrieve results
+
+**Use this document for:** Starting new agents, copy-paste templates, production examples
+
+---
+
+### 4. RESEARCH-SUMMARY.md (389 lines)
+**Executive Summary**
+
+High-level overview for decision makers and quick reference.
+
+**Sections:**
+1. **What Was Researched** (lines 1-23)
+   - 7 research questions
+
+2. **Key Findings** (lines 25-125)
+   - Finding 1: Architecture prevents blocking
+   - Finding 2: Golden rule of autonomy
+   - Finding 3: Five critical patterns
+   - Finding 4: AskUserQuestion problem
+   - Finding 5: Job lifecycle as key
+
+3. **Deliverables Created** (lines 127-165)
+   - 4 documents overview
+
+4. **Implementation Checklist** (lines 167-190)
+   - Using patterns
+   - Creating custom agents
+
+5. **Code References** (lines 192-217)
+   - Key files and functions
+
+6. **Knowledge Graph Integration** (lines 219-232)
+   - What was stored
+   - How to query
+
+7. **Quick Start** (lines 234-260)
+   - For developers
+   - For architects
+   - For troubleshooting
+
+8. **Metrics & Results** (lines 262-283)
+   - Documentation coverage
+   - Research completeness
+   - Knowledge graph entries
+
+9. **Recommendations** (lines 285-308)
+   - For teams
+   - For Claude development
+   - For future research
+
+**Use this document for:** Getting overview, making decisions, finding quick answers
+
+---
+
+## 🎯 Finding What You Need
+
+### By Experience Level
+
+**Beginner:**
+1. Start: `RESEARCH-SUMMARY.md` (get overview)
+2. Read: `AGENT-CLI-PATTERNS.md` - Quick Reference (5 patterns)
+3. Use: `AUTONOMOUS-AGENT-TEMPLATES.md` (pick a template)
+4. Deploy: Your first agent!
+
+**Intermediate:**
+1. Read: `AGENT-AUTONOMY-RESEARCH.md` Sections 1-3 (architecture)
+2. Study: `AGENT-CLI-PATTERNS.md` Prompt Patterns (all 5)
+3. Review: Anti-Patterns section
+4. Adapt: Templates to your needs
+
+**Advanced:**
+1. Deep dive: `AGENT-AUTONOMY-RESEARCH.md` Sections 4-11 (all details)
+2. Design: Custom prompt patterns
+3. Implement: Advanced patterns (Section 10)
+4. Optimize: Failure recovery (Section 11)
+
+---
+
+### By Topic
+
+**Architecture & Design:**
+- `AGENT-AUTONOMY-RESEARCH.md` Sections 1-5
+- `RESEARCH-SUMMARY.md` "Key Findings"
+
+**Prompt Design:**
+- `AGENT-CLI-PATTERNS.md` "Prompt Patterns" section
+- `AGENT-AUTONOMY-RESEARCH.md` Section 6
+
+**Implementation:**
+- `AUTONOMOUS-AGENT-TEMPLATES.md` (all 6 templates)
+- `AGENT-CLI-PATTERNS.md` "Real-World Examples"
+
+**Best Practices:**
+- `AGENT-AUTONOMY-RESEARCH.md` Section 9
+- `AGENT-CLI-PATTERNS.md` Checklist section
+
+**Debugging:**
+- `AGENT-AUTONOMY-RESEARCH.md` Section 11
+- `AGENT-CLI-PATTERNS.md` "Detecting Blocking Questions"
+
+**Edge Cases:**
+- `AGENT-CLI-PATTERNS.md` "Handling Edge Cases"
+- `AGENT-AUTONOMY-RESEARCH.md` Section 11
+
+---
+
+### By Persona
+
+**Prompt Engineer:**
+→ `AGENT-CLI-PATTERNS.md` Sections 2-3
+
+**Software Developer:**
+→ `AUTONOMOUS-AGENT-TEMPLATES.md` + your favorite template
+
+**DevOps Engineer:**
+→ `AGENT-AUTONOMY-RESEARCH.md` Section 5 (async patterns)
+
+**Team Lead:**
+→ `RESEARCH-SUMMARY.md` + decide adoption path
+
+**Security Review:**
+→ `AGENT-AUTONOMY-RESEARCH.md` Section 4 (permissions)
+
+**Troubleshooter:**
+→ `AGENT-AUTONOMY-RESEARCH.md` Section 11 or `AGENT-CLI-PATTERNS.md` debugging
+
+---
+
+## 🔍 Cross-References
+
+### Key Concepts Across Documents
+
+| Concept | RESEARCH | PATTERNS | TEMPLATES | SUMMARY |
+|---------|----------|----------|-----------|---------|
+| Detached spawning | Sec 1 | Quick Ref | Usage | Key Find 1 |
+| Permission bypass | Sec 1, 4 | Quick Ref | All templates | Key Find 1 |
+| File-based IPC | Sec 5 | Quick Ref | Usage | Key Find 1 |
+| Exit code signaling | Sec 3 | Quick Ref | All templates | Key Find 1 |
+| Context-first | Sec 6 | Quick Ref, Patterns | All templates | Key Find 2 |
+| AskUserQuestion issue | Sec 2 | Quick Ref | N/A | Key Find 4 |
+| 5 patterns | Sec 7 | Throughout | N/A | Key Find 3 |
+| Job lifecycle | Sec 3 | Usage | Usage | Key Find 5 |
+| Anti-patterns | Sec 7 | Full section | N/A | Recommendations |
+| Best practices | Sec 9 | Throughout | Throughout | Checklist |
+
+---
+
+## 💾 Knowledge Graph
+
+Research findings stored in shared knowledge graph at:
+`/etc/zen-swarm/memory/projects.db`
+
+**Access via:**
+```bash
+# Search for patterns
+mcp__shared-projects-memory__search_context "autonomous agent"
+
+# Query specific relation
+mcp__shared-projects-memory__query_relations \
+  entity_name="detached-process-execution"
+```
+
+**Stored relations:**
+- 5 core patterns documented
+- 1 anti-pattern documented
+- 2 best practices documented
+- 4 deliverables linked
+- 6 key implementation references
+
+---
+
+## 📊 Statistics
+
+| Metric | Value |
+|--------|-------|
+| **Total Lines** | 2,565 |
+| **Documents** | 4 |
+| **Sections** | 42+ |
+| **Patterns** | 10 (5 good + 5 anti) |
+| **Templates** | 6 |
+| **Code Examples** | 20+ |
+| **Anti-patterns with fixes** | 5 |
+| **Case studies** | 3 |
+| **Best practices** | 9 |
+
+---
+
+## 🚀 Getting Started
+
+### One-Minute Quick Start
+
+```bash
+# 1. Read the quick reference
+head -75 AGENT-CLI-PATTERNS.md
+
+# 2. Pick a template that matches your need
+ls AUTONOMOUS-AGENT-TEMPLATES.md
+
+# 3. Copy the prompt
+grep -A 50 "Template 1:" AUTONOMOUS-AGENT-TEMPLATES.md | head -50
+
+# 4. Use it with Luzia
+luzia myproject "My task description"
+```
+
+### Five-Minute Deep Dive
+
+1. Read: `RESEARCH-SUMMARY.md` (Key Findings section)
+2. Understand: The 5 patterns
+3. Choose: A template that fits
+4. Adapt: To your specific needs
+5. Deploy: Your first agent
+
+### Thirty-Minute Mastery
+
+1. Read: `AGENT-AUTONOMY-RESEARCH.md` Sections 1-3
+2. Study: `AGENT-CLI-PATTERNS.md` All prompt patterns
+3. Review: Anti-patterns section
+4. Design: Your own prompt
+5. Test: With a simple task
+
+---
+
+## ✅ Quality Checklist
+
+Before using a prompt:
+
+- [ ] Task is specific (not "improve" or "fix")
+- [ ] Success criteria defined
+- [ ] Output format specified (JSON, file, etc)
+- [ ] Exit codes documented
+- [ ] Constraints listed (what can't change)
+- [ ] Complete context provided
+- [ ] No ambiguity
+- [ ] No approval requests
+- [ ] No "if you think..." language
+- [ ] Read from `AGENT-CLI-PATTERNS.md` checklist
+
+---
+
+## 📝 Notes for Teams
+
+### For Adoption
+
+1. **Week 1:** Team reads `RESEARCH-SUMMARY.md`
+2. **Week 1:** Prompt engineers read `AGENT-CLI-PATTERNS.md`
+3. **Week 2:** Developers use `AUTONOMOUS-AGENT-TEMPLATES.md`
+4. **Week 3:** Team creates custom agents
+5. **Ongoing:** Share findings via knowledge graph
+
+### For Training
+
+- **30-min session:** Project overview + quick reference
+- **60-min session:** Full patterns + anti-patterns
+- **90-min session:** Design workshop using templates
+- **Workshop:** Build custom agent for your use case
+
+### For Reference
+
+- Keep `RESEARCH-SUMMARY.md` handy (quick answers)
+- Bookmark `AGENT-CLI-PATTERNS.md` (prompt design)
+- Use `AUTONOMOUS-AGENT-TEMPLATES.md` (templates)
+- Deep dive `AGENT-AUTONOMY-RESEARCH.md` as needed
+
+---
+
+## 🔗 Integration Points
+
+**Knowledge Graph:**
+- Store facts about your agents
+- Link to patterns used
+- Query for similar agents
+
+**Luzia CLI:**
+- Use patterns in `spawn_claude_agent()` calls
+- Monitor jobs via job directory
+- Query job status asynchronously
+
+**Team Documentation:**
+- Reference this index
+- Link to specific sections
+- Use templates in runbooks
+
+---
+
+## 📞 Need Help?
+
+**Question Type** → **Document** → **Section**
+
+"How do I prevent agent blocking?" → RESEARCH → Section 1
+"What should I include in a prompt?" → PATTERNS → Prompt Patterns
+"Can you show me a working example?" → TEMPLATES → Pick one
+"Why is my agent asking questions?" → PATTERNS → Anti-Patterns
+"How do I monitor an agent?" → RESEARCH → Section 5
+"What exit codes should I use?" → RESEARCH → Section 3
+"How do I handle failures?" → RESEARCH → Section 11
+"Is this pattern safe?" → RESEARCH → Section 4
+
+---
+
+## 🎓 Learning Path
+
+```
+START HERE
+    ↓
+RESEARCH-SUMMARY.md (Key Findings)
+    ↓
+Choose your path:
+    ├→ "I want to understand"
+    │  → AGENT-AUTONOMY-RESEARCH.md Sections 1-3
+    │
+    ├→ "I want to build an agent"
+    │  → AGENT-CLI-PATTERNS.md Quick Reference
+    │  → AUTONOMOUS-AGENT-TEMPLATES.md (pick template)
+    │
+    └→ "I want to master this"
+       → AGENT-AUTONOMY-RESEARCH.md (all)
+       → AGENT-CLI-PATTERNS.md (all)
+       → AUTONOMOUS-AGENT-TEMPLATES.md (modify templates)
+       → Create custom agents
+```
+
+---
+
+## 📦 Files in This Research
+
+```
+/opt/server-agents/orchestrator/
+├── AGENT-AUTONOMY-RESEARCH.md          # 881 lines, comprehensive research
+├── AGENT-CLI-PATTERNS.md               # 629 lines, practical patterns
+├── AUTONOMOUS-AGENT-TEMPLATES.md       # 666 lines, code templates
+├── RESEARCH-SUMMARY.md                 # 389 lines, executive summary
+└── AGENT-AUTONOMY-INDEX.md             # This file, navigation guide
+```
+
+**Total:** 2,565 lines of production-ready documentation
+
+---
+
+## 🏁 Conclusion
+
+This research provides everything needed to:
+- ✅ Understand how autonomous agents work
+- ✅ Prevent agent blocking
+- ✅ Design effective prompts
+- ✅ Implement agents in production
+- ✅ Troubleshoot issues
+- ✅ Best practices and patterns
+
+**Start with:** This index + `RESEARCH-SUMMARY.md`
+**Go deeper with:** `AGENT-CLI-PATTERNS.md` and `AGENT-AUTONOMY-RESEARCH.md`
+**Implement with:** `AUTONOMOUS-AGENT-TEMPLATES.md`
+
+**Questions?** Check the appropriate document using the "Finding What You Need" section above.
+
+---
+
+**Research Date:** 2026-01-09
+**Status:** ✅ Complete
+**Version:** 1.0
+**Ready for:** Immediate team adoption
+