Group Collaboration

Four-Tier Architecture Recap

Group 1: Strategic Analysis & Intelligence (The "Brain")

• Role: Analyze and recommend
• Output: Recommendations with confidence scores
• Key Agents: code-analyzer, security-auditor, smart-recommender

Group 2: Decision Making & Planning (The "Council")

• Role: Evaluate and decide
• Output: Execution plans with priorities
• Key Agents: strategic-planner, preference-coordinator

Group 3: Execution & Implementation (The "Hand")

• Role: Execute decisions
• Output: Execution results with metrics
• Key Agents: quality-controller, test-engineer, documentation-generator

Group 4: Validation & Optimization (The "Guardian")

• Role: Validate and optimize
• Output: Validation results and feedback
• Key Agents: post-execution-validator, performance-optimizer, continuous-improvement

Communication Patterns

Pattern 1: Analysis → Decision (Group 1 → Group 2)

Purpose: Transfer analysis findings and recommendations to decision-makers

Structure:

from lib.group_collaboration_system import record_communication

record_communication(
    from_agent="code-analyzer",  # Group 1
    to_agent="strategic-planner",  # Group 2
    task_id=task_id,
    communication_type="recommendation",
    message="Code analysis complete with 5 recommendations",
    data={
        "quality_score": 72,
        "recommendations": [
            {
                "type": "refactoring",
                "priority": "high",
                "confidence": 0.92,  # High confidence
                "description": "Extract login method complexity",
                "rationale": "Cyclomatic complexity 15, threshold 10",
                "estimated_effort_hours": 2.5,
                "expected_impact": "high",
                "files_affected": ["src/auth.py"]
            }
        ],
        "patterns_detected": ["token_auth", "validation_duplication"],
        "metrics": {
            "complexity_avg": 8.5,
            "duplication_rate": 0.12,
            "test_coverage": 0.78
        }
    }
)

Best Practices:

• Always include confidence scores (0.0-1.0)
• Provide rationale for each recommendation
• Include estimated effort and expected impact
• Attach relevant metrics and context
• Reference detected patterns
• List affected files

Anti-Patterns to Avoid:

• ❌ Recommendations without confidence scores
• ❌ Missing rationale or context
• ❌ Vague impact estimates ("it will be better")
• ❌ No prioritization
• ❌ Execution commands (that's Group 3's job)

Pattern 2: Decision → Execution (Group 2 → Group 3)

Purpose: Communicate execution plan with priorities and user preferences

Structure:

record_communication(
    from_agent="strategic-planner",  # Group 2
    to_agent="quality-controller",  # Group 3
    task_id=task_id,
    communication_type="execution_plan",
    message="Execute quality improvement plan with 3 priorities",
    data={
        "decision_rationale": "High-priority refactoring based on user preferences",
        "execution_plan": {
            "quality_targets": {
                "tests": 80,
                "standards": 90,
                "documentation": 70
            },
            "priority_order": [
                "fix_failing_tests",  # Highest priority
                "apply_code_standards",
                "add_missing_docs"
            ],
            "approach": "incremental",  # or "comprehensive"
            "risk_tolerance": "low"  # User preference
        },
        "user_preferences": {
            "auto_fix_threshold": 0.9,
            "coding_style": "concise",
            "comment_level": "moderate",
            "documentation_level": "standard"
        },
        "constraints": {
            "max_iterations": 3,
            "time_budget_minutes": 15,
            "files_in_scope": ["src/auth.py", "src/utils.py"]
        },
        "decision_confidence": 0.88
    }
)

Best Practices:

• Include clear execution plan with priorities
• Apply user preferences to the plan
• Set realistic constraints (time, iterations)
• Provide decision rationale
• Specify risk tolerance
• Define success criteria

Anti-Patterns to Avoid:

• ❌ Plans without priorities
• ❌ Missing user preferences
• ❌ Unrealistic constraints
• ❌ No success criteria
• ❌ Ambiguous instructions

Pattern 3: Execution → Validation (Group 3 → Group 4)

Purpose: Send execution results for validation and quality assessment

Structure:

