Initial commit

2025-11-29 18:00:50 +08:00
commit c5931553a6
106 changed files with 49995 additions and 0 deletions
--- a/skills/group-collaboration/SKILL.md
+++ b/skills/group-collaboration/SKILL.md
@@ -0,0 +1,733 @@
+---
+name: Group Collaboration
+description: Best practices for inter-group communication, knowledge sharing, and collaborative workflows in four-tier architecture
+version: 7.0.0
+category: collaboration
+tags: [four-tier, inter-group, communication, knowledge-transfer, coordination]
+related_skills: [pattern-learning, contextual-pattern-learning]
+---
+
+# Group Collaboration Skill
+
+## Overview
+
+This skill provides guidelines, patterns, and best practices for effective collaboration between the four agent groups in the four-tier architecture. It covers communication protocols, knowledge transfer strategies, feedback mechanisms, and coordination patterns that enable autonomous learning and continuous improvement across groups.
+
+## When to Apply This Skill
+
+**Use this skill when:**
+- Implementing inter-group communication between any two groups
+- Designing handoff protocols between analysis, decision, execution, and validation phases
+- Setting up feedback loops for continuous improvement
+- Sharing knowledge and patterns across groups
+- Coordinating multi-group workflows
+- Troubleshooting collaboration issues between groups
+- Optimizing group performance through better coordination
+
+**Required for:**
+- All agents in four-tier architecture (Groups 1, 2, 3, 4)
+- Orchestrator coordination logic
+- Cross-group pattern learning
+- Workflow optimization
+
+## 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**:
+```python
+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**:
+```python
+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**:
+```python
+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**:
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+# ✅ 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
+
+```python
+# ✅ 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
+
+```python
+# ✅ 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
+
+```python
+# ✅ 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
+
+```python
+# 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)
+
+```python
+# 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
+
+```python
+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
+
+```python
+# 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)
+else:
+    # Normal path
+    all_findings = consolidate_all_group_1_findings()
+    plan = group_2_create_standard_plan(all_findings)
+    results = group_3_execute_standard(plan)
+```
+
+## Troubleshooting Collaboration Issues
+
+### Issue 1: Communication Not Reaching Target
+
+**Symptoms**:
+- Group 2 doesn't receive Group 1 recommendations
+- Group 3 doesn't receive execution plan
+
+**Diagnosis**:
+```python
+from lib.group_collaboration_system import get_communications_for_agent
+
+# Check if communications are recorded
+comms = get_communications_for_agent("strategic-planner", communication_type="recommendation")
+if not comms:
+    print("❌ No communications found - sender may not be recording properly")
+```
+
+**Fix**:
+- Ensure `record_communication()` is called after analysis
+- Verify task_id is consistent across groups
+- Check communication_type matches expected type
+
+### Issue 2: Feedback Loop Not Learning
+
+**Symptoms**:
+- Same mistakes repeated
+- No improvement in recommendation confidence
+- Agents don't adjust based on feedback
+
+**Diagnosis**:
+```python
+from lib.agent_feedback_system import get_feedback_stats
+
+stats = get_feedback_stats("code-analyzer")
+if stats["total_feedback"] == 0:
+    print("❌ No feedback received - feedback loop broken")
+```
+
+**Fix**:
+- Ensure Group 4 sends feedback after validation
+- Verify agents query feedback before making decisions
+- Check feedback is actionable and specific
+
+### Issue 3: Knowledge Not Transferring
+
+**Symptoms**:
+- Groups rediscover same patterns
+- Best practices not reused
+- Learning not retained
+
+**Diagnosis**:
+```python
+from lib.inter_group_knowledge_transfer import get_knowledge_transfer_stats
+
+stats = get_knowledge_transfer_stats()
+if stats["successful_transfers"] < stats["total_knowledge"] * 0.5:
+    print("⚠️ Low knowledge transfer success rate")
+```
+
+**Fix**:
+- Ensure agents query knowledge before tasks
+- Add context matching to knowledge queries
+- Increase knowledge confidence through successful applications
+
+### Issue 4: Group Specialization Not Developing
+
+**Symptoms**:
+- All agents perform similarly across task types
+- No clear specialization patterns
+- Sub-optimal task routing
+
+**Diagnosis**:
+```python
+from lib.group_specialization_learner import get_specialization_profile
+
+profile = get_specialization_profile(group_num=3)
+if not profile.get("specializations"):
+    print("⚠️ No specializations detected - need more task diversity")
+```
+
+**Fix**:
+- Record observations for all task executions
+- Ensure task types are correctly labeled
+- Allow sufficient tasks (50+) for specialization to emerge
+- Review specialization insights regularly
+
+## Success Metrics
+
+**Effective Group Collaboration Indicators**:
+- ✅ Communication flow rate > 95% (messages reach intended recipients)
+- ✅ Feedback loop cycle time < 5 minutes (validation → feedback → learning)
+- ✅ Knowledge reuse rate > 60% (discovered patterns applied in future tasks)
+- ✅ Recommendation effectiveness > 85% (Group 1 recommendations followed and successful)
+- ✅ Execution success rate > 90% (Group 3 executes plans successfully first time)
+- ✅ Validation pass rate > 80% (Group 4 validates without requiring major iterations)
+- ✅ Specialization emergence rate: Each group develops 3+ specializations after 100 tasks
+
+**Track with:**
+```python
+from lib.group_collaboration_system import get_group_collaboration_stats
+
+stats = get_group_collaboration_stats()
+print(f"Communication success rate: {stats['communication_success_rate']:.1%}")
+print(f"Average feedback cycle time: {stats['avg_feedback_cycle_seconds']}s")
+print(f"Knowledge reuse rate: {stats['knowledge_reuse_rate']:.1%}")
+```
+
+## Integration Examples
+
+### Example 1: Complete Four-Tier Workflow
+
+```python
+# Orchestrator coordinates complete workflow
+from lib.group_collaboration_system import record_communication
+from lib.agent_feedback_system import add_feedback
+from lib.inter_group_knowledge_transfer import query_knowledge, add_knowledge
+from lib.group_specialization_learner import get_recommended_group_for_task
+
+# Step 0: Get specialization recommendations
+routing = get_recommended_group_for_task(
+    task_type="refactoring",
+    complexity="medium",
+    domain="authentication"
+)
+print(f"Recommended: {routing['recommended_agents']}")
+
+# Step 1: Group 1 analyzes (code-analyzer)
+analysis = code_analyzer.analyze(task)
+
+# Query existing knowledge
+existing_patterns = query_knowledge(
+    for_group=1,
+    knowledge_type="pattern",
+    task_context={"task_type": "refactoring", "domain": "authentication"}
+)
+
+# Send findings to Group 2
+record_communication(
+    from_agent="code-analyzer",
+    to_agent="strategic-planner",
+    task_id=task_id,
+    communication_type="recommendation",
+    data=analysis
+)
+
+# Step 2: Group 2 decides (strategic-planner)
+user_prefs = preference_coordinator.load_preferences()
+plan = strategic_planner.create_plan(analysis, user_prefs)
+
+# Send plan to Group 3
+record_communication(
+    from_agent="strategic-planner",
+    to_agent="quality-controller",
+    task_id=task_id,
+    communication_type="execution_plan",
+    data=plan
+)
+
+# Step 3: Group 3 executes (quality-controller)
+results = quality_controller.execute(plan)
+
+# Send results to Group 4
+record_communication(
+    from_agent="quality-controller",
+    to_agent="post-execution-validator",
+    task_id=task_id,
+    communication_type="execution_result",
+    data=results
+)
+
+# Step 4: Group 4 validates (post-execution-validator)
+validation = post_execution_validator.validate(results)
+
+# Send feedback to Group 1
+add_feedback(
+    from_agent="post-execution-validator",
+    to_agent="code-analyzer",
+    task_id=task_id,
+    feedback_type="success",
+    message="Recommendations were 95% effective",
+    details={"quality_improvement": 18}
+)
+
+# Send feedback to Group 3
+add_feedback(
+    from_agent="post-execution-validator",
+    to_agent="quality-controller",
+    task_id=task_id,
+    feedback_type="success",
+    message="Execution was efficient and effective"
+)
+
+# Share successful pattern
+if validation.quality_score >= 90:
+    add_knowledge(
+        source_group=4,
+        knowledge_type="pattern",
+        title="Successful Authentication Refactoring Pattern",
+        description=f"Pattern used in task {task_id} achieved quality score {validation.quality_score}",
+        context={"task_type": "refactoring", "domain": "authentication"},
+        evidence={"quality_score": validation.quality_score}
+    )
+```
+
+## References
+
+**Related Systems**:
+- `lib/group_collaboration_system.py` - Communication tracking
+- `lib/agent_feedback_system.py` - Feedback management
+- `lib/inter_group_knowledge_transfer.py` - Knowledge sharing
+- `lib/group_specialization_learner.py` - Specialization tracking
+- `lib/agent_performance_tracker.py` - Performance metrics
+
+**Related Documentation**:
+- `docs/FOUR_TIER_ARCHITECTURE.md` - Complete architecture design
+- `docs/FOUR_TIER_ENHANCEMENTS.md` - Advanced features
+- `agents/orchestrator.md` - Orchestrator coordination logic