claude-comms 1.0.31 → 1.0.33

package/.agents/AGENTS.md

@@ -43,14 +43,17 @@ Evaluate the Change for a given Assignment/Task against the following criteria:
 
 
 [VALIDATE]
-1. Run required commands — all must pass without warnings or errors:
+Run required commands — all must pass without warnings or errors:
    - `pnpm lint`
    - `pnpm ts:check`
    - `pnpm test:all`
    - `pnpm build`
-2. Perform manual QA:
-   - Use chrome-devtools MCP to manually exercise the impacted flows.
-   - Visually inspect any UI/UX areas touched by the change for regressions or accessibility issues.
+
+[UAT]
+Perform manual QA:
+ - Run `uv run .agents/tools/chrome-devtools/browsertools.py --help` to learn how to use the UAT toolkit
+ - manually exercise the impacted flows.
+ - Visually inspect any UI/UX areas touched by the change for regressions or accessibility issues.
 
 
 [/AGENT OPERATING PROCEDURES]

package/.agents/tools/README.md

@@ -0,0 +1,45 @@
+# Agent Tools
+
+Collection of specialized tools for agent workflows.
+
+## Available Tools
+
+### chrome-devtools/
+Chrome DevTools MCP wrapper for browser automation and UAT.
+
+**Quick start:**
+```bash
+uv run .agents/tools/chrome-devtools/browsertools.py daemon start
+uv run .agents/tools/chrome-devtools/browsertools.py nav http://localhost:5173/
+uv run .agents/tools/chrome-devtools/browsertools.py snap
+uv run .agents/tools/chrome-devtools/browsertools.py daemon stop
+```
+
+**Documentation:**
+- [README.md](chrome-devtools/README.md) - Quick start and examples
+- [TOOL_REFERENCE.md](chrome-devtools/TOOL_REFERENCE.md) - Complete parameter reference
+- [CONFIG.md](chrome-devtools/CONFIG.md) - Environment configuration
+- [COVERAGE.md](chrome-devtools/COVERAGE.md) - Tool coverage analysis
+
+**Features:**
+- 96% context token reduction vs native MCP
+- Persistent state across CLI invocations
+- Network/console debugging
+- Configurable for any environment (local/sandbox/CI)
+
+---
+
+## Adding New Tools
+
+When creating new agent tools:
+
+1. Create subdirectory: `.agents/tools/<tool-name>/`
+2. Add main script (preferably uv-based)
+3. Add README.md with usage examples
+4. Update this index
+
+**Design principles:**
+- Minimize context token usage
+- Provide clear documentation
+- Support non-interactive CLI usage
+- Handle cleanup properly

package/.agents/tools/chrome-devtools/README.md

@@ -0,0 +1,101 @@
+# Chrome DevTools Browser Automation Tool
+
+Stateful Chrome automation wrapper that reduces context token usage by 96% while maintaining full browser state across multiple CLI invocations.
+
+## Quick Start
+
+```bash
+# From repo root - start daemon in background
+uv run .agents/tools/chrome-devtools/browsertools.py daemon start &
+sleep 5
+
+# Use commands - state persists across invocations!
+uv run .agents/tools/chrome-devtools/browsertools.py nav http://localhost:5173/
+uv run .agents/tools/chrome-devtools/browsertools.py snap
+uv run .agents/tools/chrome-devtools/browsertools.py click 1_7
+uv run .agents/tools/chrome-devtools/browsertools.py snap
+
+# Stop when done
+uv run .agents/tools/chrome-devtools/browsertools.py daemon stop
+```
+
+## Full Command Reference
+
+Run `uv run .agents/tools/chrome-devtools/browsertools.py --help` to see all commands.
+
+**Key commands:**
+- `daemon start` - Start browser (run in background with `&`)
+- `nav <url>` - Navigate to URL
+- `snap` - Get page snapshot with element UIDs
+- `click <uid>` - Click element
+- `fill <uid> <value>` - Fill input/select
+- `shot [path]` - Screenshot
+- `conslist`, `netlist` - Debug console/network
+- `daemon stop` - Clean shutdown
+
+## Configuration
+
+**Default:** Headless mode (no Chrome window)
+
+**To use visual mode:** Create `~/.browsertools/config.json`:
+```json
+{
+  "mcp_args": ["-y", "chrome-devtools-mcp@latest", "--isolated"]
+}
+```
+
+**For sandbox:** See `config.json` in this directory for examples.
+
+## Architecture
+
+- **Persistent daemon** - Single MCP server runs in background
+- **Unix socket bridge** - Multiple CLI commands share state via socket
+- **Stateful** - Snapshots, tabs, cookies persist across invocations
+- **Clean shutdown** - Process groups ensure no orphaned Chrome processes
+
+
+## Complete UAT Example
+
+```bash
+# Start daemon
+uv run .agents/tools/chrome-devtools/browsertools.py daemon start &
+sleep 5
+
+# Navigate and get page structure
+uv run .agents/tools/chrome-devtools/browsertools.py nav http://app.com/login
+uv run .agents/tools/chrome-devtools/browsertools.py snap | grep email
+# Found: uid=1_23 input "email"
+
+# Fill form
+uv run .agents/tools/chrome-devtools/browsertools.py fill 1_23 user@example.com
+uv run .agents/tools/chrome-devtools/browsertools.py fill 1_24 password
+uv run .agents/tools/chrome-devtools/browsertools.py click 1_25
+
+# Verify
+uv run .agents/tools/chrome-devtools/browsertools.py wait "Dashboard"
+uv run .agents/tools/chrome-devtools/browsertools.py conslist --types error
+uv run .agents/tools/chrome-devtools/browsertools.py shot /tmp/success.png
+
+# Cleanup
+uv run .agents/tools/chrome-devtools/browsertools.py daemon stop
+```
+
+## Troubleshooting
+
+**Chrome window appears:** Remove `~/.browsertools/config.json` to use default headless mode
+
+**"Daemon not running":**
+```bash
+uv run .agents/tools/chrome-devtools/browsertools.py daemon status
+uv run .agents/tools/chrome-devtools/browsertools.py daemon start &
+```
+
+**Timeouts:** Increase with `--timeout` flag on nav/wait commands
+
+## Files
+
+- `browsertools.py` - Main tool (24KB)
+- `config.json` - Default config (headless mode)
+- `README.md` - This file
+
+User config at `~/.browsertools/config.json` overrides repo defaults.