# AI Tools Doctor Implementation Report

**Date**: 2025-12-01
**Status**: MVP Complete
**RFC**: docs/rfc-ai-tools-doctor.md

## Summary

Implemented `ai-tools-doctor` CLI with `check` and `sync` commands per RFC. MVP scope - no `bump` command yet.

## What Was Built

### dotfiles repo

**`config/ai-tools/tools.json`** - Updated manifest
- Added `source` field (npm/nix) to each tool
- Pinned versions (was "latest")
- Added nix tools (opencode, beads)

**`bin/ai-tools-doctor`** - New CLI (212 lines bash)
- `check` - Compare installed vs declared versions
- `check --json` - Machine-readable output
- `check --quiet` - Exit code only
- `sync` - Install/update npm tools to declared versions

### skills repo

**`skills/ai-tools-doctor/`** - Skill for Claude Code / OpenCode
- SKILL.md - Agent instructions
- README.md - Human documentation

## Deviations from RFC

| RFC | Implementation | Reason |
|-----|----------------|--------|
| Exit code 1 for "updates available" | Exit 0 for success, 1 for errors only | Non-zero confuses many tools |
| `expected_version` for nix | `version` for all | Consistency |
| opencode version 0.2.1 | 1.0.119 | RFC had wrong version |

## Current Tool Versions

```
claude-code  2.0.55   (npm)
openai-codex 0.63.0   (npm)
opencode     1.0.119  (nix)
beads        0.26.0   (nix)
```

## Still TODO

1. **Delete old script** - `bin/ai-tools-sync.sh` still exists, can be removed
2. **Home Manager integration** - Symlink manifest to `~/.config/ai-tools/`
3. **Session hook** - Optional: run check on agent session start
4. **Delete obsolete skill** - `.claude/skills/update-claude/` per RFC

## Testing

```bash
# All pass
ai-tools-doctor check           # Human output
ai-tools-doctor check --json    # JSON output
ai-tools-doctor check --quiet   # Exit code only
ai-tools-doctor sync            # Syncs npm tools
```

## Files Changed

```
dotfiles/
├── config/ai-tools/tools.json  (modified)
└── bin/ai-tools-doctor         (new)

skills/
└── skills/ai-tools-doctor/
    ├── SKILL.md                (new)
    └── README.md               (new)
```

## Next Steps

1. Review and commit dotfiles changes
2. Add to Home Manager if needed
3. Consider `bump` command for future (fetches latest from npm registry)