pan-doctor · diff

git:20260923.0b1d897 to git:20260923.0260c28

15 added, 0 removed. Audit B to B.

---

name: pan-doctor

description: "pan doctor [options] — check Overdeck system health, dependencies, and configuration"

triggers:

- pan doctor

- system health

- health check

- overdeck status

- check overdeck

allowed-tools:

- Bash

- Read

---

# System Health Check

## Overview

This skill guides you through checking the health of your Overdeck installation, including configuration, dependencies, and running services.

## When to Use

- After initial installation

- Troubleshooting agent issues

- Before starting a new work session

- Verifying configuration changes

- Periodic maintenance

## Quick Command

```bash

pan doctor

```

## Health Check Workflow

### 1. Run Diagnostics

```bash

# Full health check

pan doctor

# Expected output:

# ✓ Configuration file exists

# ✓ Linear API key configured

# ✓ GitHub token configured

# ✓ Skills directory exists

# ✓ tmux available

# ✓ Docker available

# ⚠ orphan-proposed-specs: proposed xBRIEF specs without work agents, grouped by project with remediation hints

```

### 2. Check Configuration

```bash

# View current config

cat ~/.overdeck.env

# Required settings:

# LINEAR_API_KEY=lin_api_xxx

# GITHUB_TOKEN=ghp_xxx (optional but recommended)

# WORKSPACE_ROOT=/path/to/workspaces

```

### 3. Check Running Services

```bash

# Dashboard status

curl -s http://localhost:3011/api/health || echo "Dashboard not running"

# Running agents

tmux list-sessions | grep agent

# Docker containers

docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "(traefik|overdeck)"

```

### 4. Check Skills

```bash

# List installed skills

pan skills

# Verify skills are synced

ls -la ~/.claude/skills/ | head -20

```

### 5. Check Dependencies

```bash

# Node.js version (18+ required)

node --version

# npm version

npm --version

# tmux version

tmux -V

# Docker version

docker --version

# Git version

git --version

```

### 6. Herdr

Herdr is the default terminal backend and is strict: when it is selected but its binary or this home's

session socket is missing, agent launches fail and `pan doctor` exits 1. Doctor prints these rows:

| Row | Fix when it fails |

| --- | --- |

| `Terminal backend` | `pan install` (or set `terminal.backend: tmux` in `~/.overdeck/config.yaml`) |

| `Herdr binary` | `pan install` |

| `Herdr server` | `pan sync` (restarting a stale server is manual: `systemctl --user restart overdeck-herdr.service` closes every agent pane) |

| `Herdr config` | `pan sync` (sets `resume_agents_on_restore = false`) |

| `Herdr integration: <target>` | `pan sync` (pilot set `pi`, `omp`, `kimi`, `opencode`; `claude`, `codex`, `hermes` are not managed) |

Under an explicit tmux backend only the `Terminal backend` row appears.

+ ### 7. Plan home `.pan/` tracking

+ Planning artifacts are committed under `.pan/` in each project's plan home. Before the Cut, Overdeck

+ wrote `.pan/` into project `.gitignore` files, and that rule makes every planning commit fail

+ (`The following paths are ignored by one of your .gitignore files: .pan`). The

+ `Plan home .pan/ tracking` row WARNs for each registered plan home where `git check-ignore` matches

+ `.pan/`, naming the rule's `file:line`:

+ | Rule source | Fix |

+ | --- | --- |

+ | Exact `.pan/` or `.pan` line in the repo's top-level `.gitignore` (Overdeck's legacy line) | `pan admin migrate-plan-home <key> --commit` removes that line and commits `.gitignore` alone (with any artifacts it migrates), or delete the line and commit it yourself |

+ | Anything else (nested `.gitignore`, `.git/info/exclude`, `core.excludesFile`, a broader pattern) | Not Overdeck's rule: doctor never edits it. Remove or narrow it yourself |

+ Doctor only reports; it has no `--fix`.

## Health Checklist

| Component | Check Command | Expected |

|-----------|---------------|----------|

| Config | `cat ~/.overdeck.env` | File exists with keys |

| Node.js | `node --version` | v18+ |

| tmux | `tmux -V` | Any version |

| Docker | `docker info` | Running |

| Skills | `ls ~/.overdeck/skills/` | Skills present |

| Symlinks | `ls -la ~/.claude/skills/` | Symlinks to overdeck |

| Linear | `pan doctor` | API key valid |

## Component Status

### Dashboard

```bash

# Start dashboard

cd ~/.overdeck/dashboard && npm run dev

# Check health endpoint

curl http://localhost:3011/api/health

# View dashboard

open http://localhost:3010

```

### Traefik (if using)

```bash

# Check traefik

docker ps | grep traefik

# Traefik dashboard

curl -k https://traefik.overdeck.localhost:8080/api/overview

```

### Agents

```bash

# List all agents

tmux list-sessions -F "#{session_name}" | grep "^agent-"

# Check agent health

for session in $(tmux list-sessions -F "#{session_name}" | grep "^agent-"); do

echo "=== $session ==="

tmux capture-pane -t $session -p | tail -5

done

```

## Common Issues

### Configuration Missing

```bash

# Create config file

pan init

# Or manually

cat > ~/.overdeck.env << 'EOF'

LINEAR_API_KEY=your_key_here

GITHUB_TOKEN=your_token_here

WORKSPACE_ROOT=/home/user/workspaces

EOF

```

### Skills Not Synced

```bash

# Re-sync skills

pan sync

# Force overwrite

pan sync --force

```

### Dashboard Won't Start

```bash

# Check port in use

lsof -i :3010

lsof -i :3011

# Kill conflicting processes

kill $(lsof -t -i:3010)

kill $(lsof -t -i:3011)

# Restart

cd ~/.overdeck/dashboard && npm run dev

```

### tmux Issues

```bash

# Kill stuck server

tmux kill-server

# Fresh start

tmux new-session -d -s test

tmux kill-session -t test

```

## Maintenance Tasks

### Update Overdeck

```bash

npm update -g overdeck

pan init # Re-copy bundled skills

pan sync # Re-sync to AI tools

```

### Clean Up Old Workspaces

```bash

# List workspaces

ls -la $WORKSPACE_ROOT/

# Remove completed ones

rm -rf $WORKSPACE_ROOT/old-issue/

```

### Reset Configuration

```bash

# Backup and reset

cp ~/.overdeck.env ~/.overdeck.env.backup

pan init

```

## Related Skills

- `/pan:diagnose` - Deep troubleshooting

- `/pan:install` - Initial setup

- `/pan:sync` - Skill synchronization