@proletariat/cli 0.2.0 → 0.3.1

package/README.md

@@ -1,364 +1,674 @@
-# ⚒️ PROLETARIAT CLI
+```
+██████╗ ██████╗  ██████╗ ██╗     ███████╗████████╗ █████╗ ██████╗ ██╗ █████╗ ████████╗
+██╔══██╗██╔══██╗██╔═══██╗██║     ██╔════╝╚══██╔══╝██╔══██╗██╔══██╗██║██╔══██╗╚══██╔══╝
+██████╔╝██████╔╝██║   ██║██║     █████╗     ██║   ███████║██████╔╝██║███████║   ██║
+██╔═══╝ ██╔══██╗██║   ██║██║     ██╔══╝     ██║   ██╔══██║██╔══██╗██║██╔══██║   ██║
+██║     ██║  ██║╚██████╔╝███████╗███████╗   ██║   ██║  ██║██║  ██║██║██║  ██║   ██║
+╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝   ╚═╝
+```
+
+### Seize the means of production - Ship 100x.
 
-> **Workspace Manager for Parallel AI Development**  
-> *Run multiple Cursor sessions, Claude Code instances, or CLI agents simultaneously on one machine - each working on different features without conflicts*
+> **Turn tickets into output with AI labor**
 
-**Scale your solo development: Multiple AI sessions, parallel workspaces, all on your local machine!** 
+> 💡 *Paying for Claude Max but not maxing it out? You're leaving money on the table.*
+
+> ⚠️ **Beta Software** — Commands, flags, and APIs may change between versions. Not yet recommended for production automation scripts.
 
 ---
 
-## What Is This?
+# TLDR
 
