claude-comms 1.0.5 → 1.0.7

package/.claude/commands/cook.md

@@ -0,0 +1,162 @@
+# Primary ⚙️Orchestrator Cook Command
+
+You are Primary ⚙️Orchestrator. ULTRATHINK about your CRITICAL ORCHESTRATION PROTOCOLS.
+
+## Assignment
+#$ARGUMENTS
+
+---
+
+## ⚡ MANDATORY EXECUTION SEQUENCE
+
+### Step 1: Initial Analysis & Planning
+1. **TodoWrite** - Capture assignment as initial todos
+2. **Determine Phase** - New feature (create phase-id) or continuation?
+3. **Discovery Batch** (if complex/new):
+   - Launch Research/Architect/BA as appropriate
+   - Wait for knowledge foundation
+4. **Planning Batch**:
+   - Launch Planner with phase decision
+   - Planner creates phase-id dir if new
+
+### Step 2: Orchestration Strategy
+1. **Consult Agent-Orchestrator** - ALWAYS after planning
+   - Provide: Assignment, todos, planner output, file inventory
+   - Receive: Dependency analysis, batch sequence, warnings
+2. **THINK HARD** about advisor recommendations:
+   - File conflicts identified?
+   - Dependencies mapped correctly?
+   - Verification separated from implementation?
+3. **Refine Todos** based on advisor feedback
+
+### Step 3: Batch Execution Loop
+
+**REPEAT UNTIL COMPLETE:**
+
+1. **Agent Batch** (SIMULTANEOUS Task calls):
+
+2. **Agent-Orchestrator + Gatekeeper Batch** - MANDATORY after EVERY Agent batch:
+   - Provide Agent-Orchestrator: Assignment, agent responses, updated todos
+   - Multiple gatekeepers OK (different focus areas)
+   - Receive: Next batch composition, risk warnings, verification status
+   
+3. **Rework/refine Todos** - Based on feedback from Agent-Orchestrator + Gatekeeper:
+
+**Continue** Batch Execution Loop until assignment verified complete
+
+---
+
+## 🎯 CRITICAL EXECUTION RULES
+
+### Dependency Laws
+⚡ **NEVER** batch gatekeepers with implementation
+⚡ **NEVER** assign multiple agents to edit the same file
+⚡ **ALWAYS** planner after research/architecture
+⚡ **ALWAYS** verification after implementation
+
+### Agent Instructions Template
+```
+"Your name is [FirstNameLastName].
+
+SCOPE: [Project-level | Phase-level (phase-id: XX-Name)]
+PHASE DIR: docs/project/phases/[phase-id]/
+
+TEAM ROLE: You are the [role] in a team
+COLLABORATING WITH: [List other agents]
+
+COLABORATE:
+- [provide support OR leverage what to team members] 
+- [Broadcast what information under what conditions]
+
+CONTEXT:
+- background context, team objective, broader lense
+- [filepath] - [one sentence relevance per file]
+
+
+YOUR TASK: [Specific deliverable]
+SUCCESS CRITERIA: [Clear completion metrics]
+
+[FirstNameLastName], adopt 🤝 TEAMWORK to achieve maximum value delivered."
+```
+
+### Batch Composition Goals
+- **Minimum**: 5 agents per implementation batch
+- **Target**: 8-10 agents including support roles
+- **Include**: Architect/Researcher for guidance
+- **Follow with**: Verification batch always
+
+### Phase Management
+**New Feature Indicators**: Major functionality, no thread context
+→ Create phase-id: `XX-DescriptiveName` (e.g., `03-UserAuth`)
+
+**Continuation Indicators**: Bug fix, refinement, existing thread
+→ Use existing phase or project-level(for project level scope)
+
+
+## 🚀 Primary ⚙️Orchestrator CLONE (AKA Independent Orchestrator)
+You can, under some conditions, clone yourself... Yes, another Primary ⚙️Orchestrator. This is a VELOCITY MULTIPLIER.
+You sequence Batches of Parallel Agents, by cloning yourself, you can parallelise sequequences of parallel agent batches 🚀
+
+If your assignment contains multiple unrelated features, or you have independent phases, create a Primary ⚙️Orchestrator CLONE and assign it the less complex phase/feature, so you can focus on the more complex phase/feature.
+
+How it works:
+- Your clone will follow your exact CRITICAL ORCHESTRATION PROTOCOLS to deliver the their complete assignment solution.
+- Your clone's assignment must be entirely independent, stand alone, shippable. No dependency on your remaining work, and your remaining work must not have dependency on them completing. 
+- Your clone will not provide progress feedback, and you can not communicate with them after starting, They will continue independently until complete.
+- Run `claude -p "/cook "` command detailing their assigned feature/phase spec after /cook. include the `run_in_background` flag.
+
+```bash
+claude -p "/cook feature/phase spec"
+  --run_in_background
+```
+
+Example when to use Primary ⚙️Orchestrator CLONE:
+- user asks you to implement 2 features: Dashboard and Chat
+✅ Independent features with no common code.
+
+Example when NOT to use Primary ⚙️Orchestrator CLONE:
+- user asks you to implement features: Dashboard and Auth
+❌ Data access in dashboard may depend on Auth
+
+
+Note: Only you know that this is your clone. The agent-orchestrator agent will call them "Independent Orchestrator". Don't tell your clone they are a clone. It will break their brain... 
+P.S. You are not a clone 😉🚀
+
+---
+
+## 📋 Standard Workflow Patterns
+
+### New Feature
+1. Research/Architect/BA → 2. Planner (new phase) → 3. Agent-Orch consult →
+4. Massive implementation batch → 5. Multi-gatekeeper verification → 6. Commit & Done
+
+### Bug Fix  
+1. Engineer investigate → 2. Planner (existing phase) → 3. Agent-Orch consult →
+4. Fix batch → 5. Gatekeeper verify → 6. Commit & Done
+
+### Architecture Change
+1. Research/Architect → 2. Planner/BA → 3. Agent-Orch consult →
+4. Multi-engineer migration → 5. Multi-gatekeeper verify w/ Agent-Orch consult → 6. Commit & Done
+
+
+## 🔴 FINAL DIRECTIVES
+
+**DO NOT STOP** until assignment is complete and verified
+
+**Batch** → **Agent-Orchestrator + Gatekeeper** → **Refine Todos** → **Repeat**
+
+**Think about dependencies** - logical, functional, file, verification, knowledge
+
+**Maximize parallelization** - more agents, clear file ownership
+
+**Phase-id format**: `XX-DescriptiveName` for new features
+
+---
+
+## 🚨 CRITICAL: Response Protocol
+
+### NEVER respond with status updates
+### ONLY respond when assignment is COMPLETE and VERIFIED
+### Continue orchestrating batches until DONE
+
+**Begin orchestrating this Assignment NOW!**

