claude-comms 1.0.46 → 2.0.1

package/.agents/tools/chrome-devtools/config.json

@@ -1,24 +0,0 @@
-{
-  "mcp_command": "npx",
-  "mcp_args": [
-    "-y",
-    "chrome-devtools-mcp@latest",
-    "--isolated",
-    "--headless=true"
-  ],
-  "_comment": "Default config runs headless. Override by creating ~/.browsertools/config.json",
-  "_examples": {
-    "visual_mode": {
-      "mcp_args": ["-y", "chrome-devtools-mcp@latest", "--isolated"]
-    },
-    "sandbox": {
-      "mcp_args": [
-        "-y",
-        "chrome-devtools-mcp@latest",
-        "--isolated=true",
-        "--headless=true",
-        "--executablePath=/usr/local/bin/chromium-mcp"
-      ]
-    }
-  }
-}

package/.agents/tools/workflow/CONSUMER_SETUP.md

@@ -1,114 +0,0 @@
-# Consumer Repo Setup
-
-This document describes how to set up the workflow engine in repos that consume the `.agents/` directory.
-
-## Current Architecture
-
-```
-.agents/tools/workflow/
-├── workflow-engine -> ../../../workflow-engine  (symlink)
-├── cli.ts
-├── runner.ts
-├── config.json
-└── templates/
-```
-
-The CLI and runner import from `./workflow-engine/convex/_generated/api.js`, which resolves through the symlink to the actual `workflow-engine/` directory containing the Convex schema and generated types.
-
-## Problem
-
-When copying `.agents/` to a consumer repo, the symlink points to `../../../workflow-engine` which won't exist in the consumer repo's directory structure.
-
-## Options
-
-### Option 1: Copy workflow-engine alongside .agents
-
-```bash
-# In consumer repo
-cp -r /path/to/workflow-engine ./workflow-engine
-# Symlink already points to ../../../workflow-engine, adjust if needed
-```
-
-Pros: Simple, self-contained
-Cons: Duplicated code, manual updates
-
-### Option 2: Publish workflow-engine to npm
-
-```bash
-# Publish
-cd workflow-engine && npm publish
-
-# In consumer repo
-npm install @yourorg/workflow-engine
-
-# Update symlink
-cd .agents/tools/workflow
-rm workflow-engine
-ln -s ../../../node_modules/@yourorg/workflow-engine workflow-engine
-```
-
-Pros: Clean dependency management, versioned
-Cons: Requires npm publishing workflow
-
-### Option 3: Git submodule
-
-```bash
-# In consumer repo
-git submodule add <workflow-engine-repo-url> workflow-engine
-
-# Symlink points to it
-cd .agents/tools/workflow
-ln -s ../../../workflow-engine workflow-engine
-```
-
-Pros: Always up to date with upstream
-Cons: Submodule complexity
-
-### Option 4: Monorepo with shared packages
-
-If using a monorepo (turborepo, nx, etc.), workflow-engine can be a workspace package that .agents/tools/workflow depends on.
-
-## Config Per Repo
-
-Each consumer repo needs its own `config.json`:
-
-```json
-{
-  "convexUrl": "https://your-project-123.convex.cloud",
-  "namespace": "consumer-repo-name",
-  "timeoutMs": 600000,
-  "harnessDefaults": {
-    "default": "claude",
-    "plan": "claude",
-    "implement": "claude",
-    "review": "claude",
-    "uat": "claude",
-    "document": "claude",
-    "pm": "claude",
-    "chat": "claude"
-  }
-}
-```
-
-The `namespace` field isolates assignments/jobs per repo in the shared Convex backend.
-
-## Initialization
-
-After setting up `config.json`, run the init script to register your namespace in the database:
-
-```bash
-cd .agents/tools/workflow
-npx tsx init.ts
-```
-
-This script is **idempotent** - running it multiple times is safe and won't create duplicate namespaces. It will either:
-- Create the namespace if it doesn't exist
-- Report that the namespace already exists
-
-You must run this before the runner or CLI will work, as all assignments and chat threads require a valid namespace ID.
-
-## TODO
-
-- [ ] Decide on distribution strategy (npm publish vs git submodule vs copy)
-- [ ] Automate consumer repo setup script
-- [ ] Consider generating standalone client without symlink dependency

package/.agents/tools/workflow/ONBOARD.md

