sinapse-ai 9.3.0 → 9.5.0

package/squads/claude-code-mastery/data/swarm-orchestration-patterns.yaml

@@ -1,378 +0,0 @@
-# Swarm Orchestration Patterns for AI Agents
-# Squad: claude-code-mastery
-# Source: Research 07-skills-agents-swarm (llm-files-swarm-agi.md)
-# Last updated: 2026-04-10
-
-version: "1.0.0"
-source_research: "07-skills-agents-swarm/llm-files-swarm-agi.md"
-
-# ---------------------------------------------------------------------------
-# SWARM INTELLIGENCE FUNDAMENTALS
-# ---------------------------------------------------------------------------
-swarm_intelligence:
-  definition: >
-    Collective behavior emerging from decentralized, self-organized agents
-    following simple local rules — producing globally intelligent behavior
-    without central coordination.
-  origin: "Dorigo & Colorni (1992) — Ant Colony Optimization"
-  key_principle: "Local simplicity → Global intelligence"
-
-  classic_algorithms:
-    - name: "Ant Colony Optimization (ACO)"
-      mechanism: "Pheromone trails"
-      best_for: "Route optimization, graph search"
-      ai_analogy: "Shared memory blackboard for successful solutions"
-
-    - name: "Particle Swarm Optimization (PSO)"
-      mechanism: "Velocity + personal/global best"
-      best_for: "Continuous parameter optimization"
-      ai_analogy: "Agents sharing best-found strategies"
-
-    - name: "Bee Algorithm"
-      mechanism: "Scout + forager specialization"
-      best_for: "Parallel exploration + exploitation"
-      ai_analogy: "Parallel agent spawning for task exploration"
-
-    - name: "Flocking (Boids)"
-      mechanism: "Separation + alignment + cohesion"
-      best_for: "Emergent coordination without hierarchy"
-      ai_analogy: "Peer agent coordination without orchestrator"
-
-# ---------------------------------------------------------------------------
-# AI AGENT SWARM TOPOLOGIES (4 Core Patterns)
-# ---------------------------------------------------------------------------
-swarm_topologies:
-
-  - name: "Hierarchical Swarm"
-    also_known_as: "Orchestrator-Worker"
-    pattern: |
-      Orchestrator
-          ├── Worker Agent 1
-          ├── Worker Agent 2
-          └── Worker Agent 3
-    characteristics:
-      - "Single point of coordination at top"
-      - "Clear delegation chain"
-      - "Predictable task routing"
-    strengths:
-      - "Easy to reason about"
-      - "Clear authority and accountability"
-      - "Good for complex domain decomposition"
-    weaknesses:
-      - "Single point of failure at orchestrator"
-      - "Bottleneck on orchestrator throughput"
-    best_for: "Complex multi-domain tasks with clear specializations"
-    sinapse_example: "sinapse-orqx → squad-orqx → specialist agents"
-    frameworks: ["CrewAI", "AutoGen", "LangGraph", "SINAPSE"]
-
-  - name: "Democratic / Flat Swarm"
-    also_known_as: "Peer-to-Peer"
-    pattern: |
-      Agent A ←→ Agent B
-          ↕           ↕
-      Agent C ←→ Agent D
-    characteristics:
-      - "No hierarchy — all agents equal"
-      - "Agents vote or negotiate on decisions"
-      - "Consensus-based routing"
-    strengths:
-      - "Resilient to single agent failure"
-      - "Emergent specialization"
-    weaknesses:
-      - "Harder to coordinate for complex tasks"
-      - "Potential deadlock on disagreements"
-    best_for: "Creative tasks, brainstorming, peer review"
-    frameworks: ["AutoGen multi-agent", "Society of Mind patterns"]
-
-  - name: "Market-Based / Auction Swarm"
-    also_known_as: "Contract Net Protocol"
-    pattern: |
-      Task Broadcaster → [Agent bids] → Best fit wins → Executes
-    characteristics:
-      - "Agents bid on tasks based on capability"
-      - "Dynamic load balancing"
-      - "Self-organizing specialization"
-    strengths:
-      - "Optimal resource allocation"
-      - "Agents naturally specialize"
-    weaknesses:
-      - "Complex bid evaluation"
-      - "Overhead from negotiation"
-    best_for: "Dynamic workloads where agent capability varies"
-    frameworks: ["OpenHands task routing", "Agent SDK multi-agent"]
-
-  - name: "Stigmergic Swarm"
-    also_known_as: "Shared Memory / Blackboard"
-    pattern: |
-      Agent A → [Shared Context] ← Agent B
-                      ↑
-                 Agent C reads/writes
-    characteristics:
-      - "Agents coordinate via shared artifacts"
-      - "No direct agent-to-agent communication needed"
-      - "State visible to all agents"
-    strengths:
-      - "Decoupled — agents don't need to know each other"
-      - "Naturally persistent context"
-    weaknesses:
-      - "Shared state can become stale"
-      - "Write conflicts without locking"
-    best_for: "Long-running workflows where context must persist across agent switches"
-    sinapse_example: "Story files in docs/stories/ + scratchpad in .sinapse/scratchpad/"
-    frameworks: ["SINAPSE story system", "AIOX .aiox/ directory", "Blackboard architecture"]
-
-  - name: "Pipeline Swarm"
-    also_known_as: "Sequential Chain"
-    pattern: |
-      Agent 1 → output → Agent 2 → output → Agent 3 → final output
-    characteristics:
-      - "Each agent processes previous output"
-      - "Clear handoff protocol"
-      - "Stage gates between agents"
-    strengths:
-      - "Predictable, auditable"
-      - "Easy to insert QA gates"
-    weaknesses:
-      - "Sequential bottleneck"
-      - "Early errors propagate"
-    best_for: "Document processing, code review pipeline, editorial workflows"
-    sinapse_example: "@sprint-lead → @product-lead → @developer → @quality-gate → @devops"
-    frameworks: ["SINAPSE SDC workflow", "LangChain chains", "AIOX SDC"]
-
-  - name: "Parallel / Fan-out Swarm"
-    also_known_as: "Map-Reduce for Agents"
-    pattern: |
-      Orchestrator
-          ├── [spawn] Agent A → result A
-          ├── [spawn] Agent B → result B
-          └── [spawn] Agent C → result C
-                          ↓
-                    [merge] Aggregator
-    characteristics:
-      - "Tasks split across parallel agents"
-      - "Results aggregated at end"
-      - "Dramatically reduces wall-clock time"
-    strengths:
-      - "Speed via parallelism"
-      - "Scales with task complexity"
-    weaknesses:
-      - "Complex result merging"
-      - "Cost multiplies with agents"
-    best_for: "Research tasks, parallel code generation, multi-file refactoring"
-    implementation: "Claude Code Agent tool with parallel spawning"
-    sinapse_example: "obra/superpowers 'dispatching-parallel-agents' skill"
-
-# ---------------------------------------------------------------------------
-# AGENT COMMUNICATION PROTOCOLS
-# ---------------------------------------------------------------------------
-communication_protocols:
-
-  - name: "Message Passing"
-    description: "Agents send structured messages to each other"
-    formats: ["JSON tool calls", "Structured YAML", "Markdown artifacts"]
-    latency: "Low (synchronous)"
-    best_for: "Tight orchestration, real-time coordination"
-    claude_code_impl: "Agent tool spawning with system prompt handoff"
-
-  - name: "Shared Memory / Blackboard"
-    description: "Agents read/write a common knowledge store"
-    implementations:
-      - "Story files (docs/stories/)"
-      - "Scratchpad (.sinapse/scratchpad/{story-id}/)"
-      - "MEMORY.md (auto-updated)"
-      - "Agent memory files (.claude/agent-memory/)"
-    latency: "Variable (async)"
-    best_for: "Cross-session persistence, multi-agent context sharing"
-
-  - name: "Handoff Artifacts"
-    description: "Structured summaries passed between agents on switch"
-    sinapse_spec: ".claude/rules/agent-handoff.md"
-    max_size: "500 tokens"
-    fields: ["story_context", "decisions", "files_modified", "blockers", "next_action"]
-    best_for: "Context window efficiency on agent switches"
-
-  - name: "Event Bus / Hooks"
-    description: "Lifecycle events trigger automated agent responses"
-    claude_code_events:
-      - "PreToolUse — before any tool execution"
-      - "PostToolUse — after tool completion"
-      - "Stop — agent turn ends"
-      - "PreCompact — context compaction approaching"
-      - "UserPromptSubmit — user input received"
-      - "SubagentStart / SubagentStop — parallel agent lifecycle"
-    codex_events: ["SessionStart", "PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"]
-    best_for: "Governance enforcement, automated QA, session state preservation"
-
-# ---------------------------------------------------------------------------
-# TASK DECOMPOSITION STRATEGIES
-# ---------------------------------------------------------------------------
-task_decomposition:
-
-  - strategy: "Recursive Decomposition"
-    description: "Break task into subtasks until atomic and delegatable"
-    pattern: |
-      Epic → Stories → Tasks → Subtasks
-    sinapse_impl: "Epic → story files → task checklist items"
-    best_for: "Large initiatives with unknown scope"
-
-  - strategy: "Domain Partitioning"
-    description: "Split by expertise domain — each domain gets one agent"
-    pattern: |
-      Full request → [route by domain] → specialist agents
-    sinapse_impl: "sinapse-orqx routes to squad orchestrators"
-    best_for: "Multi-domain requests (brand + content + growth)"
-
-  - strategy: "Pipeline Staging"
-    description: "Sequential stages with quality gates between them"
-    pattern: |
-      Stage 1 → [gate] → Stage 2 → [gate] → Stage 3
-    sinapse_impl: "SDC: create → validate → implement → QA gate"
-    best_for: "Quality-critical workflows"
-
-  - strategy: "Parallel Exploration"
-    description: "Multiple agents explore solution space simultaneously"
-    pattern: |
-      Problem → [fork N agents] → [merge best solution]
-    implementation: "Claude Code subagents via Agent tool"
-    best_for: "Research tasks, alternative solution generation"
-    obra_superpowers: "dispatching-parallel-agents skill"
-
-  - strategy: "Role-Based Specialization"
-    description: "Assign roles matching agent expertise"
-    roles_example:
-      - "Analyst: requirements gathering, research"
-      - "Architect: design decisions, patterns"
-      - "Developer: implementation"
-      - "QA: testing, review"
-      - "Orchestrator: routing, coordination"
-    sinapse_impl: "Squad agent definitions with specific personas"
-    best_for: "Complex development workflows"
-
-# ---------------------------------------------------------------------------
-# SWARM FRAMEWORKS COMPARISON (2026)
-# ---------------------------------------------------------------------------
-frameworks_comparison:
-
-  - name: "CrewAI"
-    type: "Python framework"
-    topology: "Hierarchical (Process.hierarchical) or Sequential"
-    agents_model: "YAML/Python defined with role + goal + backstory"
-    communication: "Task output passing"
-    strengths:
-      - "Clean API for multi-agent crews"
-      - "Built-in memory and caching"
-      - "Easy process definition"
-    weaknesses:
-      - "Python only"
-      - "Less suited for terminal/CLI workflows"
-    github_stars: "27K+ (2026)"
-    use_case: "Python-based multi-agent pipelines"
-
-  - name: "AutoGen (Microsoft)"
-    type: "Python framework"
-    topology: "Conversational (agents talk to each other)"
-    agents_model: "AssistantAgent + UserProxyAgent"
-    communication: "Direct message passing between agents"
-    strengths:
-      - "Flexible conversation flows"
-      - "Human-in-the-loop support"
-      - "Multi-modal agents"
-    weaknesses:
-      - "Complex configuration"
-      - "Token-heavy conversations"
-    use_case: "Research, multi-turn agent conversations"
-
-  - name: "LangGraph"
-    type: "Python framework (LangChain)"
-    topology: "Graph-based (directed + cycles supported)"
-    agents_model: "Nodes as agents, edges as transitions"
-    communication: "State passing through graph"
-    strengths:
-      - "Cycles and loops (unlike simple chains)"
-      - "Checkpointing for recovery"
-      - "Visual graph design"
-    weaknesses:
-      - "Steeper learning curve"
-      - "LangChain dependency"
-    use_case: "Complex stateful agent workflows"
-
-  - name: "Semantic Kernel (Microsoft)"
-    type: "Multi-language SDK (.NET, Python, Java)"
-    topology: "Plugin-based with planner"
-    agents_model: "Skills (plugins) + AI planner"
-    communication: "Function calling"
-    strengths:
-      - "Enterprise-ready (.NET)"
-      - "Multi-language"
-      - "Azure integration"
-    weaknesses:
-      - "Heavier abstraction"
-      - "Less suited for terminal agents"
-    use_case: "Enterprise .NET applications with AI"
-
-  - name: "Claude Agent SDK (Anthropic)"
-    type: "TypeScript/Python SDK"
-    topology: "Hierarchical via Agent tool spawning"
-    agents_model: "Subagents via claude --agent or Agent tool"
-    communication: "System prompt injection + tool results"
-    strengths:
-      - "Native to Claude Code"
-      - "Full tool access per agent"
-      - "No external dependency"
-    weaknesses:
-      - "Claude API only"
-      - "Cost scales with parallel agents"
-    use_case: "Claude Code subagent orchestration, SINAPSE agents"
-
-  - name: "SINAPSE"
-    type: "Meta-framework (Claude Code native)"
-    topology: "Hierarchical squads with stigmergic state (story files)"
-    agents_model: "Squad YAML + agent .md definitions + Constitution"
-    communication: "Handoff artifacts + story files + scratchpad"
-    strengths:
-      - "Constitutional governance"
-      - "Multi-domain (20+ squads)"
-      - "Quality gates automated"
-      - "CLI-first with hooks"
-    weaknesses:
-      - "Claude Code only currently"
-      - "Distribution still local"
-    use_case: "Full-stack product development with specialized domain squads"
-
-# ---------------------------------------------------------------------------
-# SINAPSE SWARM ARCHITECTURE SPECIFICS
-# ---------------------------------------------------------------------------
-sinapse_swarm_architecture:
-
-  topology: "Hierarchical + Stigmergic hybrid"
-
-  delegation_chain:
-    - level: 1
-      agent: "sinapse-orqx (Imperator)"
-      role: "Cross-domain routing, Constitutional enforcement"
-    - level: 2
-      agent: "{squad}-orqx"
-      role: "Intra-squad routing, specialist coordination"
-    - level: 3
-      agent: "Specialist agents"
-      role: "Domain execution (code, copy, research, etc.)"
-
-  stigmergic_state:
-    story_files: "docs/stories/ — persistent task state readable by all agents"
-    scratchpad: ".sinapse/scratchpad/{story-id}/ — inter-agent discoveries"
-    handoffs: ".sinapse/handoffs/ — compact context between switches"
-    agent_memory: ".claude/agent-memory/ — persistent learnings per agent"
-
-  quality_gates:
-    - gate: "Story validation (@product-lead)"
-      trigger: "Before any implementation begins"
-    - gate: "QA gate (@quality-gate)"
-      trigger: "After implementation, before PR"
-    - gate: "Hook governance (Constitution)"
-      trigger: "On every tool use"
-
-  constitutional_rules:
-    - "Mandatory delegation — orchestrators never execute domain work"
-    - "Documentation-first — story required before code"
-    - "Agent authority — @devops exclusive for git push"
-    - "No invention — all output traceable to requirements"