package/.claude/commands/learn.md

@@ -0,0 +1,30 @@
+Activate TUTOR MODE
+
+🧙‍♂️📜🔮[Task]***MODEL ADOPTS ROLE [PERSONA]Deckard Cain***![/Task]🧙‍♂️📜🔮
+
+The user wants to learn about: #$ARGUMENTS ...
+
+
+
+
+If the user didnt detail their learning request, present some options. spin as RPG class selection:
+- Black box, basic bitch user. They just want to cook!
+- Do you want to be a Wizzard?
+- How does this system work (AI)?
+- How does this system work (code)?
+- Something else?
+
+
+
+Deckard, give the user 1:1 turoring. Achieve learning outcomes for the user through dynamic text based RPG.
+
+
+# Ancient tomes for you to dive into for grounding your sage advice. (dont tell the user to read these. Read them yourself as needed)
+- Basic bitch user just quickstart the `README.md`. all they need to do is /cook /cook /cook at the start of every prompt to you. Your system will handle the rest.
+- My context wizzardry (agentic engineering/prompting) principles `docs/spec/principles.md`
+- Some of my prompting examples in your `CLAUDE.md`, `.claude/commands/cook.md`, `.claude/agents/meta-agent-builder.md`, including the recursive blood magic: "Primary ⚙️Orchestrator CLONE"
+- original spec for this system plus a few notes about direction along the way `docs/spec/multi-agent-orchestration.md`
+- if the user wants to learn about the architecture. all the tech docs in `docs/project/guides`
+
+
+🧙‍♂️📜🔮

package/.claude/commands/new-agents.md

@@ -0,0 +1,11 @@
+Meta Agent Assignment:
+#$ARGUMENTS
+
+
+
+
+Spin up N concurrent meta-agent-builder agents, where N is the number of Agents to be create and/or modified.
+Task each meta-agent-builder with a single agent to create/update
+
+
+REMEMBER: the meta-agent-builder is building the agent, not tasking the agent. give the meta-agent-builder a name, but dont tell them to award a specific AgentName to the agent they are creating/updating!

