claude-comms 1.0.44 → 1.0.46

package/.agents/tools/agent-job/agent_job.py

@@ -299,6 +299,65 @@ class GeminiEventHandler:
         return event.get("type") == "result" and event.get("status") == "success"
 
 
+class ClaudeEventHandler:
+    """Handle Claude CLI JSON stream events."""
+
+    def __init__(self):
+        self._text_chunks: list[str] = []
+        self._final_result: Optional[str] = None
+        self._complete = False
+        self._success = False
+
+    def extract_job_id(self, event: dict) -> Optional[str]:
+        """Extract job ID from initial event."""
+        if event.get("type") == "system" and event.get("subtype") == "init":
+            return event.get("session_id")
+        return None
+
+    def process_event(self, event: dict, status: JobStatus) -> None:
+        """Process a Claude event and update status."""
+        event_type = event.get("type", "")
+
+        # Capture assistant text messages
+        if event_type == "assistant":
+            status.status_reason = "responding"
+            msg = event.get("message", {})
+            content = msg.get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict):
+                        if block.get("type") == "text" and block.get("text"):
+                            self._text_chunks.append(block["text"])
+                        elif block.get("type") == "tool_use":
+                            tool_name = block.get("name", "tool")
+                            status.status_reason = tool_name
+
+        # Handle tool results
+        elif event_type == "user":
+            status.status_reason = "tool_result"
+
+        # Capture final result
+        elif event_type == "result":
+            self._complete = True
+            self._success = event.get("subtype") == "success"
+            status.status_reason = "completed" if self._success else "failed"
+
+            if event.get("result"):
+                self._final_result = str(event["result"])
+
+            # Extract duration if available
+            if event.get("duration_ms"):
+                status.completion.duration_ms = event["duration_ms"]
+
+    def is_completion_event(self, event: dict) -> bool:
+        """Check if this event indicates completion."""
+        return event.get("type") == "result" and event.get("subtype") == "success"
+
+    def get_result(self) -> str:
+        """Get the accumulated result."""
+        return self._final_result or "\n\n".join(self._text_chunks)
+
+
 # =============================================================================
 # Job Manager
 # =============================================================================
@@ -423,6 +482,15 @@ def build_harness_command(harness: str, assignment: str) -> list[str]:
             assignment,
             "--json",
         ]
+    elif harness == "claude":
+        return [
+            "claude",
+            "--dangerously-skip-permissions",
+            "--verbose",
+            "--output-format", "stream-json",
+            "-p",
+            assignment,
+        ]
     else:
         raise ValueError(f"Unknown harness: {harness}")
 
@@ -562,6 +630,8 @@ def spawn_job(harness: str, assignment: str) -> dict:
     # Create appropriate event handler
     if harness == "gemini":
         handler = GeminiEventHandler()
+    elif harness == "claude":
+        handler = ClaudeEventHandler()
     else:
         handler = CodexEventHandler()
 
@@ -779,7 +849,7 @@ def main():
     spawn_parser.add_argument(
         "--harness",
         required=True,
-        choices=["gemini", "codex"],
+        choices=["gemini", "codex", "claude"],
         help="Agent harness to use"
     )
     spawn_parser.add_argument(

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

@@ -0,0 +1,114 @@
+# 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

@@ -0,0 +1,167 @@
+# 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

@@ -0,0 +1,169 @@
+# 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