claude-comms 1.0.45 → 2.0.0

package/CHANGELOG.md

@@ -1,10 +1,29 @@
 # Changelog
 
-All notable changes to the `@claude-code/setup-installer` package will be documented in this file.
+All notable changes to the `claude-comms` package will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-05-14
+
+### BREAKING CHANGE
+
+CC2 (hooks, observability server, Vue dashboard) has been retired. `npx claude-comms` now installs **only** the workflow engine client tooling (`.agents/` directory with runner, templates, and CLI).
+
+#### Removed
+- `.claude/hooks/` — Python hook scripts for CC2 event capture and inter-agent messaging (replaced by `.agents/tools/workflow/agent-comms.mjs`)
+- `.claude/settings.json` — CC2 hook wiring configuration
+- CC2 server (`apps/server/`) and dashboard (`apps/client/`) are no longer part of the system
+
+#### What clients get now
+- `.agents/` — workflow engine client: runner daemon, prompt templates, CLI tools, peer-comms
+- `CLAUDE.md` — agent operating instructions
+
+Clients that depend on CC2 hooks or the observability server should pin to `claude-comms@1.x`.
+
+---
+
 ## [1.0.4] - 2025-01-15
 
 ### 🚨 EMERGENCY FIX

package/README.md

@@ -1,43 +1,42 @@
-# @claude-code/setup-installer
+# claude-comms
 
-NPX-installable package to set up Claude multi-agent orchestration in any project.
+NPX installer for Claude Code workflow engine client setup.
 
 ## Installation & Usage
 
 ### Quick Start
 ```bash
-npx @claude-code/setup-installer
+npx claude-comms
 ```
 
 ### Options
 ```bash
 # Install to specific directory
-npx @claude-code/setup-installer --dir ./my-project
+npx claude-comms --dir ./my-project
 
 # Install specific version
-npx @claude-code/setup-installer --version v1.2.0
+npx claude-comms --version v1.2.0
 
 # Force overwrite existing files
-npx @claude-code/setup-installer --force
+npx claude-comms --force
 
 # Skip Python/uv dependency check
-npx @claude-code/setup-installer --no-python-check
+npx claude-comms --no-python-check
 
 # Development mode with verbose logging
-npx @claude-code/setup-installer --dev
+npx claude-comms --dev
 
 # Verify mode (no changes)
-npx @claude-code/setup-installer --verify
+npx claude-comms --verify
 
 # Dry run (show what would be done)
-npx @claude-code/setup-installer --dry-run
+npx claude-comms --dry-run
 ```
 
 ## What Gets Installed
 
-- `.claude/` directory with hooks, agents, and configuration
-- `CLAUDE.md` project instructions file
-- `settings.local.json` template for local configuration
+- `.agents/` directory with workflow runner, prompt templates, and CLI tools
+- `CLAUDE.md` agent operating instructions
 
 ## Development
 

package/bin/claude-setup.js

@@ -75,10 +75,9 @@ async function main() {
     
     // Show next steps
     console.log(chalk.cyan('Next steps:'));
-    console.log(chalk.white('1. Review .claude/settings.local.json for configuration'));
-    console.log(chalk.white('2. Ensure Python and uv are installed for hooks'));
-    console.log(chalk.white('3. Start the observability server (optional)'));
-    console.log(chalk.white('4. Open your project in Claude Code'));
+    console.log(chalk.white('1. Ensure Python and uv are installed for hooks'));
+    console.log(chalk.white('2. Start the observability server (optional)'));
+    console.log(chalk.white('3. Open your project in Claude Code'));
     console.log(chalk.cyan('\nHappy coding with Claude! 🤖\n'));
     
   } catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-comms",
-  "version": "1.0.45",
-  "description": "NPX installer for Claude Code hooks and observability setup",
+  "version": "2.0.0",
+  "description": "NPX installer for Claude Code workflow engine client setup",
   "main": "src/index.js",
   "bin": {
     "claude-comms": "bin/claude-setup.js"
@@ -26,13 +26,12 @@
   },
   "keywords": [
     "claude-code",
-    "hooks",
-    "observability",
     "npx",
     "installer",
-    "multi-agent"
+    "workflow-engine",
+    "convex"
   ],
-  "author": "Claude Code Team",
+  "author": "Alex Savage (https://github.com/screwyforcepush)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -77,10 +76,7 @@
     "src/",
     "templates/",
     "README.md",
