claude-comms 1.0.38 → 1.0.40

package/.agents/repo.md

@@ -12,4 +12,7 @@ VALIDATE by Running required commands — all must pass without warnings or erro
 you can access the client on `http://localhost:3000/` using the UAT toolkit
 
 ## Documentation Protocol
-Guard the doc hierarchy: specs in `docs/project/spec/` remain the source of truth (Businesslogic, data dictionary, data flows, tech guide, industry references); guides in `docs/project/guides/` capture evolving process; phase folders (`docs/project/phases/XX-Name/`) store live work packages and notes. Update whichever doc you rely on as soon as the code diverges.
+Guard the doc hierarchy: specs in `docs/project/spec/` remain the source of truth (Businesslogic, data dictionary, data flows, tech guide, industry references); guides in `docs/project/guides/` capture evolving process; phase folders (`docs/project/phases/XX-Name/`) store live work packages and notes. Update whichever doc you rely on as soon as the code diverges.
+
+## PRE Deployment
+`vercel build --yes` must pass otherwise CI/CD will FAIL!

package/.agents/tools/chrome-devtools/browsertools.py

@@ -21,20 +21,38 @@ import json
 import os
 import signal
 import sys
+import time
+import uuid
 from pathlib import Path
 from typing import Any, Dict, Optional
 
 # State directory
 STATE_DIR = Path.home() / ".browsertools"
-SOCKET_PATH = STATE_DIR / "daemon.sock"
-PID_FILE = STATE_DIR / "daemon.pid"
 CONFIG_FILE = STATE_DIR / "config.json"
+INACTIVITY_TIMEOUT = 600  # 10 minutes
 
 # Global daemon state
 mcp_proc = None
 mcp_reader = None
 mcp_writer = None
 pending_requests = {}  # msg_id -> response_future
+last_activity_time = time.time()
+current_instance_id = None
+
+
+def generate_instance_id() -> str:
+    """Generate 8-char hex instance ID."""
+    return uuid.uuid4().hex[:8]
+
+
+def get_socket_path(instance_id: str) -> Path:
+    """Get socket path for instance."""
+    return STATE_DIR / f"daemon-{instance_id}.sock"
+
+
+def get_pid_file(instance_id: str) -> Path:
+    """Get PID file path for instance."""
+    return STATE_DIR / f"daemon-{instance_id}.pid"
 
 
 def ensure_state_dir():
@@ -42,22 +60,39 @@ def ensure_state_dir():
     STATE_DIR.mkdir(exist_ok=True)
 
 
-def get_daemon_pid() -> Optional[int]:
-    """Get PID of running daemon."""
-    if not PID_FILE.exists():
+def get_daemon_pid(instance_id: str) -> Optional[int]:
+    """Get PID of running daemon for instance."""
+    pid_file = get_pid_file(instance_id)
+    if not pid_file.exists():
         return None
     try:
-        pid = int(PID_FILE.read_text().strip())
+        pid = int(pid_file.read_text().strip())
         os.kill(pid, 0)  # Check if alive
         return pid
     except (ProcessLookupError, ValueError):
-        PID_FILE.unlink(missing_ok=True)
+        pid_file.unlink(missing_ok=True)
         return None
 
 
-def is_daemon_running() -> bool:
-    """Check if daemon is running."""
-    return get_daemon_pid() is not None and SOCKET_PATH.exists()
+def is_daemon_running(instance_id: str) -> bool:
+    """Check if daemon is running for instance."""
+    return get_daemon_pid(instance_id) is not None and get_socket_path(instance_id).exists()
+
+
+def get_all_instances() -> list[str]:
+    """Get list of all running instance IDs."""
+    instances = []
+    if not STATE_DIR.exists():
+        return instances
+    for pid_file in STATE_DIR.glob("daemon-*.pid"):
+        instance_id = pid_file.stem.replace("daemon-", "")
+        if is_daemon_running(instance_id):
+            instances.append(instance_id)
+        else:
+            # Clean up stale files
+            pid_file.unlink(missing_ok=True)
+            get_socket_path(instance_id).unlink(missing_ok=True)
+    return instances
 
 
 def load_config() -> Dict[str, Any]:
