/gobby doctor - System Health and Security Skill

This skill runs a comprehensive systems check and security audit to verify Gobby's CLI commands and MCP tools are functioning correctly. All tests use the __diag__ prefix for automatic cleanup.

Subcommands

/gobby doctor - Show help

Display available options and a brief description of each check type.

/gobby doctor --functional - Functional tests (phases 1-3)

Run prerequisite checks, read-only tests, and write+cleanup tests. Does not include worktree/clone tests or security audit.

/gobby doctor --security - Security audit (phase 5 only)

Run security-focused checks: file permissions, plaintext secrets scan, HTTP binding check, webhook HTTPS validation, debug log level warning, plugin security, MCP server URLs, and permissive skills.

/gobby doctor --all - Full check (all phases)

Run everything: functional tests (phases 1-4 including worktree/clone) plus security audit (phase 5).

Note: --full is a deprecated alias for --all.

/gobby doctor --cleanup - Cleanup only

Scan for and remove stale __diag__ artifacts from previous failed runs.

Execution Protocol

Execute phases sequentially. Track all created resource IDs for cleanup. Report PASS/FAIL per test.

Phase 1: Prerequisites

Run these first. If any fail, stop and report - other tests won't be reliable.

1.1 Daemon Status

gobby status

Expected: Daemon is running.

1.2 MCP Server Connectivity

Call gobby.list_mcp_servers()

Expected: Returns list of servers. Check that core servers are connected:

• •gobby-tasks
• •gobby-memory
• •gobby-sessions

1.3 Database Connectivity

Call list_sessions(limit=1)

Expected: Returns without error (empty list is OK).

Report summary: "Prerequisites: X/3 PASS"

Phase 2: Read-Only Tests

These tests only read data - no cleanup needed.

2.1 CLI List Commands

Run each command and verify no errors:

2.2 MCP List Tools

Call each tool and verify response:

2.3 MCP Get/Search Tools

Call tools that retrieve or search data:

Report summary: "Read-Only: X/Y PASS"

Phase 3: Write + Cleanup Tests

Create test resources, verify, then delete. Track all IDs for cleanup.

CRITICAL: Initialize cleanup tracker before starting:

cleanup_tracker = {
    "memories": [],
    "tasks": [],
    "worktrees": [],
    "clones": []
}

3.1 Memory Create/Delete Cycle

Create:

# gobby-memory server:
create_memory(
    content="__diag__ diagnostic test memory - safe to delete",
    tags="__diag__,test",
    importance=0.1
)

Store returned memory_id in cleanup_tracker["memories"].

Verify: Call get_memory(memory_id=<id>) - should return the memory.

Delete: Call delete_memory(memory_id=<id>)

Verify deletion: Call get_memory(memory_id=<id>) - should return error/not found.

3.2 Task Create/Close Cycle

Get session ID first: Call get_current_session() to retrieve the current session object. Use the returned id field as the session_id parameter below.

Create:

# gobby-tasks server:
create_task(
    title="__diag__ diagnostic test task",
    description="Diagnostic test task - safe to delete",
    task_type="chore",
    session_id=<id>  # from gobby-sessions get_current_session()
)

Store returned task_id in cleanup_tracker["tasks"].

Verify: Call get_task(task_id=<id>) - should return the task.

Update: Call update_task(task_id=<id>, status="completed")

Verify update: Call get_task(task_id=<id>) - status should be "completed".

Close: Call close_task(task_id=<id>, reason="completed")

3.3 Workflow Variable Cycle (session-scoped, auto-cleaned on session termination)

Note: Workflow variables are session-scoped and automatically cleaned up when the session ends. No __diag__ prefix needed since they don't persist beyond the session.

Get session ID first: Use the same session ID obtained in Phase 3.2 from get_current_session().

Set:

# gobby-workflows server:
set_variable(
    session_id=<id>,  # from gobby-sessions get_current_session()
    name="diag_test_var",
    value="diagnostic_value"
)

Get:

# gobby-workflows server:
get_variable(
    session_id=<id>,  # from gobby-sessions get_current_session()
    name="diag_test_var"
)

Expected return: "diagnostic_value"

Report summary: "Write+Cleanup: X/3 PASS"

Phase 4: Resource-Heavy Tests (--all only)

Only run with --all flag. These create filesystem resources.

4.1 Worktree Cycle

Check spawn capability:

# gobby-worktrees server:
can_spawn_worktree()

If false, skip with note "Worktree spawn not available".

Create:

# gobby-worktrees server:
create_worktree(
    branch="__diag__/test-branch",
    base_branch="HEAD"
)

Store returned worktree_id.

Verify: Call get_worktree(worktree_id=<id>) - should return worktree.

Delete: Call delete_worktree(worktree_id=<id>, force=True)

Verify deletion: Call get_worktree(worktree_id=<id>) - should return error/not found.

4.2 Clone Cycle

Check spawn capability:

# gobby-clones server:
can_spawn_clone()

If false, skip with note "Clone spawn not available".

Create:

# gobby-clones server:
create_clone(
    name="__diag__-test-clone"
)

Store returned clone_id.

Verify: Call get_clone(clone_id=<id>) - should return clone.

Delete: Call delete_clone(clone_id=<id>, force=True)

Verify deletion: Call get_clone(clone_id=<id>) - should return error/not found.

4.3 Agent Spawn Check (read-only)

Check capability:

# gobby-agents server:
can_spawn_agent()

Report result (PASS if returns true/false without error, capability status is informational).

Report summary: "Resource-Heavy: X/3 PASS"

Phase 5: Security Audit

Read-only security checks that scan configuration and runtime state for potential security issues. These checks are non-destructive and only report findings.

