skills/docs/rfc-ai-tools-doctor.md

RFC: AI Tools Doctor - Unified Version Management

Status: Draft Author: dotfiles team Date: 2025-12-01 Related: dotfiles-6l8

Problem

Multiple AI coding tools (claude-code, codex, opencode, beads) with mixed management approaches:

• NPM tools want to self-update, drift from known state
• Nix tools are declarative but version info scattered
• No unified view for agents to report tool status
• Current ai-tools-sync.sh only handles npm tools

Goals

1. Unified view - Single tool to check all AI tools regardless of source
2. Declarative - Pin versions in manifest, updates are explicit
3. Agent-first - JSON output, exit codes, fast for hooks
4. Nix-ian - Reproducible, version-controlled, git-trackable

Design

Manifest: config/ai-tools/tools.json

{
  "tools": {
    "claude-code": {
      "source": "npm",
      "npm_package": "@anthropic-ai/claude-code",
      "version": "2.0.55",
      "install_dir": "~/.local/share/claude-code",
      "binary": "claude"
    },
    "openai-codex": {
      "source": "npm",
      "npm_package": "@openai/codex",
      "version": "0.63.0",
      "install_dir": "~/.local/share/openai-codex",
      "binary": "codex"
    },
    "opencode": {
      "source": "nix",
      "expected_version": "0.2.1",
      "binary": "opencode"
    },
    "beads": {
      "source": "nix",
      "expected_version": "0.26.0",
      "binary": "bd"
    }
  }
}

CLI: ai-tools-doctor

# Check all tools (human-readable)
ai-tools-doctor check

# Check all tools (machine-readable for agents)
ai-tools-doctor check --json

# Exit code only (for hooks)
ai-tools-doctor check --quiet

# Sync npm tools to declared versions
ai-tools-doctor sync

# Update manifest to latest, then sync
ai-tools-doctor bump [tool]
ai-tools-doctor bump --all

Exit Codes

• 0 - All tools match declared versions
• 1 - Updates available (informational, not error)
• 2 - Error (missing tools, network failure, etc.)

JSON Output Schema

{
  "status": "updates_available",
  "updates_count": 1,
  "tools": {
    "claude-code": {
      "source": "npm",
      "installed": "2.0.55",
      "declared": "2.0.55",
      "available": "2.0.56",
      "status": "update_available"
    },
    "beads": {
      "source": "nix",
      "installed": "0.26.0",
      "declared": "0.26.0",
      "status": "ok"
    }
  }
}

Shared Skill: claude/skills/ai-tools-doctor/

Following existing skills pattern, deployed to both Claude and OpenCode:

claude/skills/ai-tools-doctor/
├── SKILL.md          # Agent invocation description
├── README.md         # Documentation
└── scripts/
    └── check.sh      # Wrapper calling bin/ai-tools-doctor.sh

Replaces: .claude/skills/update-claude/ (Claude-only, obsolete)

Agent Integration

Session start hook or skill can run:

result=$(ai-tools-doctor check --json 2>/dev/null)
if [[ $? -eq 1 ]]; then
  # Agent parses JSON, mentions updates to user
fi

Key Decisions

Version Pinning (chosen over "latest")

Why: Aligns with Nix philosophy. Updates are intentional, tracked in git. Can review changelogs before bumping. Reproducible: same manifest = same tools.

Tradeoff: Requires manual bump command. Mitigated by agent visibility.

Nix Tools as Read-Only

Why: Nix tools are managed by nix flake update, not this tool. Doctor reports their status but doesn't manage them.

Behavior: Shows installed vs declared. No "available" check - that's nix territory.

Shared Skill (not Claude-only)

Why: Both Claude and OpenCode use these tools. Unified skill works for both agents via existing Home Manager deployment pattern.

Files to Modify

1. config/ai-tools/tools.json - Add source types, pin versions, add nix tools
2. bin/ai-tools-sync.sh → bin/ai-tools-doctor.sh - Rename, add JSON/exit codes
3. claude/skills/ai-tools-doctor/ - New shared skill
4. home/claude.nix - Deploy shared skill
5. Delete .claude/skills/update-claude/ - Replaced

Open Questions

1. Cache npm registry responses for faster checks?
2. Session start hook integration - automatic or manual trigger?
3. Should bump auto-commit the manifest change?

Out of Scope

• Managing nix tool versions (use nix flake update)
• Auto-updating during sessions (agent reports, human decides)
• Other non-AI tools