Files

admin ec33ac1936 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

15 KiB

Raw Blame History

Agent Autonomy Research - Complete Index

Research Date: 2026-01-09 Status: ✅ Complete & Ready for Adoption Total Documentation: 2,565 lines across 4 documents

📚 Document Overview

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:

How Luzia Prevents Agent Blocking (lines 35-165)
- Core pattern: detached spawning
- Permission bypass strategy
- Full agent spawn flow
- Why it's safe
Handling Clarification Without Blocking (lines 167-265)
- AskUserQuestion problem
- Solutions: context-first design, structured tasks, async fallback
- Why AskUserQuestion fails for async agents
Job State Machine and Exit Codes (lines 267-333)
- Job lifecycle states
- Exit code capturing
- Status determination
Handling Approval Prompts (lines 335-387)
- How approval prompts work
- Prevention mechanism (3 layers)
- Safe execution model
Async Communication Patterns (lines 389-476)
- File-based job queue
- Notification log pattern
- Job directory as IPC channel
- Example: monitoring job completion
Prompt Patterns for Autonomy (lines 478-575)
- Ideal autonomous prompt structure
- Good vs bad prompt examples
- Prompt template used in Luzia
Pattern Summary (lines 577-665)
- Five patterns overview
- Interactive vs autonomous comparison
- When to use each pattern
Real Implementation Examples (lines 667-753)
- Running tests autonomously
- Code analysis autonomously
Best Practices (lines 755-829)
- Prompt design guidelines
- Environment setup
- Failure recovery
Advanced Patterns (lines 831-887)
- Multi-phase tasks
- Knowledge graph integration
- Cross-agent coordination
Failure Cases and Solutions (lines 889-929)
- Common blocking issues with solutions
- Debugging techniques
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:

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)
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
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)
Handling Edge Cases (lines 438-488)
- File not found
- Ambiguous state
- Partial success
Prompt Template (lines 490-522)
- Complete template with all sections
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:

Simple Task Agent (lines 1-78)
- Use case: Read-only analysis
- Prompt template (complete)
- Expected output (JSON example)
- Lines: 78
Test Execution Agent (lines 80-157)
- Use case: Run tests & report
- Prompt template (complete)
- Expected output (JSON example)
- Lines: 77
Code Modification Agent (lines 159-253)
- Use case: Modify code & verify
- Prompt template (complete with constraints)
- Expected output files (3 examples)
- Lines: 94
Multi-Step Workflow Agent (lines 255-353)
- Use case: Multi-phase orchestration
- Prompt template (6 phases)
- Expected output (JSON example)
- Lines: 98
Diagnostic Agent (lines 355-459)
- Use case: Troubleshoot issues
- Prompt template (6 investigation steps)
- Expected output (comprehensive JSON)
- Lines: 104
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:

What Was Researched (lines 1-23)
- 7 research questions
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
Deliverables Created (lines 127-165)
- 4 documents overview
Implementation Checklist (lines 167-190)
- Using patterns
- Creating custom agents
Code References (lines 192-217)
- Key files and functions
Knowledge Graph Integration (lines 219-232)
- What was stored
- How to query
Quick Start (lines 234-260)
- For developers
- For architects
- For troubleshooting
Metrics & Results (lines 262-283)
- Documentation coverage
- Research completeness
- Knowledge graph entries
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:

Start: RESEARCH-SUMMARY.md (get overview)
Read: AGENT-CLI-PATTERNS.md - Quick Reference (5 patterns)
Use: AUTONOMOUS-AGENT-TEMPLATES.md (pick a template)
Deploy: Your first agent!

Intermediate:

Read: AGENT-AUTONOMY-RESEARCH.md Sections 1-3 (architecture)
Study: AGENT-CLI-PATTERNS.md Prompt Patterns (all 5)
Review: Anti-Patterns section
Adapt: Templates to your needs

Advanced:

Deep dive: AGENT-AUTONOMY-RESEARCH.md Sections 4-11 (all details)
Design: Custom prompt patterns
Implement: Advanced patterns (Section 10)
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:

# 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

# 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

Read: RESEARCH-SUMMARY.md (Key Findings section)
Understand: The 5 patterns
Choose: A template that fits
Adapt: To your specific needs
Deploy: Your first agent

Thirty-Minute Mastery

Read: AGENT-AUTONOMY-RESEARCH.md Sections 1-3
Study: AGENT-CLI-PATTERNS.md All prompt patterns
Review: Anti-patterns section
Design: Your own prompt
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

Week 1: Team reads RESEARCH-SUMMARY.md
Week 1: Prompt engineers read AGENT-CLI-PATTERNS.md
Week 2: Developers use AUTONOMOUS-AGENT-TEMPLATES.md
Week 3: Team creates custom agents
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

15 KiB

Raw Blame History

Agent Autonomy Research - Complete Index

Navigation Guide to Research Documents

📚 Document Overview

Quick Navigation by Use Case

📖 Document Descriptions

1. AGENT-AUTONOMY-RESEARCH.md (881 lines)

2. AGENT-CLI-PATTERNS.md (629 lines)

3. AUTONOMOUS-AGENT-TEMPLATES.md (666 lines)

4. RESEARCH-SUMMARY.md (389 lines)

🎯 Finding What You Need

By Experience Level

By Topic

By Persona

🔍 Cross-References

Key Concepts Across Documents

💾 Knowledge Graph

📊 Statistics

🚀 Getting Started

One-Minute Quick Start

Five-Minute Deep Dive

Thirty-Minute Mastery

✅ Quality Checklist

📝 Notes for Teams

For Adoption

For Training

For Reference

🔗 Integration Points

📞 Need Help?

🎓 Learning Path

📦 Files in This Research

🏁 Conclusion

15 KiB Raw Blame History

Agent Autonomy Research - Complete Index

Navigation Guide to Research Documents

📚 Document Overview

Quick Navigation by Use Case

📖 Document Descriptions

1. AGENT-AUTONOMY-RESEARCH.md (881 lines)

2. AGENT-CLI-PATTERNS.md (629 lines)

3. AUTONOMOUS-AGENT-TEMPLATES.md (666 lines)

4. RESEARCH-SUMMARY.md (389 lines)

🎯 Finding What You Need

By Experience Level

By Topic

By Persona

🔍 Cross-References

Key Concepts Across Documents

💾 Knowledge Graph

📊 Statistics

🚀 Getting Started

One-Minute Quick Start

Five-Minute Deep Dive

Thirty-Minute Mastery

✅ Quality Checklist

📝 Notes for Teams

For Adoption

For Training

For Reference

🔗 Integration Points

📞 Need Help?

🎓 Learning Path

📦 Files in This Research

🏁 Conclusion

15 KiB

Raw Blame History