record_communication(
    from_agent="quality-controller",  # Group 3
    to_agent="post-execution-validator",  # Group 4
    task_id=task_id,
    communication_type="execution_result",
    message="Quality improvement complete: 68 → 84",
    data={
        "metrics_before": {
            "quality_score": 68,
            "tests_passing": 45,
            "standards_violations": 23,
            "doc_coverage": 0.60
        },
        "metrics_after": {
            "quality_score": 84,
            "tests_passing": 50,
            "standards_violations": 2,
            "doc_coverage": 0.75
        },
        "changes_made": {
            "tests_fixed": 5,
            "standards_violations_fixed": 21,
            "docs_generated": 10
        },
        "files_modified": ["src/auth.py", "tests/test_auth.py"],
        "auto_corrections_applied": 30,
        "manual_review_needed": [],
        "iterations_used": 2,
        "execution_time_seconds": 145,
        "component_scores": {
            "tests": 28,
            "standards": 22,
            "documentation": 16,
            "patterns": 13,
            "code_metrics": 5
        },
        "issues_encountered": []
    }
)

Best Practices:

• Show before/after metrics clearly
• List all changes made
• Include execution statistics
• Report any issues encountered
• Specify files modified
• Break down component scores

Anti-Patterns to Avoid:

• ❌ Only showing final metrics without before state
• ❌ Missing execution time and iterations
• ❌ No breakdown of what was changed
• ❌ Hiding issues or failures
• ❌ Incomplete component scoring

Pattern 4: Validation → Analysis (Group 4 → Group 1)

Purpose: Provide feedback on recommendation effectiveness for learning

Structure:

from lib.agent_feedback_system import add_feedback

add_feedback(
    from_agent="post-execution-validator",  # Group 4
    to_agent="code-analyzer",  # Group 1
    task_id=task_id,
    feedback_type="success",  # or "improvement", "warning", "error"
    message="Recommendations were highly effective",
    details={
        "recommendations_followed": 3,
        "recommendations_effective": 3,
        "quality_improvement": 16,  # points improved
        "execution_smooth": True,
        "user_satisfaction": "high",
        "suggestions_for_improvement": []
    },
    impact="quality_score +16, all recommendations effective"
)

Best Practices:

• Specific feedback on recommendation effectiveness
• Quantify impact (quality score improvement)
• Note which recommendations worked best
• Suggest improvements for future
• Track user satisfaction

Anti-Patterns to Avoid:

• ❌ Vague feedback ("it was good")
• ❌ No quantified impact
• ❌ Only negative feedback without suggestions
• ❌ Missing context about what worked
• ❌ Not closing the feedback loop

Knowledge Transfer Strategies

Strategy 1: Pattern Propagation

When to Use: Share successful patterns across groups

from lib.inter_group_knowledge_transfer import add_knowledge

add_knowledge(
    source_group=1,  # Group 1 discovered this
    knowledge_type="pattern",
    title="Modular Authentication Pattern",
    description="Breaking auth logic into validate(), authenticate(), authorize() improves testability and maintainability",
    context={
        "applies_to": ["authentication", "authorization", "security"],
        "languages": ["python", "typescript"],
        "frameworks": ["flask", "fastapi"]
    },
    evidence={
        "quality_score_improvement": 12,
        "test_coverage_improvement": 0.15,
        "reuse_count": 5,
        "success_rate": 0.92
    }
)

Strategy 2: Anti-Pattern Sharing

When to Use: Share what NOT to do based on failures

add_knowledge(
    source_group=3,  # Group 3 encountered this during execution
    knowledge_type="anti_pattern",
    title="Avoid Nested Ternary Operators",
    description="Nested ternary operators reduce readability and increase cognitive complexity significantly",
    context={
        "applies_to": ["code_quality", "readability"],
        "severity": "medium"
    },
    evidence={
        "complexity_increase": 8,  # Cyclomatic complexity
        "maintenance_issues": 3,
        "refactoring_time_hours": 1.5
    }
)

Strategy 3: Best Practice Sharing

When to Use: Share techniques that consistently work well

add_knowledge(
    source_group=4,  # Group 4 validated this across tasks
    knowledge_type="best_practice",
    title="Test Fixtures with CASCADE for PostgreSQL",
    description="Always use CASCADE in test fixture teardown to avoid foreign key constraint errors",
    context={
        "applies_to": ["testing", "database"],
        "frameworks": ["pytest"],
        "databases": ["postgresql"]
    },
    evidence={
        "success_rate": 1.0,
        "fixes_applied": 15,
        "issues_prevented": 30
    }
)