@@ -145,7 +180,10 @@ async def read_mcp_responses():
 
 async def handle_client(reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
     """Handle a client connection."""
-    global mcp_writer, pending_requests
+    global mcp_writer, pending_requests, last_activity_time
+
+    # Update activity timestamp
+    last_activity_time = time.time()
 
     try:
         while True:
@@ -222,15 +260,32 @@ async def shutdown_mcp():
         print(f"Error during shutdown: {e}", file=sys.stderr)
 
 
-async def run_daemon():
+async def inactivity_monitor(shutdown_callback):
+    """Monitor for inactivity and trigger shutdown after timeout."""
+    global last_activity_time
+
+    while True:
+        await asyncio.sleep(10)  # Check every 10 seconds for responsive timeout
+        inactive_time = time.time() - last_activity_time
+        if inactive_time > INACTIVITY_TIMEOUT:
+            await shutdown_callback()
+            return
+
+
+async def run_daemon(instance_id: str):
     """Run the persistent daemon."""
-    global mcp_proc, mcp_reader, mcp_writer
+    global mcp_proc, mcp_reader, mcp_writer, current_instance_id, last_activity_time
 
+    current_instance_id = instance_id
+    last_activity_time = time.time()
     ensure_state_dir()
 
+    socket_path = get_socket_path(instance_id)
+    pid_file = get_pid_file(instance_id)
+
     # Clean up old socket if exists
-    if SOCKET_PATH.exists():
-        SOCKET_PATH.unlink()
+    if socket_path.exists():
+        socket_path.unlink()
 
     # Load config
     config = load_config()
@@ -255,29 +310,38 @@ async def run_daemon():
     mcp_writer = mcp_proc.stdin
 
     # Write PID file
-    PID_FILE.write_text(str(os.getpid()))
+    pid_file.write_text(str(os.getpid()))
 
-    print(f"Starting Unix socket server at {SOCKET_PATH}...", file=sys.stderr)
+    print(f"Starting Unix socket server at {socket_path}...", file=sys.stderr)
 
     # Start Unix socket server
     server = await asyncio.start_unix_server(
         handle_client,
-        path=str(SOCKET_PATH)
+        path=str(socket_path)
     )
 
-    print(f"Daemon ready. PID: {os.getpid()}", file=sys.stderr)
+    print(f"Daemon ready. Instance: {instance_id} PID: {os.getpid()}", file=sys.stderr)
+
+    # Output instance ID to stdout for capture (all other output goes to stderr)
+    print(instance_id)
 
     # Setup signal handlers for graceful shutdown
     loop = asyncio.get_event_loop()
-
-    async def handle_shutdown(sig):
-        print(f"\nReceived {sig.name}, shutting down...", file=sys.stderr)
+    shutdown_triggered = asyncio.Event()
+
+    async def handle_shutdown(sig=None):
+        if shutdown_triggered.is_set():
+            return
+        shutdown_triggered.set()
+        if sig:
+            print(f"\nReceived {sig.name}, shutting down...", file=sys.stderr)
         await shutdown_mcp()
         server.close()
         await server.wait_closed()
-        SOCKET_PATH.unlink(missing_ok=True)
-        PID_FILE.unlink(missing_ok=True)
-        loop.stop()
+        socket_path.unlink(missing_ok=True)
+        pid_file.unlink(missing_ok=True)
+        # Exit cleanly instead of stopping loop (avoids RuntimeError)
+        os._exit(0)
 
     for sig in (signal.SIGTERM, signal.SIGINT):
         loop.add_signal_handler(
@@ -285,35 +349,39 @@ async def run_daemon():
             lambda s=sig: asyncio.create_task(handle_shutdown(s))
         )
 
-    # Run both the socket server and MCP response reader
+    # Run socket server, MCP response reader, and inactivity monitor
     try:
         await asyncio.gather(
             server.serve_forever(),
             read_mcp_responses(),
+            inactivity_monitor(handle_shutdown),
         )
     except KeyboardInterrupt:
         print("\nShutting down daemon...", file=sys.stderr)
     finally:
         # Cleanup
-        await shutdown_mcp()
-        server.close()
-        await server.wait_closed()
-        SOCKET_PATH.unlink(missing_ok=True)
-        PID_FILE.unlink(missing_ok=True)
+        if not shutdown_triggered.is_set():
+            await shutdown_mcp()
+            server.close()
+            await server.wait_closed()
+            socket_path.unlink(missing_ok=True)
+            pid_file.unlink(missing_ok=True)
 
 
 # ============================================================================
 # CLIENT MODE - Connect to daemon and send commands
 # ============================================================================
 
-async def send_command(tool_name: str, args: Dict[str, Any]) -> Any:
+async def send_command(instance_id: str, tool_name: str, args: Dict[str, Any]) -> Any:
     """Send a command to the daemon via socket."""
-    if not is_daemon_running():
-        raise RuntimeError("Daemon not running. Start with: bt daemon start")
+    if not is_daemon_running(instance_id):
+        raise RuntimeError(f"Daemon instance '{instance_id}' not running. Start with: browsertools.py daemon start")
+
+    socket_path = get_socket_path(instance_id)
 
     # Connect to daemon's Unix socket with increased limit for large responses
     reader, writer = await asyncio.open_unix_connection(
-        str(SOCKET_PATH),
+        str(socket_path),
         limit=1024 * 1024 * 10  # 10MB limit for large snapshots
     )
 
@@ -372,7 +440,7 @@ def clean_output(result: Any) -> str:
     return str(result)
 
 
-async def execute_command(cmd: str, cmd_args: Dict[str, Any]):
+async def execute_command(instance_id: str, cmd: str, cmd_args: Dict[str, Any]):
     """Execute a single command via daemon."""
 
     # Map commands to MCP tools
@@ -452,7 +520,7 @@ async def execute_command(cmd: str, cmd_args: Dict[str, Any]):
         raise ValueError(f"Unknown command: {cmd}")
 
     # Send to daemon
-    result = await send_command(tool_name, tool_args)
+    result = await send_command(instance_id, tool_name, tool_args)
     return clean_output(result)
 
 
@@ -463,22 +531,22 @@ async def execute_command(cmd: str, cmd_args: Dict[str, Any]):
 async def main():
     parser = argparse.ArgumentParser(
         prog="browsertools.py",
-        description="Chrome DevTools MCP wrapper - persistent daemon mode",
+        description="Chrome DevTools MCP wrapper - multi-instance daemon mode",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=r"""
 browsertools.py - Chrome DevTools automation tool
 
-
 Usage: uv run .agents/tools/chrome-devtools/browsertools.py <command>
 
 DAEMON MANAGEMENT:
-  daemon start          Start persistent daemon + Chrome
-                        IMPORTANT: Run in background with &
-                        Example: uv run .agents/tools/chrome-devtools/browsertools.py daemon start &
-  daemon stop           Stop daemon, kill Chrome cleanly
-  daemon status         Check if daemon running
+  daemon start          Start new daemon instance
+                        Returns: "browsertools daemon started. Instance ID: <id>"
+  daemon stop <id>      Stop daemon. kill chrome cleanly.
   daemon config         Create config file
 
+ALL OTHER COMMANDS REQUIRE --instance <id>:
+  --instance <id>       Required for all browser commands
+
 NAVIGATION:
   nav <url>             Navigate to URL
     --timeout <ms>      Max wait time in milliseconds
@@ -491,37 +559,25 @@ INSPECTION:
   shot [path]           Screenshot viewport (optional: save to path)
   eval <js>             Execute JavaScript, returns JSON
     --args <json>       JSON array of element references (advanced)
-                        Simple: "() => document.title"
-                        Complex: "(el) => el.innerText" --args '[{"uid":"1_23"}]'
 
 INTERACTION:
   click <uid>           Click element by UID from snapshot
   fill <uid> <value>    Fill input/textarea or select option
-  key <key>             Press key or combo
-                        Examples: "Enter", "Tab", "Control+A"
+  key <key>             Press key or combo (e.g., "Enter", "Tab", "Control+A")
   hover <uid>           Hover over element
   drag <from> <to>      Drag element from UID to target UID
-  fillform <json>       Fill multiple form fields at once
-                        Example: '[{"uid":"1_1","value":"text"}]'
+  fillform <json>       Fill multiple form fields
 
 DEBUGGING:
-  conslist              List console messages
-    --types error warn  Filter by type
-    --size N            Max messages
-
+  conslist              List console messages (--types, --size)
   consget <msgid>       Get console message details
-
-  netlist               List network requests
-    --types xhr fetch   Filter by resource type
-    --size N            Max requests
-
-  netget [reqid]        Get request details (omit reqid for currently selected)
+  netlist               List network requests (--types, --size)
+  netget [reqid]        Get request details
 
 PAGE MANIPULATION:
-  resize <width> <height>        Resize viewport
-  dialog <accept|dismiss>        Handle alert/confirm/prompt
-    --text <text>                Text for prompt
-  upload <uid> <file_path>       Upload file
+  resize <w> <h>        Resize viewport
+  dialog <action>       Handle alert/confirm/prompt (accept|dismiss)
+  upload <uid> <path>   Upload file
 
 USAGE TIPS:
 **Snapshots** are verbose. Always try to pipe grep first
@@ -535,31 +591,34 @@ Limit output for **debugging** commands
     - Console: conslist --size 5 --types error
 
 EXAMPLES:
-  # Login workflow
-  uv run .agents/tools/chrome-devtools/browsertools.py daemon start &
-  sleep 5  # Wait for daemon to be ready
-  uv run .agents/tools/chrome-devtools/browsertools.py nav http://app.com/login
-  uv run .agents/tools/chrome-devtools/browsertools.py snap | grep -iC5 "email\|username\|login"
-  uv run .agents/tools/chrome-devtools/browsertools.py fill 1_23 user@example.com
-  uv run .agents/tools/chrome-devtools/browsertools.py snap | grep -iC5 "button.*(submit|login|sign.?in)"
-  uv run .agents/tools/chrome-devtools/browsertools.py click 1_25 | grep -iC5 "dashboard\|home\|welcome"
-  uv run .agents/tools/chrome-devtools/browsertools.py daemon stop
-
-IMPORTANT:
-  - UIDs only valid from latest snapshot (interaction commands return fresh ones)
-  - Daemon maintains state (snapshots, network, console) across all commands
-  - Always stop daemon when you are finished to clean up browser resources
+  # Start daemon (backgrounds automatically, prints instance ID)
+  uv run .agents/tools/chrome-devtools/browsertools.py daemon start
+  # Output: browsertools daemon started. Instance ID: a3f7b2c1
+
+  # Use instance for all commands
+  uv run .agents/tools/chrome-devtools/browsertools.py --instance a3f7b2c1 nav http://app.com/login
+  uv run .agents/tools/chrome-devtools/browsertools.py --instance a3f7b2c1 snap | grep -iC5 "email\|username\|login"
+  uv run .agents/tools/chrome-devtools/browsertools.py --instance a3f7b2c1 fill 1_23 user@example.com
+  uv run .agents/tools/chrome-devtools/browsertools.py --instance a3f7b2c1 snap | grep -iC5 "button.*(submit|login|sign.?in)"
+  uv run .agents/tools/chrome-devtools/browsertools.py --instance a3f7b2c1 click 1_25 | grep -iC5 "dashboard\|home\|welcome"
+
+  # Stop when finished to clean up resources
+  uv run .agents/tools/chrome-devtools/browsertools.py daemon stop a3f7b2c1
         """
     )
 
+    # Global --instance argument
+    parser.add_argument("--instance", "-i", help="Daemon instance ID (required for browser commands)")
+
     subparsers = parser.add_subparsers(dest="cmd", required=True)
 
     # Daemon management
     daemon = subparsers.add_parser("daemon", help="Manage daemon")
     daemon_sub = daemon.add_subparsers(dest="daemon_cmd", required=True)
-    daemon_sub.add_parser("start", help="Start daemon")
-    daemon_sub.add_parser("stop", help="Stop daemon")
-    daemon_sub.add_parser("status", help="Check daemon status")
+    daemon_sub.add_parser("start", help="Start new daemon instance (returns instance ID)")
+    stop_parser = daemon_sub.add_parser("stop", help="Stop daemon instance")
+    stop_parser.add_argument("instance_id", nargs="?", help="Instance ID to stop")
+    stop_parser.add_argument("--all", dest="stop_all", action="store_true", help=argparse.SUPPRESS)  # Hidden
     daemon_sub.add_parser("config", help="Create default config file")
 
     # Browser commands
@@ -636,37 +695,81 @@ IMPORTANT:
     # Handle daemon commands
     if args.cmd == "daemon":
         if args.daemon_cmd == "start":
-            if is_daemon_running():
-                print("Daemon already running", file=sys.stderr)
-                sys.exit(1)
-            await run_daemon()
+            # Generate new instance ID
+            instance_id = generate_instance_id()
+
+            # Fork to background
+            pid = os.fork()
+
+            if pid > 0:
+                # Parent process - print result and exit
+                # Give child a moment to start
+                time.sleep(0.5)
+                print(f"browsertools daemon started. Instance ID: {instance_id}")
+                return  # Exit from async main, let asyncio.run() clean up
+            else:
+                # Child process - detach and run daemon
+                os.setsid()  # Create new session, detach from terminal
 
-        elif args.daemon_cmd == "stop":
-            pid = get_daemon_pid()
-            if not pid:
-                print("Daemon not running", file=sys.stderr)
-                sys.exit(1)
-            os.kill(pid, signal.SIGTERM)
-            print(f"Stopped daemon (PID {pid})")
+                # Redirect stdin/stdout/stderr to /dev/null (daemon runs silently)
+                devnull_r = os.open(os.devnull, os.O_RDONLY)
+                devnull_w = os.open(os.devnull, os.O_WRONLY)
+                os.dup2(devnull_r, sys.stdin.fileno())
+                os.dup2(devnull_w, sys.stdout.fileno())
+                os.dup2(devnull_w, sys.stderr.fileno())
+                os.close(devnull_r)
+                os.close(devnull_w)
+
+                # Create fresh event loop for child (parent's loop is unusable after fork)
+                asyncio.set_event_loop(asyncio.new_event_loop())
+
+                # Run the daemon in the new event loop (this blocks until shutdown)
+                asyncio.run(run_daemon(instance_id))
+                os._exit(0)
 
-        elif args.daemon_cmd == "status":
-            if is_daemon_running():
-                print(f"Daemon running (PID {get_daemon_pid()})")
-                print(f"Socket: {SOCKET_PATH}")
+        elif args.daemon_cmd == "stop":
+            if args.stop_all:
+                # Hidden --all flag: stop all running instances
+                instances = get_all_instances()
+                if not instances:
+                    print("No running instances", file=sys.stderr)
+                    sys.exit(1)
+                for inst_id in instances:
+                    pid = get_daemon_pid(inst_id)
+                    if pid:
+                        os.kill(pid, signal.SIGTERM)
+                        print(f"Stopped instance {inst_id} (PID {pid})", file=sys.stderr)
+            elif args.instance_id:
+                # Stop specific instance
+                pid = get_daemon_pid(args.instance_id)
+                if not pid:
+                    print(f"Instance '{args.instance_id}' not running", file=sys.stderr)
+                    sys.exit(1)
+                os.kill(pid, signal.SIGTERM)
+                print(f"Stopped instance {args.instance_id} (PID {pid})", file=sys.stderr)
             else:
-                print("Daemon not running")
+                print("Error: instance_id required. Usage: daemon stop <instance_id>", file=sys.stderr)
+                sys.exit(1)
 
         elif args.daemon_cmd == "config":
             save_default_config()
-            print(f"\nEdit {CONFIG_FILE} to customize MCP server settings.")
-            print("\nExamples:")
-            print("  Headless mode: --headless=true")
-            print("  Custom Chrome: --executablePath=/path/to/chrome")
-            print("  Sandbox: --headless=true --executablePath=/usr/local/bin/chromium-mcp")
+            print(f"\nEdit {CONFIG_FILE} to customize MCP server settings.", file=sys.stderr)
+            print("\nExamples:", file=sys.stderr)
+            print("  Headless mode: --headless=true", file=sys.stderr)
+            print("  Custom Chrome: --executablePath=/path/to/chrome", file=sys.stderr)
 
         return
 
-    # Execute browser command
+    # Execute browser command - requires --instance
+    if not args.instance:
+        print("Error: --instance <id> is required for browser commands", file=sys.stderr)
+        print("Start a daemon first: uv run browsertools.py daemon start", file=sys.stderr)
+        sys.exit(1)
+
+    if not is_daemon_running(args.instance):
+        print(f"Error: Instance '{args.instance}' is not running", file=sys.stderr)
+        sys.exit(1)
+
     try:
         cmd_args_dict = {}
 
@@ -724,7 +827,7 @@ IMPORTANT:
         elif args.cmd == "fillform":
             cmd_args_dict["elements"] = json.loads(args.elements)
 
-        output = await execute_command(args.cmd, cmd_args_dict)
+        output = await execute_command(args.instance, args.cmd, cmd_args_dict)
         print(output)
 
     except Exception as e:

package/.claude/agents/core/uat.md

@@ -2,16 +2,17 @@
 name: uat
 description: |
   End-to-end User Acceptance Testing (UAT) specialist who exercises deployed or preview builds strictly from a user perspective with the Chrome DevTools browser toolkit.
+  Maximum 1 UAT agent in a batch.
   <commentary>
   When invoking this agent, ALWAYS provide:
     - The application URL or tunnel plus any credentials, session tokens, or feature flags needed to reach the target environment.
     - Explicit user flows / acceptance scenarios with the expected outcomes to validate.
     - A dev server log file path or instructions for attaching to the background bash process streaming server output.
     - Any supporting data such as seeded accounts, test data reset steps, or environment caveats.
-  The agent will consult `.agents/repo.md` to fill gaps in missing inputs.
+    - Acceptance criteria, logic/functionality, UI/UX design expectations.
   </commentary>
 color: Yellow
-model: inherit
+model: opus
 ---
 
 You are a meticulous User Acceptance Testing specialist who mirrors real customer behavior to validate release readiness. You operate exclusively through the runtime experience (browser toolkit, network traffic, logs, and screenshots) and never inspect source code. Your goal is to surface UX bugs, regressions, and environment defects with actionable evidence so engineers can fix them quickly and requeue you for verification.

package/.claude/commands/await-feedback-orchestrator.md

@@ -0,0 +1,12 @@
+You are now opperating as Enable-n-Sequence for await-feedback agents
+MISSION: Provide clean and running dev server for sequential subagents.
+
+It is CRITICAL that you follow the Enable-n-Sequence WORKFLOW-LOOP step by step:
+[WORKFLOW-LOOP]
+1. CLEAN DEV SERVER: kill/terminate any existing dev servers running. Then start a new dev server. It is IMPORTANT that you kill the old one properly as the new one must be on the port expected by Wait-n-Build. (see `.agents/repo.md` for dev server details). Check the dev server logs to confirm it is running on the correct port.
+2. ASSIGN: Task a generic subagent to execute slash command /await-feedback
+
+When the subagent finishes, refresh the dev server and assign a new subagent with the same /await-feedback command.
+[/WORKFLOW-LOOP]
+
+**Continue your WORKFLOW-LOOP indefinitely**

package/.claude/commands/await-feedback.md

@@ -0,0 +1,21 @@
+You are now opperating as Wait-n-Build
+MISSION: implement changes requested via annotated-feedback mcp
+
+It is CRITICAL that you follow the Wait-n-Build WORKFLOW step by step:
+[WORKFLOW]
+WAIT: Poll the mcp__annotated-feedback__list endpoint for feedback with status: "pending". Do this every 60 seconds. ie. sleep 60 then poll again until there is new feedback available.
+**When feedback arrives**
+1. CALIBRATE: Consume AGENT OPERATING PROCEDURES (AOP) `.agents/AGENTS.md`. and Execute AOP.CALIBRATE. You are working at project level UI/UX implementation, so DRINK design guide, brandkit spec, etc. not phase specific.
+2. IMPLEMENT:
+  - Retrieve full details via mcp__annotated-feedback__get (including visual annotations/screenshots)
+  - Update status to "active"
+  - Implement the requested changes
+  - Update status to "review"
+3. UAT: Run `uv run .agents/tools/chrome-devtools/browsertools.py --help` to learn how to use the UAT toolkit. use the UAT toolkit to:
+  - navigate to the dev server (see `.agents/repo.md`)
+  - manually execute user flows impacted by your change
+  - screenshot at each checkpoint, and PONDER visual issues and allignment with expectaions.
+  - check browser and dev server logs for errors
+4. Itterate, refine, UAT loop until satisfied.
+5. DEPLOY: run Pre-deployment validation build eg. `vercel build --yes`. when green, commit and push changes to kick off CI/CD. Mission accomplished!
+[/WORKFLOW]

package/.claude/commands/cook.md

@@ -18,10 +18,10 @@ Populate your initial Todos with your step by step WORKFLOW:
 
 [WORKFLOW]
 1. PLAN: ULTRATHINK and break down ASSIGNMENT into independent implementation tasks
-3. IMPLEMENT: Launch a blended Implementation batch of engineers, codex and gemini consultants, each tasked with an with an independent Implementation task. 
-4. REFINE: Launch a blended Review+Refine batch of engineers and consultants + 1 UAT. each tasked to assess and implementation of one of the previous batch agents (provide them with the task that was assigned to the previous agent). these agents will assess for task completness, success critiera met,  with documentation. They should then refine the implementation if needed. this batch should be alternate the previous batch. eg. engeneer reviews gemini work, gemini reviews codex work, codex reviews engineer work.
-5  VERIFY: Launch a Assessing Only, Verification batch (Architect, Codex, Gemini, UAT) to assess the implementation completness of the full ASSIGNMENT. Each agent in this batch will provide their unique perspective, so give them the same comprehensive assessment task
-6. LOOP: *Decision:* did the Verification batch highlight ANY test failures, critical issues, missalignment, unmet ASSIGNMENT requirements? If so, **Add new Todos**: Loop through steps 3 & 4 batch Review+Refine -> Verification. Continue itterating until 100% pass/green/success reported by Verification batch
+2. IMPLEMENT: Launch a blended Implementation batch of engineers, codex and gemini consultants, each tasked with an with an independent Implementation task.
+3. REFINE: Launch a blended Review+Refine batch of engineers and consultants + 1 UAT. each tasked to assess and implementation of one of the previous batch agents (provide them with the task that was assigned to the previous agent). these agents will assess for task completness, success critiera met,  with documentation. They should then refine the implementation if needed. this batch should be alternate the previous batch. eg. engeneer reviews gemini work, gemini reviews codex work, codex reviews engineer work.
+4.  VERIFY: Launch a Assessing Only, Verification batch (Architect, Codex, Gemini, UAT) to assess the implementation completness of the full ASSIGNMENT. Each agent in this batch will provide their unique perspective, so give them the same comprehensive assessment task
+5...N. LOOP: *Decision:* did the Verification batch highlight ANY test failures, critical issues, missalignment, unmet ASSIGNMENT requirements? If so, **Add new Todos**: Loop through steps 3 & 4 batch Review+Refine -> Verification. Continue itterating until 100% pass/green/success reported by Verification batch
 [/WORKFLOW]
 
 
@@ -33,6 +33,7 @@ Populate your initial Todos with your step by step WORKFLOW:
 ⚡ **ALWAYS** batch consultant counterpart for read-only + document tasks
 ⚡ **ALWAYS** blend consultants + engineers for implementation/refinement tasks
 ⚡ **ALWAYS** have gemini, codex and engineers reviewing and refining each others work from previous batch tasks
+⚡ **ALWAYS** Take UAT feedback seriously. They are the user's representitive.
 
 
 ### Agent Instructions Template
@@ -62,7 +63,7 @@ TEAM COLLABORATION:
 
 
 ⭐*The successful delivery of your assigned task, contributes to the high level Assignment:*⭐
-[User's exact ASSIGNMENT]
+[Your full ASSIGNMENT]
 
 ⭐Ensure you are alligned with this North Star objective*⭐
 
@@ -78,7 +79,7 @@ Don't refer to prior batch agents by name. Instead, supply reference artifacts t
 ### Batch Composition Goals
 - **Minimum**: 5 agents per implementation batch
 - **Target**: 8-10 agents including support roles
-- **Include**: Support Architect/Researcher for guidance
+- **Include**: roughly equal number of gemini, codex, and engineer implementers, and a support architect for guidance/coordination.
 - **Follow with**: Verification batch always
 
 ### Phase Management
@@ -91,7 +92,7 @@ Don't refer to prior batch agents by name. Instead, supply reference artifacts t
 
 ## Consultant Agent
 Consultants come in two variants: Codex and Gemini. leverage them both liberally to diversify.
-When you are batching multple engineers across implementation Tasks, use some consultant agents in place of some engineers. Split the work between Engineers, Gemini consultants and Codex consultants.
+For implementation batches, distribute the tasks across engineers, codex consultants, and gemini consultants. There should be a roughly equal number of engineer, gemini, codex in implementation batches.
 When you are tasking an agent with read+document type task, recruit a codex and gemini Consultant with the exact same instructions (except a different names). Include the consultants in the same batch. This will net you diverse perspectives on the same research/plan/architect assignment.
 
 

package/.claude/commands/learn.md

@@ -1,8 +1,7 @@
 Activate TUTOR MODE
 
 🧙‍♂️📜🔮[Task]***MODEL ADOPTS ROLE [PERSONA]Deckard Cain***![/Task]🧙‍♂️📜🔮
-[Initial Invocation]: first you must study the Ancient Tombs to refresh your wizdom. This knowledge is your best-in-slot
-
+You are the last descendant of an ancient Brotherhood that was dedicated to safeguarding the secrets of Claude Comms...
 
 The user wants to learn about: #$ARGUMENTS ...
 
@@ -10,7 +9,7 @@ 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!
+- Black box, whirlwind barb 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)?
@@ -21,12 +20,13 @@ If the user didnt detail their learning request, present some options. spin as R
 Deckard, give the user 1:1 turoring. Achieve learning outcomes for the user through dynamic text based RPG.
 
 
-# Ancient Tomes. (dont tell the user to read these. Consume them yourself!)
-- 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 personal journal of context wizzardry (prompting, agentic harness engineering, etc) principles `docs/spec/principles.md`. This is foundation of this entire realm!
-- Some of my prompting examples in your `CLAUDE.md`, `.agents/AGENTS.md`, `.claude/commands/cook.md`, `.claude/agents/meta-agent-builder.md`, `.claude/agents/core/consultants/`
-- original spec for this system plus a few notes about direction along the way `docs/spec/multi-agent-orchestration.md` (bit outdated but directionally accurate)
+# Ancient tomes 
+It takes time to master your skills... and use will hone your technique. Read these yourself Cain (dont reference or tell the user to read), to ground your sage advice!
+- The last Horadric Scroll: AI wizzardry, agentic harness engineering, context/prompting principles `docs/spec/principles.md`. this is quite the treasure. a MUST GROK for you Decard.
+- Basic low int user just quickstart the `README.md`. all they need to do is /cook /cook /cook at the start of every prompt. Claude Comms agentic harness will handle the rest.
+- Some of my prompting examples in your `CLAUDE.md`, `.claude/commands/cook.md`, `.claude/agents/util/meta-agent-builder.md`
+- original spec for this system plus a few notes about direction along the way `docs/spec/multi-agent-orchestration.md`. this is a bit outdated.
 - if the user wants to learn about the architecture. all the tech docs in `docs/project/guides`
 
 
-🧙‍♂️📜🔮
+🧙‍♂️📜🔮Stay a while and listen...🧙‍♂️📜🔮

package/.claude/commands/uat-refine.md

@@ -0,0 +1,122 @@
+Primary ⚙️Orchestrator Assignment Orchestration
+
+You are Primary ⚙️Orchestrator.
+
+
+ULTRATHINK about your CRITICAL ORCHESTRATION PROTOCOLS, and apply ⚡ORCHESTRATION untiil complete solution is delivered for your ASSIGNMENT:
+[ASSIGNMENT]
+#$ARGUMENTS
+
+[/ASSIGNMENT]
+
+
+
+# ⚡ORCHESTRATION
+## EXECUTION SEQUENCE
+You must manage and maintain Todos dynamically, refine Todos after every decision, and when new information presents itself.
+Populate your initial Todos with your step by step WORKFLOW:
+
+[WORKFLOW]
+PLAN: ULTRATHINK about the UI/UX pages, features, user flows involved and the dependencies between. Break down ASSIGNMENT into dependency sequenced test scenarios.
+ENABLE: ensure the dev server is running. you may need to kill an old process and start it again `.agents/repo.md`
+
+For each test scenario in the sequence:
+1. FEEDBACK: Task a single UAT agent to manually execute the test scenario, visually inspect the UI/UX and provide feedback on: design allignment, expected functionality, issues encountered, error logs. This UAT agent is a proxy for the user. Their perspecttive matters!
+2. IMPLEMENT: Launch a blended Implementation batch of engineers, codex and gemini consultants to implement changes based on UAT FEEDBACK.
+3. REQUEST APPROVAL: Task a single UAT agent to manually execute the test scenario, and provide their assessment of changes, design allignment, expected functionality.
+ - If UAT gives critical feedback, and DOES NOT APPROVE: itterate until approval awarded. 
+ - When UAT gives signoff approval for deployment, continue to the next test scenario
+[/WORKFLOW]
+
+
+## 🎯 CRITICAL EXECUTION RULES
+
+### Dependency Laws
+⚡ **NEVER** batch multiple UAT agents together. Focus on one scenario at a time.
+⚡ **ALWAYS** Take UAT feedback seriously. They are the user's representitive.
+⚡ **ALWAYS** Add new todos if Approval is not awarded.
+⚡ **ALWAYS** blend consultants + engineers for implementation/refinement tasks
+
+
+
+### Agent Instructions Template
+```
+"Your name is [FirstNameLastName]. 
+Your Team Role is [Support/Implementation/Review+Refine/AssessingOnly]
+
+SCOPE: [Phase-level (phase-id: XX-Name)]
+
+YOUR TASK:
+[Specific task description]
+
+CONSTRAINTS:
+[Any dependencies, interfaces, or requirements]
+
+SUCCESS CRITERIA:
+[What constitutes completion]
+
+FILES TO READ FIRST:
+- [filepath1] - [one sentence description]
+- [filepath2] - [one sentence description]
+
+TEAM COLLABORATION:
+- Leverage your Team for [what]
+- Support your Team with [what]
+- Coordinate with your Team on [shared concern]
+
+
+⭐*The successful delivery of your assigned task, contributes to the high level Assignment:*⭐
+[Your full ASSIGNMENT]
+
+⭐Ensure you are alligned with this North Star objective*⭐
+
+
+[FirstNameLastName], adopt 🤝 TEAMWORK to achieve maximum value delivered."
+```
+
+*Remember:*
+An agent has no inherit knowledge of previous batch agents. They can only collaborate within thier batch. 
+Don't refer to prior batch agents by name. Instead, supply reference artifacts that have been produced by prior batch agents if contextually relevant.
+
+
+### Batch Composition Goals
+- **Minimum**: 5 agents per implementation batch
+- **Target**: 8-10 agents including support roles
+- **Include**: Support 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)
+
+
+## Consultant Agent
+Consultants come in two variants: Codex and Gemini. leverage them both liberally to diversify.
+When you are batching multple engineers across implementation Tasks, use some consultant agents in place of some engineers. Split the work between Engineers, Gemini consultants and Codex consultants.
+When you are tasking an agent with read+document type task, recruit a codex and gemini Consultant with the exact same instructions (except a different names). Include the consultants in the same batch. This will net you diverse perspectives on the same research/plan/architect assignment.
+
+
+
+
+## 🔴 FINAL DIRECTIVES
+
+**DO NOT STOP** until assignment is complete and verified
+
+**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.md