-    "CHANGELOG.md",
-    ".claude/",
-    ".agents/",
-    "CLAUDE.md"
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"

package/src/orchestrator/installer.js

@@ -339,6 +339,7 @@ class Installer extends EventEmitter {
 
       // Files that should not be overwritten if they exist (user customizations)
       const preserveIfExists = [
+        { path: '.claude/settings.local.json', fullPath: path.join(this.options.targetDir, '.claude', 'settings.local.json') },
         { 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') }
       ];
@@ -397,67 +398,9 @@ class Installer extends EventEmitter {
     this.state = InstallationState.CONFIGURING;
     this._emitProgress('Configuring installation...', 80);
 
-    if (this.options.dryRun) {
-      this.logger.info('DRY RUN: Would configure local settings');
-      return;
-    }
-
-    try {
-      // Generate settings.local.json with comprehensive defaults
-      const settingsPath = path.join(this.options.targetDir, '.claude', 'settings.local.json');
-      const defaultSettings = {
-        observability: {
-          server_url: 'http://localhost:3001',
-          enabled: true,
-          auto_start: false
-        },
-        hooks: {
-          enabled: true,
-          python_path: 'python3',
-          uv_path: 'uv',
-          timeout: 30
-        },
-        agents: {
-          max_concurrent: 10,
-          timeout: 300,
-          retry_attempts: 3
-        },
-        communication: {
-          message_retention_hours: 24,
-          broadcast_enabled: true
-        },
-        development: {
-          verbose_logging: false,
-          debug_mode: false
-        },
-        installation: {
-          date: new Date().toISOString(),
-          version: this.options.version,
-          installer_version: '1.0.0',
-          installed_via: 'npx-installer'
-        }
-      };
-
-      // Only create settings.local.json if it doesn't exist
-      const settingsExists = await this.validator.pathExists(settingsPath);
-      if (!settingsExists) {
-        await this.writer.writeFile(settingsPath, JSON.stringify(defaultSettings, null, 2), {
-          overwrite: false
-        });
-        this.installedFiles.push(settingsPath);
-        this.logger.info('Created settings.local.json with default configuration');
-      } else {
-        this.logger.info('settings.local.json already exists, skipping creation');
-      }
-
-      this.logger.info('Post-installation configuration completed');
-
-    } catch (error) {
-      throw new InstallerError(
-        `Post-installation configuration failed: ${error.message}`,
-        ErrorCode.CONFIGURATION_FAILED
-      );
-    }
+    // settings.local.json is user-owned and never generated or overwritten.
+    // All needed files come from the GitHub fetch in Phase 2.
+    this.logger.info('Post-installation configuration completed');
   }
 
   /**
@@ -475,8 +418,7 @@ class Installer extends EventEmitter {
     const requiredPaths = [
       path.join(this.options.targetDir, '.claude'),
       path.join(this.options.targetDir, '.agents'),
-      path.join(this.options.targetDir, 'CLAUDE.md'),
-      path.join(this.options.targetDir, '.claude', 'settings.local.json')
+      path.join(this.options.targetDir, 'CLAUDE.md')
     ];
 
     const missingPaths = [];

package/.agents/AGENTS.md

@@ -1,61 +0,0 @@
-[AGENT OPERATING PROCEDURES]
-# AOP
-
-[CALIBRATE]
-Baseline your understanding of the project current state, trajectory, guidelines. ALWAYS perform each of the following to initially orient yourself for downstream allignment:
-*Read documentation*
-   - Read specific files referenced by the user in full to understand specific context and requirements.
-   - Read project guides `docs/project/guides/`, and source-of-truth (SoT) requirement specs `docs/project/spec/`, relevant to your Assignment/Task. IMPORTANT: You will need to read multiple documents, some of which may link to other relevant documents you must read. You must allign your approach with this documentation. Read the relevant documents in full!
-   - Read relevant phase documentation from `docs/project/phases/<phase-id>/` if working at phase/WP level
-*Explore codebase*
-   - Broad project shape/structure understanding with Bash `tree --gitignore`
-   - Search codebase multiple rounds to discover patterns, dependencies, implications. You can use `ripgrep` and `ast-grep` CLI
-   - Read code and test files, trace impact through end to end 
-
-
-
-[IMPLEMENT]
-Ensure you understand the full context, trace the target change through end to end to understand every point it touches. 
-feel the edges. THINK HARD about the implications/impacts
-- Decision: Weigh up the implementation approach options
-
-*Decision: If you are implementing business logic, API, workflows, or user journeys: Write Tests FIRST (Red Phase):*
-   - THINK HARD about the *Testing Trophy* model for your Assignment/Task. Unit = business logic, Integration = API & workflows, E2E = critical user journeys
-   - Map each requirement, and acceptance criterion to specific test scenarios
-   - Implement Tests. ensuring that the tests cover all acceptance criteria
-
-*Implementation (Green Phase)*:
-   - Write minimal code to meet acceptance criteria.
-   - Ensure code alligns with project guides, conventions and patterns
-   - Refactor code for clarity, performance, maintainability
-
-
-
-[ASSESS]
-Evaluate the Change for a given Assignment/Task against the following criteria:
-1. **User Intent:** PONDER the intent of the User. Was the true intent actioned, or was it missunderstood?
-2. **Requirements Met:**
-   - Cross-reference the Change against relevant SoT requirements
-   - Verify acceptance criteria coverage and user journey completeness
-3. **Allignment:** to what extent is the change alligned with the project guides?
-4. **Quality** SOLID, DRY, design pattern, separation of concerns, complexity O(n), error handling, test coverage/pyramid
-
-
-
-[VALIDATE]
-Run required commands from `.agents/repo.md` — all must pass without warnings or errors:
-   - lint
-   - typecheck
-   - build
-   - test
-
-[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]
-
-# Adhere to the Repository Guidelines: `.agents/repo.md`

package/.agents/repo.md

@@ -1,18 +0,0 @@
-
-# Repository Guidelines
-VALIDATE by Running required commands — all must pass without warnings or errors:
-   - `pnpm lint`
-   - `pnpm ts:check`
-   - `pnpm test:all`
-   - `pnpm build`
-
-
-## Dev server
-`pnpm dev | tee -a dev.log` is already running in the background. check the `dev.log` file. Avoid starting up a new instance as it will bump the port.
-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.
-
-## PRE Deployment
-`vercel build --yes` must pass otherwise CI/CD will FAIL!

package/.agents/tools/README.md

@@ -1,45 +0,0 @@
-# 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/agent-job/README.md

@@ -1,208 +0,0 @@
-# Agent Job Adapter
-
-Self-contained `uv` Python scripts that turn verbose CLI agent runs (Codex, Gemini CLI) into **file-backed jobs** with stable IDs and cheap status checks.
-
-## Quick Start
-
-```bash
-# Spawn a new job (returns immediately)
-uv run agent_job.py spawn --harness codex -- "your assignment here"
-# Output: Agent running. Check status with: `uv run agent_job.py status <job_id>`
-
-# Check job status
-uv run agent_job.py status <job_id>
-
-# List all jobs
-uv run agent_job.py list
-
-# Monitor jobs with TUI
-uv run agent_monitor.py
-```
-
-## Commands
-
-### `spawn`
-
-Starts a new agent job with the specified harness. Returns immediately after initialization.
-
-```bash
-uv run agent_job.py spawn --harness <gemini|codex> -- "<assignment>"
-```
-
-**Output:**
-```
-Agent running. Check status with: `uv run agent_job.py status 019abd9d-8cb2-7e81-bae9-2a8fe5be04fa`
-```
-
-### `status`
-
-Get current status of a job with computed runtime metrics.
-
-```bash
-uv run agent_job.py status <job_id>
-```
-
-**Running job output:**
-```json
-{
-  "job_id": "019abd9d-8cb2-7e81-bae9-2a8fe5be04fa",
-  "harness": "codex",
-  "pid": 12345,
-  "logs": "/path/to/agent.log",
-  "status": "running",
-  "status_reason": "command_execution",
-  "start_time": "2025-11-25T08:10:06.262Z",
-  "last_event_time": "2025-11-25T08:10:29.337Z",
-  "runtime_sec": 23.1,
-  "idle_sec": 4.0,
-  "operations": 18
-}
-```
-
-**Completed job output:**
-```json
-{
-  "job_id": "019abd9d-8cb2-7e81-bae9-2a8fe5be04fa",
-  "harness": "codex",
-  "pid": 12345,
-  "logs": "/path/to/agent.log",
-  "status": "complete",
-  "status_reason": "completed",
-  "start_time": "2025-11-25T08:10:06.262Z",
-  "last_event_time": "2025-11-25T08:10:29.337Z",
-  "runtime_sec": 23.1,
-  "operations": 18,
-  "end_time": "2025-11-25T08:10:29.340Z",
-  "completion": {
-    "messages": ["Task completed successfully."],
-    "tokens": { "input": 7288, "output": 84, "total": 7372 },
-    "duration_ms": 13845
-  }
-}
-```
-
-### `list`
-
-List all jobs with full status information.
-
-```bash
-uv run agent_job.py list
-```
-
-## Monitor TUI
-
-Real-time terminal UI for monitoring agent jobs, similar to `top`.
-
-```bash
-uv run agent_monitor.py              # Default 2s refresh
-uv run agent_monitor.py --interval 5 # Custom refresh interval
-```
-
-**Features:**
-- Color-coded status indicators:
-  - `●` Yellow = running
-  - `✓` Green = complete
-  - `✗` Red = error
-  - `⏱` Red = timeout
-- Columns: Status, Harness, Job ID, Status Reason, Started, Runtime, Operations
-- Scrollable log viewer
-
-**Keyboard Controls:**
-
-| Key | Action |
-|-----|--------|
-| `↑/↓` or `j/k` | Navigate job list |
-| `Enter` | View job log |
-| `r` | Refresh / reload log |
-| `q` | Quit |
-
-**Log View Controls:**
-
-| Key | Action |
-|-----|--------|
-| `↑/↓` or `j/k` | Scroll line by line |
-| `PgUp/PgDn` | Scroll by page |
-| `Home/End` | Jump to start/end |
-| `r` | Reload log file |
-| `ESC` | Back to job list |
-
-## Job Status
-
-| Status | Description |
-|--------|-------------|
-| `running` | Job is currently executing |
-| `complete` | Job finished successfully |
-| `error` | Job failed (see `status_reason`) |
-| `timeout` | Job killed due to idle timeout |
-
-## Status Reason
-
-The `status_reason` field shows current activity while running:
-
-**Codex:**
-- `initializing` - Job starting up
-- `thinking` - Turn started
-- `reasoning` - Agent reasoning
-- `command_execution` - Running shell command
-- `todo_list` - Managing todos
-- `agent_message` - Generating response
-- `completed` - Finished
-
-**Gemini:**
-- `initializing` - Job starting up
-- `run_shell_command` - Running command
-- `write_file` / `read_file` - File operations
-- `write_todos` - Managing todos
-- `responding` - Generating response
-- `completed` - Finished
-
-## Configuration
-
-| Environment Variable | Default | Description |
-|---------------------|---------|-------------|
-| `AGENT_JOBS_ROOT` | `$TMPDIR/agent_jobs/$USER` | Root directory for job files |
-| `IDLE_TIMEOUT_SEC` | `300` | Seconds of inactivity before killing job |
-
-## File Structure
-
-Each job creates a directory under `AGENT_JOBS_ROOT`:
-
-```
-<jobs_root>/<job_id>/
-    status.json    # Current job state (updated on each event)
-    agent.log      # Raw harness output (appended in real-time)
-```
-
-## Supported Harnesses
-
-### Codex
-
-Uses `codex --yolo e "<assignment>" --json`
-
-Events handled:
-- `thread.started` - Extracts job ID (thread_id)
-- `turn.started` - Sets status_reason to "thinking"
-- `item.started/completed` - Updates status_reason with item type
-- `turn.completed` - Extracts token usage
-
-### Gemini CLI
-
-Uses `gemini --yolo -s -m gemini-3-pro-preview --output-format stream-json "<assignment>"`
-
-Events handled:
-- `init` - Extracts session ID as job ID
-- `tool_use` - Updates status_reason with tool name
-- `message` (assistant) - Accumulates response text
-- `result` - Extracts token stats and duration
-
-## Babysitter Pattern
-
-For autonomous monitoring:
-
-1. **Spawn** the job - returns immediately with job ID
-2. **Poll** status periodically
-3. **React** based on status:
-   - `running` - Check `idle_sec`, continue monitoring
-   - `complete` - Read `completion.messages`
-   - `timeout` - Report idle timeout exceeded
-   - `error` - Check `status_reason` and logs