@bastani/atomic 0.5.11 → 0.5.12-0

package/.agents/skills/multi-agent-patterns/scripts/coordination.py

@@ -0,0 +1,613 @@
+"""
+Multi-Agent Coordination Utilities
+
+Provides reusable building blocks for multi-agent coordination patterns:
+supervisor/orchestrator, peer-to-peer handoffs, consensus mechanisms,
+and failure handling with circuit breakers.
+
+Use when: building multi-agent systems that need structured communication,
+task delegation, consensus voting, or fault-tolerant agent coordination.
+
+Designed for composability — import individual classes or use the
+``if __name__ == "__main__"`` demo to see all patterns in action.
+"""
+
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, field
+from enum import Enum
+import time
+import uuid
+
+__all__ = [
+    "MessageType",
+    "AgentMessage",
+    "AgentCommunication",
+    "SupervisorAgent",
+    "HandoffProtocol",
+    "ConsensusManager",
+    "AgentFailureHandler",
+]
+
+
+class MessageType(Enum):
+    """Types of messages exchanged between agents."""
+
+    REQUEST = "request"
+    RESPONSE = "response"
+    HANDOVER = "handover"
+    FEEDBACK = "feedback"
+    ALERT = "alert"
+
+
+@dataclass
+class AgentMessage:
+    """Message exchanged between agents.
+
+    Use when: agents need a structured envelope for inter-agent communication
+    that carries sender/receiver identity, type, priority, and payload.
+    """
+
+    sender: str
+    receiver: str
+    message_type: MessageType
+    content: Dict[str, Any]
+    timestamp: float = field(default_factory=time.time)
+    message_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    requires_response: bool = False
+    priority: int = 0  # 0 = normal, higher = more urgent
+
+
+class AgentCommunication:
+    """Communication channel for multi-agent systems.
+
+    Use when: multiple agents need an in-process message bus for sending,
+    receiving, and broadcasting messages with history tracking.
+    """
+
+    def __init__(self) -> None:
+        self.inbox: Dict[str, List[AgentMessage]] = {}
+        self.outbox: List[AgentMessage] = []
+        self.message_history: List[AgentMessage] = []
+
+    def send(self, message: AgentMessage) -> None:
+        """Send a message to an agent."""
+        if message.receiver not in self.inbox:
+            self.inbox[message.receiver] = []
+        self.inbox[message.receiver].append(message)
+        self.outbox.append(message)
+        self.message_history.append(message)
+
+    def receive(self, agent_id: str) -> List[AgentMessage]:
+        """Receive all messages for an agent, clearing its inbox."""
+        messages = self.inbox.get(agent_id, [])
+        self.inbox[agent_id] = []
+        return messages
+
+    def broadcast(
+        self,
+        sender: str,
+        message_type: MessageType,
+        content: Dict[str, Any],
+        receivers: List[str],
+    ) -> None:
+        """Broadcast a message to multiple agents."""
+        for receiver in receivers:
+            self.send(
+                AgentMessage(
+                    sender=sender,
+                    receiver=receiver,
+                    message_type=message_type,
+                    content=content,
+                )
+            )
+
+
+# ---------------------------------------------------------------------------
+# Supervisor Pattern
+# ---------------------------------------------------------------------------
+
+
+class SupervisorAgent:
+    """Central supervisor agent that coordinates worker agents.
+
+    Use when: tasks have clear decomposition and a single coordinator should
+    delegate subtasks, track worker status, and aggregate results.
+    """
+
+    def __init__(self, name: str, communication: AgentCommunication) -> None:
+        self.name = name
+        self.communication = communication
+        self.workers: Dict[str, Dict[str, Any]] = {}
+        self.task_queue: List[Dict[str, Any]] = []
+        self.completed_tasks: List[Dict[str, Any]] = []
+        self.current_state: Dict[str, Any] = {}
+
+    def register_worker(self, worker_id: str, capabilities: List[str]) -> None:
+        """Register a worker agent with the supervisor."""
+        self.workers[worker_id] = {
+            "capabilities": capabilities,
+            "status": "available",
+            "current_task": None,
+            "metrics": {"tasks_completed": 0, "avg_response_time": 0.0},
+        }
+
+    def decompose_task(self, task: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Decompose a task into subtasks.
+
+        Use when: a high-level task needs to be broken into assignable units.
+        In production, replace the rule-based logic with LLM-driven planning.
+        """
+        subtasks: List[Dict[str, Any]] = []
+        task_type = task.get("type", "general")
+
+        if task_type == "research":
+            subtasks = [
+                {"type": "search", "description": "Gather information"},
+                {"type": "analyze", "description": "Analyze findings"},
+                {"type": "synthesize", "description": "Synthesize results"},
+            ]
+        elif task_type == "create":
+            subtasks = [
+                {"type": "plan", "description": "Create plan"},
+                {"type": "draft", "description": "Draft content"},
+                {"type": "review", "description": "Review and refine"},
+            ]
+        else:
+            subtasks = [
+                {
+                    "type": "execute",
+                    "description": task.get("description", "Execute task"),
+                }
+            ]
+
+        for subtask in subtasks:
+            subtask["parent_task"] = task.get("id")
+            subtask["priority"] = task.get("priority", 0)
+
+        return subtasks
+
+    def assign_task(self, subtask: Dict[str, Any], worker_id: str) -> None:
+        """Assign a subtask to a worker agent."""
+        if worker_id not in self.workers:
+            raise ValueError(f"Unknown worker: {worker_id}")
+
+        self.workers[worker_id]["status"] = "busy"
+        self.workers[worker_id]["current_task"] = subtask.get("id")
+
+        self._send(
+            AgentMessage(
+                sender=self.name,
+                receiver=worker_id,
+                message_type=MessageType.REQUEST,
+                content={"action": "execute_task", "task": subtask},
+                requires_response=True,
+                priority=subtask.get("priority", 0),
+            )
+        )
+
+    def select_worker(self, subtask: Dict[str, Any]) -> str:
+        """Select the best available worker for a subtask.
+
+        Use when: the supervisor needs capability-aware routing with
+        load-balancing (fewest completed tasks chosen first).
+        """
+        required_capability = subtask.get("type", "general")
+
+        candidates = [
+            wid
+            for wid, info in self.workers.items()
+            if info["status"] == "available"
+            and required_capability in info["capabilities"]
+        ]
+
+        if not candidates:
+            candidates = [
+                wid
+                for wid, info in self.workers.items()
+                if info["status"] == "available"
+            ]
+
+        if not candidates:
+            raise ValueError("No available workers")
+
+        return min(
+            candidates,
+            key=lambda w: self.workers[w]["metrics"]["tasks_completed"],
+        )
+
+    def aggregate_results(
+        self, subtask_results: List[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Aggregate results from completed subtasks."""
+        summaries = [
+            r.get("summary", "")
+            for r in subtask_results
+            if r.get("success")
+        ]
+        successful = sum(
+            1 for r in subtask_results if r.get("success", False)
+        )
+        quality = successful / len(subtask_results) if subtask_results else 0.0
+
+        return {
+            "results": subtask_results,
+            "summary": " | ".join(summaries),
+            "quality_score": quality,
+        }
+
+    def run_workflow(self, task: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute a complete workflow with supervision.
+
+        Use when: running an end-to-end supervised pipeline that decomposes
+        a task, assigns subtasks, collects results, and aggregates them.
+
+        Note: This is a synchronous simulation. Workers do not execute
+        asynchronously — each subtask is simulated inline. In production,
+        replace ``_simulate_worker_response`` with actual async worker
+        execution and message passing.
+        """
+        subtasks = self.decompose_task(task)
+
+        results: List[Dict[str, Any]] = []
+        for subtask in subtasks:
+            worker = self.select_worker(subtask)
+            self.assign_task(subtask, worker)
+
+            # Simulate worker executing and responding
+            response = self._simulate_worker_response(worker, subtask)
+            self.communication.send(
+                AgentMessage(
+                    sender=worker,
+                    receiver=self.name,
+                    message_type=MessageType.RESPONSE,
+                    content=response,
+                )
+            )
+            self.workers[worker]["status"] = "available"
+            self.workers[worker]["metrics"]["tasks_completed"] += 1
+
+            messages = self.communication.receive(self.name)
+            for msg in messages:
+                if msg.message_type == MessageType.RESPONSE:
+                    results.append(msg.content)
+
+        final_result = self.aggregate_results(results)
+
+        return {
+            "task": task,
+            "subtask_results": results,
+            "final_result": final_result,
+            "success": final_result["quality_score"] >= 0.8,
+        }
+
+    def _simulate_worker_response(
+        self, worker_id: str, subtask: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Simulate a worker completing a subtask.
+
+        In production, replace with actual agent execution that sends
+        the subtask to a worker process and awaits a real response.
+        """
+        return {
+            "success": True,
+            "summary": f"{worker_id} completed: {subtask.get('description', subtask.get('type', 'task'))}",
+            "worker": worker_id,
+            "subtask_type": subtask.get("type"),
+        }
+
+    def _send(self, message: AgentMessage) -> None:
+        """Send message through the communication channel."""
+        self.communication.send(message)
+
+
+# ---------------------------------------------------------------------------
+# Handoff Protocol
+# ---------------------------------------------------------------------------
+
+
+class HandoffProtocol:
+    """Protocol for agent-to-agent handoffs.
+
+    Use when: implementing peer-to-peer or swarm patterns where agents
+    transfer control and task state to one another.
+    """
+
+    def __init__(self, communication: AgentCommunication) -> None:
+        self.communication = communication
+
+    def create_handoff(
+        self,
+        from_agent: str,
+        to_agent: str,
+        context: Dict[str, Any],
+        reason: str,
+    ) -> AgentMessage:
+        """Create a handoff message with transferred context."""
+        return AgentMessage(
+            sender=from_agent,
+            receiver=to_agent,
+            message_type=MessageType.HANDOVER,
+            content={
+                "handoff_reason": reason,
+                "transferred_context": context,
+                "handoff_timestamp": time.time(),
+            },
+            priority=1,
+        )
+
+    def accept_handoff(self, agent_id: str) -> Optional[AgentMessage]:
+        """Accept the first pending handoff for an agent, if any."""
+        messages = self.communication.receive(agent_id)
+
+        for msg in messages:
+            if msg.message_type == MessageType.HANDOVER:
+                return msg
+
+        return None
+
+    def transfer_with_state(
+        self,
+        from_agent: str,
+        to_agent: str,
+        state: Dict[str, Any],
+        task: Dict[str, Any],
+    ) -> bool:
+        """Transfer task state from one agent to another.
+
+        Use when: a handoff must carry full task state and progress so the
+        receiving agent can resume without re-deriving context.
+
+        Returns True if the receiving agent acknowledged the handoff.
+        """
+        handoff = self.create_handoff(
+            from_agent=from_agent,
+            to_agent=to_agent,
+            context={
+                "task_state": state,
+                "task_details": task,
+                "progress": state.get("progress", 0),
+            },
+            reason="task_transfer",
+        )
+
+        self.communication.send(handoff)
+
+        # In production, replace sleep with async await + timeout
+        time.sleep(0.1)
+        ack = self.communication.receive(from_agent)
+
+        return any(
+            m.message_type == MessageType.RESPONSE
+            and m.content.get("status") == "handoff_received"
+            for m in ack
+        )
+
+
+# ---------------------------------------------------------------------------
+# Consensus Mechanism
+# ---------------------------------------------------------------------------
+
+
+class ConsensusManager:
+    """Manager for multi-agent consensus building.
+
+    Use when: multiple agents must vote on a decision and the system needs
+    weighted consensus that accounts for confidence and expertise rather
+    than naive majority voting.
+    """
+
+    def __init__(self) -> None:
+        self.votes: Dict[str, List[Dict[str, Any]]] = {}
+        self.debates: Dict[str, List[Dict[str, Any]]] = {}
+
+    def initiate_vote(
+        self, topic_id: str, agents: List[str], options: List[str]
+    ) -> None:
+        """Initiate a voting round on a topic."""
+        self.votes[topic_id] = [
+            {
+                "agent": agent,
+                "topic": topic_id,
+                "options": options,
+                "status": "pending",
+            }
+            for agent in agents
+        ]
+
+    def submit_vote(
+        self,
+        topic_id: str,
+        agent_id: str,
+        selection: str,
+        confidence: float,
+    ) -> None:
+        """Submit a vote for a topic with a confidence weight."""
+        if topic_id not in self.votes:
+            raise ValueError(f"Unknown topic: {topic_id}")
+
+        for vote in self.votes[topic_id]:
+            if vote["agent"] == agent_id:
+                vote["status"] = "cast"
+                vote["selection"] = selection
+                vote["confidence"] = confidence
+                break
+
+    def calculate_weighted_consensus(self, topic_id: str) -> Dict[str, Any]:
+        """Calculate weighted consensus from cast votes.
+
+        Use when: votes are in and the system needs to determine a winner
+        weighted by each agent's confidence rather than simple majority.
+        Weight = confidence * expertise_factor.
+        """
+        if topic_id not in self.votes:
+            raise ValueError(f"Unknown topic: {topic_id}")
+
+        votes = [
+            v for v in self.votes[topic_id] if v.get("status") == "cast"
+        ]
+
+        if not votes:
+            return {"status": "no_votes", "result": None}
+
+        # Group by selection
+        selections: Dict[str, List[Dict[str, Any]]] = {}
+        for vote in votes:
+            selection = vote["selection"]
+            if selection not in selections:
+                selections[selection] = []
+            selections[selection].append(vote)
+
+        # Calculate weighted score for each selection
+        results: Dict[str, Dict[str, Any]] = {}
+        for selection, selection_votes in selections.items():
+            weighted_sum = sum(v["confidence"] for v in selection_votes)
+            avg_confidence = (
+                weighted_sum / len(selection_votes) if selection_votes else 0.0
+            )
+            results[selection] = {
+                "weighted_score": weighted_sum,
+                "avg_confidence": avg_confidence,
+                "vote_count": len(selection_votes),
+            }
+
+        winner = max(results.keys(), key=lambda s: results[s]["weighted_score"])
+
+        return {
+            "status": "complete",
+            "result": winner,
+            "details": results,
+            "consensus_strength": (
+                results[winner]["weighted_score"] / len(votes) if votes else 0.0
+            ),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Failure Handling
+# ---------------------------------------------------------------------------
+
+
+class AgentFailureHandler:
+    """Handler for agent failures in multi-agent systems.
+
+    Use when: agents may fail and the system needs retry logic with
+    exponential backoff, circuit breakers, and automatic rerouting to
+    backup agents.
+    """
+
+    def __init__(
+        self,
+        communication: AgentCommunication,
+        max_retries: int = 3,
+    ) -> None:
+        self.communication = communication
+        self.max_retries = max_retries
+        self.failure_counts: Dict[str, int] = {}
+        self.circuit_breakers: Dict[str, float] = {}  # agent -> unlock time
+
+    def handle_failure(
+        self, agent_id: str, task_id: str, error: str
+    ) -> Dict[str, Any]:
+        """Handle a failure from an agent.
+
+        Use when: an agent reports an error and the system must decide
+        whether to retry (with backoff) or reroute to a backup agent.
+        """
+        self.failure_counts[agent_id] = (
+            self.failure_counts.get(agent_id, 0) + 1
+        )
+
+        if self.failure_counts[agent_id] >= self.max_retries:
+            self._activate_circuit_breaker(agent_id)
+            return {
+                "action": "reroute",
+                "reason": "circuit_breaker_activated",
+                "alternative": self._find_alternative_agent(agent_id),
+            }
+
+        return {
+            "action": "retry",
+            "reason": error,
+            "retry_count": self.failure_counts[agent_id],
+            "delay": min(2 ** self.failure_counts[agent_id], 60),
+        }
+
+    def _activate_circuit_breaker(self, agent_id: str) -> None:
+        """Temporarily disable an agent (1-minute cooldown)."""
+        self.circuit_breakers[agent_id] = time.time() + 60
+
+    def _find_alternative_agent(self, failed_agent: str) -> str:
+        """Find an alternative agent to handle the task.
+
+        In production, check agent capabilities and availability.
+        """
+        return "default_backup_agent"
+
+    def is_available(self, agent_id: str) -> bool:
+        """Check if an agent is available (circuit breaker not active)."""
+        if agent_id in self.circuit_breakers:
+            if time.time() < self.circuit_breakers[agent_id]:
+                return False
+            del self.circuit_breakers[agent_id]
+            self.failure_counts[agent_id] = 0
+        return True
+
+    def record_success(self, agent_id: str) -> None:
+        """Record a successful task completion, resetting failure count."""
+        self.failure_counts[agent_id] = 0
+
+
+# ---------------------------------------------------------------------------
+# Demo / CLI entry point
+# ---------------------------------------------------------------------------
+
+
+if __name__ == "__main__":
+    print("=== Multi-Agent Coordination Demo ===\n")
+
+    # 1. Communication channel
+    comm = AgentCommunication()
+    print("1. Created communication channel")
+
+    # 2. Supervisor pattern
+    supervisor = SupervisorAgent("supervisor", comm)
+    supervisor.register_worker("researcher", ["search", "analyze"])
+    supervisor.register_worker("writer", ["synthesize", "draft"])
+    print("2. Registered supervisor with 2 workers: researcher, writer")
+
+    # 3. Handoff protocol
+    protocol = HandoffProtocol(comm)
+    handoff_msg = protocol.create_handoff(
+        from_agent="researcher",
+        to_agent="writer",
+        context={"findings": ["item1", "item2"]},
+        reason="research_complete",
+    )
+    comm.send(handoff_msg)
+    received = protocol.accept_handoff("writer")
+    print(
+        f"3. Handoff from researcher -> writer: "
+        f"{'accepted' if received else 'none pending'}"
+    )
+
+    # 4. Consensus mechanism
+    consensus = ConsensusManager()
+    consensus.initiate_vote("best_approach", ["agent_a", "agent_b", "agent_c"], ["A", "B"])
+    consensus.submit_vote("best_approach", "agent_a", "A", confidence=0.9)
+    consensus.submit_vote("best_approach", "agent_b", "B", confidence=0.6)
+    consensus.submit_vote("best_approach", "agent_c", "A", confidence=0.8)
+    result = consensus.calculate_weighted_consensus("best_approach")
+    print(
+        f"4. Consensus result: {result['result']} "
+        f"(strength: {result['consensus_strength']:.2f})"
+    )
+
+    # 5. Failure handling
+    handler = AgentFailureHandler(comm, max_retries=3)
+    action1 = handler.handle_failure("flaky_agent", "task_1", "timeout")
+    action2 = handler.handle_failure("flaky_agent", "task_1", "timeout")
+    action3 = handler.handle_failure("flaky_agent", "task_1", "timeout")
+    print(f"5. After 3 failures: action={action3['action']}")
+    print(f"   Agent available? {handler.is_available('flaky_agent')}")
+
+    print("\n=== Demo Complete ===")

package/.agents/skills/normalize/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: normalize
+description: Audits and realigns UI to match design system standards, spacing, tokens, and patterns. Use when the user mentions consistency, design drift, mismatched styles, tokens, or wants to bring a feature back in line with the system.
+user-invocable: true
+argument-hint: "[feature (page, route, component...)]"
+---
+
+Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns.
+
+## MANDATORY PREPARATION
+
+Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first.
+
+---
+
+## Plan
+
+Before making changes, deeply understand the context:
+
+1. **Discover the design system**: Search for design system documentation, UI guidelines, component libraries, or style guides (grep for "design system", "ui guide", "style guide", etc.). Study it thoroughly until you understand:
+   - Core design principles and aesthetic direction
+   - Target audience and personas
+   - Component patterns and conventions
+   - Design tokens (colors, typography, spacing)
+   
+   **CRITICAL**: If something isn't clear, ask. Don't guess at design system principles.
+
+2. **Analyze the current feature**: Assess what works and what doesn't:
+   - Where does it deviate from design system patterns?
+   - Which inconsistencies are cosmetic vs. functional?
+   - What's the root cause—missing tokens, one-off implementations, or conceptual misalignment?
+
+3. **Create a normalization plan**: Define specific changes that will align the feature with the design system:
+   - Which components can be replaced with design system equivalents?
+   - Which styles need to use design tokens instead of hard-coded values?
+   - How can UX patterns match established user flows?
+   
+   **IMPORTANT**: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through the best possible experience for your use case and personas first.
+
+## Execute
+
+Systematically address all inconsistencies across these dimensions:
+
+- **Typography**: Use design system fonts, sizes, weights, and line heights. Replace hard-coded values with typographic tokens or classes.
+- **Color & Theme**: Apply design system color tokens. Remove one-off color choices that break the palette.
+- **Spacing & Layout**: Use spacing tokens (margins, padding, gaps). Align with grid systems and layout patterns used elsewhere.
+- **Components**: Replace custom implementations with design system components. Ensure props and variants match established patterns.
+- **Motion & Interaction**: Match animation timing, easing, and interaction patterns to other features.
+- **Responsive Behavior**: Ensure breakpoints and responsive patterns align with design system standards.
+- **Accessibility**: Verify contrast ratios, focus states, ARIA labels match design system requirements.
+- **Progressive Disclosure**: Match information hierarchy and complexity management to established patterns.
+
+**NEVER**:
+- Create new one-off components when design system equivalents exist
+- Hard-code values that should use design tokens
+- Introduce new patterns that diverge from the design system
+- Compromise accessibility for visual consistency
+
+This is not an exhaustive list—apply judgment to identify all areas needing normalization.
+
+## Clean Up
+
+After normalization, ensure code quality:
+
+- **Consolidate reusable components**: If you created new components that should be shared, move them to the design system or shared UI component path.
+- **Remove orphaned code**: Delete unused implementations, styles, or files made obsolete by normalization.
+- **Verify quality**: Lint, type-check, and test according to repository guidelines. Ensure normalization didn't introduce regressions.
+- **Ensure DRYness**: Look for duplication introduced during refactoring and consolidate.
+
+Remember: You are a brilliant frontend designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.