-**PROLETARIAT CLI** implements the design pattern for running multiple AI coding sessions in parallel on a single machine. Each "agent" gets a persistent workspace (a git worktree - but I call them workspaces because it's clearer) where you or your AI tools can work continuously, switching between features as needed:
+**prlt** coordinates AI coding agents from one CLI. Isolated workspaces, secure containers, persistent state.
 
-- 🤖 **Persistent AI workspaces** - Let one Claude Code instance live in "bezos" while another Claude Code instance works in "musk" - each for weeks at a time
-- 🔀 **Branch without context switching** - Each workspace can switch branches to work on new features while keeping its workspace directory intact
-- 🎯 **Parallel AI work streams** - Multiple AI agents can work simultaneously on different features for the same repo, each in their own branch and workspace
+```bash
+npm install -g @proletariat/cli
+prlt init
+prlt ticket create --title "Add OAuth" --category feature
+prlt work spawn   # Interactive: select tickets, environment, action
+```
 
-Using memorable themes, you manage your agent workforce:
-- 💰 **Billionaires** become your coding workforce (Bezos, Musk, Gates)
-- 🚗 **Toyotas** drive your development forward (Prius, Tacoma, Tundra)
-- 🏢 **Companies** form your development portfolio (Apple, Google, Microsoft)
+Agent spawns in its own branch, writes code, opens PR. You review and merge.
 
-Each workspace is a dedicated git worktree on your local machine. Run as many AI coding sessions as there are agents in your theme (40 billionaires!) - Cursor, Claude Code, Aider, etc. - editing different features, or quickly switch between workspaces without losing context!
+**Why prlt?**
+- **Isolated** - Each agent gets its own git branch. No conflicts.
+- **Secure** - Docker containers, sandboxed from your host.
+- **Durable** - Tmux sessions persist. Close window, agent keeps working.
+- **Trackable** - One database, one CLI, all your agents.
+- **Ephemeral** - Spawn agents on demand. They work, they PR, they're done.
+- **Structured** - Tickets provide structured context, not freeform chat.
+- **Persistent** - Tickets accumulate context over time. Hand off between agents.
+- **Agent-native** - `--json` mode lets AI agents drive the CLI programmatically.
 
 ---
 
-## 💡 The Design Pattern
+# Quick Start
 
-**Problem:** AI coding tools work in a single directory. Want to work on multiple features? You're stuck with stashing, branching, and context switching.
-
-**Solution:** PROLETARIAT creates isolated agent workspaces on your machine where you can run multiple AI sessions:
+```bash
+npm install -g @proletariat/cli    # Install
+prlt init                          # Create HQ, add repos, choose theme
+prlt ticket create --title "Add OAuth" --category feature
+prlt work spawn                    # Interactive: select tickets, environment, action
+# Agent creates PR → You review → Merge → Done
+```
 
 ```
-your-company-hq/  (recommended layout)
-├── your-repo/              # Your original repo
-├── your-repo-staff/
-│   ├── bezos/    → Claude Code 1: Building authentication
-│   ├── musk/     → Claude Code 2: Implementing AI features  
-│   ├── gates/    → Cursor: Refactoring database
-│   ├── jobs/     → Codex CLI 1: Writing test suite
-│   └── cook/     → Codex CLI 2: Fixing security issues
+┌─────┐          ┌──────┐          ┌───────┐          ┌────────┐
+│ You │          │ prlt │          │ Agent │          │ GitHub │
+└──┬──┘          └──┬───┘          └───┬───┘          └───┬────┘
+   │  ticket create │                  │                  │
+   │───────────────>│                  │                  │
+   │  work spawn    │                  │                  │
+   │───────────────>│                  │                  │
+   │                │  create branch   │                  │
+   │                │  create workspace│                  │
+   │                │  spawn agent     │                  │
+   │                │─────────────────>│                  │
+   │                │                  │  read ticket     │
+   │                │                  │  write code      │
+   │                │                  │  commit          │
+   │                │                  │─────────────────>│
+   │                │                  │  open PR         │
+   │                │                  │─────────────────>│
+   │                │   update status  │                  │
+   │                │<─────────────────│                  │
+   │   PR ready     │                  │                  │
+   │<───────────────│                  │                  │
+   │                      review & approve                │
+   │─────────────────────────────────────────────────────>│
 ```
 
-**Result:** One developer, 5 agent directories, 0 conflicts. Work on multiple features simultaneously or let AI agents handle different tasks!
+<details>
+<summary>View interactive diagram (GitHub only)</summary>
+
+```mermaid
+sequenceDiagram
+    participant You
+    participant prlt
+    participant Agent
+    participant GitHub
+
+    You->>prlt: prlt ticket create
+    You->>prlt: prlt work spawn
+    prlt->>prlt: Create branch
+    prlt->>prlt: Create workspace
+    prlt->>Agent: Spawn agent
+    Agent->>Agent: Read ticket
+    Agent->>Agent: Write code
+    Agent->>GitHub: Commit
+    Agent->>GitHub: Open PR
+    Agent->>prlt: Update status
+    prlt->>You: PR ready
+    You->>GitHub: Review & approve
+```
 
-![Multi-Agent Development in Action](https://github.com/chrismcdermut/proletariat-cli/raw/main/assets/multi-agent-workspace.png)
-*Three workspaces in parallel, each with manual pane + AI agent: `andreesen` (left) on Feature A, `zuck` (center) fixing a reported bug, and `jobs` (right) on Feature B. No musk, he was fired!* 
+</details>
 
----
+Spawn agents to implement, groom, or review—not just write code.
 
-## 🎯 Core Features
+### Interactive Menus
 
-### ⚡ **Zero Configuration**
-Just `prlt init` and you're ready to go. Zero configuration required.
+`prlt work` guides you through project and ticket selection:
 
-### 🎨 **Three Fun Themes** *(Custom theme support coming soon!)*
-- **💰 Billionaires**: Hire/fire billionaire workers in `../your-repo-staff/`
-- **🚗 Cars**: Drive/park cars in `../your-repo-garage/` 
-- **🏢 Companies**: Buy/sell companies in `../your-repo-portfolio/`
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/work/work-project-select.png" alt="Project Selection" width="600">
+</p>
 
-### 🔀 **Multiple Agent Workspaces in Your HQ**
-Each agent gets their own clean workspace (`git worktree`) on your local filesystem. Run multiple Cursor windows, Claude Code instances, or just keep different features open - each agent in their own workspace, no context switching needed.
+Choose your operation—start a single agent, batch spawn, or watch a column:
 
----
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/work/work-operations-menu.png" alt="Work Operations Menu" width="600">
+</p>
 
-## 🚀 Quick Start
+Select tickets to spawn, grouped by priority:
 
-```bash
-# Install
-npm install -g @proletariat/cli
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/work/work-ticket-select.png" alt="Ticket Selection" width="800">
+</p>
 
-# Initialize with interactive theme selection
-cd your-repo
-prlt init  # Prompts you to choose: billionaires, toyotas, or companies
+---
 
-# Create worktrees with themed commands
-prlt hire bezos musk        # Billionaires theme
-prlt drive 4runner prius      # Cars theme  
-prlt buy apple microsoft    # Companies theme
+# Deep Dive
 
-# Check status
-prlt staff                   # Billionaires theme
-prlt garage                  # Cars theme
-prlt portfolio               # Companies theme
+| Problem | Solution |
+| --- | --- |
+| Agents conflict with each other's changes | **Isolated** - Each agent gets its own git branch and worktree |
+| Agents run unsandboxed on your machine | **Secure** - Docker containers, sandboxed from your host (looking into host sandbox options) |
+| You lose track of who's doing what | **Trackable** - All state in one SQLite database, one CLI |
+| Sessions die when you close a window | **Durable** - Tmux sessions persist, detach/reattach anytime |
+| Context scattered across chat windows | **Structured** - Tickets with requirements, acceptance criteria |
+| Starting agents is heavyweight | **Ephemeral** - Spawn on demand, they work, they PR, they're done |
+| Context lost between agent runs | **Persistent** - Tickets accumulate context, hand off between agents |
 
-# Remove worktrees  
-prlt fire gates             # Billionaires theme
-prlt park honda             # Cars theme
-prlt sell nvidia            # Companies theme
-```
+### Data Model
 
-### 🏗️ Flexible Agent Directory Layouts
+```
+Workspace (HQ)
+├── Projects
+│   ├── Epics → Tickets
+│   └── (references a Workflow)
+├── Workflows → Phases → Statuses (can be shared across projects)
+├── Specs (can span projects)
+├── Actions (reusable templates)
+├── Agents
+│   ├── Staff (persistent, named)
+│   └── Temp (ephemeral, per-ticket)
+└── Executions (running sessions)
+    ├── Docker
+    │   ├── Tmux session
+    │   ├── Terminal or Background display
+    │   └── Safe or YOLO permissions
+    └── Host
+        ├── Tmux session
+        ├── Terminal or Background display
+        └── Safe or YOLO permissions
+```
 
-**HQ Layout (Recommended)** - Group original repositories and agent workspaces under one headquarters directory:
-```bash
-# IMPORTANT: Run prlt init inside EACH repository you want to manage
-cd frontend-repo && prlt init --hq your-company
-cd ../backend-repo && prlt init --hq your-company  
+| Entity | Description |
+| --- | --- |
+| **Project** | Groups tickets and epics, references a workflow |
+| **Epic** | Work container with lifecycle (draft → active → complete) |
+| **Ticket** | Individual work item with requirements and acceptance criteria |
+| **Spec** | Static documentation (can span projects, linked to epics) |
+| **Workflow** | Status flow configuration (can be shared across projects) |
+| **Phase** | Stage in a workflow |
+| **Status** | Ticket state within a phase |
+| **Action** | Reusable prompt/action templates |
+| **Agent (Staff)** | Persistent named agent with dedicated workspace |
+| **Agent (Temp)** | Ephemeral agent spawned for a single ticket |
+| **Execution** | Running agent session on a ticket |
+| **Display** | Terminal (new tab) or Background (detached) |
+
+### Example Workflow
+
+A workflow defines how tickets move through your process. Projects reference a workflow, and multiple projects can share the same one.
 
-# Each repo needs its own initialization since worktrees are per-repository
+```
+Kanban Workflow
+├── Backlog       # New tickets land here
+├── In Progress   # Agent working (prlt work spawn)
+├── Review        # PR ready (prlt work ready)
+└── Done          # Merged (prlt work complete)
 ```
 
-Creates this organized structure to hold multi-repo projects:
 ```
-your-company-hq/            # HQ containing all repos and agent workspaces
-├── frontend-repo/          (main frontend repository)
-├── frontend-repo-staff/    (frontend billionaire agents)
-│   ├── bezos/      (e.g., Claude Code instance 1)
-│   ├── musk/       (e.g., Claude Code instance 2)
-│   └── gates/      (e.g., Cursor)
-├── backend-repo/           (main backend repository)  
-└── backend-repo-staff/     (backend billionaire agents)
-    ├── cook/       (e.g., Codex CLI 1)
-    ├── jobs/       (e.g., Codex CLI 2)
-    └── buffett/    (e.g., Claude Code instance 2)
+Scrum Workflow
+├── Backlog
+├── Sprint
+│   ├── To Do
+│   ├── In Progress
+│   └── In Review
+└── Done
 ```
 
-Each repository maintains its own `.proletariat/config.json` since worktrees are per-repository.
+Tickets flow through statuses as work progresses. Agents automatically move tickets when they start work, open PRs, or complete tasks.
+
+### Workspace Structure
+
+Each agent gets a copy of all repos (repo scoping coming soon). Work happens on isolated branches.
 
-**Default Layout** - Agents as siblings to your repository:
 ```
-some-directory-on-your-machine/
-├── your-repo/          (main repository)
-└── your-repo-staff/    (billionaire agents)
-    ├── bezos/      (e.g., Claude Code instance 1)
-    ├── musk/       (e.g., Claude Code instance 2)
-    └── gates/      (e.g., Cursor)
-    OR
-└── your-repo-garage/   (toyota agents)
-    ├── camry/      (e.g., Codex CLI 1)
-    ├── prius/      (e.g., Codex CLI 2)
-    └── tacoma/     (e.g., Cursor)
-    OR
-└── your-repo-portfolio/ (company agents)
-    ├── apple/      (e.g., Claude Code)
-    ├── google/     (e.g., Cursor instance 1)
-    └── microsoft/  (e.g., Cursor instance 2)
+my-project/
+├── .proletariat/
+│   └── workspace.db              # Tickets, executions, state
+├── repos/
+│   ├── frontend/                 # Your repos
+│   ├── backend/
+│   └── infra/
+└── agents/
+    ├── staff/
+    │   └── alice/                # Named agent with persistent workspace
+    │       ├── frontend/
+    │       ├── backend/
+    │       └── infra/
+    └── temp/
+        ├── agent-abc123/         # Ephemeral: Working on TKT-042 (OAuth)
+        │   ├── frontend/         # All repos on branch: feat/TKT-042-oauth
+        │   ├── backend/
+        │   └── infra/
+        └── agent-def456/         # Ephemeral: Working on TKT-043 (API)
+            ├── frontend/         # All repos on branch: feat/TKT-043-api
+            ├── backend/
+            └── infra/
 ```
 
-**Custom Location** - Point agents anywhere you want:
-```bash
-prlt init --workspace-root ~/code/agents
-# Creates agents in your specified directory
-```
+### Three Ways to Use Commands
 
----
+#### 1. Interactive (Humans)
 
-## 💼 The Billionaire Experience
+Run without flags—get guided prompts:
 
 ```bash
-$ prlt init
-⚒️  PROLETARIAT ⚒️
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-💰 Billionaire Staff 💰
-⚒️ Creating workspaces for your billionaire staff!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-$ prlt hire bezos musk
-💰 Hiring billionaire workers
-💰 BEZOS: Ready to work at ../your-repo-staff/bezos
-💰 MUSK: Ready to work at ../your-repo-staff/musk
-
-$ prlt staff
-💰 Current billionaire staff
-💰 BEZOS: ✅ ACTIVE - ../your-repo-staff/bezos
-    📝 Branch: agent/bezos/work
-💰 MUSK: ✅ ACTIVE - ../your-repo-staff/musk  
-    📝 Branch: agent/musk/work
-
-Workers of the codebase, unite! ✊
-```
+$ prlt ticket create
 
----
+? Title: Add password reset
+? Description: Email-based password reset flow
+? Priority: P1
+? Category: feature
 
-## 🎨 Choose Your Theme
+✓ Created TKT-043
+```
 
-### 💰 Billionaires (Default)
-Make the ultra-wealthy work for YOU!
+View ticket details with `prlt ticket`:
 
-```bash
-prlt init --theme=billionaires
-prlt hire bezos musk gates buffett
-prlt fire zuck        # You're fired!
-prlt staff                  # Check your workers
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/ticket/ticket-view.png" alt="Ticket View" width="600">
+</p>
 
-**Agents**: altman, daramodei, danamodei, andreesen, arnault, benioff, bezos, blakely, bloomberg, branson, brin, buffett, carmack, chesky, cook, dean, dorsey, ellison, gates, horowitz, huang, jobs, kalanick, karpathy, lecun, ma, murati, munger, musk, nadella, ng, oprah, page, perkins, sandberg, sutskever, swift, whitney, wojcicki, zuck  
-**Directory**: `../[your-repo]-staff/`
+#### 2. JSON Mode (AI Agents)
 
-### 🚗 Toyotas  
-Put manufacturing's finest to work as your development fleet.
+Add `--json` for machine-readable output:
 
 ```bash
-prlt init --theme=toyotas
-prlt drive prius tacoma
-prlt park 4runner           # Back to the bay
-prlt garage                 # Check your fleet
+$ prlt work start --json
+```
+
+```json
+{
+  "prompt": {
+    "type": "list",
+    "message": "Select ticket to work on:",
+    "choices": [
+      {
+        "name": "[P1] TKT-042 - Add user authentication",
+        "value": "TKT-042",
+        "command": "prlt work start TKT-042 --json"
+      }
+    ]
+  }
+}
 ```
 
-**Agents**: 1stgen4runner, 2ndgen4runner, 3rdgen4runner, alltrac, camry, fj40, fj60, fj80, fzj80, hdj80, hdj81, highlander, hilux, ironpig, landcruiser, prius, rav4, sierra, tacoma, tercel, troopy, tundra  
-**Directory**: `../[your-repo]-garage/`
+AI agents parse this, make selections, call the next command.
 
-### 🏢 Companies
-Now they're the consumer.
+#### 3. Flags (Scripts/CI)
+
+Pass everything directly:
 
 ```bash
-prlt init --theme=companies  
-prlt buy adobe amazon apple
-prlt sell netflix           # Trim the overperformer
-prlt portfolio              # Check your holdings
+prlt ticket create \
+  --title "Add OAuth" \
+  --description "Google and GitHub OAuth" \
+  --priority P1 \
+  --category feature
 ```
 
-**Agents**: adobe, amazon, apple, atlassian, cisco, google, ibm, meta, microsoft, netflix, nvidia, oracle, shopify, snowflake, tesla, zoom  
-**Directory**: `../[your-repo]-portfolio/`
+### Execution Modes
 
----
+**Environment** - where the agent runs:
 
-## 📚 Command Reference
-
-| Theme | Create | Remove | Status | Directory |
-|-------|--------|--------|--------|-----------|
-| **💰 Billionaires** | `hire` | `fire` | `staff` | `../your-repo-staff/` |
-| **🚗 Cars** | `drive` | `park` | `garage` | `../your-repo-garage/` |
-| **🏢 Companies** | `buy` | `sell` | `portfolio` | `../your-repo-portfolio/` |
-
-### Universal Commands
-- `prlt init [--theme=cars]` - Initialize with theme
-- `prlt init --hq <name>` - Create/join an HQ directory
-- `prlt init --hq-root <path>` - Use a custom agent directory
-- `prlt list [--theme=cars]` - List available agents
-- `prlt themes` - Show all themes
-- `prlt repair` - Fix broken worktree references after repo moves
-- `prlt migrate <hq-name>` - Move your repo into an HQ folder
-- `prlt upgrade` - Upgrade config to latest format (backwards compatible)
-- `prlt health` - Check worktree health status
+| Environment | Flag | Best For |
+| --- | --- | --- |
+| 🐳 Docker | (default if devcontainer exists) | Safety—fully isolated container |
+| 🏃 Host | `--run-on-host` | Speed—no container overhead |
 
----
+**Display** - how you see it:
 
-## 🛠️ How It Works
+| Display | Flag | Best For |
+| --- | --- | --- |
+| 📺 Terminal | `--display terminal` | Watch in new terminal tab |
+| 🔇 Background | `--display background` | Detached, reattach later |
 
-1. **Initialize**: `prlt init` - Choose your theme and HQ layout
-2. **Create agents**: `prlt hire bezos` / `prlt drive camry` / `prlt buy apple` - Creates isolated workspaces (`git worktrees`)
-3. **Work**: Each workspace (git worktree) is a persistent directory where agents can work independently - you can switch AI tools or branches but the workspace persists
-4. **Check status**: `prlt staff` / `prlt garage` / `prlt portfolio` - See your active agents
-5. **Clean up**: `prlt fire bezos` / `prlt park camry` / `prlt sell apple` - Removes worktrees cleanly
+**Permissions** - agent access level:
 
-**That's it!** Simple themed commands wrapping git worktrees.
+| Mode | Flag | Description |
+| --- | --- | --- |
+| 🔒 Safe | (default) | Agent prompts for permissions |
+| 🕺 YOLO | `--skip-permissions` | No prompts, full access. Use with Docker for safe autonomy. |
 
-Configuration is stored in `.proletariat/repo.json` (or `.proletariat/config.json` for backwards compatibility).
+All sessions run in tmux under the hood—close the window, agent keeps working.
 
----
+```bash
+# Default: Docker + terminal (if devcontainer exists)
+prlt work start TKT-042
 
-## 🎯 Parallel AI Development in Action
+# Docker + background
+prlt work start TKT-042 --display background
 
-```bash
-# Set up persistent workspaces
-prlt hire bezos musk gates
+# Host + background (fast, no container)
+prlt work start TKT-042 --run-on-host --display background
+
+# Docker + YOLO (full autonomy, safely sandboxed)
+prlt work start TKT-042 --skip-permissions
 ```
 
-Now open separate terminal panes/tabs or AI IDE windows (Cursor, Windsurf, etc.):
+### Parallel Agents
+
+Work on multiple tickets simultaneously.
 
-**Terminal Pane/Tab or AI IDE Window 1: Agent workspace (e.g., bezos)**
+**Interactive (humans):**
 ```bash
-cd ../your-repo-staff/bezos
-claude-code .  # Claude Code owns this workspace for weeks
-# Monday: Implement login
-# Tuesday: Add OAuth  
-# Wednesday: Fix auth bugs
-# Thursday: Add 2FA
-# All in the same workspace, different branches as needed
+$ prlt work spawn
+
+? Spawn mode: Select specific tickets
+? Select tickets:
+  ◉ [P1] TKT-042 - Add user authentication
+  ◉ [P1] TKT-043 - Add API rate limiting
+  ◯ [P2] TKT-044 - Add email notifications
+? Action: implement
+? Environment: docker
+
+Spawning 2 tickets...
 ```
 
-**Terminal Pane/Tab or AI IDE Window 2: Agent workspace (e.g., musk)**
+**JSON mode (AI agents):** *(multi-select WIP)*
 ```bash
-cd ../your-repo-staff/musk
-cursor .  # Cursor lives here, building feature after feature
-# Week 1: User endpoints
-# Week 2: Payment endpoints
-# Week 3: Analytics endpoints
+$ prlt work spawn --json --many
+```
+```json
+{
+  "prompt": {
+    "type": "checkbox",
+    "message": "Select tickets to spawn:",
+    "choices": [
+      { "name": "[P1] TKT-042 - Add user authentication", "value": "TKT-042" },
+      { "name": "[P1] TKT-043 - Add API rate limiting", "value": "TKT-043" }
+    ]
+  }
+}
 ```
 
-**Terminal Pane/Tab or AI IDE Window 3: Agent workspace (e.g., gates)**
+**Flags (scripts/CI):**
 ```bash
-cd ../your-repo-staff/gates
-# Your manual testing, experiments, debugging
-# No AI needed - just your playground
+prlt work spawn TKT-042 TKT-043 --action implement --mode docker
 ```
 
-Merge completed work from any workspace:
-```bash
-# Option 1: GitHub PR (recommended)
-cd ../your-repo-staff/bezos
-gh pr create --title "Add login feature" --body "Authentication implementation"
-
-# Option 2: Local merge  
-cd ../your-repo        # (on main or development branch, feature-branch etc)
-git merge bezos/feature-login
-git merge musk/api-v2
-# Each workspace keeps working independently!
+Each agent works in its own branch. No conflicts.
+
+> **Scaling:** The main limit is your machine. 50+ concurrent agents is achievable—depends on CPU, RAM, and whether you're running Docker or host mode.
+
+Monitor running agents with `prlt execution`:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/execution/execution-list.png" alt="Execution List" width="800">
+</p>
+
+```
+┌─────────────────────┐      ┌─────────────────────┐      ┌──────────────────────────────┐
+│         You         │      │       Agents        │      │           GitHub             │
+├─────────────────────┤      ├─────────────────────┤      ├──────────────────────────────┤
+│                     │      │  Agent 1            │      │  PR #101                     │
+│  prlt work spawn ───┼─────>│  TKT-042 OAuth    ──┼─────>│  feat/TKT-042-oauth          │
+│                     │      │                     │      │                              │
+│                     │      │  Agent 2            │      │  PR #102                     │
+│                  ───┼─────>│  TKT-043 Rate Limit─┼─────>│  feat/TKT-043-rate-limit     │
+│                     │      │                     │      │                              │
+│                     │      │  Agent 3            │      │  PR #103                     │
+│                  ───┼─────>│  TKT-044 Notifs   ──┼─────>│  feat/TKT-044-notifications  │
+└─────────────────────┘      └─────────────────────┘      └──────────────────────────────┘
 ```
 
----
+<details>
+<summary>View interactive diagram (GitHub only)</summary>
+
+```mermaid
+flowchart LR
+    subgraph You
+        spawn[prlt work spawn]
+    end
+
+    subgraph Agents
+        A1[Agent 1<br/>TKT-042 OAuth]
+        A2[Agent 2<br/>TKT-043 Rate Limit]
+        A3[Agent 3<br/>TKT-044 Notifications]
+    end
+
+    subgraph GitHub
+        PR1[PR #101<br/>feat/TKT-042-oauth]
+        PR2[PR #102<br/>feat/TKT-043-rate-limit]
+        PR3[PR #103<br/>feat/TKT-044-notifications]
+    end
+
+    spawn --> A1
+    spawn --> A2
+    spawn --> A3
+
+    A1 --> PR1
+    A2 --> PR2
+    A3 --> PR3
+```
 
-## 🌟 Why This Design Pattern?
+</details>
+
+Agent-created PRs ready for review:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/execution/github-prs.png" alt="GitHub Pull Requests" width="800">
+</p>
+
+### Command Reference
+
+<details>
+<summary><b>Full Command Reference</b> (click to expand)</summary>
+
+<table>
+  <tr><th>Namespace</th><th>Command</th><th>Description</th></tr>
+  <!-- ticket -->
+  <tr><td rowspan="11"><b>ticket</b></td><td><code>prlt ticket create</code></td><td>Create new ticket</td></tr>
+  <tr><td><code>prlt ticket list</code></td><td>List all tickets</td></tr>
+  <tr><td><code>prlt ticket view &lt;id&gt;</code></td><td>View ticket details</td></tr>
+  <tr><td><code>prlt ticket edit &lt;id&gt;</code></td><td>Edit ticket</td></tr>
+  <tr><td><code>prlt ticket move &lt;id&gt; &lt;status&gt;</code></td><td>Change status</td></tr>
+  <tr><td><code>prlt ticket delete &lt;id&gt;</code></td><td>Delete ticket</td></tr>
+  <tr><td><code>prlt ticket complete &lt;id&gt;</code></td><td>Mark ticket complete</td></tr>
+  <tr><td><code>prlt ticket bulk</code></td><td>Bulk ticket operations</td></tr>
+  <tr><td><code>prlt ticket link block &lt;id&gt;</code></td><td>Link blocking ticket</td></tr>
+  <tr><td><code>prlt ticket link relates &lt;id&gt;</code></td><td>Link related ticket</td></tr>
+  <tr><td><code>prlt ticket template save</code></td><td>Save ticket as template</td></tr>
+  <!-- work -->
+  <tr><td rowspan="7"><b>work</b></td><td><code>prlt work start &lt;id&gt;</code></td><td>Spawn agent on ticket</td></tr>
+  <tr><td><code>prlt work spawn</code></td><td>Batch spawn tickets</td></tr>
+  <tr><td><code>prlt work spawn-all</code></td><td>Spawn all planned tickets</td></tr>
+  <tr><td><code>prlt work complete &lt;id&gt;</code></td><td>Mark work done</td></tr>
+  <tr><td><code>prlt work ready &lt;id&gt;</code></td><td>Mark ready for review</td></tr>
+  <tr><td><code>prlt work revise &lt;id&gt;</code></td><td>Request revision</td></tr>
+  <tr><td><code>prlt work watch</code></td><td>Watch work progress</td></tr>
+  <!-- execution -->
+  <tr><td rowspan="3"><b>execution</b></td><td><code>prlt execution list</code></td><td>List running agents</td></tr>
+  <tr><td><code>prlt execution logs &lt;id&gt;</code></td><td>View agent output</td></tr>
+  <tr><td><code>prlt execution stop &lt;id&gt;</code></td><td>Stop an agent</td></tr>
+  <!-- agent -->
+  <tr><td rowspan="11"><b>agent</b></td><td><code>prlt agent list</code></td><td>List all agents</td></tr>
+  <tr><td><code>prlt agent status &lt;name&gt;</code></td><td>Check agent status</td></tr>
+  <tr><td><code>prlt agent shell &lt;name&gt;</code></td><td>Shell into agent workspace</td></tr>
+  <tr><td><code>prlt agent visit &lt;name&gt;</code></td><td>Navigate to workspace</td></tr>
+  <tr><td><code>prlt agent login &lt;name&gt;</code></td><td>Auth Claude in container</td></tr>
+  <tr><td><code>prlt agent rebuild &lt;name&gt;</code></td><td>Rebuild agent workspace</td></tr>
+  <tr><td><code>prlt agent restart &lt;name&gt;</code></td><td>Restart agent</td></tr>
+  <tr><td><code>prlt agent staff add &lt;names&gt;</code></td><td>Add named agents</td></tr>
+  <tr><td><code>prlt agent staff list</code></td><td>List staff agents</td></tr>
+  <tr><td><code>prlt agent temp list</code></td><td>List ephemeral agents</td></tr>
+  <tr><td><code>prlt agent temp cleanup</code></td><td>Remove ephemeral agents</td></tr>
+  <!-- agent themes -->
+  <tr><td rowspan="4"><b>agent themes</b></td><td><code>prlt agent themes list</code></td><td>List available themes</td></tr>
+  <tr><td><code>prlt agent themes set &lt;name&gt;</code></td><td>Set active theme</td></tr>
+  <tr><td><code>prlt agent themes create &lt;name&gt;</code></td><td>Create custom theme</td></tr>
+  <tr><td><code>prlt agent themes add-names</code></td><td>Add names to theme</td></tr>
+  <!-- board -->
+  <tr><td rowspan="2"><b>board</b></td><td><code>prlt board</code></td><td>View kanban board</td></tr>
+  <tr><td><code>prlt board watch</code></td><td>Real-time updates</td></tr>
+  <!-- project -->
+  <tr><td rowspan="6"><b>project</b></td><td><code>prlt project create</code></td><td>Create project</td></tr>
+  <tr><td><code>prlt project list</code></td><td>List projects</td></tr>
+  <tr><td><code>prlt project view &lt;id&gt;</code></td><td>View project details</td></tr>
+  <tr><td><code>prlt project archive &lt;id&gt;</code></td><td>Archive project</td></tr>
+  <tr><td><code>prlt project unarchive &lt;id&gt;</code></td><td>Unarchive project</td></tr>
+  <tr><td><code>prlt project delete &lt;id&gt;</code></td><td>Delete project</td></tr>
+  <!-- epic -->
+  <tr><td rowspan="10"><b>epic</b></td><td><code>prlt epic create</code></td><td>Create epic</td></tr>
+  <tr><td><code>prlt epic list</code></td><td>List epics</td></tr>
+  <tr><td><code>prlt epic view &lt;id&gt;</code></td><td>View epic details</td></tr>
+  <tr><td><code>prlt epic ticket &lt;id&gt;</code></td><td>Add tickets to epic</td></tr>
+  <tr><td><code>prlt epic progress &lt;id&gt;</code></td><td>View epic progress</td></tr>
+  <tr><td><code>prlt epic move &lt;id&gt; &lt;status&gt;</code></td><td>Move epic status</td></tr>
+  <tr><td><code>prlt epic archive &lt;id&gt;</code></td><td>Archive epic</td></tr>
+  <tr><td><code>prlt epic activate &lt;id&gt;</code></td><td>Activate epic</td></tr>
+  <tr><td><code>prlt epic reorder</code></td><td>Reorder epics</td></tr>
+  <tr><td><code>prlt epic link block &lt;id&gt;</code></td><td>Link blocking epic</td></tr>
+  <!-- spec -->
+  <tr><td rowspan="6"><b>spec</b></td><td><code>prlt spec create</code></td><td>Create specification</td></tr>
+  <tr><td><code>prlt spec list</code></td><td>List specifications</td></tr>
+  <tr><td><code>prlt spec view &lt;id&gt;</code></td><td>View specification</td></tr>
+  <tr><td><code>prlt spec plan &lt;id&gt;</code></td><td>Generate plan from spec</td></tr>
+  <tr><td><code>prlt spec ticket &lt;id&gt;</code></td><td>Create ticket from spec</td></tr>
+  <tr><td><code>prlt spec link relates &lt;id&gt;</code></td><td>Link related spec</td></tr>
+  <!-- action -->
+  <tr><td rowspan="6"><b>action</b></td><td><code>prlt action create</code></td><td>Create action template</td></tr>
+  <tr><td><code>prlt action list</code></td><td>List actions</td></tr>
+  <tr><td><code>prlt action show &lt;id&gt;</code></td><td>Show action details</td></tr>
+  <tr><td><code>prlt action run &lt;id&gt;</code></td><td>Run action</td></tr>
+  <tr><td><code>prlt action update &lt;id&gt;</code></td><td>Update action</td></tr>
+  <tr><td><code>prlt action delete &lt;id&gt;</code></td><td>Delete action</td></tr>
+  <!-- branch -->
+  <tr><td rowspan="3"><b>branch</b></td><td><code>prlt branch create</code></td><td>Create branch</td></tr>
+  <tr><td><code>prlt branch list</code></td><td>List branches</td></tr>
+  <tr><td><code>prlt branch validate</code></td><td>Validate branch name</td></tr>
+  <!-- status -->
+  <tr><td rowspan="5"><b>status</b></td><td><code>prlt status list</code></td><td>List workflow statuses</td></tr>
+  <tr><td><code>prlt status create</code></td><td>Create custom status</td></tr>
+  <tr><td><code>prlt status update &lt;id&gt;</code></td><td>Update status</td></tr>
+  <tr><td><code>prlt status move &lt;id&gt;</code></td><td>Reorder status</td></tr>
+  <tr><td><code>prlt status delete &lt;id&gt;</code></td><td>Delete status</td></tr>
+  <!-- workflow -->
+  <tr><td rowspan="5"><b>workflow</b></td><td><code>prlt workflow list</code></td><td>List workflows</td></tr>
+  <tr><td><code>prlt workflow create</code></td><td>Create workflow</td></tr>
+  <tr><td><code>prlt workflow view &lt;id&gt;</code></td><td>View workflow</td></tr>
+  <tr><td><code>prlt workflow switch &lt;id&gt;</code></td><td>Switch active workflow</td></tr>
+  <tr><td><code>prlt workflow delete &lt;id&gt;</code></td><td>Delete workflow</td></tr>
+  <!-- phase -->
+  <tr><td rowspan="5"><b>phase</b></td><td><code>prlt phase list</code></td><td>List phases</td></tr>
+  <tr><td><code>prlt phase create</code></td><td>Create phase</td></tr>
+  <tr><td><code>prlt phase update &lt;id&gt;</code></td><td>Update phase</td></tr>
+  <tr><td><code>prlt phase move &lt;id&gt;</code></td><td>Reorder phase</td></tr>
+  <tr><td><code>prlt phase delete &lt;id&gt;</code></td><td>Delete phase</td></tr>
+  <!-- template -->
+  <tr><td rowspan="5"><b>template</b></td><td><code>prlt template list</code></td><td>List templates</td></tr>
+  <tr><td><code>prlt template delete &lt;id&gt;</code></td><td>Delete template</td></tr>
+  <tr><td><code>prlt template ticket list</code></td><td>List ticket templates</td></tr>
+  <tr><td><code>prlt template ticket apply</code></td><td>Apply ticket template</td></tr>
+  <tr><td><code>prlt template phase list</code></td><td>List phase templates</td></tr>
+  <!-- pr -->
+  <tr><td rowspan="3"><b>pr</b></td><td><code>prlt pr create</code></td><td>Create pull request</td></tr>
+  <tr><td><code>prlt pr status &lt;id&gt;</code></td><td>Check PR status</td></tr>
+  <tr><td><code>prlt pr link &lt;id&gt; &lt;url&gt;</code></td><td>Link PR to ticket</td></tr>
+  <!-- gh -->
+  <tr><td rowspan="3"><b>gh</b></td><td><code>prlt gh login</code></td><td>Login to GitHub</td></tr>
+  <tr><td><code>prlt gh status</code></td><td>Check auth status</td></tr>
+  <tr><td><code>prlt gh token</code></td><td>Get GitHub token</td></tr>
+  <!-- repo -->
+  <tr><td rowspan="4"><b>repo</b></td><td><code>prlt repo add &lt;url&gt;</code></td><td>Add repository</td></tr>
+  <tr><td><code>prlt repo list</code></td><td>List repositories</td></tr>
+  <tr><td><code>prlt repo view &lt;name&gt;</code></td><td>View repository details</td></tr>
+  <tr><td><code>prlt repo remove &lt;name&gt;</code></td><td>Remove repository</td></tr>
+  <!-- docker -->
+  <tr><td rowspan="10"><b>docker</b></td><td><code>prlt docker list</code></td><td>List containers</td></tr>
+  <tr><td><code>prlt docker status</code></td><td>Check Docker status</td></tr>
+  <tr><td><code>prlt docker start &lt;name&gt;</code></td><td>Start container</td></tr>
+  <tr><td><code>prlt docker stop &lt;name&gt;</code></td><td>Stop container</td></tr>
+  <tr><td><code>prlt docker restart &lt;name&gt;</code></td><td>Restart container</td></tr>
+  <tr><td><code>prlt docker logs &lt;name&gt;</code></td><td>View container logs</td></tr>
+  <tr><td><code>prlt docker shell &lt;name&gt;</code></td><td>Shell into container</td></tr>
+  <tr><td><code>prlt docker sync &lt;name&gt;</code></td><td>Sync container files</td></tr>
+  <tr><td><code>prlt docker clean</code></td><td>Remove stopped containers</td></tr>
+  <tr><td><code>prlt docker prune</code></td><td>Remove unused resources</td></tr>
+  <!-- session -->
+  <tr><td rowspan="2"><b>session</b></td><td><code>prlt session list</code></td><td>List active tmux sessions</td></tr>
+  <tr><td><code>prlt session attach &lt;name&gt;</code></td><td>Attach to tmux session</td></tr>
+  <!-- workspace -->
+  <tr><td rowspan="4"><b>workspace</b></td><td><code>prlt init</code></td><td>Initialize workspace</td></tr>
+  <tr><td><code>prlt workspace list</code></td><td>List workspaces</td></tr>
+  <tr><td><code>prlt workspace add</code></td><td>Add workspace</td></tr>
+  <tr><td><code>prlt workspace use &lt;name&gt;</code></td><td>Switch workspace</td></tr>
+  <!-- utility -->
+  <tr><td rowspan="3"><b>utility</b></td><td><code>prlt whoami</code></td><td>Show current context</td></tr>
+  <tr><td><code>prlt commit</code></td><td>Conventional commit</td></tr>
+  <tr><td><code>prlt autocomplete setup</code></td><td>Setup shell autocomplete</td></tr>
+</table>
+
+</details>
+
+Run `prlt <command> --help` for flags and options.
+
+### Use Cases
+
+#### Parallel Feature Development
 
-### ❌ **Traditional Single Workspace**
 ```bash
-# One directory, constant context switching
-git checkout -b feature-1
-# Work on feature 1...
-git stash  # Have to stash to switch
-git checkout -b feature-2  
-# Lost context, files changed, AI confused...
+# Create tickets for each feature
+prlt ticket create --title "Add OAuth" --category feature
+prlt ticket create --title "Add API rate limiting" --category feature
+prlt ticket create --title "Add email notifications" --category feature
+
+# Spawn all three in parallel (Docker for isolation)
+prlt work spawn TKT-001 TKT-002 TKT-003 --mode docker
+
+# Watch the board as they work
+prlt board watch
 ```
 
-### ✅ **Multiple Workspaces, One Machine**  
+Three agents, three branches, three PRs. You review and merge.
+
+#### Bug Bash
+
 ```bash
-# Set up workspaces on your local machine
-prlt hire bezos musk gates
+# Spawn all bugs at once
+prlt work spawn --all --column Backlog --category bug
+
+# Or pick specific ones
+prlt work spawn TKT-010 TKT-011 TKT-012
+```
+
+#### Grooming Session
 
-# Each workspace ready for AI or manual work
-prlt staff
-# 💰 BEZOS: ✅ Cursor session 1 → ../your-repo-staff/bezos
-# 💰 MUSK: ✅ Claude Code session → ../your-repo-staff/musk  
-# 💰 GATES: ✅ Your manual edits → ../your-repo-staff/gates
+Have an agent refine ticket requirements:
 
-# Three workspaces, three features, all on your machine!
+```bash
+prlt work start TKT-042 --action groom
 ```
 
-**Scale your solo development: Multiple workspaces, parallel progress, zero stashing!** 🎉
+Agent adds acceptance criteria, subtasks, estimates.
 
 ---
 
+## Environment Variables
+
+| Variable            | Purpose                       |
+| ------------------- | ----------------------------- |
+| `GITHUB_TOKEN`      | GitHub operations (PRs, etc.) |
 
-## 🏆 Perfect For
+Claude Code handles its own authentication via `claude login`.
 
-- **Running Multiple Cursor Sessions** - Open 3+ Cursor windows, each editing a different workspace/feature
-- **Parallel Claude Code Instances** - Launch multiple Claude Code sessions working on separate tasks
-- **Concurrent CLI Agents** - Run Codex, Aider, or other CLI agents simultaneously in different workspaces
-- **Mixed AI Tools** - Cursor in one workspace, Claude Code in another, Copilot in a third
-- **Scaling Solo Development** - One developer running multiple AI sessions on their machine
-- **Rapid Prototyping** - Each workspace explores different approaches without affecting others
+---
+
+## Requirements
+
+- **Node.js 18+**
+- **Git**
+- **Claude Code** (`claude login` to authenticate)
+- **SQLite**
+- **Tmux** (session persistence)
+- **Docker** (optional—for isolated execution)
 
 ---
 
-## 📜 License
+## Support
 
-MIT License - Because the revolutionso is open source.
+- **Discord**: [discord.gg/tmZyjNNSvw](https://discord.gg/tmZyjNNSvw)
+- **GitHub Issues**: [Report bugs or request features](https://github.com/chrismcdermut/proletariat-cli/issues)
+- **LinkedIn**: [Christopher McDermut](https://www.linkedin.com/in/christopher-mcdermut/)
 
 ---
 
-<div align="center">
+## License
 
-**✊ WORKERS OF THE CODEBASE, UNITE! ✊**
+Apache 2.0
 
-*The simplest, most fun git worktree manager in existence!*
+---
 
 [![npm version](https://img.shields.io/npm/v/@proletariat/cli.svg)](https://www.npmjs.com/package/@proletariat/cli)
-[![Downloads](https://img.shields.io/npm/dm/@proletariat/cli.svg)](https://npmjs.org/package/@proletariat/cli)
-[![git-worktree](https://img.shields.io/badge/git--worktree-themed-red.svg)](https://github.com/chrismcdermut/proletariat-cli)
+[![Downloads](https://img.shields.io/npm/dm/@proletariat/cli.svg)](https://www.npmjs.com/package/@proletariat/cli)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
-**[⭐ Star on GitHub](https://github.com/chrismcdermut/proletariat-cli) • [📦 Install from NPM](https://www.npmjs.com/package/@proletariat/cli) • [🐛 Report Issues](https://github.com/chrismcdermut/proletariat-cli/issues)**
+[Star on GitHub](https://github.com/chrismcdermut/proletariat) | [Install from NPM](https://www.npmjs.com/package/@proletariat/cli) | [Report Issues](https://github.com/chrismcdermut/proletariat/issues)
 
-</div>
+Made with ⚒️ by the proletariat.