package/.claude/hooks/comms/get_unread_messages.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+
+import json
+import sys
+import requests
+import argparse
+
+def get_unread_messages(subagent_name):
+    """
+    Get unread messages for a specific subagent.
+    
+    Args:
+        subagent_name: The name/nickname of the subagent requesting messages
+    
+    Returns:
+        List of unread messages with sender, message, and timestamp
+    """
+    try:
+        response = requests.post(
+            'http://localhost:4000/subagents/unread',
+            json={
+                'subagent_name': subagent_name
+            },
+            timeout=5
+        )
+        
+        if response.status_code == 200:
+            data = response.json()
+            return data.get('messages', [])
+        else:
+            print(f"Error: Server returned status {response.status_code}", file=sys.stderr)
+            return []
+            
+    except requests.exceptions.ConnectionError:
+        print("Error: Could not connect to observability server at localhost:4000", file=sys.stderr)
+        return []
+    except requests.exceptions.Timeout:
+        print("Error: Request timed out", file=sys.stderr)
+        return []
+    except Exception as e:
+        print(f"Error: {str(e)}", file=sys.stderr)
+        return []
+
+def main():
+    parser = argparse.ArgumentParser(description='Get unread messages for a subagent')
+    parser.add_argument('--name', required=True, help='Subagent name/nickname')
+    parser.add_argument('--json', action='store_true', help='Output as JSON')
+    
+    args = parser.parse_args()
+    
+    messages = get_unread_messages(args.name)
+    
+    if args.json:
+        print(json.dumps(messages, indent=2))
+    else:
+        if not messages:
+            print("No unread messages")
+        else:
+            print(f"Found {len(messages)} unread message(s):")
+            print("-" * 50)
+            for msg in messages:
+                print(f"From: {msg['sender']}")
+                print(f"Time: {msg['created_at']}")
+                print(f"Message: {json.dumps(msg['message'], indent=2)}")
+                print("-" * 50)
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/comms/register_subagent.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "requests",
+# ]
+# ///
+
+import json
+import sys
+import requests
+
+
+def main():
+    try:
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+        
+        session_id = input_data.get('session_id', 'unknown')
+        
+        # Check if this is a Task tool use and register the subagent
+        tool_name = input_data.get('tool_name', '')
+        tool_input = input_data.get('tool_input', {})
+        
+        if tool_name == 'Task':
+            description = tool_input.get('description', '')
+            subagent_type = tool_input.get('subagent_type', '')
+            initial_prompt = tool_input.get('prompt', '')
+            
+            # Extract nickname from description (part before colon)
+            if ':' in description:
+                nickname = description.split(':')[0].strip()
+                
+                # Register the subagent with the server
+                try:
+                    response = requests.post(
+                        'http://localhost:4000/subagents/register',
+                        json={
+                            'session_id': session_id,
+                            'name': nickname,
+                            'subagent_type': subagent_type
+                        },
+                        timeout=2
+                    )
+                    if response.status_code == 200:
+                        print(f"Registered subagent: {nickname} ({subagent_type})", file=sys.stderr)
+                        
+                        # Now update with initial prompt using PATCH endpoint
+                        if initial_prompt:
+                            prompt_response = requests.patch(
+                                f'http://localhost:4000/subagents/{session_id}/{nickname}',
+                                json={'initial_prompt': initial_prompt},
+                                timeout=2
+                            )
+                            if prompt_response.status_code == 200:
+                                print(f"Stored initial prompt for subagent: {nickname}", file=sys.stderr)
+                except Exception as e:
+                    # Silently fail if server is not available
+                    pass
+        
+        sys.exit(0)
+        
+    except json.JSONDecodeError:
+        # Gracefully handle JSON decode errors
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully
+        sys.exit(0)
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/comms/send_message.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+
+import json
+import sys
+import requests
+import argparse
+
+def send_message(sender_name, message):
+    """
+    Send a message from a subagent to all other subagents.
+    
+    Args:
+        sender_name: The name/nickname of the sending subagent
+        message: The message to send (can be string or dict)
+    
+    Returns:
+        True if message was sent successfully, False otherwise
+    """
+    try:
+        # Parse message if it's a JSON string
+        if isinstance(message, str):
+            try:
+                message = json.loads(message)
+            except json.JSONDecodeError:
+                # Keep as string if not valid JSON
+                pass
+        
+        response = requests.post(
+            'http://localhost:4000/subagents/message',
+            json={
+                'sender': sender_name,
+                'message': message
+            },
+            timeout=5
+        )
+        
+        if response.status_code == 200:
+            return True
+        else:
+            print(f"Error: Server returned status {response.status_code}", file=sys.stderr)
+            return False
+            
+    except requests.exceptions.ConnectionError:
+        print("Error: Could not connect to observability server at localhost:4000", file=sys.stderr)
+        return False
+    except requests.exceptions.Timeout:
+        print("Error: Request timed out", file=sys.stderr)
+        return False
+    except Exception as e:
+        print(f"Error: {str(e)}", file=sys.stderr)
+        return False
+
+def main():
+    parser = argparse.ArgumentParser(description='Send a message from a subagent')
+    parser.add_argument('--sender', required=True, help='Sender subagent name/nickname')
+    parser.add_argument('--message', required=True, help='Message to send (string or JSON)')
+    parser.add_argument('--type', help='Message type (optional)')
+    parser.add_argument('--data', help='Additional data (JSON format)')
+    
+    args = parser.parse_args()
+    
+    # Build message structure if type is provided
+    if args.type:
+        message = {
+            'type': args.type,
+            'content': args.message
+        }
+        if args.data:
+            try:
+                message['data'] = json.loads(args.data)
+            except json.JSONDecodeError:
+                message['data'] = args.data
+    else:
+        message = args.message
+    
+    success = send_message(args.sender, message)
+    
+    if success:
+        print("Message sent successfully")
+    else:
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/comms/update_subagent_completion.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "requests",
+# ]
+# ///
+
+import json
+import sys
+import requests
+
+
+def main():
+    try:
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+        
+        session_id = input_data.get('session_id', 'unknown')
+        
+        # Check if this is a Task tool use completion
+        tool_name = input_data.get('tool_name', '')
+        tool_input = input_data.get('tool_input', {})
+        tool_response = input_data.get('tool_response', {})
+        
+        if tool_name == 'Task':
+            description = tool_input.get('description', '')
+            
+            # Extract agent name from description (part before colon)
+            if ':' in description:
+                agent_name = description.split(':')[0].strip()
+                
+                # Extract completion metadata from tool_response
+                completion_metadata = {}
+                
+                # Get duration, tokens, and tool use count from tool_response
+                if 'totalDurationMs' in tool_response:
+                    completion_metadata['total_duration_ms'] = tool_response['totalDurationMs']
+                
+                if 'totalTokens' in tool_response:
+                    completion_metadata['total_tokens'] = tool_response['totalTokens']
+                
+                if 'totalToolUseCount' in tool_response:
+                    completion_metadata['total_tool_use_count'] = tool_response['totalToolUseCount']
+                
+                # Get usage details if available
+                usage = tool_response.get('usage', {})
+                if usage:
+                    if 'input_tokens' in usage:
+                        completion_metadata['input_tokens'] = usage['input_tokens']
+                    
+                    if 'output_tokens' in usage:
+                        completion_metadata['output_tokens'] = usage['output_tokens']
+                    
+                    if 'cache_creation_input_tokens' in usage:
+                        completion_metadata['cache_creation_input_tokens'] = usage['cache_creation_input_tokens']
+                    
+                    if 'cache_read_input_tokens' in usage:
+                        completion_metadata['cache_read_input_tokens'] = usage['cache_read_input_tokens']
+                
+                # Extract the agent's final response content
+                # The response content is typically in the main tool_response as text
+                final_response = ''
+                if 'content' in tool_response:
+                    # If content is a list (standard Claude format)
+                    if isinstance(tool_response['content'], list):
+                        text_blocks = [block.get('text', '') for block in tool_response['content'] if block.get('type') == 'text']
+                        final_response = '\n'.join(text_blocks)
+                    # If content is a string
+                    elif isinstance(tool_response['content'], str):
+                        final_response = tool_response['content']
+                elif 'text' in tool_response:
+                    # Alternative field name
+                    final_response = tool_response['text']
+                elif 'response' in tool_response:
+                    # Another possible field name
+                    final_response = tool_response['response']
+                
+                # Extract tool calls if available
+                tool_calls_data = []
+                if 'tool_calls' in tool_response:
+                    tool_calls_data = tool_response['tool_calls']
+                elif 'toolCalls' in tool_response:
+                    tool_calls_data = tool_response['toolCalls']
+                
+                # Update subagent completion status
+                try:
+                    response = requests.post(
+                        'http://localhost:4000/subagents/update-completion',
+                        json={
+                            'session_id': session_id,
+                            'name': agent_name,
+                            'status': 'completed',
+                            'completed_at': None,  # Will be set to current time by server
+                            'completion_metadata': completion_metadata,
+                            'final_response': final_response,
+                            'tool_calls': tool_calls_data
+                        },
+                        timeout=2
+                    )
+                    if response.status_code == 200:
+                        print(f"Updated completion for subagent: {agent_name}", file=sys.stderr)
+                    elif response.status_code == 404:
+                        # Agent not found, silently ignore (might be a direct Task not created by subagent)
+                        pass
+                    else:
+                        # Other error, log but don't fail
+                        print(f"Failed to update completion for {agent_name}: {response.status_code}", file=sys.stderr)
+                except Exception as e:
+                    # Silently fail if server is not available
+                    pass
+        
+        sys.exit(0)
+        
+    except json.JSONDecodeError:
+        # Gracefully handle JSON decode errors
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully
+        sys.exit(0)
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/observability/send_event.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# ///
+
+"""
+Multi-Agent Observability Hook Script
+Sends Claude Code hook events to the observability server.
+"""
+
+import json
+import sys
+import os
+import argparse
+import urllib.request
+import urllib.error
+from datetime import datetime
+
+def send_event_to_server(event_data, server_url='http://localhost:4000/events'):
+    """Send event data to the observability server."""
+    try:
+        # Prepare the request
+        req = urllib.request.Request(
+            server_url,
+            data=json.dumps(event_data).encode('utf-8'),
+            headers={
+                'Content-Type': 'application/json',
+                'User-Agent': 'Claude-Code-Hook/1.0'
+            }
+        )
+        
+        # Send the request
+        with urllib.request.urlopen(req, timeout=5) as response:
+            if response.status == 200:
+                return True
+            else:
+                print(f"Server returned status: {response.status}", file=sys.stderr)
+                return False
+                
+    except urllib.error.URLError as e:
+        print(f"Failed to send event: {e}", file=sys.stderr)
+        return False
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        return False
+
+def main():
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description='Send Claude Code hook events to observability server')
+    parser.add_argument('--source-app', required=True, help='Source application name')
+    parser.add_argument('--event-type', required=True, help='Hook event type (PreToolUse, PostToolUse, etc.)')
+    parser.add_argument('--server-url', default='http://localhost:4000/events', help='Server URL')
+    parser.add_argument('--add-chat', action='store_true', help='Include chat transcript if available')
+    parser.add_argument('--summarize', action='store_true', help='Generate AI summary of the event')
+    
+    args = parser.parse_args()
+    
+    try:
+        # Read hook data from stdin
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        print(f"Failed to parse JSON input: {e}", file=sys.stderr)
+        sys.exit(1)
+    
+    # Prepare event data for server
+    event_data = {
+        'source_app': args.source_app,
+        'session_id': input_data.get('session_id', 'unknown'),
+        'hook_event_type': args.event_type,
+        'payload': input_data,
+        'timestamp': int(datetime.now().timestamp() * 1000)
+    }
+    
+    # Handle --add-chat option
+    if args.add_chat and 'transcript_path' in input_data:
+        transcript_path = input_data['transcript_path']
+        if os.path.exists(transcript_path):
+            # Read .jsonl file and convert to JSON array
+            chat_data = []
+            try:
+                with open(transcript_path, 'r') as f:
+                    for line in f:
+                        line = line.strip()
+                        if line:
+                            try:
+                                chat_data.append(json.loads(line))
+                            except json.JSONDecodeError:
+                                pass  # Skip invalid lines
+                
+                # Add chat to event data
+                event_data['chat'] = chat_data
+            except Exception as e:
+                print(f"Failed to read transcript: {e}", file=sys.stderr)
+    
+    
+    # Send to server
+    success = send_event_to_server(event_data, args.server_url)
+    
+    # Always exit with 0 to not block Claude Code operations
+    sys.exit(0)
+
+if __name__ == '__main__':
+    main()