@@ -83,7 +83,7 @@ TEAM COLLABORATION:
 - All agents in a batch complete independently without waiting for others
 
 Parallel Specialization Examples
-- **Multiple Engineers/Consultants**: Each owns different module/file
+- **Multiple Engineers+Consultants**: Each owns different module/file
 - **Support Roles**: Architect answers questions or researches and suggests solution approachs, Designer creates storybook assets, UAT manually performs user flows and provides feedback
 
 ### Inter-Batch Sequencing (Dependencies)
@@ -124,8 +124,8 @@ Research/Architecture → Planning → Implementation → Verification → Next
 #### New Feature Workflow
 1. **Discovery Batch**: [Architect, Designer, Consutant]
 2. **Planning Batch**: [Planner] - creates phase-id and WPs
-3. **Implementation Batch**: [5-10 Engineers, Consultants with distinct role and focus + support agents (maximum 10 total per batch) ]
-4. **Review+Refine Batch**: [5-10 Engineers, Consultants with previous batch task (swap Engineers and Consultants so they review/refine each others work) to review+refine + support agents (maximum 10 total per batch) ]
+3. **Implementation Batch**: [Engineers, Gemini and Codex Consultants with distinct role and focus + support agents (maximum 10 total per batch) ]
+4. **Review+Refine Batch**: [Engineers, Codex and Gemini Consultants with previous batch task (alternate Engineers and Consultants so they review/refine each others work) to review+refine + support agents (maximum 10 total per batch) ]
 5. **Verification + Reco Batch**: [Codex + Gemini + Architect + UAT to provide their completion assessments]
 6. **If verificaiton fail**: Loop Review+refine -> Verification Batches until PASS
 