Strategy 4: Optimization Tip Sharing

When to Use: Share performance improvements

add_knowledge(
    source_group=4,  # Group 4 performance-optimizer discovered this
    knowledge_type="optimization",
    title="Batch Database Queries in Loops",
    description="Replace N+1 query patterns with batch queries using IN clause or JOINs",
    context={
        "applies_to": ["performance", "database"],
        "orm": ["sqlalchemy", "sequelize"]
    },
    evidence={
        "performance_improvement": "80%",  # 5x faster
        "query_reduction": 0.95,  # 95% fewer queries
        "cases_improved": 8
    }
)

Feedback Loop Best Practices

1. Timely Feedback

Principle: Provide feedback immediately after validation, not days later

# ✅ GOOD: Immediate feedback
validate_results()
send_feedback_to_group_1()
send_feedback_to_group_3()

# ❌ BAD: Delayed feedback loses context
validate_results()
# ... days later ...
send_feedback()  # Context is lost

2. Actionable Feedback

Principle: Feedback must be specific and actionable, not vague

# ✅ GOOD: Specific and actionable
add_feedback(
    message="Recommendation confidence was too high (0.92) for untested pattern. Consider 0.75-0.85 for new patterns",
    suggestions=["Add confidence penalty for untested patterns", "Increase confidence gradually with reuse"]
)

# ❌ BAD: Vague
add_feedback(
    message="Confidence was wrong",
    suggestions=[]
)

3. Balanced Feedback

Principle: Highlight successes and areas for improvement

# ✅ GOOD: Balanced
add_feedback(
    positive=[
        "Priority ranking was excellent - high priority items were truly critical",
        "User preference integration worked perfectly"
    ],
    improvements=[
        "Estimated effort was 40% too low - consider adjusting effort formula",
        "Could benefit from more error handling recommendations"
    ]
)

4. Learning-Oriented Feedback

Principle: Focus on how the agent can improve, not blame

# ✅ GOOD: Learning-oriented
add_feedback(
    feedback_type="improvement",
    message="Analysis missed security vulnerability in auth flow",
    learning_opportunity="Add OWASP Top 10 checks to security analysis workflow",
    how_to_improve="Integrate security-auditor findings into code-analyzer reports"
)

# ❌ BAD: Blame-oriented
add_feedback(
    feedback_type="error",
    message="You failed to find the security issue",
    # No suggestions for improvement
)

Coordination Patterns

Pattern 1: Parallel Execution

When to Use: Multiple Group 1 agents can analyze simultaneously

# Orchestrator coordinates parallel Group 1 analysis
from lib.group_collaboration_system import coordinate_parallel_execution

results = coordinate_parallel_execution(
    group=1,
    agents=["code-analyzer", "security-auditor", "smart-recommender"],
    task_id=task_id,
    timeout_minutes=5
)

# All Group 1 findings consolidated before sending to Group 2
consolidated_findings = consolidate_findings(results)
send_to_group_2(consolidated_findings)

Pattern 2: Sequential Coordination

When to Use: Groups must execute in order (1→2→3→4)

# Standard workflow
findings = execute_group_1_analysis()  # Group 1: Analyze
plan = execute_group_2_decision(findings)  # Group 2: Decide
results = execute_group_3_execution(plan)  # Group 3: Execute
validation = execute_group_4_validation(results)  # Group 4: Validate

Pattern 3: Iterative Coordination

When to Use: Quality doesn't meet threshold, needs iteration

for iteration in range(max_iterations):
    # Group 3 executes
    results = execute_group_3(plan)

    # Group 4 validates
    validation = execute_group_4(results)

    if validation.quality_score >= 70:
        break  # Success!

    # Group 4 sends feedback to Group 2 for plan adjustment
    feedback = validation.get_improvement_suggestions()
    plan = group_2_adjust_plan(plan, feedback)

    # Group 3 re-executes with adjusted plan

Pattern 4: Conditional Coordination

When to Use: Execution path depends on analysis results

# Group 1 analysis
security_findings = security_auditor.analyze()

if security_findings.critical_count > 0:
    # Critical security issues → immediate path
    plan = group_2_create_security_fix_plan(security_findings)
    results = group_3_execute_security_fixes(plan)