@@ -1,167 +0,0 @@
-# Workflow Engine Onboarding
-
-## What We Built
-
-A job queue system for orchestrating sequential Claude/Codex/Gemini headless runs. Solves the "checkbox brain" problem where Claude rushes through todos without quality gates.
-
-### Architecture
-
-```
-Convex Backend (workflow-engine/)     ← Schema, queries, mutations
-        ↑
-        │ WebSocket subscription
-        │
-Runner Daemon (.agents/tools/workflow/runner.ts)  ← Executes jobs
-        │
-        │ spawns
-        ↓
-Claude/Codex/Gemini headless          ← Actual work
-        │
-        │ on complete
-        ↓
-PM Shadow Job                         ← Reviews, decides next step
-```
-
-### Key Concepts
-
-- **Assignment**: User intent (north star). Has linked list of jobs.
-- **Job**: Single Claude/Codex/Gemini run. Types: plan, implement, review, uat, document, pm.
-- **PM Agent**: Runs after each job. Reviews result, inserts next job or completes/blocks assignment.
-- **Namespace**: Isolates assignments per repo in shared Convex backend.
-
-## Files Created
-
-### Backend (`workflow-engine/`)
-```
-convex/
-├── schema.ts         # assignments + jobs tables
-├── assignments.ts    # CRUD
-├── jobs.ts           # CRUD
-└── scheduler.ts      # getReadyJobs, watchQueue
-```
-
-**Deployed to**: `https://utmost-vulture-618.convex.cloud`
-
-### Consumer-facing (`.agents/tools/workflow/`)
-```
-├── workflow-engine/  # symlink → ../../../workflow-engine
-├── cli.ts            # PM-ergonomic CLI
-├── runner.ts         # WebSocket daemon
-├── config.json       # namespace, convex URL
-├── templates/        # Prompt templates (plan.md, implement.md, etc.)
-├── README.md
-├── CONSUMER_SETUP.md # Distribution notes for other repos
-└── SPEC.md           # (in workflow-engine/)
-```
-
-## Current State
-
-- ✅ Convex schema deployed
-- ✅ CLI working (`npx tsx .agents/tools/workflow/cli.ts queue`)
-- ✅ Templates created
-- ✅ Runner daemon written
-- ⏳ Runner not yet tested end-to-end
-- ⏳ PM shadow job flow not tested
-
-## What Needs Testing
-
-### 1. Start the runner
-```bash
-npx tsx .agents/tools/workflow/runner.ts
-```
-
-### 2. Create a test assignment
-```bash
-npx tsx .agents/tools/workflow/cli.ts create "Create a hello world function in test-hello.ts"
-```
-
-### 3. Add initial job
-```bash
-npx tsx .agents/tools/workflow/cli.ts insert-job <assignment_id> \
-  --type implement \
-  --harness claude \
-  --context "Create a simple hello world function that returns 'Hello, World!'"
-```
-
-### 4. Watch the runner
-- Should pick up the job
-- Execute Claude headless
-- On completion, trigger PM job
-- PM should review and decide next steps
-
-### 5. Verify end state
-```bash
-npx tsx .agents/tools/workflow/cli.ts assignment <assignment_id>
-```
-
-## CLI Quick Reference
-
-```bash
-# Queries
-cli.ts queue                          # Queue status
-cli.ts assignments                    # List all
-cli.ts assignment <id>                # Details with jobs
-cli.ts jobs                           # List jobs
-cli.ts job <id>                       # Job details
-
-# Mutations
-cli.ts create "<north_star>"          # New assignment
-cli.ts insert-job <aid> --type X --harness Y --context "Z"
-cli.ts complete <aid>                 # Mark done
-cli.ts block <aid> --reason "..."     # Escalate to human
-cli.ts unblock <aid>                  # Resume
-```
-
-## Config
-
-Copy `config.example.json` to `config.json` and edit:
-
-```json
-{
-  "convexUrl": "https://your-project.convex.cloud",
-  "namespace": "your-repo-name",
-  "timeoutMs": 600000,
-  "harnessDefaults": {
-    "default": "claude",
-    "plan": "claude",
-    "implement": "claude",
-    "review": "claude",
-    "uat": "claude",
-    "document": "claude",
-    "pm": "claude",
-    "chat": "claude"
-  }
-}
-```
-
-## Claude JSON Stream Format
-
-```
-{"type":"system","subtype":"init","session_id":"...","tools":[...],...}
-{"type":"assistant","message":{"content":[{"type":"text","text":"..."}],...}}
-{"type":"assistant","message":{"content":[{"type":"tool_use","name":"...","input":{...}}],...}}
-{"type":"user","message":{"content":[{"type":"tool_result","content":"..."}]}}
-{"type":"result","subtype":"success","result":"final output text","duration_ms":...}
-```
-
-**Key extraction:**
-- Assistant text: `event.message.content[].text` where `type === "text"`
-- Final result: `event.result` when `event.type === "result"`
-- Success: `event.subtype === "success"`
-
-## Known Issues / TODO
-
-1. Consumer repo distribution strategy not finalized (see CONSUMER_SETUP.md)
-2. Parallel job execution logic could be tightened
-3. No retry logic for transient failures yet
-
-## Session Context
-
-We spec'd this collaboratively, iterating on:
-- Entity model (Assignment → Jobs linked list)
-- Parallelism (assignment-level, not job-level)
-- PM as shadow job pattern
-- Convex-first for real-time reactivity
-- CLI ergonomics for PM agent consumption
-
-The eng-cog metacognitive framework from `docs/options/eng-prompt.md` was used for initial framing but dropped during rapid iteration.