5.1 File Permissions

Check that sensitive files have restrictive permissions (0o600 or stricter):

Report: WARN if permissions are more permissive than expected.

5.2 Plaintext Secrets Scan

Scan configuration files for potential plaintext secrets:

# Check for API keys, tokens, passwords in config files
grep -iE "(api_key|api-key|apikey|secret|token|password|auth)" ~/.gobby/config.yaml

Patterns to flag:

• •api_key: sk-...
• •password: ... (if not using env var reference)
• •Any value that looks like a token (long alphanumeric strings)

Report: WARN if potential plaintext secrets found. Recommend using environment variables.

5.3 HTTP Binding Check

Check if the daemon is bound to a non-localhost address:

# In config.yaml, check server binding
server:
  host: "127.0.0.1"  # OK
  host: "0.0.0.0"    # WARN - exposed to network

Report: WARN if server is bound to 0.0.0.0 or a public IP address.

5.4 Webhook HTTPS Validation

Check that any configured webhooks use HTTPS:

# In config.yaml
webhooks:
  - url: "https://example.com/hook"  # OK
  - url: "http://example.com/hook"   # WARN - unencrypted

Report: WARN for each webhook using HTTP instead of HTTPS.

5.5 Debug Log Level Warning

Check if debug logging is enabled in production:

# In config.yaml
logging:
  level: "DEBUG"  # WARN in production
  level: "INFO"   # OK

Report: WARN if log level is DEBUG (may expose sensitive information).

5.6 Plugin Security Warning

List any third-party or non-bundled skills/plugins:

# Check for skills not in the bundled skills directory
gobby-skills.list_skills()

Report: INFO listing non-bundled skills. Note: These have access to MCP tools and should be reviewed.

5.7 MCP Server URL Validation

Check that MCP server URLs are valid and use HTTPS where appropriate:

gobby.list_mcp_servers()

For each server:

• •HTTP servers: WARN if not localhost
• •Stdio servers: OK (local process)
• •WebSocket servers: WARN if not using wss://

Report: WARN for any MCP server communicating over unencrypted channels to non-localhost.

5.8 Permissive Skills Listing

Check for skills with overly permissive tool access:

# Check skills that allow all tools or sensitive tool categories
gobby-skills.list_skills()

Flag skills where:

• •allowed_tools is empty/null (allows all tools)
• •allowed_tools includes sensitive tools (file write, shell execute)

Report: INFO listing skills with broad tool access.

Report summary: "Security Audit: X/8 PASS, Y WARN"

Cleanup Protocol

Run cleanup in this order (reverse dependency):

Step 1: Clean Clones

Search for clones with __diag__ prefix:

# gobby-clones server:
list_clones()

For each clone with name starting with __diag__:

# gobby-clones server:
delete_clone(clone_id=<id>, force=True)

Step 2: Clean Worktrees

Search for worktrees with __diag__ prefix:

# gobby-worktrees server:
list_worktrees()

For each worktree with branch starting with __diag__:

# gobby-worktrees server:
delete_worktree(worktree_id=<id>, force=True)

Step 3: Clean Tasks

Search for tasks with __diag__ prefix:

# gobby-tasks server:
list_tasks()

For each task with title starting with __diag__:

# gobby-tasks server:
close_task(task_id=<id>, reason="obsolete")

Step 4: Clean Memories

Search for memories with __diag__ tag:

# gobby-memory server:
list_memories(tags_any="__diag__")

For each memory:

# gobby-memory server:
delete_memory(memory_id=<id>)

Stale Artifact Detection

Before running tests, check for orphaned __diag__ artifacts:

1. •Call list_memories(tags_any="__diag__")
2. •Call list_tasks() and filter for __diag__ prefix
3. •Call list_worktrees() and filter for __diag__ prefix
4. •Call list_clones() and filter for __diag__ prefix

If any found, report:

WARNING: Found X stale diagnostic artifacts from previous run.
Run `/gobby doctor --cleanup` to remove them, or they will be cleaned after this run.

Output Format

Progress Reporting

For each test, report:

[PASS] <Test Name>
[FAIL] <Test Name>: <Error Message>
[SKIP] <Test Name>: <Reason>

Summary

At the end, report:

=== Doctor Summary ===
Phase 1 (Prerequisites):  X/3 PASS
Phase 2 (Read-Only):      X/Y PASS
Phase 3 (Write+Cleanup):  X/3 PASS
Phase 4 (Resource-Heavy): X/3 PASS (or "Skipped - use --all")
Phase 5 (Security Audit): X/8 PASS, Y WARN (or "Skipped - use --security or --all")

Overall: X/Y tests passed, Z warnings
Cleanup: All __diag__ artifacts removed

Failure Report

If any tests fail, include a failure summary:

=== Failures ===
1. [Phase 2] list_memories: Connection timeout after 10s
2. [Phase 3] create_task: Permission denied

Timeouts

If a timeout occurs, log the failure and continue to the next test.

Error Handling

1. •Prerequisite failures: Stop immediately - report which prerequisite failed
2. •Test failures: Log failure, continue to next test, ensure cleanup still runs
3. •Cleanup failures: Log warning but don't fail the diagnostic
4. •Timeout: Treat as failure, continue to next test

Examples

Show help

User: /gobby doctor Display available options and descriptions.

Functional health check

User: /gobby doctor --functional Run phases 1-3 (prerequisites, read-only, write+cleanup tests).

Security audit

User: /gobby doctor --security Run phase 5 security checks only.

Full system test

User: /gobby doctor --all Run all phases including worktree/clone tests and security audit.

Cleanup stale artifacts

User: /gobby doctor --cleanup Only run cleanup protocol, report what was removed.