panopticon-cli 0.3.6 → 0.4.0

package/README.md

@@ -26,6 +26,7 @@ Panopticon is a unified orchestration layer for AI coding assistants. It works w
 - **Health Monitoring** - Deacon-style stuck detection with auto-recovery
 - **Context Engineering** - Structured state management (STATE.md, WORKSPACE.md)
 - **Agent CVs** - Work history tracking for capability-based routing
+- **Google Stitch Integration** - AI-powered UI design with automatic design-to-code workflows
 
 ---
 
@@ -221,7 +222,8 @@ See [docs/DNS_SETUP.md](docs/DNS_SETUP.md) for detailed DNS configuration (espec
 ### Optional
 - **mkcert** - For HTTPS certificates (recommended)
 - **Linear API key** - For issue tracking integration
-- **Beads CLI (bd)** - For persistent task tracking across sessions
+- **Beads CLI (bd)** - For persistent task tracking across sessions. Auto-installed by `pan install`. Upgrade with `pan beads upgrade`.
+- **Google Stitch MCP** - For AI-powered UI design integration (see below)
 
 ### Platform Support
 
@@ -303,6 +305,80 @@ If you have multiple Linear projects, configure which local directory each maps
 
 The dashboard uses this mapping to determine where to create workspaces when you click "Create Workspace" or "Start Agent" for an issue.
 
+## Google Stitch Integration
+
+Panopticon integrates with [Google Stitch](https://stitch.withgoogle.com), Google's AI-powered UI design tool, enabling design-to-code workflows.
+
+### What is Google Stitch?
+
+Google Stitch generates production-ready UI designs from natural language prompts or image inputs. It's free (350 standard + 50 experimental generations/month) and requires only a Google account.
+
+### Setup (Optional)
+
+Use the `/pan-stitch` skill to set up the integration:
+
+```bash
+# Run the setup skill
+/pan-stitch
+
+# Or manually:
+# 1. Install gcloud CLI
+curl -sSL https://sdk.cloud.google.com | bash
+
+# 2. Authenticate
+gcloud auth login
+gcloud auth application-default login
+
+# 3. Create project and enable API
+gcloud projects create stitch-tools-$(date +%s)
+gcloud config set project YOUR_PROJECT_ID
+gcloud billing projects link YOUR_PROJECT_ID --billing-account=YOUR_BILLING_ID
+gcloud beta services mcp enable stitch.googleapis.com  # MUST use beta!
+
+# 4. Register MCP (note "proxy" subcommand)
+claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y @_davideast/stitch-mcp proxy
+```
+
+### How It Works
+
+When Stitch is configured, the planning agent can:
+
+1. **Create UI designs** - Generate screens for UI-related issues
+2. **Document in STATE.md** - Record Stitch project/screen IDs for workers
+3. **Worker agents pick up designs** - Use the Stitch skills to convert to React
+
+### Stitch Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/pan-stitch` | Setup and configure Stitch MCP |
+| `/stitch-design-md` | Create DESIGN.md from Stitch projects |
+| `/stitch-react-components` | Convert Stitch HTML to React components |
+
+### STATE.md Integration
+
+When planning UI work, add a Stitch section to STATE.md:
+
+```markdown
+## UI Designs
+
+### Stitch Assets
+- **Project ID:** 12345678
+- **Screen:** "Dashboard" (screen ID: 87654321)
+- **Design Notes:** Dark mode, glassmorphism cards, gradient accents
+- **DESIGN.md:** Generated at `src/components/DESIGN.md`
+
+Worker: Use `/stitch-react-components` to convert the Dashboard screen to React.
+```
+
+### Manual Workflow (No MCP)
+
+If you prefer not to set up the MCP:
+
+1. Design at https://stitch.withgoogle.com
+2. Export HTML/CSS from the UI
+3. Use `/stitch-react-components` with the exported files
+
 ## Cloister: AI Lifecycle Manager
 
 Cloister is Panopticon's intelligent agent lifecycle manager. It monitors all running agents and automatically handles:
@@ -389,6 +465,90 @@ The merge-agent uses a specialized prompt template that instructs it to:
 - Document conflict resolution decisions
 - Provide detailed feedback on what was merged
 
+#### Review Pipeline Flow
+
+The review pipeline is a sequential handoff between specialists:
+
+```
+Human clicks "Review"
+        │
+        ▼
+┌───────────────────┐
+│   review-agent    │ Reviews code, checks for issues
+└─────────┬─────────┘
+          │ If PASSED: queues test-agent
+          │ If BLOCKED: sends feedback to work-agent
+          ▼
+┌───────────────────┐
+│    test-agent     │ Runs test suite, analyzes failures
+└─────────┬─────────┘
+          │ If PASSED: marks ready for merge
+          │ If FAILED: sends feedback to work-agent
+          ▼
+┌───────────────────┐
+│  (Human clicks    │ Human approval required
+│  "Approve & Merge"│ before merge
+└─────────┬─────────┘
+          ▼
+┌───────────────────┐
+│   merge-agent     │ Performs merge, resolves conflicts
+└───────────────────┘
+```
+
+**Key Points:**
+- **Human-initiated start** - A human must click "Review" to start the pipeline
+- **Automatic handoffs** - review-agent → test-agent happens automatically
+- **Human approval for merge** - Merge is NOT automatic; human clicks "Approve & Merge"
+- **Feedback loops** - Failed reviews/tests send feedback back to the work-agent
+
+#### Queue Processing
+
+Each specialist has a task queue (`~/.panopticon/specialists/{name}/hook.json`) managed via the FPP (Fixed Point Principle):
+
+```
+1. Task arrives (via API or handoff)
+        │
+        ▼
+2. wakeSpecialistOrQueue() checks if specialist is busy
+        │
+        ├── If IDLE: Wake specialist immediately with task
+        │
+        └── If BUSY: Add task to queue (hook.json)
+                │
+                ▼
+3. When specialist completes current task:
+        │
+        ├── Updates status via API (passed/failed/skipped)
+        │
+        └── Dashboard automatically wakes specialist for next queued task
+```
+
+**Queue priority order:** `urgent` > `high` > `normal` > `low`
+
+**Completion triggers:** When a specialist reports status (`passed`, `failed`, or `skipped`), the dashboard:
+1. Sets the specialist state to `idle`
+2. Checks the specialist's queue for pending work
+3. If work exists, immediately wakes the specialist with the next task
+
+#### Agent Self-Requeue (Circuit Breaker)
+
+After a human initiates the first review, work-agents can request re-review up to 3 times automatically:
+
+```bash
+# Work-agent requests re-review after fixing issues
+pan work request-review MIN-123 -m "Fixed: added tests for edge cases"
+```
+
+**Circuit breaker behavior:**
+- First human click resets the counter to 0
+- Each `pan work request-review` increments the counter
+- After 3 automatic re-requests, returns HTTP 429
+- Human must click "Review" in dashboard to continue
+
+This prevents infinite loops where an agent repeatedly fails review.
+
+**API endpoint:** `POST /api/workspaces/:issueId/request-review`
+
 #### Specialist Auto-Initialization
 
 When Cloister starts, it automatically initializes specialists that don't exist yet. This ensures the test-agent, review-agent, and merge-agent are ready to receive wake signals without manual setup.
@@ -642,6 +802,395 @@ Issues are routed to different subdirectories based on their labels:
 
 Example: An issue with label "splash" in the MIN team would create its workspace at `/home/user/projects/myn/splash/workspaces/feature-min-xxx/`.
 
+### Custom Workspace Commands (Legacy)
+
+> **Note:** For most polyrepo projects, use the built-in `workspace` configuration (see below) instead of custom scripts. Custom commands are only needed for highly specialized setups.
+
+For projects that need logic beyond what the configuration supports, you can specify custom workspace scripts:
+
+```yaml
+projects:
+  myn:
+    name: "Mind Your Now"
+    path: /home/user/projects/myn
+    linear_team: MIN
+    # Custom scripts handle complex workspace setup
+    workspace_command: /home/user/projects/myn/infra/new-feature
+    workspace_remove_command: /home/user/projects/myn/infra/remove-feature
+```
+
+When `workspace_command` is specified, Panopticon calls your script instead of creating a standard git worktree. The script receives the normalized issue ID (e.g., `min-123`) as an argument.
+
+When `workspace_remove_command` is specified, Panopticon calls your script when deleting workspaces (e.g., aborting planning with "delete workspace" enabled). This is important for complex setups that need to:
+- Stop Docker containers and remove volumes
+- Clean up root-owned files created by containers
+- Remove git worktrees from multiple repositories
+- Release port assignments
+- Remove DNS entries
+
+**What your custom script should handle:**
+- Creating git worktrees for multiple repositories (polyrepo structure)
+- Setting up Docker Compose files and dev containers
+- Configuring environment variables and `.env` files
+- Setting up DNS entries for workspace-specific URLs (e.g., Traefik routing)
+- Creating a `./dev` script for container management
+- Copying agent configuration templates (CLAUDE.md, .mcp.json, etc.)
+
+**Example script flow:**
+```bash
+#!/bin/bash
+# new-feature script for a polyrepo project
+ISSUE_ID=$1  # e.g., "min-123"
+
+# Create worktrees for frontend and api repos
+git -C /path/to/frontend worktree add ../workspaces/feature-$ISSUE_ID/fe feature/$ISSUE_ID
+git -C /path/to/api worktree add ../workspaces/feature-$ISSUE_ID/api feature/$ISSUE_ID
+
+# Generate docker-compose from templates
+sed "s/{{FEATURE_FOLDER}}/feature-$ISSUE_ID/g" template.yml > workspace/docker-compose.yml
+
+# Set up DNS and Traefik routing
+# ... additional setup
+```
+
+The standard `pan workspace create` command will automatically detect and use your custom script.
+
+#### Container Configuration Tips
+
+When setting up Docker containers for workspaces, avoid these common pitfalls:
+
+**Maven projects:**
+- DO NOT set `MAVEN_CONFIG=/some/path` as an environment variable
+- Maven interprets `MAVEN_CONFIG` as additional CLI arguments, not a directory path
+- This causes "Unknown lifecycle phase" errors (e.g., "Unknown lifecycle phase /maven-cache")
+- Instead, use `-Dmaven.repo.local=/path/to/cache` in the Maven command
+
+```yaml
+# WRONG - causes Maven startup failure
+environment:
+  - MAVEN_CONFIG=/maven-cache
+
+# CORRECT - use command line argument
+command: ./mvnw spring-boot:run -Dmaven.repo.local=/maven-cache/repository
+volumes:
+  - ~/.m2:/maven-cache:cached
+```
+
+**pnpm projects:**
+- Set `PNPM_HOME=/path` to configure the pnpm store location
+- Mount a named volume for the store to share across containers
+
+### What Your Project Needs to Provide
+
+Panopticon is an orchestration layer - it manages workspaces, agents, and workflows, but **your project repository provides the actual templates and configuration**.
+
+Projects can be as simple as just a git repo (for worktree-only workspaces) or as complex as a full polyrepo with Docker, Traefik, and database seeding. Here's what you need for each level:
+
+### Required: Workspace Templates
+
+Your project needs a `.devcontainer/` or template directory with:
+
+```
+your-project/
+├── infra/
+│   └── .devcontainer-template/      # Template for workspace containers
+│       ├── docker-compose.devcontainer.yml.template
+│       ├── compose.infra.yml.template   # Optional: separate infra services
+│       ├── Dockerfile
+│       └── devcontainer.json.template
+└── ...
+```
+
+**Docker Compose templates** should use placeholders that Panopticon will replace:
+
+```yaml
+# docker-compose.devcontainer.yml.template
+services:
+  api:
+    build: ./api
+    user: vscode  # Run as non-root to avoid permission issues
+    labels:
+      - "traefik.http.routers.{{FEATURE_FOLDER}}-api.rule=Host(`api-{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
+    environment:
+      - DATABASE_URL=postgres://app:app@postgres:5432/mydb
+
+  frontend:
+    build: ./fe
+    user: vscode  # Run as non-root to avoid permission issues
+    labels:
+      - "traefik.http.routers.{{FEATURE_FOLDER}}.rule=Host(`{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
+```
+
+> **⚠️ Important: File Permissions**
+>
+> Always run containers as a non-root user (e.g., `user: vscode`) to avoid permission issues.
+> Files created by root-owned containers cannot be removed by `pan workspace destroy` without sudo.
+> The Microsoft devcontainers base image includes a `vscode` user (UID 1000) that matches most host users.
+
+### Required for HTTPS: Traefik Configuration
+
+If you want local HTTPS (recommended), provide a Traefik compose file:
+
+```
+your-project/
+├── infra/
+│   └── docker-compose.traefik.yml   # Traefik reverse proxy
+└── ...
+```
+
+Example Traefik config:
+```yaml
+# infra/docker-compose.traefik.yml
+services:
+  traefik:
+    image: traefik:v2.10
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ~/.panopticon/traefik/certs:/certs:ro
+    command:
+      - --providers.docker=true
+      - --entrypoints.web.address=:80
+      - --entrypoints.websecure.address=:443
+```
+
+### Required for Database Seeding: Seed Directory
+
+For projects with databases:
+
+```
+your-project/
+├── infra/
+│   └── seed/
+│       └── seed.sql              # Sanitized production data
+└── ...
+```
+
+Your compose template should mount this:
+```yaml
+services:
+  postgres:
+    image: postgres:16
+    volumes:
+      - /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro
+```
+
+### Optional: Agent Templates
+
+For customizing how agents work in your project:
+
+```
+your-project/
+├── infra/
+│   └── .agent-template/
+│       ├── CLAUDE.md.template    # Project-specific AI instructions
+│       └── .mcp.json.template    # MCP server configuration
+└── .claude/
+    └── skills/                   # Project-specific skills
+        └── my-project-standards/
+            └── SKILL.md
+```
+
+### Configuration in projects.yaml
+
+Point Panopticon to your templates:
+
+```yaml
+# ~/.panopticon/projects.yaml
+projects:
+  myproject:
+    name: "My Project"
+    path: /home/user/projects/myproject
+    linear_team: PRJ
+
+    workspace:
+      type: polyrepo  # or monorepo
+      workspaces_dir: workspaces
+
+      docker:
+        traefik: infra/docker-compose.traefik.yml
+        compose_template: infra/.devcontainer-template
+
+      database:
+        seed_file: /home/user/projects/myproject/infra/seed/seed.sql
+        container_name: "{{PROJECT}}-postgres-1"
+
+      agent:
+        template_dir: infra/.agent-template
+        templates:
+          - source: CLAUDE.md.template
+            target: CLAUDE.md
+```
+
+### Quick Checklist
+
+| Component | Required? | Location | Purpose |
+|-----------|-----------|----------|---------|
+| Docker Compose template | Yes (for Docker workspaces) | `infra/.devcontainer-template/` | Container configuration |
+| Traefik config | Only for HTTPS | `infra/docker-compose.traefik.yml` | Reverse proxy |
+| Seed file | Only if database needed | `infra/seed/seed.sql` | Pre-populate database |
+| Agent template | Recommended | `infra/.agent-template/` | AI instructions |
+| Project skills | Optional | `.claude/skills/` | Project-specific workflows |
+
+### Example: Minimal Setup
+
+For a simple monorepo with no Docker:
+
+```yaml
+# ~/.panopticon/projects.yaml
+projects:
+  simple-app:
+    name: "Simple App"
+    path: /home/user/projects/simple-app
+    linear_team: APP
+    # No workspace config needed - uses git worktrees
+```
+
+Panopticon creates workspaces as git worktrees. Docker, HTTPS, and seeding are opt-in.
+
+---
+
+## Polyrepo Workspace Configuration
+
+For projects with multiple git repositories (like separate frontend/backend repos), configure workspace settings directly in `projects.yaml`:
+
+```yaml
+projects:
+  myapp:
+    name: "My App"
+    path: /home/user/projects/myapp
+    linear_team: APP
+
+    workspace:
+      type: polyrepo
+      workspaces_dir: workspaces
+      # Default branch for all repos (optional, defaults to 'main')
+      default_branch: main
+
+      # Git repositories to include in each workspace
+      # Each repo is a SEPARATE git repository with its own .git
+      repos:
+        - name: fe
+          path: frontend           # Relative to project root
+          branch_prefix: "feature/"
+          # default_branch: main   # Can override workspace default per-repo
+        - name: api
+          path: backend
+          branch_prefix: "feature/"
+          # default_branch: develop  # Example: API uses 'develop' as default
+
+      # DNS entries for local development
+      dns:
+        domain: myapp.test
+        entries:
+          - "{{FEATURE_FOLDER}}.{{DOMAIN}}"
+          - "api-{{FEATURE_FOLDER}}.{{DOMAIN}}"
+        sync_method: wsl2hosts  # or: hosts_file, dnsmasq
+
+      # Port assignments for services
+      ports:
+        redis:
+          range: [6380, 6499]
+
+      # Service definitions - how to start each service
+      services:
+        - name: api
+          path: api
+          start_command: ./mvnw spring-boot:run
+          docker_command: ./mvnw spring-boot:run
+          health_url: "https://api-{{FEATURE_FOLDER}}.{{DOMAIN}}/actuator/health"
+          port: 8080
+        - name: frontend
+          path: fe
+          start_command: pnpm start
+          docker_command: pnpm start
+          health_url: "https://{{FEATURE_FOLDER}}.{{DOMAIN}}"
+          port: 3000
+
+      # Docker configuration
+      docker:
+        traefik: infra/docker-compose.traefik.yml
+        compose_template: infra/.devcontainer-template
+
+      # Agent configuration templates
+      agent:
+        template_dir: infra/.agent-template
+        templates:
+          - source: CLAUDE.md.template
+            target: CLAUDE.md
+        symlinks:
+          - .claude/commands
+          - .claude/skills
+
+      # Environment template
+      env:
+        template: |
+          COMPOSE_PROJECT_NAME={{COMPOSE_PROJECT}}
+          FRONTEND_URL=https://{{FEATURE_FOLDER}}.{{DOMAIN}}
+```
+
+**Template Placeholders:**
+
+| Placeholder | Example | Description |
+|------------|---------|-------------|
+| `{{FEATURE_NAME}}` | `min-123` | Normalized issue ID |
+| `{{FEATURE_FOLDER}}` | `feature-min-123` | Workspace folder name |
+| `{{BRANCH_NAME}}` | `feature/min-123` | Git branch name |
+| `{{COMPOSE_PROJECT}}` | `myapp-feature-min-123` | Docker Compose project |
+| `{{DOMAIN}}` | `myapp.test` | DNS domain |
+
+**Service Templates:**
+
+Panopticon provides built-in templates for common frameworks. Use these to avoid boilerplate:
+
+| Template | Start Command | Port |
+|----------|--------------|------|
+| `react` | `npm start` | 3000 |
+| `react-vite` | `npm run dev` | 5173 |
+| `react-pnpm` | `pnpm start` | 3000 |
+| `nextjs` | `npm run dev` | 3000 |
+| `spring-boot-maven` | `./mvnw spring-boot:run` | 8080 |
+| `spring-boot-gradle` | `./gradlew bootRun` | 8080 |
+| `express` | `npm start` | 3000 |
+| `fastapi` | `uvicorn main:app --reload` | 8000 |
+| `django` | `python manage.py runserver` | 8000 |
+
+Use a template by referencing it in your service config:
+
+```yaml
+services:
+  - name: api
+    template: spring-boot-maven
+    path: api
+    health_url: "https://api-{{FEATURE_FOLDER}}.myapp.test/health"
+```
+
+See `/pan-workspace-config` skill for complete documentation.
+
+### Polyrepo Merge Considerations
+
+> **⚠️ Important:** Polyrepo merging requires special handling. The current merge-agent is optimized for monorepos.
+
+For polyrepo projects:
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Workspace creation | ✅ Supported | Creates worktrees in each repo |
+| Branch management | ✅ Supported | Each repo gets its own feature branch |
+| Agent work | ✅ Supported | Agents can work across repos |
+| Merge | ⚠️ Manual | Push each repo's branch, merge via GitLab/GitHub |
+
+**Current workflow for polyrepo merges:**
+
+1. Agent completes work and pushes branches to each repo
+2. Create merge requests for each repo manually (or via `gh pr create`)
+3. Review and merge each MR separately
+4. The "Approve & Merge" button is not yet polyrepo-aware
+
+**Future enhancement:** Polyrepo-aware merge-agent that handles multiple repos automatically.
+
 ### Managing Projects
 
 ```bash
@@ -655,6 +1204,134 @@ pan project add /path/to/project --name myproject --linear-team PRJ
 pan project remove myproject
 ```
 
+### Database Seeding
+
+Many projects need a pre-populated database for development and testing. Panopticon provides database seeding commands that work with your existing infrastructure.
+
+**Problem:** Development databases often need:
+- Schema with 100+ migrations already applied
+- Seed data for testing (users, reference data)
+- External QA database connections
+- Database snapshots from staging/production (sanitized)
+
+**Solution:** Configure database seeding in `projects.yaml`:
+
+```yaml
+projects:
+  myapp:
+    workspace:
+      database:
+        # Path to seed file (loaded on first container start)
+        seed_file: /path/to/sanitized-seed.sql
+
+        # Command to create new snapshots from external source
+        snapshot_command: "kubectl exec -n prod pod/postgres -- pg_dump -U app mydb"
+
+        # Or connect to external database directly
+        external_db:
+          host: qa-db.example.com
+          database: myapp_qa
+          user: readonly
+          password_env: QA_DB_PASSWORD
+
+        # Container naming pattern
+        container_name: "{{PROJECT}}-postgres-1"
+
+        # Migration tool (for status checks)
+        migrations:
+          type: flyway  # flyway | liquibase | prisma | typeorm | custom
+          path: src/main/resources/db/migration
+```
+
+**Commands:**
+
+```bash
+# Create a snapshot from production/staging
+pan db snapshot --project myapp --output /path/to/seed.sql
+
+# Seed a workspace database
+pan db seed MIN-123
+
+# Check database status
+pan db status MIN-123
+
+# Clean kubectl noise from pg_dump files
+pan db clean /path/to/dump.sql
+
+# View database configuration
+pan db config myapp
+```
+
+**Workflow for capturing production data:**
+
+1. **Create snapshot** from production (via kubectl or direct connection):
+   ```bash
+   pan db snapshot --project myapp --sanitize
+   ```
+
+2. **Verify** the seed file:
+   ```bash
+   pan db clean /path/to/seed.sql --dry-run
+   ```
+
+3. **Update projects.yaml** with seed file path
+
+4. **Workspaces** automatically seed on first postgres container start
+
+**Container integration:**
+
+Your Docker Compose template should mount the seed directory:
+
+```yaml
+# compose.infra.yml
+services:
+  postgres:
+    image: postgres:16
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      # Seed database on first startup
+      - /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro
+```
+
+**Troubleshooting:**
+
+| Issue | Solution |
+|-------|----------|
+| "relation does not exist" | Seed file missing or incomplete - run `pan db snapshot` |
+| Slow database startup | Large seed file - consider pruning old data |
+| kubectl garbage in dump | Run `pan db clean <file>` to remove stderr noise |
+| Migrations fail after seed | Check Flyway version matches seed file's schema_history |
+
+### Agent Completion Notifications
+
+Panopticon includes a notification system that alerts you when agents complete their work.
+
+**Desktop Notifications:**
+
+The `notify-complete` script sends desktop notifications across platforms:
+
+| Platform | Notification Method |
+|----------|---------------------|
+| WSL2/Windows | PowerShell toast notifications |
+| macOS | osascript display notification |
+| Linux | notify-send |
+
+**Usage:**
+```bash
+# Send a completion notification
+~/.panopticon/bin/notify-complete MIN-123 "Fixed login button" "https://gitlab.com/mr/456"
+```
+
+**Completion log:** All notifications are logged to `~/.panopticon/agent-completed.log` with timestamps.
+
+**Integration with agent workflows:**
+
+Agents can call `notify-complete` at the end of their work:
+```bash
+# In agent completion script or /work-complete skill
+notify-complete "$ISSUE_ID" "$SUMMARY" "$MR_URL"
+```
+
 ---
 
 ## Commands
@@ -670,8 +1347,71 @@ pan skills            # List available skills
 pan status            # Show running agents
 pan up                # Start dashboard (Docker or minimal)
 pan down              # Stop dashboard and services
+pan update            # Update Panopticon to latest version
+pan backup            # Create backup of ~/.panopticon/
+pan restore           # Restore from backup
+pan setup hooks       # Install Claude Code hooks (heartbeat, etc.)
+```
+
+### Beads Management
+
+Beads is an optional git-backed issue tracker for persistent task tracking. Panopticon includes commands to manage beads databases and automatic cleanup after merges.
+
+**Installation:** Beads is automatically installed during `pan install`. You can also install/upgrade manually:
+
+```bash
+# Check beads version and available updates
+pan beads upgrade --check
+
+# Upgrade to latest version
+pan beads upgrade
+
+# Show beads statistics (total, open, closed, old)
+pan beads stats
+
+# Compact beads - remove closed issues older than 30 days
+pan beads compact
+
+# Customize the threshold (e.g., 60 days)
+pan beads compact --days 60
+
+# Preview what would be removed (dry run)
+pan beads compact --dry-run
+```
+
+**Recommended version:** v0.47.1+ includes important fixes for git worktree isolation.
+
+**Workspace Isolation:**
+
+With beads v0.47.1+, workspaces share the same database but use labels for isolation:
+
+```bash
+# In workspace for PAN-83, list only that workspace's tasks
+bd list --label workspace:pan-83
+
+# Or use bd ready with label filter
+bd ready --label workspace:pan-83
 ```
 
+Panopticon automatically creates beads with `workspace:<issue-id>` labels when you create a workspace. Agents can filter to see only their workspace's tasks.
+
+**Automatic Compaction:**
+
+After every successful merge, the merge-agent automatically:
+1. Checks for closed beads older than 30 days
+2. If found, runs `bd admin compact --days 30`
+3. Commits the compacted beads
+4. Pushes to remote
+
+This keeps the beads database clean without manual intervention.
+
+**Why compact beads?**
+
+Beads are committed to git for collaborative planning (see "Git-Backed Collaborative Planning" section). Over time, closed issues accumulate. Compaction removes old closed issues while preserving:
+- Open issues (always kept)
+- Recently closed issues (< 30 days by default)
+- All issue history in git commits
+
 #### What `pan sync` Does
 
 `pan sync` synchronizes Panopticon assets to all supported AI tools:
@@ -694,11 +1434,38 @@ pan work issue MIN-123
 # List all running agents
 pan work status
 
-# Send a message to an agent
+# Send a message to an agent (handles Enter key automatically)
 pan work tell min-123 "Please also add tests"
 
 # Kill an agent
 pan work kill min-123
+
+# Show work completed and awaiting review
+pan work pending
+
+# Approve agent work, merge MR, update Linear
+pan work approve min-123
+
+# List issues from configured trackers
+pan work list
+
+# Triage issues from secondary tracker
+pan work triage
+
+# Reopen a closed issue and re-run planning
+pan work reopen min-123
+
+# Request re-review after fixing feedback (for agents, max 3 auto-requeues)
+pan work request-review min-123 -m "Fixed: added tests and removed duplication"
+
+# Deep wipe: completely reset all state for an issue
+pan work wipe min-123           # Cleans up agents, state, Linear status
+pan work wipe min-123 -w        # Also delete workspace
+pan work wipe min-123 -y -w     # Skip confirmation
+
+# Recover crashed agents
+pan work recover min-123
+pan work recover --all
 ```
 
 ### Health Monitoring
@@ -714,6 +1481,63 @@ pan work health status
 pan work health daemon --interval 30
 ```
 
+### Test Runner
+
+```bash
+# Run all tests for a workspace
+pan test run min-123
+
+# Run tests for main branch
+pan test run main
+
+# Run specific test suites only
+pan test run min-123 --tests backend,frontend_unit
+
+# List configured tests for a project
+pan test list
+
+# List tests for specific project
+pan test list myproject
+```
+
+**Test Configuration:**
+
+Configure test suites in `projects.yaml`:
+
+```yaml
+projects:
+  myapp:
+    tests:
+      backend:
+        type: maven           # maven, vitest, jest, playwright, pytest, cargo
+        path: api             # Path relative to workspace
+        command: ./mvnw test  # Command to run
+
+      frontend_unit:
+        type: vitest
+        path: fe
+        command: pnpm test:unit --run
+        container: true       # Run inside Docker container
+        container_name: "{{COMPOSE_PROJECT}}-fe-1"
+
+      frontend_e2e:
+        type: playwright
+        path: fe
+        command: pnpm test:e2e
+        env:
+          BASE_URL: "https://{{FEATURE_FOLDER}}.myapp.test"
+```
+
+**Reports:**
+
+Test results are saved to `{project}/reports/test-run-{target}-{timestamp}.md` with detailed logs for each suite.
+
+**Notifications:**
+
+Desktop notifications are sent when tests complete (disable with `--no-notify`).
+
+See `/pan-test-config` skill for complete documentation.
+
 ### FPP Hooks (Fixed Point Principle)
 
 ```bash
@@ -737,6 +1561,67 @@ pan work hook mail agent-min-123 "Review feedback received"
 
 This allows multiple agents to work on different features simultaneously without conflicts.
 
+> **IMPORTANT: Main Project Branch Convention**
+>
+> The main project directory should **ALWAYS** stay on the `main` branch. All feature work happens in workspaces (git worktrees), never in the main project.
+>
+> - **Main project**: Always on `main` - serves as the stable reference point
+> - **Workspaces**: Each has its own feature branch checked out
+> - **Want to check something?** Create a worktree, don't checkout in main
+> - **Quick test?** Create a worktree
+> - **Emergency hotfix?** Create a worktree
+>
+> This convention ensures:
+> 1. Specialists (review-agent, test-agent) always find the correct code
+> 2. Merge operations have a clean target
+> 3. Multiple agents don't interfere with each other
+>
+> If you see a warning like "Main project is on branch 'feature/xxx' instead of 'main'", something has incorrectly checked out a feature branch in the main project. Fix it with `git checkout main`.
+
+#### Git Hooks for Branch Protection
+
+Panopticon provides git hooks to enforce the main branch convention. These hooks are automatically installed:
+
+- **On `pan project add`** - Hooks are installed when registering a new project
+- **On `pan sync`** - Hooks are updated in all registered projects
+
+The hooks are polyrepo-aware and will install in all git repositories within your project.
+
+**Auto-revert behavior:**
+- **Agents & planning sessions**: Automatically revert to `main` if they accidentally checkout a feature branch
+- **Human users**: Display a prominent warning (no auto-revert by default)
+
+To enable auto-revert for humans:
+```bash
+export PANOPTICON_AUTO_REVERT_CHECKOUT=1  # Add to .bashrc/.zshrc
+```
+
+Manual hook installation (for projects not in registry):
+```bash
+./scripts/install-git-hooks.sh /path/to/your/project
+```
+
+#### Planning vs Work Agent Safeguard
+
+The dashboard prevents starting a work agent (`agent-<issue>`) while a planning agent (`planning-<issue>`) is still running for the same issue. This prevents conflicts where both agents try to modify the same workspace.
+
+If you see "Planning agent is still running" when trying to start work:
+1. **Complete the planning session** - Use "Complete Planning" button
+2. **Or abort planning** - Use "Abort Planning" if you want to discard
+3. **Or kill the session manually** - `tmux kill-session -t planning-<issue>`
+
+#### Specialist Agent Safeguards
+
+All specialist agents (review-agent, test-agent, merge-agent) are configured to:
+1. **Run in workspaces only** - Never in the main project directory
+2. **Never checkout branches** - They work with the branch already in the workspace
+3. **Create workspaces if needed** - Use `pan workspace create <ISSUE-ID>` instead of `git checkout`
+
+These safeguards are enforced through:
+- **Prompt instructions** - Clear warnings in all specialist prompts
+- **Code enforcement** - Specialists spawn with workspace as cwd
+- **Git hooks** - Auto-revert if checkout detected in tmux sessions
+
 #### Git-Backed Collaborative Planning
 
 | Start Planning | Codebase Exploration | Discovery Questions |
@@ -804,6 +1689,9 @@ pan work plan MIN-123 --continue
 # Create a workspace (git worktree) without starting an agent
 pan workspace create MIN-123
 
+# Create workspace and start Docker containers
+pan workspace create MIN-123 --docker
+
 # List all workspaces
 pan workspace list
 
@@ -814,6 +1702,69 @@ pan workspace destroy MIN-123
 pan workspace destroy MIN-123 --force
 ```
 
+#### Docker Integration
+
+The `--docker` flag automatically starts containers after workspace creation:
+
+```bash
+pan workspace create MIN-123 --docker
+```
+
+**What it does:**
+1. Creates the workspace (git worktree or custom command)
+2. Looks for docker-compose files in:
+   - `{workspace}/docker-compose.yml`
+   - `{workspace}/docker-compose.yaml`
+   - `{workspace}/.devcontainer/docker-compose.yml`
+   - `{workspace}/.devcontainer/docker-compose.devcontainer.yml`
+   - `{workspace}/.devcontainer/compose.yml`
+3. Runs `docker compose -p "{project}-feature-{issue}" -f {file} up -d --build`
+
+**Docker Project Naming:**
+
+Each workspace gets a unique Docker Compose project name to avoid container conflicts:
+- Format: `{project-name}-feature-{issue-id}` (e.g., `mind-your-now-feature-min-123`)
+- The project name comes from `name` in your `~/.panopticon/projects.yaml`
+- Container names follow: `{project}-{service}-1` (e.g., `mind-your-now-feature-min-123-api-1`)
+
+This allows multiple workspaces to run simultaneously without port or name conflicts.
+
+**Why this matters:**
+- Containers start warming up while you review the issue
+- Environment is ready when the planning agent starts asking questions
+- You can test assumptions during planning without waiting for builds
+
+**Dashboard integration:**
+
+The planning dialog includes a "Start Docker containers" checkbox:
+- **Default:** Enabled (containers start automatically)
+- **Preference saved:** Your choice is remembered in browser localStorage
+- **Key:** `panopticon.planning.startDocker`
+
+To change the default via browser console:
+```javascript
+// Disable Docker by default
+localStorage.setItem('panopticon.planning.startDocker', 'false');
+
+// Enable Docker by default (this is the out-of-box default)
+localStorage.setItem('panopticon.planning.startDocker', 'true');
+```
+
+**Example workflow:**
+```bash
+# From dashboard: click "Start Planning" (Docker enabled by default)
+# Or from CLI:
+pan workspace create MIN-123 --docker
+
+# While containers build in background:
+# - Review the Linear issue
+# - Check related PRs
+# - Think about approach
+
+# By the time you're ready to engage with the planning agent,
+# the dev environment is warm and ready for testing
+```
+
 ### Project Management
 
 ```bash
@@ -823,6 +1774,12 @@ pan project add /path/to/project --name myproject
 # List managed projects
 pan project list
 
+# Show project details
+pan project show myproject
+
+# Initialize project config (creates .panopticon.json)
+pan project init
+
 # Remove a project
 pan project remove myproject
 ```
@@ -869,20 +1826,29 @@ pan cloister start
 # Stop Cloister
 pan cloister stop
 
+# Emergency stop all agents (force kill)
+pan cloister emergency-stop
+
 # Check Cloister status
 pan cloister status
 
 # List all specialists
 pan specialists list
 
-# Wake a specific specialist
-pan specialists wake merge-agent --issue MIN-123
+# Wake a specialist (resumes previous session if exists)
+pan specialists wake merge-agent
+
+# Wake and send a task
+pan specialists wake merge-agent --task "Review PR #123 for security issues"
 
 # View specialist queue
-pan specialists queue
+pan specialists queue merge-agent
 
-# Reset specialist state
+# Reset a single specialist (wipes context)
 pan specialists reset merge-agent
+
+# Reset ALL specialists (fresh start)
+pan specialists reset --all
 ```
 
 ## Dashboard
@@ -920,6 +1886,16 @@ Stop with `pan down`.
 | **Skills** | Available skills and their descriptions |
 | **Health** | System health checks and diagnostics |
 
+### Issue Filtering
+
+The dashboard automatically filters issues to reduce visual clutter:
+
+- **Linear issues** - Shows current cycle issues only
+- **Done column** - Shows items completed in the last 24 hours
+- **Canceled column** - Shows items canceled in the last 24 hours
+
+This filtering applies to both Linear and GitHub issues. Older completed items are excluded from the dashboard but remain in your issue tracker.
+
 ### Issue Cards
 
 Issue cards on the Kanban board display:
@@ -1034,6 +2010,8 @@ Panopticon ships with 25+ skills organized into categories:
 | `pan-convoy-synthesis` | Synthesize convoy coordination |
 | `pan-subagent-creator` | Create specialized subagents |
 | `pan-skill-creator` | Create new skills (guided) |
+| `pan-workspace-config` | Configure polyrepo workspaces, DNS, ports |
+| `pan-test-config` | Configure project test suites |
 
 ### Utilities
 
@@ -1298,6 +2276,26 @@ Each agent's state is tracked in `~/.panopticon/agents/{agent-id}/state.json`:
 
 **State Cleanup:** When an agent is killed or aborted (`pan work kill`), Panopticon automatically cleans up its state files to prevent stale data from affecting future runs.
 
+### Deep Wipe
+
+For issues that get into a stuck or inconsistent state, use `pan work wipe` to completely reset:
+
+```bash
+pan work wipe MIN-123           # Basic cleanup
+pan work wipe MIN-123 -w        # Also delete workspace
+pan work wipe MIN-123 -y -w     # Skip confirmation
+```
+
+**Deep wipe cleans up:**
+- Tmux sessions (`planning-min-123`, `agent-min-123`)
+- Agent state directories (`~/.panopticon/agents/planning-*`, `agent-*`)
+- Legacy planning directories (`project/.planning/min-123/`)
+- Workspace (if `-w` flag is used)
+- Linear issue status (reset to Backlog)
+- Linear labels (removes "Review Ready", "Planning")
+
+**Dashboard UI:** When aborting planning, click "🔥 Deep Wipe" for a complete reset.
+
 ## Health Monitoring (Deacon Pattern)
 
 Panopticon implements the Deacon pattern for stuck agent detection:
@@ -1390,8 +2388,166 @@ If you're both developing Panopticon AND using it for your own projects:
 3. **Config is shared** - workspaces/agents work the same either way
 4. **Test in a real project** - your own usage is the best test
 
+### Developer Skills (dev-skills/)
+
+Panopticon has two types of skills:
+
+| Directory | Purpose | Synced When |
+|-----------|---------|-------------|
+| `skills/` | User-facing skills for all Panopticon users | Always via `pan sync` |
+| `dev-skills/` | Developer-only skills for Panopticon contributors | Only in dev mode |
+
+**Dev mode is automatically detected** when running from the Panopticon source repo (npm link). Skills in `dev-skills/` are:
+- Checked into the repo and version-controlled
+- Only synced to developers' machines, not end users
+- Shown with `[dev]` label in `pan sync --dry-run`
+
+```bash
+# Check what will be synced (including dev-skills)
+pan sync --dry-run
+
+# Output shows:
+# Developer mode detected - dev-skills will be synced
+# ...
+#   + skill/test-specialist-workflow [dev]
+```
+
+### Testing the Specialist System
+
+The `test-specialist-workflow` skill provides end-to-end testing for the specialist handoff pipeline.
+
+**Location:** `dev-skills/test-specialist-workflow/SKILL.md`
+
+**What it tests:**
+- Full approve workflow: review-agent → test-agent → merge-agent
+- Specialist handoffs via `pan specialists wake --task`
+- Merge completion and branch preservation
+
+**Usage:**
+
+```bash
+# First sync to get dev-skills
+pan sync
+
+# In Claude Code, invoke the skill
+/test-specialist-workflow
+```
+
+The skill guides you through:
+
+1. **Prerequisites check** - Dashboard running, specialists available
+2. **Create test issue** - GitHub issue for tracking
+3. **Create workspace** - Git worktree for the test
+4. **Make test change** - Trivial commit to verify merge
+5. **Trigger approve** - Kicks off the specialist pipeline
+6. **Monitor handoffs** - Watch each specialist complete and hand off
+7. **Verify merge** - Confirm change reached main branch
+8. **Cleanup** - Close issue, remove workspace
+
+**Expected timeline:** 2-4 minutes total
+
+**When to use:**
+- After making changes to the specialist system
+- After modifying the approve workflow
+- As a smoke test before releases
+
 ## Troubleshooting
 
+### WSL2 Stability Issues (Windows Users)
+
+WSL2 can experience crashes and networking issues, especially under heavy AI agent workloads. Here are recommended `.wslconfig` settings to improve stability.
+
+**Create/edit `C:\Users\<username>\.wslconfig`:**
+
+```ini
+[wsl2]
+# Resource allocation (adjust based on your system)
+memory=40GB
+processors=18
+swap=8GB
+
+# Localhost forwarding between Windows and WSL
+localhostForwarding=true
+
+# Disable GPU/GUI passthrough - reduces dxg driver errors
+guiApplications=false
+
+# Route DNS through Windows - prevents getaddrinfo() failures
+dnsTunneling=true
+
+# Inherit Windows proxy settings
+autoProxy=true
+
+# Windows 11 22H2+ ONLY: Use mirrored networking
+# This bypasses the Hyper-V NAT layer that can cause "Object Name not found" errors
+# networkingMode=mirrored
+```
+
+**After changing `.wslconfig`:**
+```powershell
+wsl --shutdown
+# Then relaunch your WSL terminal
+```
+
+**Verify settings applied:**
+```bash
+# Check resources
+free -h          # Should show configured memory
+nproc            # Should show configured processors
+swapon --show    # Should show configured swap
+
+# Check networking mode (Windows 11 only)
+ip addr show eth0  # NAT mode shows 172.x.x.x IP
+                   # Mirrored mode shares Windows network directly
+```
+
+#### Windows 10 Limitations
+
+| Feature | Windows 10 | Windows 11 22H2+ |
+|---------|-----------|------------------|
+| `networkingMode=mirrored` | ❌ Not supported | ✅ Supported |
+| `dnsTunneling=true` | ✅ Works | ✅ Works |
+| `guiApplications=false` | ✅ Works | ✅ Works |
+
+**Windows 10 users:** The `networkingMode=mirrored` setting will be silently ignored. You'll stay on NAT mode, which can be less stable. The other settings (`dnsTunneling`, `guiApplications=false`) still help with stability.
+
+If you experience frequent WSL2 crashes on Windows 10, consider:
+- Upgrading to Windows 11 for mirrored networking support
+- Reducing `memory` allocation if system is under pressure
+- Checking Windows Event Viewer for specific crash causes
+
+#### Additional Windows 10 Workarounds
+
+If NAT networking is unstable on Windows 10:
+
+```powershell
+# 1. Update WSL to latest version
+wsl --update
+
+# 2. Check for VPN/firewall conflicts
+# Disable VPN temporarily to test if it's causing issues
+
+# 3. Reset Windows network stack (run as Admin)
+netsh winsock reset
+netsh int ip reset
+
+# 4. Restart after network reset
+Restart-Computer
+```
+
+**Common conflict sources:**
+- VPN clients (especially corporate VPNs)
+- Docker Desktop (can conflict with WSL networking)
+- Third-party firewalls
+- Hyper-V virtual switch issues
+
+**If NAT fails completely**, WSL 2.3.25+ automatically falls back to VirtioProxy mode. This is less performant but more stable. You'll see: `"Failed to configure network (networkingMode Nat), falling back to networkingMode VirtioProxy."`
+
+**References:**
+- [Microsoft WSL Networking Documentation](https://learn.microsoft.com/en-us/windows/wsl/networking)
+- [WSL GitHub Issues - Networking](https://github.com/microsoft/WSL/issues?q=networking+mirrored)
+- [WSL NAT Fallback Issue #12297](https://github.com/microsoft/WSL/issues/12297)
+
 ### Slow Vite/React Frontend with Multiple Workspaces
 
 If running multiple containerized workspaces with Vite/React frontends, you may notice CPU spikes and slow HMR. This is because Vite's default file watching polls every 100ms, which compounds with multiple instances.