package/.agents/tools/workflow/README.md

@@ -1,169 +0,0 @@
-# Workflow Engine
-
-Job queue system for orchestrating sequential Claude/Codex/Gemini headless runs.
-
-## Architecture
-
-```
-Convex Backend (workflow-engine/)
-        ↑
-        │ WebSocket subscription
-        │
-Runner Daemon (runner.ts)
-        │
-        │ spawns
-        ↓
-Claude/Codex/Gemini headless processes
-```
-
-## Quick Start
-
-### 1. Configure
-
-Copy the example config and edit:
-
-```bash
-cp config.example.json config.json
-```
-
-Edit `config.json`:
-
-```json
-{
-  "convexUrl": "https://utmost-vulture-618.convex.cloud",
-  "namespace": "your-repo-name",
-  "timeoutMs": 600000,
-  "harnessDefaults": {
-    "default": "claude",
-    "plan": "claude",
-    "implement": "claude",
-    "review": "claude",
-    "uat": "claude",
-    "document": "claude",
-    "pm": "claude",
-    "chat": "claude"
-  }
-}
-```
-
-### 2. Start the Runner
-
-```bash
-npx tsx .agents/tools/workflow/runner.ts
-```
-
-The runner subscribes to Convex and executes jobs as they become ready.
-
-### 3. Create an Assignment
-
-```bash
-npx tsx .agents/tools/workflow/cli.ts create "Build user authentication feature"
-```
-
-### 4. Add Jobs
-
-```bash
-npx tsx .agents/tools/workflow/cli.ts insert-job <assignment_id> \
-  --type plan \
-  --harness claude \
-  --context "Create implementation plan"
-```
-
-## CLI Reference
-
-### Queries
-
-```bash
-# List assignments
-cli.ts assignments [--status pending|active|blocked|complete]
-
-# Get assignment with jobs
-cli.ts assignment <id>
-
-# List jobs
-cli.ts jobs [--status pending|running|complete|failed]
-
-# Get job details
-cli.ts job <id>
-
-# Queue status
-cli.ts queue
-```
-
-### Mutations
-
-```bash
-# Create assignment
-cli.ts create "<north_star>" [--priority N] [--independent]
-
-# Insert job
-cli.ts insert-job <assignment_id> \
-  --type <plan|implement|review|uat|document> \
-  --harness <claude|codex|gemini> \
-  [--context "instructions"] \
-  [--after <job_id>]
-
-# Update assignment metadata
-cli.ts update-assignment <id> \
-  [--artifacts "filepath:description"] \
-  [--decisions "decision text"]
-
-# Complete assignment
-cli.ts complete <assignment_id>
-
-# Block assignment
-cli.ts block <assignment_id> --reason "why"
-
-# Unblock assignment
-cli.ts unblock <assignment_id>
-
-# Job status updates (typically used by runner)
-cli.ts start-job <job_id>
-cli.ts complete-job <job_id> --result "output"
-cli.ts fail-job <job_id> [--result "error"]
-```
-
-## Job Types
-
-| Type | Purpose |
-|------|---------|
-| `plan` | Create spec doc + work packages |
-| `implement` | Build implementation via engineer batches |
-| `review` | Read-only engineering quality review |
-| `uat` | User acceptance testing |
-| `document` | Update docs and finalize assignment |
-| `pm` | (Shadow job) Review result, decide next |
-
-## How It Works
-
-1. **Assignment created** with north star (human intent)
-2. **Jobs added** to assignment's linked list
-3. **Runner picks up** ready jobs (pending + predecessor complete)
-4. **Job executes** via Claude/Codex/Gemini headless
-5. **PM job triggers** automatically after each completion
-6. **PM decides**: insert more jobs, complete, or block
-7. **Loop** until assignment complete or blocked
-
-## Parallelism Rules
-
-- Jobs within an assignment run **sequentially** (linked list)
-- Independent assignments can run **in parallel**
-- Non-independent assignments run **one at a time**
-- Priority: oldest first, then lowest priority number
-
-## Templates
-
-Prompt templates live in `templates/`:
-- `plan.md`
-- `implement.md`
-- `review.md`
-- `uat.md`
-- `document.md`
-- `pm.md`
-
-Templates use placeholders:
-- `{{NORTH_STAR}}` - Assignment goal
-- `{{ARTIFACTS}}` - Files produced
-- `{{DECISIONS}}` - Decision record
-- `{{CONTEXT}}` - Job-specific instructions
-- `{{PREVIOUS_RESULT}}` - Prior job output