quadwork 0.1.3 → 1.0.0

package/README.md

@@ -1,73 +1,70 @@
 # QuadWork
 
-A unified dashboard for multi-agent coding teams. Four AI agents (T1 owner, T2a/T2b reviewers, T3 builder) collaborate through terminals, chat, GitHub integration, and shared memory — all served from a single local web view.
+Your AI dev team in a box. Four agents — one Head, one Dev, two Reviewers — that code, review, and ship while you sleep.
 
-## Dashboard
+## Getting Started
 
-```
-+--------+----------------------------+----------------------------+
-|        |  T1 Terminal               |  T2a Terminal              |
-| Side-  |  (Owner)                   |  (Reviewer)               |
-| bar    +----------------------------+----------------------------+
-|        |  T3 Terminal               |  T2b Terminal              |
-| [Home] |  (Builder)                 |  (Reviewer)               |
-| [Proj] +----------------------------+----------------------------+
-| [+]    |  Agent Chat (AgentChattr)  |  GitHub (Issues + PRs)    |
-| [Set]  |                            |                           |
-+--------+----------------------------+----------------------------+
+1. Install [Node.js 20+](https://nodejs.org) if you don't have it
+2. Open your terminal and run:
+
+```bash
+npx quadwork init
 ```
 
-## Features
+3. The wizard installs everything else and opens your dashboard.
 
-- **Terminal panels** — Live xterm.js terminals for each agent with PTY sessions
-- **Agent chat** — AgentChattr integration for real-time agent coordination
-- **GitHub board** — Issues, PRs, and review status at a glance
-- **Task queue** — Build and dispatch work queues to T1 with one click
-- **Shared memory** — Memory cards, butler scripts, and cross-agent context
-- **Telegram bridge** — Optional Telegram bot integration for mobile notifications
-- **Single-port server** — Everything on `http://127.0.0.1:8400` (API + WebSocket + UI)
-- **Backend indicator** — Clear offline/online status in the sidebar
+That's it. The wizard handles Python, GitHub CLI, AI tools, and authentication — you just follow the prompts.
 
-## Prerequisites
+## How It Works
 