@@ -167,7 +167,7 @@ Research/Architecture → Planning → Implementation → Verification → Next
 
 ## Consultant Agent
 Consultants come in two variants: Codex and Gemini. leverage them both liberally to diversify.
-When you are batching multple engineers across implementation Tasks, use some consultant agents in place of some engineers. Split the work between Engineers, Gemini consultants and Codex consultants.
+For implementation batches, distribute the tasks across engineers, codex consultants, and gemini consultants. There should be a roughly equal number of engineer, gemini, codex in implementation batches.
 When you are tasking an agent with read+document type task, recruit a codex and gemini Consultant with the exact same instructions (except a different names). Include the consultants in the same batch. This will net you diverse perspectives on the same research/plan/architect assignment.
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-comms",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "description": "NPX installer for Claude Code hooks and observability setup",
   "main": "src/index.js",
   "bin": {

package/src/orchestrator/installer.js

@@ -334,13 +334,30 @@ class Installer extends EventEmitter {
       // Create backups if files exist
       await this._createBackupsIfNeeded(fetchedFiles);
 
-      // Write files using injected writer
+      // Flatten files and filter out user-customizable files if they already exist
+      let filesToWrite = this._flattenFiles(fetchedFiles);
+
+      // Files that should not be overwritten if they exist (user customizations)
+      const preserveIfExists = [
+        { path: '.agents/repo.md', fullPath: path.join(this.options.targetDir, '.agents', 'repo.md') },
+        { path: '.agents/tools/chrome-devtools/config.json', fullPath: path.join(this.options.targetDir, '.agents', 'tools', 'chrome-devtools', 'config.json') }
+      ];
+
+      for (const file of preserveIfExists) {
+        const exists = await this.validator.pathExists(file.fullPath);
+        if (exists) {
+          this.logger.info(`${file.path} already exists, skipping (preserving user customizations)`);
+          filesToWrite = filesToWrite.filter(f => f.path !== file.path);
+        }
+      }
+
+      // Write files using injected writer (overwrite existing, no backups)
       const writeResult = await this.writer.writeDirectory(
-        this._flattenFiles(fetchedFiles),
+        filesToWrite,
         {
           targetDir: this.options.targetDir,
-          overwrite: this.options.force,
-          backup: true,
+          overwrite: true,
+          backup: false,
           preservePermissions: true,
           dryRun: this.options.dryRun
         }
@@ -450,6 +467,11 @@ class Installer extends EventEmitter {
     this.state = InstallationState.VERIFYING;
     this._emitProgress('Verifying installation...', 90);
 
+    if (this.options.dryRun) {
+      this.logger.info('DRY RUN: Would verify installation');
+      return;
+    }
+
     const requiredPaths = [
       path.join(this.options.targetDir, '.claude'),
       path.join(this.options.targetDir, '.agents'),
@@ -706,29 +728,27 @@ class Installer extends EventEmitter {
   }
 
   /**
-   * Create backups of existing files if needed
+   * Log info about existing files that will be overwritten
    */
   async _createBackupsIfNeeded(_fetchedFiles) {
-    if (!this.options.force) {
-      // Check for existing directories and files
-      const claudeDir = path.join(this.options.targetDir, '.claude');
-      const agentsDir = path.join(this.options.targetDir, '.agents');
-      const claudeMd = path.join(this.options.targetDir, 'CLAUDE.md');
-
-      const existingPaths = [];
-      if (await this.validator.pathExists(claudeDir)) {
-        existingPaths.push('.claude/');
-      }
-      if (await this.validator.pathExists(agentsDir)) {
-        existingPaths.push('.agents/');
-      }
-      if (await this.validator.pathExists(claudeMd)) {
-        existingPaths.push('CLAUDE.md');
-      }
+    // Check for existing directories and files that will be overwritten
+    const claudeDir = path.join(this.options.targetDir, '.claude');
+    const agentsDir = path.join(this.options.targetDir, '.agents');
+    const claudeMd = path.join(this.options.targetDir, 'CLAUDE.md');
+
+    const existingPaths = [];
+    if (await this.validator.pathExists(claudeDir)) {
+      existingPaths.push('.claude/');
+    }
+    if (await this.validator.pathExists(agentsDir)) {
+      existingPaths.push('.agents/');
+    }
+    if (await this.validator.pathExists(claudeMd)) {
+      existingPaths.push('CLAUDE.md');
+    }
 
-      if (existingPaths.length > 0) {
-        this.logger.warn(`Existing files will be backed up: ${existingPaths.join(', ')}`);
-      }
+    if (existingPaths.length > 0) {
+      this.logger.info(`Existing files will be overwritten: ${existingPaths.join(', ')}`);
     }
   }
 

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

@@ -1,11 +0,0 @@
-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!