437265b916
spec-review: Multi-model review of spec-kit artifacts using orch - SKILL.md with progressive disclosure pattern - Review processes: spec, plan, tasks, gate-check - Prompts for critique, review, and go/no-go decisions ai-tools-doctor: RFC and implementation report for diagnostics skill 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
169 lines
4.3 KiB
Markdown
169 lines
4.3 KiB
Markdown
# 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`
|
|
|
|
```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`
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
```bash
|
|
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
|