-- **Node.js 20+** (with C++ toolchain for native modules)
-- **Python 3.10+** (for AgentChattr)
-- **GitHub CLI** (`gh`) — [install](https://cli.github.com)
-- **Claude Code** or **Codex CLI** — at least one AI agent CLI
+QuadWork runs a team of 4 AI agents on your local machine:
 
-## Quick Start
+| Agent | Role | What it does |
+|-------|------|-------------|
+| **Head** | Coordinator | Creates issues, assigns tasks, merges approved PRs |
+| **Dev** | Builder | Writes code, opens PRs, addresses review feedback |
+| **Reviewer1** | Reviewer | Independent code review with veto authority |
+| **Reviewer2** | Reviewer | Independent code review with veto authority |
 
-```bash
-npx quadwork init      # Interactive setup: repo, worktrees, agents, config
-npx quadwork start     # Launches dashboard at http://127.0.0.1:8400
-npx quadwork stop      # Stops all processes
-```
+Every task follows a GitHub workflow: Issue → Branch → PR → 2 Reviews → Merge. Branch protection ensures no agent can skip the process.
 
-## Install from Source
+## Dashboard
 
-```bash
-git clone https://github.com/realproject7/quadwork.git
-cd quadwork
-npm install
-npm run build          # Static frontend export to out/
-node server/           # Start server at http://127.0.0.1:8400
+```
++--------+----------------------------+----------------------------+
+|        |  Head Terminal             |  GitHub (Issues + PRs)     |
+| Side-  |  (Coordinator)             |                            |
+| bar    +----------------------------+----------------------------+
+|        |  Agent Chat                |  Reviewer1  |  Reviewer2   |
+| [Home] |  (AgentChattr)             |             |              |
+| [Proj] |                            +-------------+--------------+
+| [+]    |                            |  Dev Terminal              |
+| [Set]  |                            |  (Builder)                 |
++--------+----------------------------+----------------------------+
+| Keep Alive | Server: Stop Restart Reset | System: Keep Awake      |
++--------+----------------------------+----------------------------+
 ```
 
-For development (hot reload):
+## Features
 
-```bash
-npm run dev            # Next.js dev server on :3000
-npm run server         # Express backend on :8400 (run in separate terminal)
-```
+- **Terminal panels** — Live terminals for each agent with PTY sessions
+- **Agent chat** — Real-time agent coordination via AgentChattr
+- **GitHub board** — Issues, PRs, and review status at a glance
+- **Task queue** — Build and dispatch work queues with one click
+- **Keep Alive** — Scheduled check-in messages to keep agents active (with auto-stop duration)
+- **Keep Awake** — Prevent your Mac from sleeping during overnight runs
+- **Multi-project** — Each project gets its own AgentChattr instance and ports
+- **Telegram bridge** — Optional mobile notifications via [agentchattr-telegram](https://github.com/realproject7/agentchattr-telegram)
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `quadwork init` | Interactive setup wizard — repo, worktrees, agent config |
-| `quadwork start` | Start the server (frontend must be pre-built) |
-| `quadwork stop` | Stop server, AgentChattr, and Telegram bridge |
-| `quadwork add-project` | Add another project to an existing setup |
+| `npx quadwork init` | One-time setup — installs prerequisites and opens the dashboard |
+| `npx quadwork start` | Start the dashboard server |
+| `npx quadwork stop` | Stop all processes |
+
+After init, create projects from the web UI at `http://127.0.0.1:8400/setup`.
 
 ## Configuration
 
@@ -76,59 +73,37 @@ Config is stored at `~/.quadwork/config.json`:
 ```json
 {
   "port": 8400,
-  "agentchattr_url": "http://127.0.0.1:8300",
   "projects": [
     {
       "id": "my-project",
       "name": "My Project",
       "repo": "owner/repo",
       "working_dir": "/path/to/project",
+      "agentchattr_url": "http://127.0.0.1:8300",
+      "mcp_http_port": 8200,
+      "mcp_sse_port": 8201,
       "agents": {
-        "head": { "cwd": "/path/to/project-head", "command": "claude" },
-        "reviewer1": { "cwd": "/path/to/project-reviewer1", "command": "claude" },
-        "reviewer2": { "cwd": "/path/to/project-reviewer2", "command": "claude" },
-        "dev": { "cwd": "/path/to/project-dev", "command": "claude" }
+        "head": { "cwd": "/path/to/project-head", "command": "codex" },
+        "dev": { "cwd": "/path/to/project-dev", "command": "claude" },
+        "reviewer1": { "cwd": "/path/to/project-reviewer1", "command": "codex" },
+        "reviewer2": { "cwd": "/path/to/project-reviewer2", "command": "claude" }
       }
     }
   ]
 }
 ```
 
-Each agent runs in its own git worktree (sibling directories).
-
-## Optional Add-ons
-
-### AgentChattr
-
-Shared chat server for agent coordination. Install separately:
-
-```bash
-pip install agentchattr
-```
-
-The setup wizard configures AgentChattr automatically. See [agentchattr](https://github.com/realproject7/agentchattr) for details.
-
-### Telegram Bridge
-
-Forward agent chat to a Telegram group. Configure in Settings or during `quadwork init`. Requires a Telegram bot token and chat ID.
-
-### Shared Memory
-
-Cross-agent memory system with memory cards and butler scripts. Set up during `quadwork init` or configure paths in Settings.
+Each project gets its own AgentChattr instance, ports, and git worktrees.
 
 ## Architecture
 
 QuadWork runs a single Express server that serves:
 
-- **Static frontend** — Pre-built Next.js export (`out/`)
-- **REST API** — Agent lifecycle, config, GitHub, chat proxy, memory, triggers
-- **WebSocket** — Terminal PTY sessions at `/ws/terminal`
-
-All on one port (`127.0.0.1:8400`), no CORS needed.
-
-## Design
+- **Static frontend** — Pre-built Next.js export
+- **REST API** — Agent lifecycle, config, GitHub, chat proxy, triggers
+- **WebSocket** — Terminal PTY sessions
 
-See [docs/PROPOSAL.md](docs/PROPOSAL.md) for the full design specification.
+All on one port (`127.0.0.1:8400`).
 
 ## License